apollo (version 0.1.0)

apollo_cnl: Calculates probabilities of a cross nested logit

Description

Calculates probabilities of a cross nested logit model.

Usage

apollo_cnl(cnl_settings, functionality)

Arguments

cnl_settings

List of inputs of the CNL 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.

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

• V: Named list of deterministic utilities . Utilities of the alternatives. Names of elements must match those 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.

• rows: Boolean vector. Consideration of rows in the likelihood calculation, FALSE to exclude. Length equal to the number of observations (nObs). Default is "all", equivalent to rep(TRUE, nObs).

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

• "conditionals": Used for calculating conditionals.

• "output": Used for preparing output after model estimation.

• "raw": Used for debugging.

Value

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 alternatives, with an extra element for the chosen alternative probability.

• "validate": Same as "estimate"

• "zero_LL": vector/matrix/array. Returns the probability of the chosen alternative when all parameters are zero.

• "conditionals": Same as "estimate"

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

• "raw": Same as "prediction"

Details

For the model to be consistent with utility maximisation, the estimated value of the lambda parameter of all nests should be between 0 and 1. Lambda parameters are inversely proportional to the correlation between the error terms of alternatives in a nest. If lambda=1, there is no relevant correlation between the unobserved utility of alternatives in that nest. The tree must contain an upper nest called "root". The lambda parameter of the root is automatically set to 1 if not specified in nlNests. And while setting it to another value is possible, it is not recommended. Alpha parameters inside cnlStructure should be between 0 and 1. Using a transformation to ensure this constraint is satisfied is recommended (e.g. logistic transformation).

Examples

# NOT RUN {
### Load data
data(apollo_modeChoiceData)
database <- apollo_modeChoiceData
rm(apollo_modeChoiceData)

### Parameters
b = list(asc_1=0, asc_2=0, asc_3=0, asc_4=0, tt=0, tc=0, acc=0,
         lambda_fastPT=0.5, lambda_groundPT=0.5, alpha_rail_fastPT=0.5)

### List of utilities
V = list()
V[['car' ]] = b$asc_1 + b$tt*database$time_car  + b$tc*database$cost_car
V[['bus' ]] = b$asc_2 + b$tt*database$time_bus  + b$tc*database$cost_bus  +
              b$acc*database$access_bus
V[['air' ]] = b$asc_3 + b$tt*database$time_air  + b$tc*database$cost_air  +
              b$acc*database$access_air
V[['rail']] = b$asc_4 + b$tt*database$time_rail + b$tc*database$cost_rail +
              b$acc*database$access_rail

cnlStructure     = matrix(0, nrow=3, ncol=4)
cnlStructure[1,] = c( 0,  0, 1, b$alpha_rail_fastPT  ) # fastPT
cnlStructure[2,] = c( 0,  1, 0, 1-b$alpha_rail_fastPT) # groundPT
cnlStructure[3,] = c( 1,  0, 0, 0                    ) # car

### CNL settings
cnl_settings <- list(
    alternatives = c(car=1, bus=2, air=3, rail=4),
    avail        = list(car=database$av_car, bus=database$av_bus,
                        air=database$av_air, rail=database$av_rail),
    choiceVar    = database$choice,
    V            = V,
    cnlNests     = list(fastPT=b$lambda_fastPT, groundPT=b$lambda_groundPT, car=1),
    cnlStructure = cnlStructure
)

### Compute choice probabilities using CNL model
apollo_cnl(cnl_settings, functionality="estimate")
# }