Name of library.

Name of package.

Model object. Estimated model object as returned by function apollo_estimate.

List grouping most common inputs. Created by function apollo_validateInputs.

Named numeric vector. Names and values for parameters.

List grouping most common inputs. Created by function apollo_validateInputs.

List of vectors, matrices or 3-dim arrays. Likelihood of the model components.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of vectors, matrices or 3-dim arrays. Likelihood of the model components.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Either a character variable with the name (and possibly path) of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate.

Either a character variable with the name (and possibly path) of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Options controlling the estimation process. See apollo_estimate. hessianRoutine="none" by default.

List containing settings for the sampling procedure. User input is required for all settings except those with a default or marked as optional.

• calledByEstimate: Logical. TRUE if apollo_bootstrap is called by apollo_estimate. FALSE by default.

• nRep: Numeric scalar. Number of times the model must be estimated with different samples. Default is 30.

• recycle: Logical. If TRUE, the function will look for old output files and append new repetitions to them. If FALSE, output files will be overwritten.

• samples: Numeric matrix or data.frame. Optional argument. Must have as many rows as observations in the database, and as many columns as number of repetitions wanted. Each column represents a re-sample, and each element the number of times that observation must be included in the sample. If this argument is provided, then nRep is ignored. Note that this allows sampling at the observation rather than the individual level, which is not recommended for panel data.

• seed: DEPRECATED, apollo_control$seed is used since v0.2.5. Numeric scalar (integer). Random number generator seed to generate the bootstrap samples. Only used if samples is NA. Default is 24.

Function. Likelihood function as defined by the user.

Function. Used with mixing models. Constructs the random parameters of a mixing model. Receives two arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: The output of this function (apollo_validateInputs).

Function. Used with latent class models. Constructs a list of parameters for each latent class. Receives two arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: The output of this function (apollo_validateInputs).

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar. Note that these need not necessarily be the alternatives as defined in the model, but could e.g. relate to cheapest/most expensive.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• explanators: data.frame. Variables determining subsamples of the database. Values in each column must describe a group or groups of individuals (e.g. socio-demographics). Most usually a subset of columns from the database.

• printToScreen: Logical. TRUE for returning output to screen as well as file. TRUE by default.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

List. Options controlling the running of the code. See apollo_validateInputs.

data.frame. Data used by model.

List of inputs of the MNL model. It should contain the following.

• avail: Named list of numeric vectors or scalars. Availabilities of classes, one element per class Names of elements must match those in classes. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• utilities: Named list of deterministic utilities . Utilities of the classes in class allocation model. Names of elements must match those in avail, if provided.

List of inputs of the CNL model. User input is required for all settings except those with a default or marked as optional.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• cnlNests: List of numeric scalars or vectors. Lambda parameters for each nest. Elements must be named according to nests. The lambda at the root is fixed to 1, and therefore does not need to be defined.

• cnlStructure: Numeric matrix. One row per nest and one column per alternative. Each element of the matrix is the alpha parameter of that (nest, alternative) pair.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of inputs of the CNL model. User input is required for all settings except those with a default or marked as optional.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• cnlNests: List of numeric scalars or vectors. Lambda parameters for each nest. Elements must be named according to nests. The lambda at the root is fixed to 1, and therefore does not need to be defined.

• cnlStructure: Numeric matrix. One row per nest and one column per alternative. Each element of the matrix is the alpha parameter of that (nest, alternative) pair.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of vectors, matrices or 3-dim arrays. Likelihood of the model components.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Character vector. Optional argument. Names of elements in P that should be multiplied to construct the whole model likelihood. If a single element is provided, it is interpreted as a regular expression. Default is to include all components in P.

Logical. Only used if functionality is "conditionals","estimate","validate","zero_LL" or "output". If TRUE, it will return a list as described in the 'Value' section. If FALSE, it will only return a vector/matrix/3-dim array of the product of likelihoods inside P. Default is TRUE.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• estimateDigits: Numeric scalar. Number of decimal places to print for estimates. Default is 4.

• modelNames: Character vector. Optional names of models to combine. Omit or use an empty vector to combine results from all models in the working/output directory.

• pDigits: Numeric scalar. Number of decimal places to print for p-values. Default is 2.

• printClassical: Boolean. TRUE for printing classical standard errors. FALSE by default.

• printPVal: Boolean. TRUE for printing p-values. FALSE by default.

• printT1: Boolean. If TRUE, t-test for H0: apollo_beta=1 are printed. FALSE by default.

• sortByDate: Boolean. If TRUE, models are ordered by date. Default is TRUE.

• tDigits: Numeric scalar. Number of decimal places to print for t-ratios values. Default is 2.

List grouping most common inputs. Created by function apollo_validateInputs.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Named numeric vector of parameters.

List grouping most common inputs. Created by function apollo_validateInputs.

List of functions

Named numeric vector of parameters.

List grouping most common inputs. Created by function apollo_validateInputs.

List of functions

Model object. Estimated model object as returned by function apollo_estimate.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• expression: Character vector. A character vector with a single or multiple arbitrary functions of the estimated parameters, as text. For example: c(VTT="b1/b2*60"). Each expression can only contain model parameters (estimated or fixed), numeric values, and operands. At least one of the parameters used needs to not have been fixed in estimation. Variables in the database cannot be included. If the user does not provide a name for an expression, then the expression itself is used in the output. If this setting is provided, then operation, parName1, parName2, multPar1 and multPar2 are ignored.

• allPairs: Logical. If set to TRUE, Delta method calculations are carried out for the ratio and difference for all pairs of parameters and returned as two separate matrices with values and t-ratios. FALSE by default.

• varcov: Character. Type of variance-covariance matrix to use in calculations. It can take values "classical", "robust" and "bootstrap". Default is "robust".

• printPVal: Logical or Scalar. TRUE or 1 for printing p-values for one-sided test, 2 for printing p-values for two-sided test, FALSE for not printing p-values. FALSE by default.

• operation: Character. Function to calculate the delta method for. See details. Not used if expression is provided.

• parName1: Character. Name of the first parameter if operation is used. See details. Not used if expression is provided.

• parName2: Character. Name of the second parameter if operation is used. See details. Not used if expression is provided.. Optional depending on operation.

• multPar1: Numeric scalar. An optional value to scale parName1. Not used if expression is provided.

• multPar2: Numeric scalar. An optional value to scale parName2. Not used if expression is provided.

Named numeric vector. Names and values for parameters.

List grouping most common inputs. Created by function apollo_validateInputs.

List of settings for the DFT model. It should contain the following elements.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• altStart: A named list with as many elements as alternatives. Each element can be a scalar or vector containing the starting preference value for the alternative.

• attrScalings: A named list with as many elements as attributes, or fewer. Each element is a factor that scale the attribute, and can be a scalar, a vector or a matrix/array. They do not need to add up to one for each observation. attrWeights and attrScalings are incompatible, and they should not be both defined for an attribute. Default is 1 for all attributes.

• attrValues: A named list with as many elements as alternatives. Each element is itself a named list of vectors of the alternative attributes for each observation (usually a column from the database). All alternatives must have the same attributes (can be set to zero if not relevant).

• attrWeights: A named list with as many elements as attributes, or fewer. Each element is the weight of the attribute, and can be a scalar, a vector with as many elements as observations, or a matrix/array if random. They should add up to one for each observation and draw (if present), and will be re-scaled if they do not. attrWeights and attrScalings are incompatible, and they should not be both defined for an attribute. Default is 1 for all attributes.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• procPars: A list containing the four DFT 'process parameters'

  • error_sd: Numeric scalar or vector. The standard deviation of the the error term in each timestep.

  • timesteps: Numeric scalar or vector. Number of timesteps to consider. Should be an integer bigger than 0.

  • phi1: Numeric scalar or vector. Sensitivity.

  • phi2: Numeric scalar or vector. Process parameter.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of settings

Character. Type of model, e.g. "mnl", "nl", "cnl", etc.

List of main inputs to the model estimation process. See apollo_validateInputs.

Boolean. TRUE for printing report related to dependent and independent variables. FALSE for not printing it. Default is TRUE.

Boolean. TRUE for printing report related to estimated parameters (e.g. model structure). FALSE for not printing it. Default is TRUE.

List of inputs of the Exploded Logit model. It shoud contain the following.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVars: List of numeric vectors. Contain choices for each position of the ranking. The list must be ordered with the best choice first, second best second, etc. It will usually be a list of columns from the database. Use value -1 if a stage does not apply for a given observations (e.g. when some individuals have shorter rankings).

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• scales: List of vectors. Scale factors of each Logit model. At least one element should be normalized to 1. If omitted, scale=1 for all positions is assumed.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of settings for the model. It includes the following.

• avail: Named list of numeric vectors. Availability of each product. Can also be called "A".

• budget: Optional numeric vector. Budget. Must be bigger that the expenditure on all inside goods. Can also be called "B".

• cost: Named list of numeric vectors. Price of each product.

• delta: Lower triangular numeric matrix, or list of lists. Complementarity/substitution parameter.

• continuousChoice: Named list of numeric vectors. Amount consumed of each inside good. Outside good must not be included. Can also be called "X".

• gamma: Named list of numeric vectors. Satiation parameter of each product.

• nRep: Scalar positive integer. Number of repetitions used when prediction

• sigma: Numeric vector or scalar. Standard deviation of the error term. Default is one.

• timeLimit: Positive scalar. Maximum amount of seconds the optimiser can spend calculating a prediction before setting it to NA.

• tol: Positive scalar. Tolerance of the prediction algorithm.

• utilities: Named list of numeric vectors (or matrices or arrays). Base utility of each product. Can also be called "V".

• utilityOutside: Numeric vector (or matrix or array). Shadow price of the budget. Must be normalised to 0 for at least one individual. Default is 0 for every observation. Can also be called "V0".

Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction"

List of settings for the model. It includes the following.

• avail: Named list of numeric vectors. Availability of each product. Can also be called "A".

• budget: Numeric vector. Budget. Must be bigger that the expenditure on all inside goods. Can also be called "B".

• continuousChoice: Named list of numeric vectors. Amount consumed of each inside good. Outside good must not be included. Can also be called "X".

• cost: Named list of numeric vectors. Price of each product.

• delta: Lower triangular numeric matrix, or list of lists. Complementarity/substitution parameter.

• gamma: Named list of numeric vectors. Satiation parameter of each product.

• nRep: Scalar positive integer. Number of repetitions used when prediction

• sigma: Numeric vector or scalar. Standard deviation of the error term. Default is one.

• timeLimit: Positive scalar. Maximum amount of seconds the optimiser can spend calculating a prediction before setting it to NA.

• tol: Positive scalar. Tolerance of the prediction algorithm.

• utilities: Named list of numeric vectors (or matrices or arrays). Base utility of each product. Can also be called "V".

• utilityOutside: Numeric vector (or matrix or array). Shadow price of the budget. Must be normalised to 0 for at least one individual. Default is 0 for every observation. Can also be called "V0".

Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction"

List of settings for the model. It includes the following.

• avail: Named list of numeric vectors. Availability of each product. Can also be called "A".

• continuousChoice: Named list of numeric vectors. Amount consumed of each inside good. Outside good must not be included. Can also be called "X".

• cost: Named list of numeric vectors. Price of each product.

• delta: Lower triangular numeric matrix, or list of lists. Complementarity/substitution parameter.

• gamma: Named list of numeric vectors. Satiation parameter of each product.

• sigma: Numeric scalar. Scale parameter.

• nIter: Vector of two positive integers. Number of maximum iterations used during prediction, for the upper and lower iterative levels.

• nRep: Scalar positive integer. Number of repetitions used when predictiong

• rawPrediction: Scalar logical. When functionality is equal to "prediction", it returns the full set of simulations. Defaults is FALSE.

• tolerance: Positive scalar Tolerance of the prediction algorithm.

• utilities: Named list of numeric vectors (or matrices or arrays). Base utility of each product. Can also be called "V".

• utilityOutside: Numeric vector (or matrix or array). Shadow price of the budget. Must be normalised to 0 for at least one individual. Default is 0 for every observation. Can also be called "V0".

Character. Either "validate", "zero_LL", "estimate", "conditionals", "raw", "output" or "prediction"

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• bgw_settings: List. Additional arguments to the BGW optimisation method. See bgw_mle for more details.

• bootstrapSE: Numeric. Number of bootstrap samples to calculate standard errors. Default is 0, meaning no bootstrap s.e. will be calculated. Number must zero or a positive integer. Only used if apollo_control$estMethod!="HB".

• bootstrapSeed: Numeric scalar (integer). Random number generator seed to generate the bootstrap samples. Only used if bootstrapSE>0. Default is 24.

• constraints: Character vector. Linear constraints on parameters to estimate. For example c('b1>0', 'b1 + 2*b2>1'). Only >, < and = can be used. Inequalities cannot be mixed with equality constraints, e.g. c(b1-b2=0, b2>0) will fail. All parameter names must be on the left side. Fixed parameters cannot go into constraints. Alternatively, constraints can be defined as in maxLik. Constraints can only be used with maximum likelihood estimation and the BFGS routine in particular.

• estimationRoutine: Character. Estimation method. Can take values "bfgs", "bgw", "bhhh", or "nr". Used only if apollo_control$HB is FALSE. Default is "bgw".

• hessianRoutine: Character. Name of routine used to calculate the Hessian of the log-likelihood function after estimation. Valid values are "analytic" (default), "numDeriv" (to use the numeric routine in package numDeric), "maxLik" (to use the numeric routine in packahe maxLik), and "none" to avoid calculating the Hessian and the covariance matrix. Only used if apollo_control$HB=FALSE.

• maxIterations: Numeric. Maximum number of iterations of the estimation routine before stopping. Used only if apollo_control$HB is FALSE. Default is 200.

• maxLik_settings: List. Additional settings for maxLik. See argument control in maxBFGS, maxBHHH and maxNM for more details. Only used for maximum likelihood estimation.

• numDeriv_method: Character. Method used for numerical differentiation when calculating the covariance matrix. Can be "Richardson" or "simple", Only used if analytic gradients are available. See argument method in grad for more details.

• numDeriv_settings: List. Additional arguments to the method used by numDeriv to calculate the Hessian. See argument method.args in grad for more details.

• printLevel: Higher values render more verbous outputs. Can take values 0, 1, 2 or 3. Ignored if apollo_control$HB is TRUE. Default is 3.

• scaleAfterConvergence: Logical. Used to increase numerical precision of convergence. If TRUE, parameters are scaled to 1 after convergence, and the estimation is repeated from this new starting values. Results are reported scaled back, so it is a transparent process for the user. Default is FALSE.

• scaleHessian: Logical. If TRUE, parameters are scaled to 1 for Hessian estimation. Default is TRUE.

• scaling: Named vector. Names of elements should match those in apollo_beta. Optional scaling for parameters. If provided, for each parameter i, (apollo_beta[i]/scaling[i]) is optimised, but scaling[i]*(apollo_beta[i]/scaling[i]) is used during estimation. For example, if parameter b3=10, while b1 and b2 are close to 1, then setting scaling = c(b3=10) can help estimation, specially the calculation of the Hessian. Reports will still be based on the non-scaled parameters.

• silent: Logical. If TRUE, no information is printed to the console during estimation. Default is FALSE.

• validateGrad: Logical. If TRUE, the analytical gradient (if used) is compared to the numerical one. Default is FALSE.

• writeIter: Logical. Writes value of the parameters in each iteration to a csv file. Works only if estimation_routine=="bfgs"|"bgw". Default is TRUE.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Options controlling the estimation process, as used for in apollo_estimate.

function (usually apollo_probabilities) inside which the name of the components are inserted.

List grouping most common inputs. Created by function apollo_validateInputs.

Logical. If TRUE, the new function will be validated before being returned

List of vectors, matrices or 3-dim arrays. Likelihood of the model components (or other object).

List grouping most common inputs. Created by function apollo_validateInputs.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• subsamples: Named list of boolean vectors. Each element of the list defines whether a given observation belongs to a given subsample (e.g. by sociodemographics).

List of inputs of the FMNL model. It should contain the following.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceShares: Named list of numeric vectors. Share allocated to each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of inputs of the FNL model. It should contain the following.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceShares: Named list of numeric vectors. Share allocated to each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• nlNests: List of numeric scalars or vectors. Lambda parameters for each nest. Elements must be named with the nest name. The lambda at the root is automatically fixed to 1 if not provided by the user.

• nlStructure: Named list of character vectors. As many elements as nests, it must include the "root". Each element contains the names of the nests or alternatives that belong to it. Element names must match those in nlNests.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

An expression or a function. It will usually be apollo_probabilities.

Function. Expressions inside it will be turned into functions. Usually apollo_probabilities or apollo_randCoeff.

Logical. Must be TRUE if f is apollo_probabilities. FALSE otherwise.

Logical. Must be TRUE if f is apollo_randCoeff. FALSE otherwise.

Logical. Must be TRUE if f is apollo_lcPars. FALSE otherwise.

Function. Usually apollo_probabilities, apollo_randCoeff, or apollo_lcPars.

Function. Usually apollo_probabilities.

Numeric scalar, vector, matrix or 3-dim array.

Boolean vector. TRUE for inserting a row from v, FALSE to insert a new row with value val.

Numeric scalar. Value that will fill new rows.

Function, expression, call or symbol to alter.

Named numeric vector with the scales. The names in these vectors determine which variables should be scaled.

Numeric scalar, vector, matrix or 3-dim array.

Boolean vector. As many elements as rows in utilities. TRUE for keeping the row. FALSE to drop it.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• classProb: List of probabilities. Allocation probability for each class. One element per class, in the same order as inClassProb.

• componentName: Character. Name given to model component (optional).

• inClassProb: List of probabilities. Conditional likelihood for each class. One element per class, in the same order as classProb.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Options controlling the EM process.

• EMmaxIterations: Numeric. Maximum number of iterations of the EM algorithm before stopping. Default is 100.

• postEM: Numeric scalar. Determines the tasks performed by this function after the EM algorithm has converged. Can take values 0, 1 or 2 only. If value is 0, only the EM algorithm will be performed, and the results will be a model object without a covariance matrix (i.e. estimates only). If value is 1, after the EM algorithm, the covariance matrix of the model will be calculated as well, and the result will be a model object with a covariance matrix. If value is 2, after the EM algorithm, the estimated parameter values will be used as starting value for a maximum likelihood estimation process, which will render a model object with a covariance matrix. Performing maximum likelihood estimation after the EM algorithm is useful, as there may be room for further improvement. Default is 2.

• silent: Boolean. If TRUE, no information is printed to the console during estimation. Default is FALSE.

• stoppingCriterion: Numeric. Convergence criterion. The EM process will stop when improvements in the log-likelihood fall below this value. Default is 10^-5.

List. Options controlling the estimation process within each EM iteration. See apollo_estimate for details.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Named numeric vector. Names and values for parameters.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Boolean. If TRUE, no information is printed to the console by the function. Default is FALSE.

Character. Name of the model to load.

data.frame. Data in long format.

List. Contains settings for this function. User input is required for all settings.

• altColumn: Character. Name of column in long data that contains the names of the alternatives (either numeric or character).

• altSpecAtts: Character vector. Names of columns in long data with attributes that vary across alternatives within an observation.

• choiceColumn: Character. Name of column in long data that contains the choice.

• idColumn: Character. Name of column in long data that contains the ID of individuals.

• obsColumn: Character. Name of column in long data that contains the observation index.

Either a character variable with the name of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate.

Either a character variable with the name of a previously estimated model, or an estimated model in memory, as returned by apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Boolean. If TRUE, no messages are printed to the terminal. FALSE by default. It overrides apollo_inputs$silent.

Boolean. If TRUE, it saves apollo_inputs to disc, and removes database and draws from the apollo_inputs in .GlobalEnv and the parent environment.

List grouping most common inputs. Created by function apollo_validateInputs.

Boolean. If true, then no information is printed to console or default output. FALSE by default.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function to calculate the log-likelihood of the model, as created by apollo_makeLogLike If provided, the value of the analytical gradient will be compared to the value of the numerical gradient as calculated using apollo_logLike and the numDeriv package. If the difference between the two is bigger than 1 that the analytical gradient is wrong and NULL will be returned.

Logical. If TRUE, it compares the value of the analytical gradient evaluated at apollo_beta against the numeric gradient (using numDeriv) at the same value. If the difference is bigger than 1 return NULL.

Named numeric vector. Names and values for (all) parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function to calculate the log-likelihood of the model, as created by apollo_makeLogLike If provided, the value of the analytical gradient will be compared to the value of the numerical gradient as calculated using apollo_logLike and the numDeriv package. If the difference between the two is bigger than 1 that the analytical gradient is wrong and NULL will be returned.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List of estimation options. It must contain at least one element called estimationRoutine defining the estimation algorithm. See apollo_estimate.

Logical. If TRUE, then apollo_inputs$draws and apollo_inputs$database are erased throughout the calling stack. Used to reduce memory usage in case of multithreading and a large database or number o draws.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alpha: Named list. Alpha parameters for each alternative, including for any outside good. As many elements as alternatives.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability.

• budget: Numeric vector. Budget for each observation.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• continuousChoice: Named list of numeric vectors. Amount of consumption of each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• cost: Named list of numeric vectors. Price of each alternative. One element per alternative, each one as long as the number of observations or a scalar. Names must match those in alternatives.

• gamma: Named list. Gamma parameters for each alternative, excluding any outside good. As many elements as inside good alternatives.

• nRep: Numeric scalar. Number of simulations of the whole dataset used for forecasting. The forecast is the average of these simulations. Default is 100.

• outside: Character. Optional name of the outside good.

• rawPrediction: Logical scalar. TRUE for prediction to be returned at the draw level (a 3-dim array). FALSE for prediction to be returned averaged across draws. Default is FALSE.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• sigma: Numeric scalar. Scale parameter of the model extreme value type I error.

• utilities: Named list. Utilities of the alternatives. Names of elements must match those in argument 'alternatives'.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alpha: Named list. Alpha parameters for each alternative, including for any outside good. As many elements as alternatives.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• budget: Numeric vector. Budget for each observation.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• continuousChoice: Named list of numeric vectors. Amount of consumption of each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• cost: Named list of numeric vectors. Price of each alternative. One element per alternative, each one as long as the number of observations or a scalar. Names must match those in alternatives.

• fastPred: Boolean scalar. TRUE to mix parameter draws with repetition draws. This is formally incorrect, but a good a approximation to the true prediction, and much faster. FALSE by default.

• gamma: Named list. Gamma parameters for each alternative, excluding any outside good. As many elements as inside good alternatives.

• nRep: Numeric scalar. Number of simulations of the whole dataset used for forecasting. The forecast is the average of these simulations. Default is 100.

• outside: Character. Optional name of the outside good.

• rawPrediction: Logical scalar. TRUE for prediction to be returned at the draw level (a 3-dim array). FALSE for prediction to be returned averaged across draws. Default is FALSE.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• sigma: Numeric scalar. Scale parameter of the model extreme value type I error.

• utilities: Named list. Utilities of the alternatives. Names of elements must match those in argument 'alternatives'.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alpha: Named list. Alpha parameters for each alternative, including for the outside good. As many elements as alternatives.

• alternatives: Character vector. Names of alternatives, elements must match the names in list 'utilities'.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• budget: Numeric vector. Budget for each observation.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• continuousChoice: Named list of numeric vectors. Amount of consumption of each alternative. One element per alternative, as long as the number of observations or a scalar. Names must match those in alternatives.

• cost: Named list of numeric vectors. Price of each alternative. One element per alternative, each one as long as the number of observations or a scalar. Names must match those in alternatives.

• gamma: Named list. Gamma parameters for each alternative, including for the outside good. As many elements as alternatives.

• mdcnevNests: Named list. Lambda parameters for each nest. Elements must be named with the nest name. The lambda at the root is fixed to 1, and therefore must be no be defined. The value of the estimated mdcnevNests parameters should be between 0 and 1 to ensure consistency with random utility maximization.

• mdcnevStructure: Numeric matrix. One row per nest and one column per alternative. Each element of the matrix is 1 if an alternative belongs to the corresponding nest.

• outside: Character. Alternative name for the outside good. Default is "outside"

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• utilities: Named list. Utilities of the alternatives. Names of elements must match those in argument 'alternatives'.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Named numeric vector. Names and values for parameters. These need to be provided in the following order. With K random parameters, K means for the underlying Normals, followed by the elements of the lower triangle of the Cholesky matrix, by row.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• EMmaxIterations: Numeric. Maximum number of iterations of the EM algorithm before stopping. Default is 100.

• postEM: Numeric scalar. Determines the tasks performed by this function after the EM algorithm has converged. Can take values 0, 1 or 2 only. If value is 0, only the EM algorithm will be performed, and the results will be a model object without a covariance matrix (i.e. estimates only). If value is 1, after the EM algorithm, the covariance matrix of the model will be calculated as well, and the result will be a model object with a covariance matrix. If value is 2, after the EM algorithm, the estimated parameter values will be used as starting value for a maximum likelihood estimation process, which will render a model object with a covariance matrix. Performing maximum likelihood estimation after the EM algorithm is useful, as there may be room for further improvement. Default is 2.

• silent: Boolean. If TRUE, no information is printed to the console during estimation. Default is FALSE.

• stoppingCriterion: Numeric. Convergence criterion. The EM process will stop when improvements in the log-likelihood fall below this value. Default is 10^-5.

• transforms: List. Optional argument, with one entry per parameter, showing the inverse transform to return from beta to the underlying Normal. E.g. if the first parameter is specified as negative logormal inside apollo_randCoeff, then the entry in transforms should be transforms[[1]]=function(x) log(-x)

List. Options controlling the estimation process within each EM iteration. See apollo_estimate for details.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Numeric. The number of draws to generate in each dimension

Numeric. The number of dimensions to generate draws in

Numeric. The number of individuals to generate draws for

List of inputs of the MNL model. It should contain the following.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs). Set to "all" by default if omitted.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Model object. Estimated model object as returned by function apollo_estimate.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• printChange: Logical. TRUE for printing difference between starting values and estimates. FALSE by default.

• printClassical: Logical. TRUE for printing classical standard errors. TRUE by default.

• printCorr: Boolean. TRUE for printing parameters correlation matrix. If printClassical=TRUE, both classical and robust matrices are printed. For Bayesian estimation, this setting is used for the covariane of random parameters. FALSE by default.

• printCovar: Boolean. TRUE for printing parameters covariance matrix. If printClassical=TRUE, both classical and robust matrices are printed. For Bayesian estimation, this setting is used for the correlation of random parameters. FALSE by default.

• printDataReport: Logical. TRUE for printing summary of choices in database and other diagnostics. FALSE by default.

• printFixed: Logical. TRUE for printing fixed parameters among estimated parameter. TRUE by default.

• printFunctions: Logical. TRUE for printing apollo_control, apollo_randCoeff (when available), apollo_lcPars (when available) and apollo_probabilities. FALSE by default.

• printHBconvergence: Boolean. TRUE for printing Geweke convergence tests. FALSE by default.

• printHBiterations: Boolean. TRUE for printing an iterations report for HB estimation. TRUE by default.

• printModelStructure: Logical. TRUE for printing model structure. TRUE by default.

• printOutliers: Logical or Scalar. TRUE for printing 20 individuals with worst average fit across observations. FALSE by default. If Scalar is given, this replaces the default of 20.

• printPVal: Logical or Scalar. TRUE or 1 for printing p-values for one-sided test, 2 for printing p-values for two-sided test, FALSE for not printing p-values. FALSE by default.

• printT1: Logical. If TRUE, t-test for H0: apollo_beta=1 are printed. FALSE by default.

Named numeric vector. Names and values for parameters.

Character vector. Names of parameters inside apollo_beta whose values should be kept constant throughout estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

Logical. If TRUE, the original and modified apollo_probabilities functions are estimated. If their results do not match, then the original functions are returned, and success is set to FALSE inside the returned list.

Logical. If TRUE, loop expansion etc are skipped.

List of inputs of the NL model. It should contain the following.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• nlNests: List of numeric scalars or vectors. Lambda parameters for each nest. Elements must be named with the nest name. The lambda at the root is automatically fixed to 1 if not provided by the user.

• nlStructure: Named list of character vectors. As many elements as nests, it must include the "root". Each element contains the names of the nests or alternatives that belong to it. Element names must match those in nlNests.

• utilities: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those in alternatives.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of arguments to the functions. It must contain the following.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• mu: Numeric scalar. Intercept of the linear model.

• outcomeNormal: Numeric vector. Dependent variable.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• sigma: Numeric scalar. Variance of error component of linear model to be estimated.

• xNormal: Numeric vector. Single explanatory variable.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of settings for the OL model. It should include the following.

• coding: Numeric or character vector. Optional argument. Defines the order of the levels in outcomeOrdered. The first value is associated with the lowest level of outcomeOrdered, and the last one with the highest value. If not provided, is assumed to be 1:(length(tau) + 1).

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• outcomeOrdered: Numeric vector. Dependent variable. The coding of this variable is assumed to be from 1 to the maximum number of different levels. For example, if the ordered response has three possible values: "never", "sometimes" and "always", then it is assumed that outcomeOrdered contains "1" for "never", "2" for "sometimes", and 3 for "always". If another coding is used, then it should be specified using the coding argument.

• rows: Boolean vector. TRUE if a row must be considered in the calculations, FALSE if it must be excluded. It must have length equal to the length of argument outcomeOrdered. Default value is "all", meaning all rows are considered in the calculation.

• tau: List of numeric vectors/matrices/3-dim arrays. Thresholds. As many as number of different levels in the dependent variable - 1. Extreme thresholds are fixed at -inf and +inf. Mixing is allowed in thresholds. Can also be a matrix with as many rows as observations and as many columns as thresholds.

• utilities: Numeric vector/matrix/3-sim array. A single explanatory variable (usually a latent variable). Must have the same number of rows as outcomeOrdered.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of settings for the OP model. It should include the following.

• coding: Numeric or character vector. Optional argument. Defines the order of the levels in outcomeOrdered. The first value is associated with the lowest level of outcomeOrdered, and the last one with the highest value. If not provided, is assumed to be 1:(length(tau) + 1).

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• outcomeOrdered: Numeric vector. Dependent variable. The coding of this variable is assumed to be from 1 to the maximum number of different levels. For example, if the ordered response has three possible values: "never", "sometimes" and "always", then it is assumed that outcomeOrdered contains "1" for "never", "2" for "sometimes", and 3 for "always". If another coding is used, then it should be specified using the coding argument.

• rows: Boolean vector. TRUE if a row must be considered in the calculations, FALSE if it must be excluded. It must have length equal to the length of argument outcomeOrdered. Default value is "all", meaning all rows are considered in the calculation.

• tau: List of numeric vectors/matrices/3-dim arrays. Thresholds. As many as number of different levels in the dependent variable - 1. Extreme thresholds are fixed at -inf and +inf. Mixing is allowed in thresholds. Can also be a matrix with as many rows as observations and as many columns as thresholds.

• utilities: Numeric vector/matrix/3-sim array. A single explanatory variable (usually a latent variable). Must have the same number of rows as outcomeOrdered.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Options controlling the estimation process. See apollo_estimate.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

nRep

Numeric scalar. Number of times a different pair of estimation and validation sets are to be extracted from the full database. Default is 30.

rmse

Character matrix with two columns. Used to calculate Root Mean Squared Error (RMSE) of prediction. The first column must contain the names of observed outcomes in the database. The second column must contain the names of the predicted outcomes as returned by apollo_prediction. If omitted or NULL, no RMSE is calculated. This only works for models with a single component.

samples

Numeric matrix or data.frame. Optional argument. Must have as many rows as observations in the database, and as many columns as number of repetitions wanted. Each column represents a re-sample, and each element must be a 0 if the observation should be assigned to the estimation sample, or 1 if the observation should be assigned to the prediction sample. If this argument is provided, then nRep and validationSize are ignored. Note that this allows sampling at the observation rather than the individual level.

validationSize

Numeric scalar. Size of the validation sample. Can be a percentage of the sample (0-1) or the number of individuals in the validation sample (>1). Default is 0.1.

List of arguments. Only likelihood is mandatory.

• gradient: Function or expression used to calculate the gradient of the likelihood. If not provided, Apollo will attempt to calculate it automatically.

• likelihood: Function or expression used to calculate the likelihood of the model. Should evaluate to a vector, matrix, or 3-dimensional array.

• prediction: Function or expression used to calculate the prediction of the model. Should evaluate to a vector, matrix, or 3-dimensional array.

• report: List of functions or expressions used to produce a text report summarising the input and parameter estimates of the model. Should contain two elements: "data" (with a summary of the input data), and "param" (with a summary of the estimated parameters).

• shares_LL: Function or expression used to calculate the likelihood of the constants-only model.

• zero_LL: Function or expression used to calculate the likelihood of the base model (e.g. equiprobable model).

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of vectors, matrices or 3-dim arrays. Likelihood of the model components.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• modelComponent: Character. Name of component of apollo_probabilities output to calculate predictions for. Default is to predict for all components.

• nRep: Scalar integer. Only used for models that require simulation for prediction (e.g. MDCEV). Number of draws used to calculate prediction. Default is 100.

• runs: Numeric. Number of runs to use for computing confidence intervals of predictions.

• silent: Boolean. If TRUE, this function won't print any output to screen.

• summary: Boolean. If TRUE, a summary of the prediction is printed to screen. TRUE by default.

Deprecated. Same as modelComponent inside prediction_settings.

List of vectors, matrices or 3-dim arrays. Likelihood of the model components.

List grouping most common inputs. Created by function apollo_validateInputs.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List of settings

Character. Type of model, e.g. "mnl", "nl", "cnl", etc.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

List grouping most common inputs. Created by function apollo_validateInputs.

Character, what to print.

Optional numeric integer. Minimum number of significant digits when printing numeric matrices. Default is 4.

Optional numeric integer. Minimum width (in characters) of each column when printing numeric matrices. Default is 11

Scalar integer. Number of seconds the execution will pause after printing the message. Default is 0.

Character. "t" for regular text (default), "w" for warning, "i" for information.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Character. modelName for model from which results are used as starting values.

Boolean. TRUE if starting values for fixed parameters should also be updated from input file.

List of inputs of the RRM model. It should contain the following.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• avail: Named list of numeric vectors or scalars. Availabilities of alternatives, one element per alternative. Names of elements must match those in alternatives. Values can be 0 or 1. These can be scalars or vectors (of length equal to rows in the database). A user can also specify avail=1 to indicate universal availability, or omit the setting completely.

• choiceset_scaling: Vector. One entry per row in the database, often set to 2 divided by the number of available alternatives.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• componentName: Character. Name given to model component. If not provided by the user, Apollo will set the name automatically according to the element in P to which the function output is directed.

• regret_inputs: Named list of regret functions. This should contain one list per attribute, where these lists themselves contain two vectors, namely a vector of attributes (at the alternative level) and parameters (either generic or attribute specific). Zeros can be used for omitted attributes for some alternatives. The order for each attribute needs to be the same as the order in alternatives..

• regret_scale: Named list of regret scales. This should have the same length as 'rrm_settings$regret_inputs' or be a single entry in the case of a generic scale parameter across regret attributes.

• rows: Boolean vector. Consideration of which rows to include. Length equal to the number of observations (nObs), with entries equal to TRUE for rows to include, and FALSE for rows to exclude. Default is "all", equivalent to rep(TRUE, nObs).

• rum_inputs: Named list of (optional) deterministic utilities. Utilities of the alternatives to be included in combined RUM-RRM models. Names of elements must match those in alternatives.

Character. Setting instructing Apollo what processing to apply to the likelihood function. This is in general controlled by the functions that call apollo_probabilities, though the user can also call apollo_probabilities manually with a given functionality for testing/debugging. Possible values are:

• "components": For further processing/debugging, produces likelihood for each model component (if multiple components are present), at the level of individual draws and observations.

• "conditionals": For conditionals, produces likelihood of the full model, at the level of individual inter-individual draws.

• "estimate": For model estimation, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "gradient": For model estimation, produces analytical gradients of the likelihood, where possible.

• "output": Prepares output for post-estimation reporting.

• "prediction": For model prediction, produces probabilities for individual alternatives and individual model components (if multiple components are present) at the level of an observation, after averaging across draws.

• "preprocess": Prepares likelihood functions for use in estimation.

• "raw": For debugging, produces probabilities of all alternatives and individual model components at the level of an observation, at the level of individual draws.

• "report": Prepares output summarising model and choiceset structure.

• "shares_LL": Produces overall model likelihood with constants only.

• "validate": Validates model specification, produces likelihood of the full model, at the level of individual decision-makers, after averaging across draws.

• "zero_LL": Produces overall model likelihood with all parameters at zero.

Model object. Estimated model object as returned by function apollo_estimate.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• printChange: Boolean. TRUE for printing difference between starting values and estimates. TRUE by default.

• printClassical: Boolean. TRUE for printing classical standard errors. TRUE by default.

• printCorr: Boolean. TRUE for printing parameters correlation matrix. If printClassical=TRUE, both classical and robust matrices are printed. For Bayesian estimation, this setting is used for the covariane of random parameters. TRUE by default.

• printCovar: Boolean. TRUE for printing parameters covariance matrix. If printClassical=TRUE, both classical and robust matrices are printed. For Bayesian estimation, this setting is used for the correlation of random parameters. TRUE by default.

• printDataReport: Boolean. TRUE for printing summary of choices in database and other diagnostics. FALSE by default.

• printFixed: Logical. TRUE for printing fixed parameters among estimated parameter. TRUE by default.

• printFunctions: Boolean. TRUE for printing apollo_control, apollo_randCoeff (when available), apollo_lcPars (when available) and apollo_probabilities. TRUE by default.

• printHBconvergence: Boolean. TRUE for printing Geweke convergence tests. TRUE by default.

• printHBiterations: Boolean. TRUE for printing an iterations report for HB estimation. TRUE by default.

• printModelStructure: Boolean. TRUE for printing model structure. TRUE by default.

• printOutliers: Boolean or Scalar. TRUE for printing 20 individuals with worst average fit across observations. FALSE by default. If Scalar is given, this replaces the default of 20.

• printPVal: Boolean or Scalar. TRUE or 1 for printing p-values for one-sided test, 2 for printing p-values for two-sided test, FALSE for not printing p-values. FALSE by default.

• printT1: Boolean. If TRUE, t-test for H0: apollo_beta=1 are printed. FALSE by default.

• saveEst: Boolean. TRUE for saving estimated parameters and standard errors to a CSV file. TRUE by default.

• saveCorr: Boolean. TRUE for saving estimated correlation matrix to a CSV file. FALSE by default.

• saveCov: Boolean. TRUE for saving estimated covariance matrix to a CSV file. FALSE by default.

• saveHBiterations: Boolean. TRUE for including HB iterations in the saved model object. FALSE by default.

• saveModelObject: Boolean. TRUE to save the R model object to a file (use apollo_loadModel to load it to memory). TRUE by default.

• saveOld: Boolean. If TRUE, existing files are kept with an added OLD suffix. If not, they are overwritten. TRUE by default.

• writeF12: Boolean. TRUE for writing results into an F12 file (ALOGIT format). FALSE by default.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• apolloBetaMax: Vector. Maximum possible value of parameters when generating candidates. Ignored if smartStart is TRUE. Default is apollo_beta + 0.1.

• apolloBetaMin: Vector. Minimum possible value of parameters when generating candidates. Ignored if smartStart is TRUE. Default is apollo_beta - 0.1.

• bfgsIter: Numeric scalar. Number od BFGS iterations to perform at each stage to each remaining candidate. Default is 20.

• dTest: Numeric scalar. Tolerance for test 1. A candidate is discarded if its distance in parameter space to a better one is smaller than dTest. Default is 1.

• gTest: Numeric scalar. Tolerance for test 2. A candidate is discarded if the norm of its gradient is smaller than gTest AND its LL is further than llTest from a better candidate. Default is 10^(-3).

• llTest: Numeric scalar. Tolerance for test 2. A candidate is discarded if the norm of its gradient is smaller than gTest AND its LL is further than llTest from a better candidate. Default is 3.

• maxStages: Numeric scalar. Maximum number of search stages. The algorithm will stop when there is only one candidate left, or if it reaches this number of stages. Default is 5.

• nCandidates: Numeric scalar. Number of candidate sets of parameters to be used at the start. Should be an integer bigger than 1. Default is 100.

• smartStart: Boolean. If TRUE, candidates are randomly generated with more chances in the directions the Hessian indicates improvement of the LL function. Default is FALSE.

Numeric scalar, vector, matrix or 3-dim array. Rows of this object will be replaced by val and

Boolean vector. As many elements as rows in utilities. TRUE for replacing that row, FALSE for not changing it.

Numeric scalar. Value to which the specified rows must be set to.

Model object. Estimated model object as returned by function apollo_estimate.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• alternatives: Named numeric vector. Names of alternatives and their corresponding value in choiceVar.

• choiceVar: Numeric vector. Contains choices for all observations. It will usually be a column from the database. Values are defined in alternatives.

• modelComponent: Name of model component. Set to model by default.

• newAlts: Optional list describing the new alternatives to be used by apollo_sharesTest. This should have as many elements as new alternatives, with each entry being a matrix of 0-1 entries, with one row per observation, and one column per alternative used in the model.

• newAltsOnly: Boolean. If TRUE, results will only be printed for the 'new' alternatives defined in newAlts, not the original alternatives used in the model. Set to FALSE by default.

• subsamples: Named list of boolean vectors. Each element of the list defines whether a given observation belongs to a given subsample (e.g. by sociodemographics).

List grouping most common inputs. Created by function apollo_validateInputs. If not provided, it will be looked for in the global environment.

Named numeric vector. Names and values for parameters.

Character vector. Names (as defined in apollo_beta) of parameters whose value should not change during estimation.

Function. Returns probabilities of the model to be estimated. Must receive three arguments:

• apollo_beta: Named numeric vector. Names and values of model parameters.

• apollo_inputs: List containing options of the model. See apollo_validateInputs.

• functionality: Character. Can be either "components", "conditionals", "estimate" (default), "gradient", "output", "prediction", "preprocess", "raw", "report", "shares_LL", "validate" or "zero_LL".

List grouping most common inputs. Created by function apollo_validateInputs.

List. Contains settings for this function. User input is required for all settings except those with a default or marked as optional.

• nCoresTry: Numeric vector. Number of threads to try. Default is from 1 to the detected number of cores.

• nDrawsTry: Numeric vector. Number of inter and intra-person draws to try. Default value is c(50, 100, 200).

• nRep: Numeric scalar. Number of times the likelihood is evaluated for each combination of threads and draws. Default is 10.