apollo_op {apollo}

Calculates Ordered Probit probabilities

Description

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

Usage

apollo_op(op_settings, functionality)

Arguments

op_settings

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.

functionality

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.

Details

This function estimates an ordered probit model of the type:

y^{*} = V + \epsilon \\ y = 1 if -\infty < y^{*} < \tau_1, 2 if \tau_1 < y^{*} < \tau_2, ..., max(y) if \tau_{max(y)-1} < y^{*} < \infty

Where \epsilon 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.

Value

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

• "components": Same as "estimate"

• "conditionals": Same as "estimate"

• "estimate": vector/matrix/array. Returns the probabilities for the chosen alternative for each observation.

• "gradient": List containing the likelihood and gradient of the model component.

• "output": Same as "estimate" but also writes summary of input data to internal Apollo log.

• "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.

• "preprocess": Returns a list with pre-processed inputs, based on op_settings.

• "raw": Same as "prediction"

• "report": Dependent variable overview.

• "shares_LL": vector/matrix/array. Returns the probability of the chosen alternative when only constants are estimated.

• "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.