apollo_op {apollo} | R Documentation |
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.
[Package
apollo version 0.3.3
Index]