From 1866330545de1ee30997a06db9372966a567b5aa Mon Sep 17 00:00:00 2001 From: navsarmajs Date: Fri, 27 Oct 2023 13:06:17 -0600 Subject: [PATCH 01/16] updated documentation for few models --- docs/dev-guide/components/initialize_los.md | 31 +++++++++++++ .../components/transit_pass_ownership.md | 46 +++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 docs/dev-guide/components/initialize_los.md create mode 100644 docs/dev-guide/components/transit_pass_ownership.md diff --git a/docs/dev-guide/components/initialize_los.md b/docs/dev-guide/components/initialize_los.md new file mode 100644 index 000000000..658219ba7 --- /dev/null +++ b/docs/dev-guide/components/initialize_los.md @@ -0,0 +1,31 @@ +(component-initialize-los)= +# Initialize LOS + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize_los +``` + +The initialize LOS model isn't really a model, but rather a series of data processing steps in the data pipeline. +The initialize LOS model does two things: + + * Loads skims and cache for later if desired + * Loads network LOS inputs for transit virtual path building (see :ref:`transit_virtual_path_builder`), pre-computes tap-to-tap total utilities and cache for later if desired + + +The main interface to the initialize LOS step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_los` +function. The main interface to the initialize TVPB step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_tvpb` + +function. These functions are registered as Inject steps in the example Pipeline. + + + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_los +``` diff --git a/docs/dev-guide/components/transit_pass_ownership.md b/docs/dev-guide/components/transit_pass_ownership.md new file mode 100644 index 000000000..c67398ed0 --- /dev/null +++ b/docs/dev-guide/components/transit_pass_ownership.md @@ -0,0 +1,46 @@ +(component-transit-pass-ownership)= +# Transit Pass Ownership + + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.transit_pass_ownership +``` + +The transit fare discount is defined as persons who purchase or are +provided a transit pass. The transit fare discount consists of two submodels - this +transit pass ownership model and a person :ref:`transit_pass_subsidy` model. The +result of this model can be used to condition downstream models such as the tour and trip +mode choice models via fare discount adjustments. + +The main interface to the transit pass ownership model is the +:py:func:`~activitysim.abm.models.transit_pass_ownership` function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `transit_pass_ownership.yaml` +- *Core Table*: `persons` +- *Result Field*: `transit_pass_ownership` +- *Skim Keys*: NA + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: FreeParkingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: transit_pass_ownership +``` From 2b667d1127f1ef339f25d153f8f38e3ffd828670 Mon Sep 17 00:00:00 2001 From: navsarmajs Date: Sun, 29 Oct 2023 20:39:49 -0600 Subject: [PATCH 02/16] Added component documentation for more models --- docs/dev-guide/components/initialize_los.md | 5 --- .../components/transit_pass_ownership.md | 9 ++-- .../components/transit_pass_subsidy.md | 45 +++++++++++++++++++ 3 files changed, 51 insertions(+), 8 deletions(-) create mode 100644 docs/dev-guide/components/transit_pass_subsidy.md diff --git a/docs/dev-guide/components/initialize_los.md b/docs/dev-guide/components/initialize_los.md index 658219ba7..032bcf21e 100644 --- a/docs/dev-guide/components/initialize_los.md +++ b/docs/dev-guide/components/initialize_los.md @@ -19,11 +19,6 @@ function. These functions are registered as Inject steps in the example Pipelin -### Examples - -- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) -- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) - ## Implementation ```{eval-rst} diff --git a/docs/dev-guide/components/transit_pass_ownership.md b/docs/dev-guide/components/transit_pass_ownership.md index c67398ed0..49ec91ee7 100644 --- a/docs/dev-guide/components/transit_pass_ownership.md +++ b/docs/dev-guide/components/transit_pass_ownership.md @@ -16,6 +16,9 @@ The main interface to the transit pass ownership model is the :py:func:`~activitysim.abm.models.transit_pass_ownership` function. This function is registered as an Inject step in the example Pipeline. +This model generates only True or False outcomes, and is structured as a binary +logit model. + ## Structure - *Configuration File*: `transit_pass_ownership.yaml` @@ -29,15 +32,15 @@ function is registered as an Inject step in the example Pipeline. ## Configuration ```{eval-rst} -.. autopydantic_model:: FreeParkingSettings +.. autopydantic_model:: TransitPassOwnershipSettings :inherited-members: BaseModel, PydanticReadable :show-inheritance: ``` ### Examples -- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/free_parking.yaml) -- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/free_parking.yaml) +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/transit_pass_ownership.yaml) +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/transit_pass_ownership.yaml) ## Implementation diff --git a/docs/dev-guide/components/transit_pass_subsidy.md b/docs/dev-guide/components/transit_pass_subsidy.md new file mode 100644 index 000000000..342104aea --- /dev/null +++ b/docs/dev-guide/components/transit_pass_subsidy.md @@ -0,0 +1,45 @@ +(component-free-parking)= +# Transit Pass Subsidy + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.free_parking +``` + +The transit pass subsidy model is a component of the transit fare discount model, which models persons who purchase or are +provided a transit pass. The transit fare discount consists of two submodels - this +transit pass subsidy model and a person :ref:`transit_pass_ownership` model. The +result of this model can be used to condition downstream models such as the +person :ref:`transit_pass_ownership` model and the tour and trip mode choice models +via fare discount adjustments. + +The main interface to the transit pass subsidy model is the +:py:func:`~activitysim.abm.models.transit_pass_subsidy` function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `transit_pass_subsidy.yaml` +- *Core Table*: `persons` +- *Result Field*: `transit_pass_subsidy` + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TransitPassSubsidySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/transit_pass_subsidy.yaml) +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/transit_pass_subsidy.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: transit_pass_subsidy +``` From 66d6989f5d810bbc9252d5e72fbb0df169551fb3 Mon Sep 17 00:00:00 2001 From: navsarmajs Date: Mon, 30 Oct 2023 00:00:27 -0600 Subject: [PATCH 03/16] Documented more model componets and added to index toctree --- .../components/disaggregate_accessibility.md | 107 ++++++++++++++++++ docs/dev-guide/components/index.rst | 22 ++-- docs/dev-guide/components/initialize.md | 24 ++++ docs/dev-guide/components/initialize_tours.md | 15 +++ .../components/transit_pass_subsidy.md | 4 +- 5 files changed, 162 insertions(+), 10 deletions(-) create mode 100644 docs/dev-guide/components/disaggregate_accessibility.md create mode 100644 docs/dev-guide/components/initialize.md create mode 100644 docs/dev-guide/components/initialize_tours.md diff --git a/docs/dev-guide/components/disaggregate_accessibility.md b/docs/dev-guide/components/disaggregate_accessibility.md new file mode 100644 index 000000000..5fed111cb --- /dev/null +++ b/docs/dev-guide/components/disaggregate_accessibility.md @@ -0,0 +1,107 @@ +(component-disaggregate-accessibility)= +# Disaggregate Accessibility + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.disaggregate_accessibility +``` + +The disaggregate accessibility model is an extension of the base accessibility model. +While the base accessibility model is based on a mode-specific decay function and uses fixed market +segments in the population (i.e., income), the disaggregate accessibility model extracts the actual +destination choice logsums by purpose (i.e., mandatory fixed school/work location and non-mandatory +tour destinations by purpose) from the actual model calculations using a user-defined proto-population. +This enables users to include features that may be more critical to destination +choice than just income (e.g., automobile ownership). + +## Structure + +*Inputs* + * disaggregate_accessibility.yaml - Configuration settings for disaggregate accessibility model. + * annotate.csv [optional] - Users can specify additional annotations specific to disaggregate accessibility. For example, annotating the proto-population tables. + +*Outputs* + * final_disaggregate_accessibility.csv [optional] + * final_non_mandatory_tour_destination_accesibility.csv [optional] + * final_workplace_location_accessibility.csv [optional] + * final_school_location_accessibility.csv [optional] + * final_proto_persons.csv [optional] + * final_proto_households.csv [optional] + * final_proto_tours.csv [optional] + +The above tables are created in the model pipeline, but the model will not save +any outputs unless specified in settings.yaml - output_tables. Users can return +the proto population tables for inspection, as well as the raw logsum accessibilities +for mandatory school/work and non-mandatory destinations. The logsums are then merged +at the household level in final_disaggregate_accessibility.csv, which each tour purpose +logsums shown as separate columns. + +*Usage* + +The disaggregate accessibility model is run as a model step in the model list. +There are two necessary steps: + +* ``- initialize_proto_population`` +* ``- compute_disaggregate_accessibility`` + +The reason the steps must be separate is to enable multiprocessing. +The proto-population must be fully generated and initialized before activitysim +slices the tables into separate threads. These steps must also occur before +initialize_households in order to avoid conflict with the shadow_pricing model. + + +The model steps can be run either as part the activitysim model run, or setup +to run as a standalone run to pre-computing the accessibility values. +For standalone implementations, the final_disaggregate_accessibility.csv is read +into the pipeline and initialized with the initialize_household model step. + + + +- *Configuration File*: `disaggregate_accessibility.yaml` +- *Core Table*: Users define the variables to be generated for 'PROTO_HOUSEHOLDS', 'PROTO_PERSONS', and 'PROTO_TOURS' tables. These tables must include all basic fields necessary for running the actual model. Additional fields can be annotated in pre-processing using the annotation settings of this file. +- *Variables*: + - VARIABLES - The base variable, must be a value or a list. Results in the cartesian product (all non-repeating combinations) of the fields. + - mapped_fields [optional] - For non-combinatorial fields, users can map a variable to the fields generated in VARIABLES (e.g., income category bins mapped to median dollar values). + - filter_rows [optional] - Users can also filter rows using pandas expressions if specific variable combinations are not desired. + - JOIN_ON [required only for PROTO_TOURS] - specify the persons variable to join the tours to (e.g., person_number). + * MERGE_ON - User specified fields to merge the proto-population logsums onto the full synthetic population. The proto-population should be designed such that the logsums are able to be joined exactly on these variables specified to the full population. Users specify the to join on using: + + - by: An exact merge will be attempted using these discrete variables. + - asof [optional]: The model can peform an "asof" join for continuous variables, which finds the nearest value. This method should not be necessary since synthetic populations are all discrete. + + - method [optional]: Optional join method can be "soft", default is None. For cases where a full inner join is not possible, a Naive Bayes clustering method is fast but discretely constrained method. The proto-population is treated as the "training data" to match the synthetic population value to the best possible proto-population candidate. The Some refinement may be necessary to make this procedure work. + + * annotate_proto_tables [optional] - Annotation configurations if users which to modify the proto-population beyond basic generation in the YAML. + * DESTINATION_SAMPLE_SIZE - The *destination* sample size (0 = all zones), e.g., the number of destination zone alternatives sampled for calculating the destination logsum. Decimal values < 1 will be interpreted as a percentage, e.g., 0.5 = 50% sample. + * ORIGIN_SAMPLE_SIZE - The *origin* sample size (0 = all zones), e.g., the number of origins where logsum is calculated. Origins without a logsum will draw from the nearest zone with a logsum. This parameter is useful for systems with a large number of zones with similar accessibility. Decimal values < 1 will be interpreted as a percentage, e.g., 0.5 = 50% sample. + * ORIGIN_SAMPLE_METHOD - The method in which origins are sampled. Population weighted sampling can be TAZ-based or "TAZ-agnostic" using KMeans clustering. The potential advantage of KMeans is to provide a more geographically even spread of MAZs sampled that do not rely on TAZ hierarchies. Unweighted sampling is also possible using 'uniform' and 'uniform-taz'. + + - None [Default] - Sample zones weighted by population, ensuring at least one TAZ is sampled per MAZ. If n-samples > n-tazs then sample 1 MAZ from each TAZ until n-remaining-samples < n-tazs, then sample n-remaining-samples TAZs and sample an MAZ within each of those TAZs. If n-samples < n-tazs, then it proceeds to the above 'then' condition. + + - "kmeans" - K-Means clustering is performed on the zone centroids (must be provided as maz_centroids.csv), weighted by population. The clustering yields k XY coordinates weighted by zone population for n-samples = k-clusters specified. Once k new cluster centroids are found, these are then approximated into the nearest available zone centroid and used to calculate accessibilities on. By default, the k-means method is run on 10 different initial cluster seeds (n_init) using using [k-means++ seeding algorithm](https://en.wikipedia.org/wiki/K-means%2B%2B). The k-means method runs for max_iter iterations (default=300). + + - "uniform" - Unweighted sample of N zones independent of each other. + + - "uniform-taz" - Unweighted sample of 1 zone per taz up to the N samples specified. + + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: DisaggregateAccessibilitySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC_Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/disaggregate_accessibility.yaml) +- [Placeholder_SANDAG_2_Zone](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/placeholder_sandag/test/configs_2_zone/disaggregate_accessibility.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: disaggregate-accessibility +``` diff --git a/docs/dev-guide/components/index.rst b/docs/dev-guide/components/index.rst index 939fae69b..aa7305f8c 100644 --- a/docs/dev-guide/components/index.rst +++ b/docs/dev-guide/components/index.rst @@ -4,14 +4,20 @@ Components .. toctree:: :maxdepth: 1 - - accessibility - auto_ownership - free_parking - school_location_choice - trip_destination - work_from_home - work_location_choice + + initialize + initialize_los + initialize_tours + accessibility + auto_ownership + disaggregate_accessibility + free_parking + school_location_choice + transit_pass_ownership + transit_pass_subsidy + trip_destination + work_from_home + work_location_choice diff --git a/docs/dev-guide/components/initialize.md b/docs/dev-guide/components/initialize.md new file mode 100644 index 000000000..6bc49e518 --- /dev/null +++ b/docs/dev-guide/components/initialize.md @@ -0,0 +1,24 @@ +(component-initialize)= +# Initialize + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize +``` + +The initialize model isn't really a model, but rather a few data processing steps in the data pipeline. +The initialize data processing steps code variables used in downstream models, such as household and person +value-of-time. This step also pre-loads the land_use, households, persons, and person_windows tables because +random seeds are set differently for each step and therefore the sampling of households depends on which step +they are initially loaded in. + +The main interface to the initialize land use step is the :py:func:`~activitysim.abm.models.initialize.initialize_landuse` +function. The main interface to the initialize household step is the :py:func:`~activitysim.abm.models.initialize.initialize_households` +function. The main interface to the initialize tours step is the :py:func:`~activitysim.abm.models.initialize_tours.initialize_tours` +function. These functions are registered as Inject steps in the example Pipeline. + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize +``` diff --git a/docs/dev-guide/components/initialize_tours.md b/docs/dev-guide/components/initialize_tours.md new file mode 100644 index 000000000..a05ec127f --- /dev/null +++ b/docs/dev-guide/components/initialize_tours.md @@ -0,0 +1,15 @@ +(component-initialize-tours)= +# Initialize Tours + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.initialize_tours +``` + + + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_tours +``` diff --git a/docs/dev-guide/components/transit_pass_subsidy.md b/docs/dev-guide/components/transit_pass_subsidy.md index 342104aea..5f5b5fc25 100644 --- a/docs/dev-guide/components/transit_pass_subsidy.md +++ b/docs/dev-guide/components/transit_pass_subsidy.md @@ -1,8 +1,8 @@ -(component-free-parking)= +(component-transit-pass-subsidy)= # Transit Pass Subsidy ```{eval-rst} -.. currentmodule:: activitysim.abm.models.free_parking +.. currentmodule:: activitysim.abm.models.transit_pass_subsidy ``` The transit pass subsidy model is a component of the transit fare discount model, which models persons who purchase or are From 257b5aa835f6b1dc0967b6ce2a16d169bc950d69 Mon Sep 17 00:00:00 2001 From: navsarmajs Date: Mon, 30 Oct 2023 10:22:14 -0600 Subject: [PATCH 04/16] Model Component Documentation --- docs/dev-guide/components/vehicle_type_choice.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 docs/dev-guide/components/vehicle_type_choice.md diff --git a/docs/dev-guide/components/vehicle_type_choice.md b/docs/dev-guide/components/vehicle_type_choice.md new file mode 100644 index 000000000..e69de29bb From 2eb75f97e9eea96ab4dfcdb8bc65a9e43f507194 Mon Sep 17 00:00:00 2001 From: navsarmajs Date: Mon, 30 Oct 2023 14:46:22 -0600 Subject: [PATCH 05/16] Added Documentation for more models --- docs/dev-guide/components/cdap.md | 55 ++++++++++++ docs/dev-guide/components/index.rst | 5 ++ .../components/mandatory_scheduling.md | 60 +++++++++++++ .../components/mandatory_tour_frequency.md | 44 +++++++++ .../components/telecommute_frequency.md | 44 +++++++++ .../components/vehicle_type_choice.md | 89 +++++++++++++++++++ 6 files changed, 297 insertions(+) create mode 100644 docs/dev-guide/components/cdap.md create mode 100644 docs/dev-guide/components/mandatory_scheduling.md create mode 100644 docs/dev-guide/components/mandatory_tour_frequency.md create mode 100644 docs/dev-guide/components/telecommute_frequency.md diff --git a/docs/dev-guide/components/cdap.md b/docs/dev-guide/components/cdap.md new file mode 100644 index 000000000..0a3b1840b --- /dev/null +++ b/docs/dev-guide/components/cdap.md @@ -0,0 +1,55 @@ +(component-cdap)= +# Coordinated Daily Activity Pattern + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.cdap +``` + +The Coordinated Daily Activity Pattern (CDAP) model predicts the choice of daily activity pattern (DAP) +for each member in the household, simultaneously. The DAP is categorized in to three types as +follows: +* Mandatory: the person engages in travel to at least one out-of-home mandatory activity - work, university, or school. The mandatory pattern may also include non-mandatory activities such as separate home-based tours or intermediate stops on mandatory tours. +* Non-mandatory: the person engages in only maintenance and discretionary tours, which, by definition, do not contain mandatory activities. +* Home: the person does not travel outside the home. + +The CDAP model is a sequence of vectorized table operations: + +* create a person level table and rank each person in the household for inclusion in the CDAP model. Priority is given to full time workers (up to two), then to part time workers (up to two workers, of any type), then to children (youngest to oldest, up to three). Additional members up to five are randomly included for the CDAP calculation. +* solve individual M/N/H utilities for each person +* take as input an interaction coefficients table and then programmatically produce and write out the expression files for households size 1, 2, 3, 4, and 5 models independent of one another +* select households of size 1, join all required person attributes, and then read and solve the automatically generated expressions +* repeat for households size 2, 3, 4, and 5. Each model is independent of one another. + +The main interface to the CDAP model is the :py:func:`~activitysim.abm.models.util.cdap.run_cdap` +function. This function is called by the Inject step ``cdap_simulate`` which is +registered as an Inject step in the example Pipeline. There are two cdap class definitions in +ActivitySim. The first is at :py:func:`~activitysim.abm.models.cdap` and contains the Inject +wrapper for running it as part of the model pipeline. The second is +at :py:func:`~activitysim.abm.models.util.cdap` and contains CDAP model logic. +## Structure + +- *Configuration File*: `cdap.yaml` +- *Core Table*: `persons` +- *Result Field*: `cdap_activity` + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: CDAPSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/cdap.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/cdap.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: cdap +``` diff --git a/docs/dev-guide/components/index.rst b/docs/dev-guide/components/index.rst index aa7305f8c..5239b76ec 100644 --- a/docs/dev-guide/components/index.rst +++ b/docs/dev-guide/components/index.rst @@ -10,6 +10,11 @@ Components initialize_tours accessibility auto_ownership + vehicle_type_choice + telecommute_frequency + cdap + mandatory_tour_frequency + mandatory_scheduling disaggregate_accessibility free_parking school_location_choice diff --git a/docs/dev-guide/components/mandatory_scheduling.md b/docs/dev-guide/components/mandatory_scheduling.md new file mode 100644 index 000000000..e60755989 --- /dev/null +++ b/docs/dev-guide/components/mandatory_scheduling.md @@ -0,0 +1,60 @@ +(component-mandatory-scheduling)= +# Mandatory Tour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.mandatory_scheduling +``` + +The mandatory tour scheduling model selects a tour departure and duration period (and therefore a +start and end period as well) for each mandatory tour. The primary drivers in the model are +accessibility-based parameters such as the mode choice logsum for the departure/arrival hour +combination, demographics, and time pattern characteristics such as the time windows available +from previously scheduled tours. This model uses person :ref:`time_windows`. + + +.. note:: + For ``prototype_mtc``, the modeled time periods for all submodels are hourly from 3 am to 3 am the next day, and any times before 5 am are shifted to time period 5, and any times after 11 pm are shifted to time period 23. + + +If ``tour_departure_and_duration_segments.csv`` is included in the configs, then the model +will use these representative start and end time periods when calculating mode choice logsums +instead of the specific start and end combinations for each alternative to reduce runtime. This +feature, know as ``representative logsums``, takes advantage of the fact that the mode choice logsum, +say, from 6 am to 2 pm is very similar to the logsum from 6 am to 3 pm, and 6 am to 4 pm, and so using +just 6 am to 3 pm (with the idea that 3 pm is the "representative time period") for these alternatives is +sufficient for tour scheduling. By reusing the 6 am to 3 pm mode choice logsum, ActivitySim saves +significant runtime. + +The main interface to the mandatory tour purpose scheduling model is the +:py:func:`~activitysim.abm.models.mandatory_scheduling.mandatory_tour_scheduling` +function. This function is registered as an Inject step in the example Pipeline + +## Structure + +- *Configuration File*: `mandatory_tour_scheduling.yaml` +- *Core Table*: `tours` +- *Result Field*: `start`,`end`,`duration` +- *Skim Keys*: `TAZ`,`workplace_taz`,`school_taz`,`start`,`end` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: MandatoryTourSchedulingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/mandatory_tour_scheduling.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/mandatory_tour_scheduling.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: mandatory_tour_scheduling +``` diff --git a/docs/dev-guide/components/mandatory_tour_frequency.md b/docs/dev-guide/components/mandatory_tour_frequency.md new file mode 100644 index 000000000..ac8cbeabf --- /dev/null +++ b/docs/dev-guide/components/mandatory_tour_frequency.md @@ -0,0 +1,44 @@ +(component-mandatory-tour-frequency)= +# Mandatory Tour Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.mandatory_tour_frequency +``` + +The individual mandatory tour frequency model predicts the number of work and school tours +taken by each person with a mandatory DAP. The primary drivers of mandatory tour frequency +are demographics, accessibility-based parameters such as drive time to work, and household +automobile ownership. It also creates mandatory tours in the data pipeline. + +The main interface to the mandatory tour purpose frequency model is the +:py:func:`~activitysim.abm.models.mandatory_tour_frequency.mandatory_tour_frequency` +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `mandatory_tour_frequency.yaml` +- *Core Table*: `persons` +- *Result Field*: `mandatory_tour_frequency` + +This model generates only True or False outcomes, and is structured as a binary +logit model. + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: MandatoryTourFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/mandatory_tour_frequency.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/mandatory_tour_frequency.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: mandatory_tour_frequency +``` diff --git a/docs/dev-guide/components/telecommute_frequency.md b/docs/dev-guide/components/telecommute_frequency.md new file mode 100644 index 000000000..e53daf954 --- /dev/null +++ b/docs/dev-guide/components/telecommute_frequency.md @@ -0,0 +1,44 @@ +(component-telecommute-frequency)= +# Telecommute Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.telecommute_frequency +``` + +Telecommuting is defined as workers who work from home instead of going to work. It only applies to +workers with a regular workplace outside of home. The telecommute model consists of two +submodels - a person :ref:`work_from_home` model and this person telecommute frequency model. + +For all workers that work out of the home, the telecommute models predicts the +level of telecommuting. The model alternatives are the frequency of telecommuting in +days per week (0 days, 1 day, 2 to 3 days, 4+ days). + +The main interface to the work from home model is the +:py:func:`~activitysim.abm.models.telecommute_frequency` function. This +function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `telecommute_frequency.yaml` +- *Core Table*: `persons` +- *Result Field*: `telecommute_frequency` + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TelecommuteFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/telecommute_frequency.yaml) +- [Prototype SEMCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_semcog/configs/telecommute_frequency.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: telecommute_frequency +``` diff --git a/docs/dev-guide/components/vehicle_type_choice.md b/docs/dev-guide/components/vehicle_type_choice.md index e69de29bb..769215454 100644 --- a/docs/dev-guide/components/vehicle_type_choice.md +++ b/docs/dev-guide/components/vehicle_type_choice.md @@ -0,0 +1,89 @@ +(component-vehicle-type-choice)= +# Vehicle Type Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.vehicle_type_choice +``` + +The vehicle type choice model selects a vehicle type for each household vehicle. A vehicle type +is a combination of the vehicle's body type, age, and fuel type. For example, a 13 year old +gas powered van would have a vehicle type of *van_13_gas*. + +There are two vehicle type choice model structures implemented: + +1. Simultaneous choice of body type, age, and fuel type. +2. Simultaneous choice of body type and age, with fuel type assigned from a probability distribution. + +## Structure + +- *Configuration File*: `vehicle_type_choice.yaml` + The *vehicle_type_choice.yaml* file contains the following model specific options: + - ``SPEC``: Filename for input utility expressions + - ``COEFS``: Filename for input utility expression coefficients + - `LOGIT_TYPE``: Specifies whether you are using a nested or multinomial logit structure + - ``combinatorial_alts``: Specifies the alternatives for the choice model. + Has sub-categories of ``body_type``, ``age``, and ``fuel_type``. + - ``PROBS_SPEC``: Filename for input fuel type probabilities. Supplying probabilities + corresponds to implementation structure 2 above, and not supplying probabilities would correspond to implementation structure 1. + If provided, the ``fuel_type`` category in ``combinatorial_alts`` + will be excluded from the model alternatives such that only body type and age are selected. Input ``PROBS_SPEC`` table will have an index + column named *vehicle_type* which is a combination of body type and age in the form ``{body type}_{age}``. Subsequent column names + specify the fuel type that will be added and the column values are the probabilities of that fuel type. + The vehicle type model will select a fuel type for each vehicle based on the provided probabilities. + - ``VEHICLE_TYPE_DATA_FILE``: Filename for input vehicle type data. Must have columns ``body_type``, ``fuel_type``, and ``vehicle_year``. + Vehicle ``age`` is computed using the ``FLEET_YEAR`` option. Data for every alternative specified in the ``combinatorial_alts`` option must be included + in the file. Vehicle type data file will be joined to the alternatives and can be used in the utility expressions if ``PROBS_SPEC`` is not provided. + If ``PROBS_SPEC`` is provided, the vehicle type data will be joined after a vehicle type is decided so the data can be used in downstream models. + - ``COLS_TO_INCLUDE_IN_VEHICLE_TABLE``: List of columns from the vehicle type data file to include in the vehicle table that can be used in downstream models. + Examples of data that might be needed is vehicle range for the :ref:`vehicle_allocation` model, auto operating costs to use in tour and trip mode choice, + and emissions data for post-model-run analysis. + - ``FLEET_YEAR``: Integer specifying the fleet year to be used in the model run. This is used to compute ``age`` in the + vehicle type data table where ``age = (1 + FLEET_YEAR - vehicle_year)``. Computing age on the fly with the ``FLEET_YEAR`` variable allows the + user flexibility to compile and share a single vehicle type data file containing all years and simply change the ``FLEET_YEAR`` to run + different scenario years. + - Optional additional settings that work the same in other models are constants, expression preprocessor, and annotate tables. +- *Core Table*: +- *Result Field*: + +Input vehicle type data included in :ref:`prototype_mtc_extended` came from a variety of sources. The number of vehicle makes, models, MPG, and +electric vehicle range was sourced from the Enivornmental Protection Agency (EPA). Additional data on vehicle costs were derived from the +National Household Travel Survey. Auto operating costs in the vehicle type data file were a sum of fuel costs and maintenance costs. +Fuel costs were calculated from MPG assuming a $3.00 cost for a gallon of gas. When MPG was not available to calculate fuel costs, +the closest year, vehicle type, or body type available was used. Maintenance costs were taken from AAA's +[2017 driving cost study](https://exchange.aaa.com/wp-content/uploads/2017/08/17-0013_Your-Driving-Costs-Brochure-2017-FNL-CX-1.pdf). +Size categories within body types were averaged, e.g. car was an average of AAA's small, medium, and large sedan categories. +Motorcycles were assigned the small sedan maintenance costs since they were not included in AAA's report. +Maintenance costs were not varied by vehicle year. (According to +`data from the U.S. Bureau of Labor Statistics `_, +there was no consistent relationship between vehicle age and maintenance costs.) + +Using the above methodology, the average auto operating costs of vehicles output from :ref:`prototype_mtc_extended` was 18.4 cents. +This value is very close to the auto operating cost of 18.3 cents used in :ref:`prototype_mtc`. +Non-household vehicles in prototype_mtc_extended use the auto operating cost of 18.3 cents used in prototype_mtc. +Users are encouraged to make their own assumptions and calculate auto operating costs as they see fit. + +The distribution of fuel type probabilities included in :ref:`prototype_mtc_extended` are computed directly from the National Household Travel Survey data +and include the entire US. Therefore, there is "lumpiness" in probabilities due to poor statistics in the data for some vehicle types. +The user is encouraged to adjust the probabilities to their modeling region and "smooth" them for more consistent results. + +Further discussion of output results and model sensitivities can be found [here](https://github.com/ActivitySim/activitysim/wiki/Project-Meeting-2022.05.05). + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: VehicleTypeChoiceSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/vehicle_type_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: vehicle_type_choice +``` From 246e6118b333e3e488dab99651c46b848e3be2cb Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:09:12 -0500 Subject: [PATCH 06/16] Update cdap.md --- docs/dev-guide/components/cdap.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/dev-guide/components/cdap.md b/docs/dev-guide/components/cdap.md index 0a3b1840b..9bf2c8d91 100644 --- a/docs/dev-guide/components/cdap.md +++ b/docs/dev-guide/components/cdap.md @@ -20,12 +20,12 @@ The CDAP model is a sequence of vectorized table operations: * select households of size 1, join all required person attributes, and then read and solve the automatically generated expressions * repeat for households size 2, 3, 4, and 5. Each model is independent of one another. -The main interface to the CDAP model is the :py:func:`~activitysim.abm.models.util.cdap.run_cdap` +The main interface to the CDAP model is the [run_cdap](activitysim.abm.models.util.cdap.run_cdap) function. This function is called by the Inject step ``cdap_simulate`` which is registered as an Inject step in the example Pipeline. There are two cdap class definitions in ActivitySim. The first is at :py:func:`~activitysim.abm.models.cdap` and contains the Inject wrapper for running it as part of the model pipeline. The second is -at :py:func:`~activitysim.abm.models.util.cdap` and contains CDAP model logic. +at [cdap](activitysim.abm.models.util.cdap) and contains CDAP model logic. ## Structure - *Configuration File*: `cdap.yaml` @@ -33,8 +33,6 @@ at :py:func:`~activitysim.abm.models.util.cdap` and contains CDAP model logic. - *Result Field*: `cdap_activity` - - ## Configuration ```{eval-rst} From 195c1edcf934e1c6add95c1821b4648ac4c1fe83 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:10:12 -0500 Subject: [PATCH 07/16] Update disaggregate_accessibility.md --- docs/dev-guide/components/disaggregate_accessibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev-guide/components/disaggregate_accessibility.md b/docs/dev-guide/components/disaggregate_accessibility.md index 5fed111cb..58660b1e9 100644 --- a/docs/dev-guide/components/disaggregate_accessibility.md +++ b/docs/dev-guide/components/disaggregate_accessibility.md @@ -103,5 +103,5 @@ into the pipeline and initialized with the initialize_household model step. ## Implementation ```{eval-rst} -.. autofunction:: disaggregate-accessibility +.. autofunction:: disaggregate_accessibility ``` From d990db33dbf7c976b014d55edc9853928dc51b52 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:11:35 -0500 Subject: [PATCH 08/16] Update initialize.md --- docs/dev-guide/components/initialize.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev-guide/components/initialize.md b/docs/dev-guide/components/initialize.md index 6bc49e518..ed3633df6 100644 --- a/docs/dev-guide/components/initialize.md +++ b/docs/dev-guide/components/initialize.md @@ -11,9 +11,9 @@ value-of-time. This step also pre-loads the land_use, households, persons, and random seeds are set differently for each step and therefore the sampling of households depends on which step they are initially loaded in. -The main interface to the initialize land use step is the :py:func:`~activitysim.abm.models.initialize.initialize_landuse` -function. The main interface to the initialize household step is the :py:func:`~activitysim.abm.models.initialize.initialize_households` -function. The main interface to the initialize tours step is the :py:func:`~activitysim.abm.models.initialize_tours.initialize_tours` +The main interface to the initialize land use step is the [initialize_landuse](activitysim.abm.models.initialize.initialize_landuse) +function. The main interface to the initialize household step is the [initialize_households](activitysim.abm.models.initialize.initialize_households) +function. The main interface to the initialize tours step is the [initialize_tours](activitysim.abm.models.initialize_tours.initialize_tours) function. These functions are registered as Inject steps in the example Pipeline. From 83c1b2d40c40d79ff4ab6572590a27a604ef5607 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:12:14 -0500 Subject: [PATCH 09/16] Update initialize_los.md --- docs/dev-guide/components/initialize_los.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/dev-guide/components/initialize_los.md b/docs/dev-guide/components/initialize_los.md index 032bcf21e..c03a2e7f1 100644 --- a/docs/dev-guide/components/initialize_los.md +++ b/docs/dev-guide/components/initialize_los.md @@ -12,8 +12,8 @@ The initialize LOS model does two things: * Loads network LOS inputs for transit virtual path building (see :ref:`transit_virtual_path_builder`), pre-computes tap-to-tap total utilities and cache for later if desired -The main interface to the initialize LOS step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_los` -function. The main interface to the initialize TVPB step is the :py:func:`~activitysim.abm.models.initialize_los.initialize_tvpb` +The main interface to the initialize LOS step is the [initialize_los](activitysim.abm.models.initialize_los.initialize_los) +function. The main interface to the initialize TVPB step is the [initialize_tvpb](activitysim.abm.models.initialize_los.initialize_tvpb) function. These functions are registered as Inject steps in the example Pipeline. From 90bb7a2b23ad426989268d82f379e0911c241a3b Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:13:34 -0500 Subject: [PATCH 10/16] Update mandatory_scheduling.md --- docs/dev-guide/components/mandatory_scheduling.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/dev-guide/components/mandatory_scheduling.md b/docs/dev-guide/components/mandatory_scheduling.md index e60755989..523084182 100644 --- a/docs/dev-guide/components/mandatory_scheduling.md +++ b/docs/dev-guide/components/mandatory_scheduling.md @@ -12,8 +12,8 @@ combination, demographics, and time pattern characteristics such as the time win from previously scheduled tours. This model uses person :ref:`time_windows`. -.. note:: - For ``prototype_mtc``, the modeled time periods for all submodels are hourly from 3 am to 3 am the next day, and any times before 5 am are shifted to time period 5, and any times after 11 pm are shifted to time period 23. +## note: + For `prototype_mtc`, the modeled time periods for all submodels are hourly from 3 am to 3 am the next day, and any times before 5 am are shifted to time period 5, and any times after 11 pm are shifted to time period 23. If ``tour_departure_and_duration_segments.csv`` is included in the configs, then the model @@ -26,7 +26,7 @@ sufficient for tour scheduling. By reusing the 6 am to 3 pm mode choice logsum, significant runtime. The main interface to the mandatory tour purpose scheduling model is the -:py:func:`~activitysim.abm.models.mandatory_scheduling.mandatory_tour_scheduling` +[mandatory_tour_scheduling](activitysim.abm.models.mandatory_scheduling.mandatory_tour_scheduling) function. This function is registered as an Inject step in the example Pipeline ## Structure From e9acd33e0279d2ce90299ea3b63b948acb0bc576 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:14:10 -0500 Subject: [PATCH 11/16] Update mandatory_tour_frequency.md --- docs/dev-guide/components/mandatory_tour_frequency.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev-guide/components/mandatory_tour_frequency.md b/docs/dev-guide/components/mandatory_tour_frequency.md index ac8cbeabf..2a5e61706 100644 --- a/docs/dev-guide/components/mandatory_tour_frequency.md +++ b/docs/dev-guide/components/mandatory_tour_frequency.md @@ -11,7 +11,7 @@ are demographics, accessibility-based parameters such as drive time to work, and automobile ownership. It also creates mandatory tours in the data pipeline. The main interface to the mandatory tour purpose frequency model is the -:py:func:`~activitysim.abm.models.mandatory_tour_frequency.mandatory_tour_frequency` +[mandatory_tour_frequency](activitysim.abm.models.mandatory_tour_frequency.mandatory_tour_frequency) function. This function is registered as an Inject step in the example Pipeline. ## Structure From 2d558c4af09a329e5aae5ae11edf6abe681f5ca3 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:14:42 -0500 Subject: [PATCH 12/16] Update telecommute_frequency.md --- docs/dev-guide/components/telecommute_frequency.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev-guide/components/telecommute_frequency.md b/docs/dev-guide/components/telecommute_frequency.md index e53daf954..c06c62fbb 100644 --- a/docs/dev-guide/components/telecommute_frequency.md +++ b/docs/dev-guide/components/telecommute_frequency.md @@ -14,7 +14,7 @@ level of telecommuting. The model alternatives are the frequency of telecommutin days per week (0 days, 1 day, 2 to 3 days, 4+ days). The main interface to the work from home model is the -:py:func:`~activitysim.abm.models.telecommute_frequency` function. This +[telecommute_frequency](activitysim.abm.models.telecommute_frequency) function. This function is registered as an Inject step in the example Pipeline. ## Structure From d9e7c9310023fd4e66f7c1cda3ce8103aa26ed1e Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:15:11 -0500 Subject: [PATCH 13/16] Update telecommute_frequency.md --- docs/dev-guide/components/telecommute_frequency.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/dev-guide/components/telecommute_frequency.md b/docs/dev-guide/components/telecommute_frequency.md index c06c62fbb..971188533 100644 --- a/docs/dev-guide/components/telecommute_frequency.md +++ b/docs/dev-guide/components/telecommute_frequency.md @@ -7,7 +7,7 @@ Telecommuting is defined as workers who work from home instead of going to work. It only applies to workers with a regular workplace outside of home. The telecommute model consists of two -submodels - a person :ref:`work_from_home` model and this person telecommute frequency model. +submodels - a person [work_from_home](work_from_home) model and this person telecommute frequency model. For all workers that work out of the home, the telecommute models predicts the level of telecommuting. The model alternatives are the frequency of telecommuting in From 538f405de6a6a62a8322e7dd621b1e126951d75c Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:16:00 -0500 Subject: [PATCH 14/16] Update transit_pass_ownership.md --- docs/dev-guide/components/transit_pass_ownership.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/docs/dev-guide/components/transit_pass_ownership.md b/docs/dev-guide/components/transit_pass_ownership.md index 49ec91ee7..bff0c80eb 100644 --- a/docs/dev-guide/components/transit_pass_ownership.md +++ b/docs/dev-guide/components/transit_pass_ownership.md @@ -8,12 +8,12 @@ The transit fare discount is defined as persons who purchase or are provided a transit pass. The transit fare discount consists of two submodels - this -transit pass ownership model and a person :ref:`transit_pass_subsidy` model. The +transit pass ownership model and a person [transit_pass_subsidy](transit_pass_subsidy) model. The result of this model can be used to condition downstream models such as the tour and trip mode choice models via fare discount adjustments. The main interface to the transit pass ownership model is the -:py:func:`~activitysim.abm.models.transit_pass_ownership` function. This +[transit_pass_ownership](activitysim.abm.models.transit_pass_ownership) function. This function is registered as an Inject step in the example Pipeline. This model generates only True or False outcomes, and is structured as a binary @@ -24,9 +24,6 @@ logit model. - *Configuration File*: `transit_pass_ownership.yaml` - *Core Table*: `persons` - *Result Field*: `transit_pass_ownership` -- *Skim Keys*: NA - - ## Configuration From 28b3fa3236c5a76f7a1e860076cbf3269b7a801f Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:16:58 -0500 Subject: [PATCH 15/16] Update transit_pass_subsidy.md --- docs/dev-guide/components/transit_pass_subsidy.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/docs/dev-guide/components/transit_pass_subsidy.md b/docs/dev-guide/components/transit_pass_subsidy.md index 5f5b5fc25..e8e2bf772 100644 --- a/docs/dev-guide/components/transit_pass_subsidy.md +++ b/docs/dev-guide/components/transit_pass_subsidy.md @@ -7,13 +7,13 @@ The transit pass subsidy model is a component of the transit fare discount model, which models persons who purchase or are provided a transit pass. The transit fare discount consists of two submodels - this -transit pass subsidy model and a person :ref:`transit_pass_ownership` model. The +transit pass subsidy model and a person [transit_pass_ownership](transit_pass_ownership) model. The result of this model can be used to condition downstream models such as the -person :ref:`transit_pass_ownership` model and the tour and trip mode choice models +person [transit_pass_ownership](transit_pass_ownership) model and the tour and trip mode choice models via fare discount adjustments. The main interface to the transit pass subsidy model is the -:py:func:`~activitysim.abm.models.transit_pass_subsidy` function. This +[transit_pass_subsidy](activitysim.abm.models.transit_pass_subsidy) function. This function is registered as an Inject step in the example Pipeline. ## Structure @@ -22,9 +22,6 @@ function is registered as an Inject step in the example Pipeline. - *Core Table*: `persons` - *Result Field*: `transit_pass_subsidy` - - - ## Configuration ```{eval-rst} From b0e61311495a21ddb4b3df2e13df72425f5f4e18 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Tue, 31 Oct 2023 09:20:17 -0500 Subject: [PATCH 16/16] Update vehicle_type_choice.md --- .../components/vehicle_type_choice.md | 37 +++---------------- 1 file changed, 5 insertions(+), 32 deletions(-) diff --git a/docs/dev-guide/components/vehicle_type_choice.md b/docs/dev-guide/components/vehicle_type_choice.md index 769215454..6ac97e172 100644 --- a/docs/dev-guide/components/vehicle_type_choice.md +++ b/docs/dev-guide/components/vehicle_type_choice.md @@ -17,35 +17,8 @@ There are two vehicle type choice model structures implemented: ## Structure - *Configuration File*: `vehicle_type_choice.yaml` - The *vehicle_type_choice.yaml* file contains the following model specific options: - - ``SPEC``: Filename for input utility expressions - - ``COEFS``: Filename for input utility expression coefficients - - `LOGIT_TYPE``: Specifies whether you are using a nested or multinomial logit structure - - ``combinatorial_alts``: Specifies the alternatives for the choice model. - Has sub-categories of ``body_type``, ``age``, and ``fuel_type``. - - ``PROBS_SPEC``: Filename for input fuel type probabilities. Supplying probabilities - corresponds to implementation structure 2 above, and not supplying probabilities would correspond to implementation structure 1. - If provided, the ``fuel_type`` category in ``combinatorial_alts`` - will be excluded from the model alternatives such that only body type and age are selected. Input ``PROBS_SPEC`` table will have an index - column named *vehicle_type* which is a combination of body type and age in the form ``{body type}_{age}``. Subsequent column names - specify the fuel type that will be added and the column values are the probabilities of that fuel type. - The vehicle type model will select a fuel type for each vehicle based on the provided probabilities. - - ``VEHICLE_TYPE_DATA_FILE``: Filename for input vehicle type data. Must have columns ``body_type``, ``fuel_type``, and ``vehicle_year``. - Vehicle ``age`` is computed using the ``FLEET_YEAR`` option. Data for every alternative specified in the ``combinatorial_alts`` option must be included - in the file. Vehicle type data file will be joined to the alternatives and can be used in the utility expressions if ``PROBS_SPEC`` is not provided. - If ``PROBS_SPEC`` is provided, the vehicle type data will be joined after a vehicle type is decided so the data can be used in downstream models. - - ``COLS_TO_INCLUDE_IN_VEHICLE_TABLE``: List of columns from the vehicle type data file to include in the vehicle table that can be used in downstream models. - Examples of data that might be needed is vehicle range for the :ref:`vehicle_allocation` model, auto operating costs to use in tour and trip mode choice, - and emissions data for post-model-run analysis. - - ``FLEET_YEAR``: Integer specifying the fleet year to be used in the model run. This is used to compute ``age`` in the - vehicle type data table where ``age = (1 + FLEET_YEAR - vehicle_year)``. Computing age on the fly with the ``FLEET_YEAR`` variable allows the - user flexibility to compile and share a single vehicle type data file containing all years and simply change the ``FLEET_YEAR`` to run - different scenario years. - - Optional additional settings that work the same in other models are constants, expression preprocessor, and annotate tables. -- *Core Table*: -- *Result Field*: - -Input vehicle type data included in :ref:`prototype_mtc_extended` came from a variety of sources. The number of vehicle makes, models, MPG, and + +Input vehicle type data included in [prototype_mtc_extended](prototype_mtc_extended) came from a variety of sources. The number of vehicle makes, models, MPG, and electric vehicle range was sourced from the Enivornmental Protection Agency (EPA). Additional data on vehicle costs were derived from the National Household Travel Survey. Auto operating costs in the vehicle type data file were a sum of fuel costs and maintenance costs. Fuel costs were calculated from MPG assuming a $3.00 cost for a gallon of gas. When MPG was not available to calculate fuel costs, @@ -54,15 +27,15 @@ the closest year, vehicle type, or body type available was used. Maintenance cos Size categories within body types were averaged, e.g. car was an average of AAA's small, medium, and large sedan categories. Motorcycles were assigned the small sedan maintenance costs since they were not included in AAA's report. Maintenance costs were not varied by vehicle year. (According to -`data from the U.S. Bureau of Labor Statistics `_, +`data from the U.S. [Bureau of Labor Statistics](https://www.bls.gov/opub/btn/volume-3/pdf/americans-aging-autos.pdf), there was no consistent relationship between vehicle age and maintenance costs.) Using the above methodology, the average auto operating costs of vehicles output from :ref:`prototype_mtc_extended` was 18.4 cents. -This value is very close to the auto operating cost of 18.3 cents used in :ref:`prototype_mtc`. +This value is very close to the auto operating cost of 18.3 cents used in [prototype_mtc](prototype_mtc). Non-household vehicles in prototype_mtc_extended use the auto operating cost of 18.3 cents used in prototype_mtc. Users are encouraged to make their own assumptions and calculate auto operating costs as they see fit. -The distribution of fuel type probabilities included in :ref:`prototype_mtc_extended` are computed directly from the National Household Travel Survey data +The distribution of fuel type probabilities included in [prototype_mtc_extended](prototype_mtc_extended) are computed directly from the National Household Travel Survey data and include the entire US. Therefore, there is "lumpiness" in probabilities due to poor statistics in the data for some vehicle types. The user is encouraged to adjust the probabilities to their modeling region and "smooth" them for more consistent results.