Skip to contents

Set the quantities of interest (QoIs)

Source: R/set_qoi.R
set_qoi.Rd

Constructs a quantities-of-interest (QoI) specification for projoint. Use this to request specific estimands—marginal means (MMs) or average marginal component effects (AMCEs)—at either the choice- or profile-level, and to declare which attribute levels are compared (including baselines).

Usage

set_qoi(
  .structure = "choice_level",
  .estimand = "mm",
  .att_choose,
  .lev_choose,
  .att_notchoose = NULL,
  .lev_notchoose = NULL,
  .att_choose_b = NULL,
  .lev_choose_b = NULL,
  .att_notchoose_b = NULL,
  .lev_notchoose_b = NULL
)

Arguments

.structure

Either "choice_level" (default) or "profile_level".

.estimand

Either "mm" for marginal means or "amce" for average marginal component effects.

.att_choose

Character scalar: the attribute (column) for the level(s) that are chosen.

.lev_choose

Character vector: the level id(s) for the chosen side. Length 1 for profile-level, \(\ge\)1 for choice-level.

.att_notchoose

Character scalar: the attribute (column) for the level(s) that are not chosen. Only used for .structure == "choice_level".

.lev_notchoose

Character vector: the level id(s) for the not chosen side. Length 1 for profile-level, \(\ge\)1 for choice-level. Only used for .structure == "choice_level".

.att_choose_b

Character scalar: baseline attribute for the chosen side when computing AMCEs.

.lev_choose_b

Character vector: baseline level id(s) for the chosen side when computing AMCEs. Length 1 for profile-level, \(\ge\)1 for choice-level.

.att_notchoose_b

Character scalar: baseline attribute for the not-chosen side (choice-level only) when computing AMCEs.

.lev_notchoose_b

Character vector: baseline level id(s) for the not-chosen side (choice-level only) when computing AMCEs.

Value

A projoint_qoi object (list-like) containing fields such as: structure, estimand, attribute_of_interest, levels_of_interest, and their baseline counterparts. This object can be supplied to downstream estimation helpers that accept a QoI spec.

Examples

# Specify a simple choice-level MM comparison for att1 levels:
q_mm <- set_qoi(
  .structure  = "choice_level",
  .estimand   = "mm",
  .att_choose = "att1",
  .lev_choose = c("att1:lev2"),
  .att_notchoose = "att1",
  .lev_notchoose = c("att1:lev1")
)
str(q_mm)
#> List of 10
#>  $ structure                       : chr "choice_level"
#>  $ estimand                        : chr "mm"
#>  $ attribute_of_interest           : chr "att1"
#>  $ levels_of_interest              : chr "att1:lev2"
#>  $ attribute_of_interest_0         : chr "att1"
#>  $ levels_of_interest_0            : chr "att1:lev1"
#>  $ attribute_of_interest_baseline  : NULL
#>  $ levels_of_interest_baseline     : NULL
#>  $ attribute_of_interest_0_baseline: NULL
#>  $ levels_of_interest_0_baseline   : NULL
#>  - attr(*, "class")= chr "projoint_qoi"

# Example AMCE with explicit baselines (profile-level):
q_amce <- set_qoi(
  .structure   = "profile_level",
  .estimand    = "amce",
  .att_choose  = "att2",
  .lev_choose  = "att2:lev3",
  .att_choose_b = "att2",
  .lev_choose_b = "att2:lev1"
)
str(q_amce)
#> List of 10
#>  $ structure                       : chr "profile_level"
#>  $ estimand                        : chr "amce"
#>  $ attribute_of_interest           : chr "att2"
#>  $ levels_of_interest              : chr "att2:lev3"
#>  $ attribute_of_interest_0         : NULL
#>  $ levels_of_interest_0            : NULL
#>  $ attribute_of_interest_baseline  : chr "att2"
#>  $ levels_of_interest_baseline     : chr "att2:lev1"
#>  $ attribute_of_interest_0_baseline: NULL
#>  $ levels_of_interest_0_baseline   : NULL
#>  - attr(*, "class")= chr "projoint_qoi"