apollo_op: Calculates the probability of an ordered probit model
In byu-transpolab/apollo-byu: Tools for Choice Model Estimation and Application

Description Usage Arguments Details Value

Calculates the probabilities of an ordered probit model and can also perform other operations based on the value of the functionality argument.

1	apollo_op(op_settings, functionality)

op_settings

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

outcomeOrdered Numeric vector. Dependant 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.
V Numeric vector/matrix/3-sim array. A single explanatory variable (usually a latent variable). Must have the same number of rows as outcomeOrdered.
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.
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).
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.
componentName Character. Name given to model component.

functionality

Character. Can take different values depending on desired output.

"estimate" Used for model estimation.
"prediction" Used for model predictions.
"validate" Used for validating input.
"zero_LL" Used for calculating null likelihood.n Not implemented for ordered probit.
"conditionals" Used for calculating conditionals.
"output" Used for preparing output after model estimation.
"raw" Used for debugging.

This function estimates an ordered probit model of the type:

y^{*} = V + ε \\ y = 1 if -∞ < y^{*} < τ_1, 2 if τ_1 < y^{*} < τ_2, ..., max(y) if τ_{max(y)-1} < y^{*} < ∞

Where ε is distributed standard normal, and the values 1, 2, ..., max(y) can be replaced by coding[1], coding[2], ..., coding[maxLvl]. The behaviour of the function changes depending on the value of the functionality argument.

The returned object depends on the value of argument functionality as follows.

"estimate": vector/matrix/array. Returns the probabilities for the chosen alternative for each observation.
"prediction": List of vectors/matrices/arrays. Returns a list with the probabilities for all possible levels, with an extra element for the probability of the chosen alternative.
"validate": Same as "estimate", but it also runs a set of tests to validate the function inputs.
"zero_LL": Not implemented. Returns a vector of NA with as many elements as observations.
"conditionals": Same as "estimate"
"output": Same as "estimate" but also writes summary of input data to internal Apollo log.
"raw": Same as "prediction"