1\name{add.response} 2\alias{add.response} 3%- Also NEED an '\alias' for EACH other topic documented here. 4\title{ Function to add response values to an experimental design} 5\description{ 6This function allows to add numeric response variables to an experimental plan of 7class design. The responses are added both to the data frame and to its desnum 8attribute; the response.names element of the design.info attribute is updated - 9the function is still experimental. 10} 11\usage{ 12add.response(design, response, rdapath=NULL, replace = FALSE, 13 InDec=options("OutDec")[[1]], tol = .Machine$double.eps ^ 0.5, ...) 14} 15%- maybe also 'usage' for other objects documented here. 16\arguments{ 17 \item{design}{a character string that gives the name of a class \code{\link{design}} 18 object, to which responses are to be added} 19 \item{response}{EITHER 20 21 a numeric vector, numeric matrix or data frame with at least 22 one numeric variable (the treatment of these is explained in the details section) 23 24 OR 25 26 a character string indicating a csv file that contains the typed-in response values; 27 after reading the csv file with the csv version indicated in the \code{InDec} argument, 28 numeric variables from response will be added to the design as responses } 29 \item{rdapath}{a character string indicating the path to a stored rda file that contains the 30 design } 31 \item{replace}{ logical: TRUE implies that existing variables are overwritten in \code{design}; 32 cf. also the details section} 33 \item{InDec}{ decimal separator in the external csv file; defaults to the 34 \code{OutDec} option (viewable under \code{options("OutDec"}), 35 and also governs whether the \code{csv}-file is read with \code{\link[utils:read.table]{read.csv}} or with 36 \code{\link[utils:read.table]{read.csv}}: 37 separator semicolon goes with decimal comma and triggers use of \code{\link[utils:read.table]{read.csv2}}, 38 separator comma goes with decimal point and trigggers use of \code{\link[utils:read.table]{read.csv}}. )} 39 \item{tol}{tolerance for comparing numerical values;\cr 40 useful for designs with numeric factors and for partial replacement of response values; 41 the value is used in comparisons of design and response via \code{\link{all.equal}}; 42 errors from peculiar rounding behavior of spreadsheet programs can be prevented by 43 allowing a larger \code{tol} } 44 \item{\dots}{further arguments; currently not used} 45 } 46\details{ 47 If \code{response} is a data frame or a matrix, responses are assumed to be 48 all the numeric variables that are neither factor names or block names in \code{design} 49 (i.e. names of the \code{factor.names} element of the \code{design.info} attribute 50 or the \code{block.name} element of that same attribute) 51 nor column names of the \code{run.order} attribute, nor \code{name} or \code{Name}. 52 53 If \code{design} already contains columns for the response(s), NA entries of these 54 are overwritten, if all non-NA entries coincide between \code{design} 55 and \code{response}. 56 57 The idea behind this function is as follows: 58 After using \code{\link{export.design}} for storing an R work space with the 59 design object and either a csv or html file externally, 60 Excel or some other external software is used to type in experimental information. 61 The thus-obtained data sheet is saved as a csv-file and imported into R again (name provided 62 in argument \code{response}, and the design object with all attached information is 63 linked to the typed in response values using function \code{add.response}. 64 65 Alternatively, it is possible to simply type in experimental results in R, both 66 using the R commander plugin (\pkg{RcmdrPlugin.DoE}) or simply function \code{\link[utils]{fix}}. 67 Copy-pasting into R from Excel is per default NOT possible, which has been the reason for programming this routine. 68} 69\value{ 70The value is a modified version of the argument object \code{design}, 71which remains an object of class \code{\link{design}} with the following modifications: 72\item{}{Response columns are added to the data frame} 73\item{}{the same response columns are added to the desnum attribute} 74\item{}{the \code{response.names} element of the \code{design.info} attribute 75 is added or modified} 76} 77 78\author{ Ulrike Groemping } 79\seealso{ See also \code{\link{export.design}} } 80\examples{ 81 plan <- fac.design(nlevels=c(2,3,2,4)) 82 result <- rnorm(2*3*2*4) 83 add.response(plan,response=result) 84 ## direct use of rnorm() is also possible, but looks better with 48 85 add.response(plan,response=rnorm(48)) 86 87 \dontrun{ 88 export.design(path="c:/projectA/experiments",plan) 89 ## open exported file c:/projectA/experiments/plan.html 90 ## with Excel 91 ## carry out the experiment, input data in Excel or elsewhere 92 ## store as csv file with the same name (or a different one, just use 93 ## the correct storage name later in R), after deleting 94 ## the legend portion to the right of the data area 95 ## (alternatively, input data by typing them in in R (function fix or R-commander) 96 add.response(design="plan",response="c:/projectA/experiments/plan.csv", 97 rdapath="c:/projectA/experiments/plan.rda") 98 ## plan is the name of the design in the workspace stored in rdapath 99 ## assuming only responses were typed in 100 ## should work on your computer regardless of system, 101 ## if you adapt the path names accordingly 102 } 103} 104% Add one or more standard keywords, see file 'KEYWORDS' in the 105% R documentation directory. 106\keyword{ array } 107\keyword{ design }% __ONLY ONE__ keyword per line 108