R/amce-documentation.R

In cjoint: AMCE Estimator for Conjoint Experiments

#' Estimating Causal Effects in Conjoint Experiments
#'
#' This function takes a dataset and a conjoint design and returns Average
#' Marginal Component Effects (AMCEs) and Average Component Interaction
#' Effects (ACIE) for the attributes specified in the formula. By default,
#' this function assumes uniform randomization of attribute levels and no
#' profile restrictions. If your design incorporates weighted randomization or
#' restrictions on displayable profiles, first generate a design object using
#' \code{makeDesign}. Interactions with respondent-level characteristics are
#' handled by identifying relevant variables as respondent-varying.
#'
#'
#' @param formula A \code{formula} object specifying the name of the outcome
#' variable on the left-hand side and the attributes for which effects are to
#' be estimated on the right-hand side. RHS attributes should be separated by
#' \code{+} signs. Interaction effects can be specified using standard
#' interaction syntax - joining attribute names using either \code{:} or
#' \code{*}.  However using the \code{:} syntax will produce the same results
#' as \code{*} since missing base terms are automatically added to the
#' formula. For example \code{Y ~ X1 + X2} will return AMCEs for X1 and X2.
#' \code{Y ~ X1 + X2 + X1:X2} will return AMCEs for X1 and X2 along with an
#' ACIE for X1/X2. \code{Y ~ X1*X2} and \code{Y ~ X1:X2} will produce
#' identical results to \code{Y ~ X1 + X2 + X1:X2}. Note that you can place
#' backticks around a variable name containing spaces in order to have
#' \code{\link{formula}} interpret it as a single variable name. Any
#' respondent characteristics must be designated as such in
#' \code{redpondent.varying}.
#' @param data A dataframe containing the outcome variable, attributes,
#' respondent identifiers, respondent covariate data and sampling weights from
#' a conjoint experiment.
#' @param design Either the character string \code{"uniform"} or a
#' \code{conjointDesign} object created by the \code{\link{makeDesign}}
#' function. If a \code{conjointDesign} is not passed, the function will
#' assume all attribute levels have an equal probability of being presented to
#' a respondent and that no profiles are restricted. Defaults to
#' \code{"uniform"}.
#' @param respondent.varying A vector of character strings giving the names of
#' any respondent-varying characteristics being interacted with AMCEs or ACIEs
#' in the \code{formula}.
#' @param subset A logical vector with length \code{nrow(data)} denoting which
#' rows in \code{data} should be included in estimation. This can for example
#' be used to subset the data along respondent-level covariates. Defaults to
#' \code{NULL}.
#' @param respondent.id A character string indicating the column of
#' \code{data} containing a unique identifier for each respondent. Defaults to
#' \code{NULL}.
#' @param cluster A logical indicating whether estimated standard errors
#' should be clustered on \code{respondent.id}. Defaults to \code{TRUE}.
#' @param na.ignore A logical indicating whether the function should ignore
#' missing rows in \code{data}. If \code{FALSE}, amce() will raise an error if
#' there are rows with missing values. Defaults to \code{FALSE}.
#' @param weights A character string giving the name of the column in the data
#' containing any survey weights. See documentation for \code{survey} package
#' for more information.
#' @param baselines Manually adjust the baselines of select factor variables
#' (either attributes or respondent varying) by supplying a list. Names of
#' list entries should correspond with variable names. The content of each
#' entry should be a character string giving the new baseline.
#' @return An object of class "amce" containing: \item{attributes}{A list
#' containing the names of attributes.} \item{baselines}{Baseline levels for
#' each attribute in \code{estimates}. Baselines determined using the first
#' element of \code{levels()}. If a different baseline level is desired for an
#' attribute, use the \code{relevel()} function on the variable prior to
#' calling the \code{amce()} routine or supply an alternative baseline in
#' \code{baselines} argument.} \item{continuous}{List of quantiles for any
#' non-factor variables, whether attributes or respondent varying.}
#' \item{data}{The original data.} \item{estimates}{A list containing AMCE and
#' ACIE estimates for each attribute in \code{formula}. Each element of
#' \code{estimates} corresponds to a single attribute or interaction.}
#' \item{formula}{The \code{formula} passed to the \code{amce()} routine.}
#' \item{samplesize_prof}{The number of valid profiles (rows) in the dataset}
#' \item{user.names}{A vector with the original user supplied names for any
#' attributes. These may differ from the attribute names in \code{estimates}
#' if the original names contain spaces.} \item{vcov.prof}{The modified
#' variance-covariance matrix for AMCE and ACIE estimates. Incorporates
#' cluster corrections as well as attribute dependencies. Profile varying
#' attributes only.} \item{numrespondents}{The number of respondents in the
#' dataset (if \code{respondent.id} is not \code{NULL}). }
#' \item{respondent.varying}{Names of respondent-varying variables, if any.}
#' \item{cond.formula}{The formula used for calculating estimates conditional
#' on respondent varying characteristics. Only returned when
#' respondent-varying characteristics are present.} \item{cond.estimates}{A
#' list containing AMCE and ACIE estimates conditional on the values of the
#' respondent-varying characteristics. Each element of \code{cond.estimates}
#' corresponds to a single attribute or interaction. Only returned when
#' respondent-varying characteristics are present} \item{samplesize_full}{The
#' number of valid profiles (rows) in the dataset when respondent varying
#' characteristics are included. Only returned when respondent-varying
#' characteristics are present. } \item{vcov.resp}{The modified
#' variance-covariance matrix for effect estimates conditional on
#' respondent-varying characteristics, where dependent relationships have been
#' incorporated into variances and covariances. Only returned when
#' respondent-varying characteristics are present. }
#' @seealso \code{\link{summary.amce}} for summaries and
#' \code{\link{plot.amce}} for generating a coefficient plot using
#' \code{ggplot2}.
#'
#' \code{\link{makeDesign}} to create \code{conjointDesign} objects.
#' @references Hainmueller, J., Hopkins, D., and Yamamoto T. (2014) Causal
#' Inference in Conjoint Analysis: Understanding Multi-Dimensional Choices via
#' Stated Preference Experiments. Political Analysis 22(1):1-30
#' @examples
#'
#' # Immigration Choice Conjoint Experiment Data from Hainmueller et. al. (2014).
#' data("immigrationconjoint")
#' data("immigrationdesign")
#'
#' # Run AMCE estimator using all attributes in the design
#' results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry`, data=immigrationconjoint,
#'                 cluster=TRUE, respondent.id="CaseID", design=immigrationdesign)
#' # Print summary
#' summary(results)
#'
#' \dontrun{
#' # Run AMCE estimator using all attributes in the design with interactions
#' interaction_results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry` + Education:`Language Skills` +
#' 		Job: `Job Experience` + `Job Plans`:`Reason for Application`,
#' 		data=immigrationconjoint, cluster=TRUE, respondent.id="CaseID",
#' 		design=immigrationdesign)
#' # Print summary
#' summary(interaction_results)
#'
#' # create weights in data
#' weights <- runif(nrow(immigrationconjoint))
#' immigrationconjoint$weights <- weights
#' # Run AMCE estimator using weights
#' results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry`, data=immigrationconjoint,
#'                 cluster=TRUE, respondent.id="CaseID", design=immigrationdesign,
#' 		weights = "weights")
#' # Print summary
#' summary(results)
#'
#' # Include a respondent-varying interaction
#' results <- amce(Chosen_Immigrant ~ Gender + Education + Job +
#' 	   	ethnocentrism:Job + Education:Job,
#' 		data=immigrationconjoint, na.ignore = TRUE,
#' 		cluster=FALSE,design=immigrationdesign,
#' 		respondent.varying = "ethnocentrism")
#' # Print summary
#' summary(results)
#'
#' # Change the baseline for "Education"
#' baselines <- list()
#' baselines$Education <- "graduate degree"
#'
#' results <- amce(Chosen_Immigrant ~ Gender + Education + Job +
#' 		 Education:Job, data=immigrationconjoint,
#' 		 cluster=FALSE,design=immigrationdesign,
#' 		 baselines=baselines)
#' # Print summary
#' summary(results)
#' }
#'
#'




## start here

#' @examples
#' data("immigrationconjoint")
#' data("immigrationdesign")
#'
#' # Run AMCE estimator using all attributes in the design
#' results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry`, data=immigrationconjoint,
#'                 cluster=TRUE, respondent.id="CaseID", design=immigrationdesign)
#' # Print summary
#' summary(results)
#' 
#' #'
#' \dontrun{
#' # Run AMCE estimator using all attributes in the design with interactions
#' interaction_results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry` + Education:`Language Skills` +
#' 		Job: `Job Experience` + `Job Plans`:`Reason for Application`,
#' 		data=immigrationconjoint, cluster=TRUE, respondent.id="CaseID",
#' 		design=immigrationdesign)
#' # Print summary
#' summary(interaction_results)
#'
#' # create weights in data
#' weights <- runif(nrow(immigrationconjoint))
#' immigrationconjoint$weights <- weights
#' # Run AMCE estimator using weights
#' results <- amce(Chosen_Immigrant ~  Gender + Education + `Language Skills` +
#'                 `Country of Origin` + Job + `Job Experience` + `Job Plans` +
#'                 `Reason for Application` + `Prior Entry`, data=immigrationconjoint,
#'                 cluster=TRUE, respondent.id="CaseID", design=immigrationdesign,
#' 		weights = "weights")
#' # Print summary
#' summary(results)
#'
#' # Include a respondent-varying interaction
#' results <- amce(Chosen_Immigrant ~ Gender + Education + Job +
#' 	   	ethnocentrism:Job + Education:Job,
#' 		data=immigrationconjoint, na.ignore = TRUE,
#' 		cluster=FALSE,design=immigrationdesign,
#' 		respondent.varying = "ethnocentrism")
#' # Print summary
#' summary(results)
#'
#' # Change the baseline for "Education"
#' baselines <- list()
#' baselines$Education <- "graduate degree"
#'
#' results <- amce(Chosen_Immigrant ~ Gender + Education + Job +
#' 		 Education:Job, data=immigrationconjoint,
#' 		 cluster=FALSE,design=immigrationdesign,
#' 		 baselines=baselines)
#' # Print summary
#' summary(results)
#' }
#'
#'