Larch Tool API#
activitysim.estimation.larch.general#
- activitysim.estimation.larch.general.apply_coef_template(linear_utility, template_col, condition=None)#
Apply a coefficient template over a linear utility function.
- Parameters:
- linear_utilityLinearFunction_C
- template_colMapping
- conditionany
- Returns:
- LinearFunction_C
- activitysim.estimation.larch.general.apply_coefficients(coefficients, model, minimum=None, maximum=None)#
Read the coefficients CSV file to a DataFrame and set model parameters.
- Parameters:
- coefficientspandas.DataFrame
The coefficients table in the ActivitySim data bundle for this model.
- modelModel
Apply coefficient values and constraints to this model.
- activitysim.estimation.larch.general.clean_values(values, choice_col='override_choice', alt_names_to_codes=None, choice_code='override_choice_code')#
- Parameters:
- valuespd.DataFrame
- alt_namesCollection
- override_choicestr
The columns of values containing the observed choices.
- alt_names_to_codesMapping, optional
If the override_choice column contains alternative names, use this mapping to convert the names into alternative code numbers.
- choice_codestr, default ‘override_choice_code’
The name of the observed choice code number column that will be added to values.
- Returns:
- pd.DataFrame
- activitysim.estimation.larch.general.construct_nesting_tree(alternatives, nesting_settings)#
Construct a NestingTree from ActivitySim settings.
- Parameters:
- alternativesMapping or Sequence
If given as a Mapping (dict), the keys are the alternative names as strings, and the values are alternative code numbers to use in larch. If given as a Sequence, the values are the alternative names, and unique sequential codes will be created starting from 1.
- nesting_settingsMapping
The ‘NESTS’ section of the ActivitySim config file.
- Returns:
- NestingTree
- activitysim.estimation.larch.general.cv_to_ca(alt_values, dtype='float64', required_labels=None)#
Convert a choosers-variables DataFrame to an idca DataFrame.
- Parameters:
- alt_valuespandas.DataFrame
This DataFrame should be in choosers-variables format, with one row per chooser and variable, and one column per alternative. The id’s for the choosers and variables must be in that order, in a two-level MultiIndex.
- dtypedtype
Convert the incoming data to this type. Set to None to skip data conversion.
- required_labelsCollection, optional
If given, any columns in the output that are not required will be pre-emptively dropped.
- Returns:
- pandas.DataFrame
The resulting DataFrame is transformed into Larch’s idca format, with one row per chooser (case) and alternative, and one column per variable.
- activitysim.estimation.larch.general.dict_of_linear_utility_from_spec(spec, x_col, p_col, ignore_x=(), x_validator=None, expr_col=None)#
Create a linear function from a spec DataFrame.
- Parameters:
- specpandas.DataFrame
A spec for an ActivitySim model.
- x_col: str
The name of the columns in spec representing the data.
- p_col: dict
The name of the columns in spec representing the parameters. The keys give the names of the columns to use, and the values will become the keys of the output dictionary.
- ignore_xCollection, optional
Labels in the spec file to ignore. Typically this includes variables that are pre-processed by ActivitySim and therefore don’t need to be made available in Larch.
- segment_idstr, optional
The CHOOSER_SEGMENT_COLUMN_NAME identified for ActivitySim. This value is ignored if p_col is a string, and required if p_col is a dict.
- x_validatorContainer, optional
A container of valid values for the x_col. If given, the x_col values will be used if they are in the x_validator, otherwise the value from expr_col will be used.
- expr_colstr, optional
The name of the column to use when the x_col value is not in the x_validator.
- Returns:
- dict
- activitysim.estimation.larch.general.explicit_value_parameters(model)#
Define and lock parameters given as fixed values.
- Parameters:
- modellarch.Model
The model to insert fixed value parameters.
- Returns:
- activitysim.estimation.larch.general.explicit_value_parameters_from_spec(spec, p_col, model)#
Define and lock parameters given as fixed values in the spec.
- Parameters:
- specpandas.DataFrame
A spec for an ActivitySim model.
- p_colstr or dict
The name of the columns in spec representing the parameters. Give as a string for a single column, or as a dict to have segments on multiple columns. If given as a dict, the keys give the names of the columns to use, and the values give the identifiers that will need to match the loaded segment_id value. Only the keys are used in this function.
- modellarch.Model
The model to insert fixed value parameters.
- Returns:
- activitysim.estimation.larch.general.linear_utility_from_spec(spec, x_col, p_col, ignore_x=(), segment_id=None, x_validator=None, expr_col=None)#
Create a linear function from a spec DataFrame.
- Parameters:
- specpandas.DataFrame
A spec for an ActivitySim model.
- x_col: str
The name of the columns in spec representing the data.
- p_col: str or dict
The name of the columns in spec representing the parameters. Give as a string for a single column, or as a dict to have segments on multiple columns. If given as a dict, the keys give the names of the columns to use, and the values give the identifiers that will need to match the loaded segment_id value.
- ignore_xCollection, optional
Labels in the spec file to ignore. Typically this includes variables that are pre-processed by ActivitySim and therefore don’t need to be made available in Larch.
- segment_idstr, optional
The CHOOSER_SEGMENT_COLUMN_NAME identified for ActivitySim. This value is ignored if p_col is a string, and required if p_col is a dict.
- x_validatorContainer, optional
A container of valid values for the x_col. If given, the x_col values will be used if they are in the x_validator, otherwise the value from expr_col will be used.
- expr_colstr, optional
The name of the column to use when the x_col value is not in the x_validator.
- Returns:
- LinearFunction_C
- activitysim.estimation.larch.general.prevent_overlapping_column_names(x_ca, x_co)#
Rename columns in idca data to prevent overlapping names.
- Parameters:
- x_ca, x_copandas.DataFrame
The idca and idco data, respectively
- Returns:
- x_ca, x_co
- activitysim.estimation.larch.general.remove_apostrophes(df, from_columns=None)#
Remove apostrophes from columns names and from data in given columns.
Also strips leading and trailing whitespace.
This function operates in-place on DataFrames.
- Parameters:
- dfpandas.DataFrame
- from_columnsCollection, optional
- Returns:
- pandas.DataFrame
activitysim.estimation.larch.data_maker#
activitysim.estimation.larch.simple_simulate#
- class activitysim.estimation.larch.simple_simulate.SimpleSimulateData(edb_directory, settings, chooser_data, coefficients, coef_template, spec, alt_names, alt_codes, alt_names_to_codes, alt_codes_to_names)#
- alt_codes#
Alias for field number 7
- alt_codes_to_names#
Alias for field number 9
- alt_names#
Alias for field number 6
- alt_names_to_codes#
Alias for field number 8
- chooser_data#
Alias for field number 2
- coef_template#
Alias for field number 4
- coefficients#
Alias for field number 3
- edb_directory#
Alias for field number 0
- settings#
Alias for field number 1
- spec#
Alias for field number 5
- activitysim.estimation.larch.simple_simulate.construct_availability(model, chooser_data, alt_codes_to_names)#
Construct an availability dataframe based on -999 parameters.
- Parameters:
- modellarch.Model
- chooser_datapandas.DataFrame
- alt_codes_to_namesMapping[int,str]
- Returns:
- pandas.DataFrame
activitysim.estimation.larch.cdap#
- activitysim.estimation.larch.cdap.apply_replacements(expression, prefix, tokens)#
Convert general person terms to specific person terms for the CDAP model.
- Parameters:
- expressionstr
An expression from the “Expression” column of cdap_INDIV_AND_HHSIZE1_SPEC.csv, or similar.
- prefixstr
A prefix to attach to each token in expression.
- tokenslist-like of str
A list of tokens to edit within an expression.
- Returns:
- expressionstr
The modified expression
- activitysim.estimation.larch.cdap.cdap_base_utility_by_person(model, n_persons, spec, alts=None, value_tokens=(), add_joint=False)#
Build the base utility by person for each pattern.
- Parameters:
- modellarch.Model
- n_personsint
- specpandas.DataFrame
The base utility by person spec provided by the ActivitySim framework.
- altsdict, optional
The keys are the names of the patterns, and the values are the alternative code numbers, as created by generate_alternatives. If not given, the alts are automatically regenerated using that function.
- value_tokenslist-like of str, optional
A list of tokens to edit within an the expressions, generally the column names of the provided values from the estimation data bundle. Only used when n_persons is more than 1.
- activitysim.estimation.larch.cdap.cdap_joint_tour_utility(model, n_persons, alts, joint_coef, values)#
FIXME: Not fully implemented!!!!
Code is adapted from the cdap model in ActivitySim with the joint tour component Structure is pretty much in place, but dependencies need to be filtered out.
- activitysim.estimation.larch.cdap.generate_alternatives(n_persons, add_joint=False)#
Generate a dictionary of CDAP alternatives.
The keys are the names of the patterns, and the values are the alternative code numbers.
- Parameters:
- n_personsint
- Returns:
- Dict
- activitysim.estimation.larch.cdap.interact_pattern(n_persons, select_persons, tag)#
Compile a regex pattern to match CDAP alternatives.
- Parameters:
- n_personsint
- select_personslist-like of int
The persons to be selected.
- tagstr
The activity letter, currently one of {M,N,H}.
- Returns:
- re.compile
activitysim.estimation.larch.location_choice#
- class activitysim.estimation.larch.location_choice.LocationChoiceData(edb_directory, alt_values, chooser_data, coefficients, landuse, spec, size_spec, master_size_spec, model_selector, settings)#
- alt_values#
Alias for field number 1
- chooser_data#
Alias for field number 2
- coefficients#
Alias for field number 3
- edb_directory#
Alias for field number 0
- landuse#
Alias for field number 4
- master_size_spec#
Alias for field number 7
- model_selector#
Alias for field number 8
- settings#
Alias for field number 9
- size_spec#
Alias for field number 6
- spec#
Alias for field number 5
- activitysim.estimation.larch.location_choice.location_choice_model(name='workplace_location', edb_directory='output/estimation_data_bundle/{name}/', coefficients_file='{name}_coefficients.csv', spec_file='{name}_SPEC.csv', size_spec_file='{name}_size_terms.csv', alt_values_file='{name}_alternatives_combined.csv', chooser_file='{name}_choosers_combined.csv', settings_file='{name}_model_settings.yaml', landuse_file='{name}_landuse.csv', return_data=False, alt_values_to_feather=False, chunking_size=None, *, alts_in_cv_format=False, availability_expression=None) Model | tuple[larch.model.jaxmodel.Model, LocationChoiceData]#
Construct a location choice model from the estimation data bundle.
- Parameters:
- namestr, optional
The name of the location choice model. The default is “workplace_location”.
- edb_directorystr, optional
The directory containing the estimation data bundle. The default is “output/estimation_data_bundle/{name}/”, where “{name}” is the name of the model (see above).
- coefficients_filestr, optional
The name of the coefficients file. The default is “{name}_coefficients.csv”, where “{name}” is the name of the model (see above).
- spec_filestr, optional
The name of the spec file. The default is “{name}_SPEC.csv”, where “{name}” is the name of the model (see above).
- size_spec_filestr, optional
The name of the size spec file. The default is “{name}_size_terms.csv”, where “{name}” is the name of the model (see above).
- alt_values_filestr, optional
The name of the alternative values file. The default is “{name}_alternatives_combined.csv”, where “{name}” is the name of the model (see above).
- chooser_filestr, optional
The name of the chooser file. The default is “{name}_choosers_combined.csv”, where “{name}” is the name of the model (see above).
- settings_filestr, optional
The name of the settings file. The default is “{name}_model_settings.yaml”, where “{name}” is the name of the model (see above).
- landuse_filestr, optional
The name of the land use file. The default is “{name}_landuse.csv”, where “{name}” is the name of the model (see above).
- return_databool, optional
If True, return a tuple containing the model and the location choice data. The default is False, which returns only the model.
- alt_values_to_featherbool, default False
If True, convert the alternative values to a feather file.
- chunking_sizeint, optional
The number of rows per chunk for processing the alternative values. The default is None, which processes all rows at once.
- alts_in_cv_formatbool, default False
If True, the alternatives are in CV format. The default is False.
- availability_expressionstr, optional
The name of the availability expression. This is the “Label” from the spec file that identifies an expression that evaluates truthy (non-zero) if the alternative is available, and falsey otherwise. If not provided, the code will attempt to infer the availability expression from the expressions, but this is not reliable. The default is None.
- activitysim.estimation.larch.nonmand_tour_freq.nonmand_tour_freq_model(edb_directory='output/estimation_data_bundle/{name}/', return_data=False, condense_parameters=False, segment_subset=(), num_chunks=1, *, alts_in_cv_format=False)#
Prepare nonmandatory tour frequency models for estimation.
- Parameters:
- edb_directorystr
Location of estimation data bundle for these models.
- return_databool, default False
Whether to return the data used in preparing this function. If returned, data is a dict in the second return value.
- condense_parametersbool, default False
Apply a transformation whereby all parameters in each model that have the same initial value are converted to have the same name (and thus to be the same parameter, used in various places).
- activitysim.estimation.larch.scheduling.construct_availability_ca(model, chooser_data, alt_codes_to_names)#
Construct an availability dataframe based on -999 parameters.
- Parameters:
- modellarch.Model
- chooser_datapandas.DataFrame
- alt_codes_to_namesMapping[int,str]
- Returns:
- pandas.DataFrame