School Location#

The usual school location choice models assign a usual school location for the primary mandatory activity of each child and university student in the synthetic population. The models are composed of a set of accessibility-based parameters (including one-way distance between home and primary destination and the tour mode choice logsum - the expected maximum utility in the mode choice model which is given by the logarithm of the sum of exponentials in the denominator of the logit formula) and size terms, which describe the quantity of grade-school or university opportunities in each possible destination.

The school location model is made up of four steps:

  • sampling - selects a sample of alternative school locations for the next model step. This selects X locations from the full set of model zones using a simple utility.

  • logsums - starts with the table created above and calculates and adds the mode choice logsum expression for each alternative school location.

  • simulate - starts with the table created above and chooses a final school location, this time with the mode choice logsum included.

  • shadow prices - compare modeled zonal destinations to target zonal size terms and calculate updated shadow prices.

These steps are repeated until shadow pricing convergence criteria are satisfied or a max number of iterations is reached. See shadow_pricing.

School location choice for multiple_zone_systems models uses presampling by default.

The main interfaces to the model is the school_location function. This function is registered as an Inject step in the example Pipeline. writing_logsums for how to write logsums for estimation.

Structure#

  • Configuration File: school_location.yaml

  • Core Table: persons

  • Result Field: school_taz

  • School Location - Skims Keys: TAZ, alt_dest, AM time period, MD time period

Configuration#

settings activitysim.abm.models.location_choice.TourLocationComponentSettings#
Config:

  • extra: str = forbid

Fields:

  • ALT_DEST_COL_NAME (str)

  • CHOOSER_FILTER_COLUMN_NAME (str | None)

  • CHOOSER_ID_COLUMN (str)

  • CHOOSER_ORIG_COL_NAME (str)

  • CHOOSER_SEGMENT_COLUMN_NAME (str | None)

  • CHOOSER_TABLE_NAME (str | None)

  • COEFFICIENTS (Path | None)

  • CONSTANTS (dict[str, Any])

  • DEST_CHOICE_COLUMN_NAME (str | None)

  • DEST_CHOICE_LOGSUM_COLUMN_NAME (str | None)

  • DEST_CHOICE_SAMPLE_TABLE_NAME (str | None)

  • ESTIMATION_SAMPLE_SIZE (int)

  • IN_PERIOD (int | dict[str, int] | None)

  • LOGSUM_PREPROCESSOR (str)

  • LOGSUM_SETTINGS (Path | None)

  • LOGSUM_TOUR_PURPOSE (str | dict[str, str] | None)

  • MODELED_SIZE_TABLE (str | None)

  • MODEL_SELECTOR (str | None)

  • MODE_CHOICE_LOGSUM_COLUMN_NAME (str | None)

  • ORIG_ZONE_ID (str | None)

  • OUT_PERIOD (int | dict[str, int] | None)

  • SAMPLE_SIZE (int)

  • SAMPLE_SPEC (Path)

  • SAVED_SHADOW_PRICE_TABLE_NAME (str | None)

  • SEGMENTS (list[str] | None)

  • SEGMENT_IDS (dict[str, int] | dict[str, str] | dict[str, bool] | None)

  • SHADOW_PRICE_TABLE (str | None)

  • SIMULATE_CHOOSER_COLUMNS (list[str] | None)

  • SIZE_TERM_SELECTOR (str | None)

  • SPEC (Path)

  • alts_preprocessor_sample (PreprocessorSettings | None)

  • alts_preprocessor_simulate (PreprocessorSettings | None)

  • annotate_households (PreprocessorSettings | None)

  • annotate_persons (PreprocessorSettings | None)

  • annotate_tours (PreprocessorSettings | None)

  • annotate_trips (PreprocessorSettings | None)

  • annotate_vehicles (PreprocessorSettings | None)

  • compute_settings (ComputeSettings)

  • explicit_chunk (float)

  • preprocessor (PreprocessorSettings | list[PreprocessorSettings] | None)

  • source_file_paths (list[Path])

Validators:

field ALT_DEST_COL_NAME: str [Required]#
Validated by:

  • update_sharrow_skip

field CHOOSER_FILTER_COLUMN_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field CHOOSER_ID_COLUMN: str = 'person_id'#
Validated by:

  • update_sharrow_skip

field CHOOSER_ORIG_COL_NAME: str [Required]#
Validated by:

  • update_sharrow_skip

field CHOOSER_SEGMENT_COLUMN_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field CHOOSER_TABLE_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field COEFFICIENTS: Path | None = None#

Coefficients filename.

This is a CSV file giving named parameters for use in the utility expression. If it is not provided, then it is assumed that all model coefficients are given explicitly in the SPEC as numerical values instead of named parameters. This is perfectly acceptable for use with ActivitySim for typical simulation applications, but may be problematic if used with “estimation mode”.

Validated by:

  • update_sharrow_skip

field CONSTANTS: dict[str, Any] = {}#

Named constants usable in the utility expressions.

Validated by:

  • update_sharrow_skip

field DEST_CHOICE_COLUMN_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field DEST_CHOICE_LOGSUM_COLUMN_NAME: str | None = None#

Column name for logsum calculated across all sampled destinations.

Validated by:

  • update_sharrow_skip

field DEST_CHOICE_SAMPLE_TABLE_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field ESTIMATION_SAMPLE_SIZE: int = -1#

The number of alternatives to sample for estimation mode. If zero, then all alternatives are used. If negative, then the regular SAMPLE_SIZE is used. Truth alternative will be included in the sample.

Validated by:

  • update_sharrow_skip

field IN_PERIOD: int | dict[str, int] | None = None#
Validated by:

  • update_sharrow_skip

field LOGSUM_PREPROCESSOR: str = 'preprocessor'#
Validated by:

  • update_sharrow_skip

field LOGSUM_SETTINGS: Path | None = None#

Settings for the logsum computation. If None, no logsum is computed and logsum field is populated with zeros.

Validated by:

  • update_sharrow_skip

field LOGSUM_TOUR_PURPOSE: str | dict[str, str] | None = None#
Validated by:

  • update_sharrow_skip

field MODELED_SIZE_TABLE: str | None = None#
Validated by:

  • update_sharrow_skip

field MODEL_SELECTOR: str | None = None#
Validated by:

  • update_sharrow_skip

field MODE_CHOICE_LOGSUM_COLUMN_NAME: str | None = None#

Column name for logsum calculated across all sampled modes to selected destination.

Validated by:

  • update_sharrow_skip

field ORIG_ZONE_ID: str | None = None#

This setting appears to do nothing…

Validated by:

  • update_sharrow_skip

field OUT_PERIOD: int | dict[str, int] | None = None#
Validated by:

  • update_sharrow_skip

field SAMPLE_SIZE: int [Required]#

This many candidate alternatives will be sampled for each choice.

Validated by:

  • update_sharrow_skip

field SAMPLE_SPEC: Path [Required]#

The utility spec giving expressions to use in alternative sampling.

Validated by:

  • update_sharrow_skip

field SAVED_SHADOW_PRICE_TABLE_NAME: str | None = None#
Validated by:

  • update_sharrow_skip

field SEGMENTS: list[str] | None = None#
Validated by:

  • update_sharrow_skip

field SEGMENT_IDS: dict[str, int] | dict[str, str] | dict[str, bool] | None = None#
Validated by:

  • update_sharrow_skip

field SHADOW_PRICE_TABLE: str | None = None#
Validated by:

  • update_sharrow_skip

field SIMULATE_CHOOSER_COLUMNS: list[str] | None = None#
Validated by:

  • update_sharrow_skip

field SIZE_TERM_SELECTOR: str | None = None#
Validated by:

  • update_sharrow_skip

field SPEC: Path [Required]#

Utility specification filename.

This is sometimes alternatively called the utility expressions calculator (UEC). It is a CSV file giving all the functions for the terms of a linear-in-parameters utility expression.

Validated by:

  • update_sharrow_skip

field alts_preprocessor_sample: PreprocessorSettings | None = None#

Alternatives preprocessor settings to use when sampling alternatives.

Validated by:

  • update_sharrow_skip

field alts_preprocessor_simulate: PreprocessorSettings | None = None#

Alternatives preprocessor settings to use when simulating choices.

Validated by:

  • update_sharrow_skip

field annotate_households: PreprocessorSettings | None = None#

Annotate households output tables with additional columns.

These settings are used to add additional columns to the output tables after the logit model is run. They are typically used to add additional attributes that are derived from the model results.

Validated by:

  • update_sharrow_skip

field annotate_persons: PreprocessorSettings | None = None#

Annotate persons output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_tours: PreprocessorSettings | None = None#

Annotate tours output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_trips: PreprocessorSettings | None = None#

Annotate trips output tables with additional columns.

Validated by:

  • update_sharrow_skip

field annotate_vehicles: PreprocessorSettings | None = None#

Annotate vehicles output tables with additional columns.

Validated by:

  • update_sharrow_skip

field compute_settings: ComputeSettings = ComputeSettings(sharrow_skip=False, fastmath=True, use_bottleneck=None, use_numexpr=None, use_numba=None, drop_unused_columns=True, protect_columns=[], performance_log=None)#

Sharrow settings for this component.

Validated by:

  • update_sharrow_skip

field explicit_chunk: float = 0#

If > 0, use this chunk size instead of adaptive chunking. If less than 1, use this fraction of the total number of rows.

Validated by:

  • update_sharrow_skip

field preprocessor: PreprocessorSettings | list[PreprocessorSettings] | None = None#

Chooser preprocessor settings.

This is a set of expressions to be evaluated on the choosers before the logit model is run. It is used to prepare the choosers for the logit model by adding columns that are used in the utility expressions.

Validated by:

  • update_sharrow_skip

field source_file_paths: list[Path] = None#

A list of source files from which these settings were loaded.

This value should not be set by the user within the YAML settings files, instead it is populated as those files are loaded. It is primarily provided for debugging purposes, and does not actually affect the operation of any model.

Validated by:

  • update_sharrow_skip

Examples#

Implementation#

activitysim.abm.models.location_choice.school_location(state: State, persons_merged: DataFrame, persons: DataFrame, households: DataFrame, network_los: Network_LOS, locutor: bool, model_settings: TourLocationComponentSettings | None = None, model_settings_file_name: str = 'school_location.yaml', trace_label: str = 'school_location') → None#

School location choice model

iterate_location_choice adds location choice column and annotations to persons table

On this page

This Page