\name{set_interaction}
\alias{set_interaction}
\alias{includeInteraction}
\alias{set_interaction.sienaEffects}
\title{
Function to create user-specified interactions for a Siena model.
}
\description{This function allows the user to include or exclude
  an interaction effect in a Siena effects object.
}
\usage{
\method{set_interaction}{sienaEffects}(x, shortNames, type="eval",
            depvar=x$name[1], covar1=rep("", 3), covar2=rep("", 3),
            initialValue = 0, random=FALSE,
            include=TRUE, fix=FALSE, test=FALSE, verbose=TRUE, ...)

includeInteraction(x, ..., include = TRUE, name = x$name[1],
    type = "eval", interaction1 = rep("", 3), interaction2 = rep("", 3),
    fix=FALSE, test=FALSE, random=FALSE,
    initialValue=0,
    character = FALSE, verbose = TRUE)
}
\arguments{
  \item{x}{A Siena effects object as created by \code{\link{make_specification}},
    which is either an object of class \code{sienaEffects}
    or \code{sienaGroupEffects}.
  }
  \item{shortNames}{List of 2 or 3 shortNames to identify the effects
    which should be interacted.
  }
  \item{type}{
    Type of effects to be interacted.
  }
  \item{depvar}{Name of dependent variable (network or behavior)
    for which interactions are being defined.
    Defaults to the first in the effects object.
  }
  \item{covar1}{
    Vector of Siena objects where needed to completely identify the
    effect e.g. covariate name or behavior variable name.
    See the examples below. Trailing blanks may be omitted.
  }
  \item{covar2}{
    Vector of Siena objects where needed to completely identify the
    effect e.g. covariate name or behavior variable name.
    Trailing blanks may be omitted.
  }
  \item{initialValue}{Initial value for estimation. Default 0.}
  \item{random}{For specifying that the interaction effect will vary randomly;
    not relevant for \code{RSiena} at this moment.
    Boolean required. Default FALSE.}
  \item{include}{
    Boolean. default TRUE, but can be switched to FALSE to
    turn off an interaction.
  }
  \item{fix}{
    Boolean. Are the effects to be fixed at the value stored in
    \code{x$initialValue} or not.}
  \item{test}{
    Boolean. Are the effects to be tested or not (requires \code{fix}).}
  \item{character}{Boolean: are the effect names character strings or not.}
  \item{verbose}{Boolean: should the print of altered effects be produced.}
  \item{\dots}{for \code{includeInteraction}: 2 or 3 shortNames to identify the effects
    which should be interacted. Not used for \code{set_interaction}.
  }
  \item{name}{Name of dependent variable (network or behavior)
    for which interactions are being defined.
    Defaults to the first in the effects object.
  }
  \item{interaction1}{
    Vector of Siena objects where needed to completely identify the
    effect e.g. covariate name or behavior variable name.
    See the examples below.
    Trailing blanks may be omitted.
  }
  \item{interaction2}{
    Vector of Siena objects where needed to completely identify the
    effect e.g. covariate name or behavior variable name.
    Trailing blanks may be omitted.
  }
}
\details{The details provided should uniquely identify two or three
  effects. If so, an interaction effect will be created and included or
  not in the model. \cr
  Whether interactions between two or three given effects
  can be created depends on their
  \code{interactionType} (which can be, for
  dependent network variables, \code{empty}, \code{ego}, or \code{dyadic};
  and for dependent behavioral variables, \code{empty} \code{or OK}).
  Consult the section on Interaction
  Effects in the manual for this. The \code{interactionType} is shown
  in the list of effects obtained from the function \cr
  \code{\link{effectsDocumentation}}.\cr
  The short names must not be set between quotes,
  unless you use \code{character=TRUE}.\cr
  From the point of view of model building it is usually advisable, when
  including an interaction effect in a model, also to include the
  corresponding main effects. This is however not enforced
  by \code{set_interaction}.\cr

  As from version 1.3.24, effects object have a "version" attribute.
  Effects objects including interaction effects are not necessarily compatible
  between versions of \code{RSiena}. Therefore it is recommended to create
  such effects objects again when changing to a new version of \code{RSiena}.
  If an effects object including any interaction effects is used from an
  old version of \code{RSiena}, this will lead to a warning when running
  \code{\link{siena07}}. \cr

  An interaction effect does not have its own internal effect parameter.
  The internal effect parameters of the interacting main effects are used,
  whether or not these are included in the model. This implies that if an
  interaction effect is included but not the corresponding main effects,
  or not all of them, then nevertheless the internal effect parameters as
  specified in the effects object are used for the interaction.
  These can be set using function \code{setEffect} with the desired value
  of \code{parameter} and (in this case) \code{include=FALSE} or
  \code{fix=TRUE, initialValue=0}. \cr
  If an internal effect parameter is changed for one of the main effects
  after the last call of \cr
  \code{set_interaction} for a given interaction
  effect, this will not be visible in the name of the interaction effect
  when the effects object is printed.
  However, the correct value of the internal effect parameter
  will be used by \code{\link{siena07}}.\cr
  The values of the internal effect parameters can be checked for a
  \code{\link{sienaFit}} object \code{ans} produced by \code{\link{siena07}}
  by looking at \code{ans$effects}, which is the requested effects object
  to which the main effects of the user-defined interactions were added,
  if they were not included.\cr

  Interaction effects are constructed from effects with shortName
  \code{unspInt} (for networks), \cr
  \code{behUnspInt} (for discrete behavior),
  and \code{contUnspInt} (for continuous behavior) by specifying their
  elements \code{effect1} and \code{effect2}, and possibly \code{effect3}.
  The shortName is not altered by this function.

  The number of possible user-specified interaction effects is limited
  by the parameters \code{nintn} (for dependent network variables)
  and \code{behNintn} (for dependent behavior variables) in the call of
  \code{\link{make_specification}}, which determine the numbers of effects with
  shortNames \code{unspInt}, \code{behUnspInt}, and \code{contUnspInt}
  (for the latter two, the maximum is \code{behNintn} each).

  The input names \code{interaction1} and \code{interaction2},
  which are vectors as indicated above, do not themselves
  refer to created interactions, but to dependence of the base effects on
  other variables in the data set.
  They are used to completely identify the effects.\cr
  The first element of these vectors applies to the first shortName,
  the second to the second, and if \dots contains 3 shortNames,
  the third to the third. See the list of examples below for the interaction
  between \code{recip} and \code{simX} for an example.

  Further information about Siena effects objects is given
  in the help page for \cr
  \code{\link{make_specification}}.

  A list of all effects in a given effects object (e.g., \code{myeff}),
  including their names of dependent variables, effect names, short names,
  and values of interaction1 and interaction2 (if any),
  is obtained by executing \code{\link{effectsDocumentation}(myeff)}.
}
\value{
  An updated version of the input effects object; if \code{include},
  containing the interaction effect between "effect1" and "effect2" and
  possibly "effect3"; if not, without this interaction effect.
  The shortName of the interaction effect is "unspInt" for network effects,
  "behUnspInt" for discrete behavior effects, and "contUnspInt" for
  continuous behavior effects. \cr
  If \code{verbose=TRUE}, the interacting effects and the interaction effect
  will be printed, with their row numbers in the effects object.
}
\references{See \url{https://www.stats.ox.ac.uk/~snijders/siena/}}
\author{Ruth Ripley, Tom Snijders}
\seealso{
  \code{\link{make_specification}}, \code{\link{set_effect}},
  \code{\link{includeEffects}}, \code{\link{effectsDocumentation}
}}
\examples{
mynet <- as_dependent_rsiena(array(c(s501, s502, s503), dim=c(50, 50, 3)))
alc <- as_covariate_rsiena(s50a)
sm <- as_covariate_rsiena(s50s)
mydata <- make_data_rsiena(mynet, alc, sm)
myeff <- make_specification(mydata)
myeff
myeff <- set_effect(myeff, inPop)
myeff <- set_interaction(myeff, list(recip, inPop))
myeff <- set_interaction(myeff, list("recip", "inPop"))
myeff
myeff <- set_interaction(myeff, list(egoX, altX, simX), covar1=c("alc", "alc", "alc"))
myeff <- set_interaction(myeff, list(egoX, altX), covar1=c("alc", "sm"))
myeff <- set_interaction(myeff, list(recip, simX), covar1=c("", "alc"))
myeff
myeff <- set_effect(myeff, gwespFF, parameter=20)
myeff <- set_interaction(myeff, list(recip, gwespFF))
myeff
(myeff <- set_effect(myeff, gwespFF, parameter=69, include=FALSE))
myeff <- set_interaction(myeff, list(recip, gwespFF))
myeff
}
\keyword{classes}
