choice_data: Define choice data
In choicedata: Working with Choice Data

choice_data

R Documentation

Define choice data

Description

The choice_data object defines the choice data, it is a combination of choice_responses and choice_covariates.

Usage

choice_data(
  data_frame,
  format = "wide",
  column_choice = "choice",
  column_decider = "deciderID",
  column_occasion = NULL,
  column_alternative = NULL,
  column_ac_covariates = NULL,
  column_as_covariates = NULL,
  delimiter = "_",
  cross_section = is.null(column_occasion),
  choice_type = c("discrete", "ordered", "ranked")
)

generate_choice_data(
  choice_effects,
  choice_identifiers = generate_choice_identifiers(N = 100),
  choice_covariates = NULL,
  choice_parameters = NULL,
  choice_preferences = NULL,
  column_choice = "choice",
  choice_type = c("auto", "discrete", "ordered", "ranked")
)

long_to_wide(
  data_frame,
  column_ac_covariates = NULL,
  column_as_covariates = NULL,
  column_choice = "choice",
  column_alternative = "alternative",
  column_decider = "deciderID",
  column_occasion = NULL,
  alternatives = unique(data_frame[[column_alternative]]),
  delimiter = "_",
  choice_type = c("discrete", "ordered", "ranked")
)

wide_to_long(
  data_frame,
  column_choice = "choice",
  column_alternative = "alternative",
  alternatives = NULL,
  delimiter = "_",
  choice_type = c("discrete", "ordered", "ranked")
)

Arguments

`data_frame`	[`data.frame`] Contains the choice data.
`format`	[`character(1)`] Format of `data_frame`. Use `"wide"` when each row contains all alternatives of an occasion and `"long"` when each row contains a single alternative.
`column_choice`	[`character(1)`] Column name with the observed choices. In wide layout this column should contain a single value per observation: for discrete data the value is the label of the chosen alternative, for ordered data it is the ordered factor or integer score, and for ranked data it is omitted in favour of one column per alternative (see `choice_type`). In long layout the same column is evaluated once per alternative: discrete data must use a binary indicator (1 for the chosen alternative, 0 otherwise), ordered data repeats the ordinal value for every alternative, and ranked data stores the integer rank `1:J` for each alternative within an observation. Set to `NULL` when no observed choices are available (e.g., for purely covariate tables).
`column_decider`	[`character(1)`] Column name with decider identifiers.
`column_occasion`	[`character(1)` \| `NULL`] Column name with occasion identifiers. Set to `NULL` in cross-sectional data.
`column_alternative`	[`character(1)` \| `NULL`] Column name with alternative identifiers when `format = "long"`.
`column_ac_covariates`	[`character()` \| `NULL`] Column names with alternative-constant covariates.
`column_as_covariates`	[`character()`] Column names of `data_frame` with alternative-specific covariates.
`delimiter`	[`character(1)`] Delimiter separating alternative identifiers from covariate names in wide format. May consist of one or more characters.
`cross_section`	[`logical(1)`] Treat choice data as cross-sectional?
`choice_type`	[`character(1)`] Requested response type. Use `"auto"` (default) to infer the mode from `choice_alternatives()`, or explicitly simulate `"discrete"`, `"ordered"`, or `"ranked"` outcomes.
`choice_effects`	[`choice_effects`] A `choice_effects` object describing the model.
`choice_identifiers`	[`choice_identifiers`] A `choice_identifiers` object that provides the decider and occasion identifiers.
`choice_covariates`	[`choice_covariates`] Covariates to include in the generated data.
`choice_parameters`	[`choice_parameters`] Model parameters supplying utilities and covariance structures.
`choice_preferences`	[`choice_preferences`] Decider-specific preference draws used for simulation.
`alternatives`	[`character(J)`] Unique labels for the choice alternatives.

Details

choice_data() acts as the main entry point for observed data. It accepts either long or wide layouts and performs validation before returning a tidy tibble with consistent identifiers. Columns that refer to the same alternative are aligned using delimiter so that downstream helpers can detect them automatically. When used with ranked or ordered choices the function checks that rankings are complete and warns about inconsistencies.

Internally the helper converts long inputs to wide format. This guarantees that subsequent steps (such as computing probabilities) receive the same structure regardless of the original layout and keeps the workflow concise.

generate_choice_data() simulates choice data.
wide_to_long() and long_to_wide() transform to wide and long format.

The generated choice_data object inherits a choice_type attribute for the requested simulation mode. Ordered alternatives (ordered = TRUE) yield ordered responses, unordered alternatives default to discrete multinomial outcomes, and ranked simulations return complete rankings for every observation.

Value

A tibble that inherits from choice_data.

Examples

### simulate data from a multinomial probit model
choice_effects <- choice_effects(
  choice_formula = choice_formula(
    formula = choice ~ A | B, error_term = "probit",
    random_effects = c("A" = "cn")
  ),
  choice_alternatives = choice_alternatives(J = 3)
)
generate_choice_data(choice_effects)

### transform between long/wide format
long_to_wide(
  data_frame = travel_mode_choice,
  column_alternative = "mode",
  column_decider = "individual"
)
wide_to_long(
  data_frame = train_choice
)

choicedata documentation built on Nov. 5, 2025, 5:46 p.m.