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