From db2a5c4a7fd4bdcc4060a0ec8aa32515ba80e965 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Mon, 30 Oct 2023 13:40:13 -0500 Subject: [PATCH 1/5] updating component documentation --- .../components/atwork_subtour_destination.md | 46 +++++++++++++ .../components/atwork_subtour_frequency.md | 48 ++++++++++++++ .../components/atwork_subtour_mode_choice.md | 41 ++++++++++++ .../components/atwork_subtour_scheduling.md | 50 +++++++++++++++ docs/dev-guide/components/index.rst | 37 ++++++++--- docs/dev-guide/components/initialize.md | 24 +++++++ docs/dev-guide/components/initialize_los.md | 26 ++++++++ docs/dev-guide/components/initialize_tours.md | 15 +++++ docs/dev-guide/components/tour_mode_choice.md | 64 +++++++++++++++++++ .../components/transit_pass_ownership.md | 49 ++++++++++++++ .../components/transit_pass_subsidy.md | 45 +++++++++++++ docs/dev-guide/components/trip_purpose.md | 2 +- .../trip_purpose_and_destination.md | 41 ++++++++++++ 13 files changed, 479 insertions(+), 9 deletions(-) create mode 100644 docs/dev-guide/components/atwork_subtour_destination.md create mode 100644 docs/dev-guide/components/atwork_subtour_frequency.md create mode 100644 docs/dev-guide/components/atwork_subtour_mode_choice.md create mode 100644 docs/dev-guide/components/atwork_subtour_scheduling.md create mode 100644 docs/dev-guide/components/initialize.md create mode 100644 docs/dev-guide/components/initialize_los.md create mode 100644 docs/dev-guide/components/initialize_tours.md create mode 100644 docs/dev-guide/components/tour_mode_choice.md create mode 100644 docs/dev-guide/components/transit_pass_ownership.md create mode 100644 docs/dev-guide/components/transit_pass_subsidy.md create mode 100644 docs/dev-guide/components/trip_purpose_and_destination.md diff --git a/docs/dev-guide/components/atwork_subtour_destination.md b/docs/dev-guide/components/atwork_subtour_destination.md new file mode 100644 index 000000000..8c2bf4533 --- /dev/null +++ b/docs/dev-guide/components/atwork_subtour_destination.md @@ -0,0 +1,46 @@ +(component-atwork-subtour-destination)= +# At-work Subtours Destination Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_destination.py +``` + +The at-work subtours destination choice model is made up of three model steps: + + * sample - selects a sample of alternative 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 location. + * simulate - starts with the table created above and chooses a final location, this time with the mode choice logsum included. + +At-work subtour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default. + +The main interface to the at-work subtour destination model is the +[atwork_subtour_destination](ctivitysim.abm.models.atwork_subtour_destination.atwork_subtour_destination) +function. This function is registered as an Inject step in the example Pipeline. +[writing_logsums]`writing_logsums` for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `atwork_subtour_destination.yaml` +- *Core Table*: `tours` +- *Result Field*: `destination` +- *Skims keys*: `workplace_taz, alt_dest, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourLocationComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_destination +``` diff --git a/docs/dev-guide/components/atwork_subtour_frequency.md b/docs/dev-guide/components/atwork_subtour_frequency.md new file mode 100644 index 000000000..e59421669 --- /dev/null +++ b/docs/dev-guide/components/atwork_subtour_frequency.md @@ -0,0 +1,48 @@ +(component-atwork-subtour-frequency)= +# At-work Subtours Frequency + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_frequency.py +``` + +The at-work subtour frequency model selects the number of at-work subtours made for each work tour. +It also creates at-work subtours by adding them to the tours table in the data pipeline. +These at-work sub-tours are travel tours taken during the workday with their origin at the work +location, rather than from home. Explanatory variables include employment status, +income, auto ownership, the frequency of other tours, characteristics of the parent work tour, and +characteristics of the workplace zone. + +Choosers: work tours +Alternatives: none, 1 eating out tour, 1 business tour, 1 maintenance tour, 2 business tours, 1 eating out tour + 1 business tour +Dependent tables: household, person, accessibility +Outputs: work tour subtour frequency choice, at-work tours table (with only tour origin zone at this point) + +The main interface to the at-work subtours frequency model is the +[atwork_subtour_frequency](activitysim.abm.models.atwork_subtour_frequency.atwork_subtour_frequency) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `atwork_subtour_frequency.yaml` +- *Core Table*: `tours` +- *Result Field*: `atwork_subtour_frequency` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: AtworkSubtourFrequencySettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/atwork_subtour_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/atwork_subtour_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_frequency +``` diff --git a/docs/dev-guide/components/atwork_subtour_mode_choice.md b/docs/dev-guide/components/atwork_subtour_mode_choice.md new file mode 100644 index 000000000..d6bf05e37 --- /dev/null +++ b/docs/dev-guide/components/atwork_subtour_mode_choice.md @@ -0,0 +1,41 @@ +(component-atwork-subtour-mode-choice)= +# At-work Subtour Mode + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_mode_choice.py +``` + +The at-work subtour mode choice model assigns a travel mode to each at-work subtour using the `tour_mode_choice` model. + +The main interface to the at-work subtour mode choice model is the +[atwork_subtour_mode_choice](activitysim.abm.models.atwork_subtour_mode_choice.atwork_subtour_mode_choice) +function. This function is called in the Inject step `atwork_subtour_mode_choice` and +is registered as an Inject step in the example Pipeline. +[writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `tour_mode_choice.yaml` +- *Core Table*: `tour` +- *Result Field*: `tour_mode` +- *Skims keys*: `workplace_taz, destination, start, end` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourModeComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_mode_choice +``` diff --git a/docs/dev-guide/components/atwork_subtour_scheduling.md b/docs/dev-guide/components/atwork_subtour_scheduling.md new file mode 100644 index 000000000..d818ab27f --- /dev/null +++ b/docs/dev-guide/components/atwork_subtour_scheduling.md @@ -0,0 +1,50 @@ +(component-atwork-subtour-scheduling)= +# At-work Subtour Scheduling + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.atwork_subtour_scheduling.py +``` + +The at-work subtours scheduling model selects a tour departure and duration period (and therefore a start and end +period as well) for each at-work subtour. This model uses person `time_windows`. + +This model is the same as the mandatory tour scheduling model except it operates on the at-work tours and +constrains the alternative set to available person `time_windows`. The at-work subtour scheduling model does not use mode choice logsums. +The at-work subtour frequency model can choose multiple tours so this model must process all first tours and then second +tours since isFirstAtWorkTour is an explanatory variable. + +Choosers: at-work tours +Alternatives: alternative departure time and arrival back at origin time pairs WITHIN the work tour departure time and arrival time back at origin AND the person time window. If no time window is available for the tour, make the first and last time periods within the work tour available, make the choice, and log the number of times this occurs. +Dependent tables: skims, person, land use, work tour +Outputs: at-work tour departure time and arrival back at origin time, updated person time windows + +The main interface to the at-work subtours scheduling model is the +[atwork_subtour_scheduling](activitysim.abm.models.atwork_subtour_scheduling.atwork_subtour_scheduling) +function. This function is registered as an Inject step in the example Pipeline. + +## Structure + +- *Configuration File*: `tour_scheduling_atwork.yaml` +- *Core Table*: `tours` +- *Result Field*: `start, end, duration` +- *Skims keys*: `workplace_taz, alt_dest, MD time period, MD time period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: AtworkSubtourSchedulingSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_scheduling_atwork.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_scheduling_atwork.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: atwork_subtour_scheduling +``` diff --git a/docs/dev-guide/components/index.rst b/docs/dev-guide/components/index.rst index 939fae69b..537578614 100644 --- a/docs/dev-guide/components/index.rst +++ b/docs/dev-guide/components/index.rst @@ -5,14 +5,35 @@ 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 + free_parking + school_location_choice + work_from_home + work_location_choice + tour_mode_choice + atwork_subtour_frequency + atwork_subtour_destination + atwork_subtour_scheduling + atwork_subtour_mode_choice + stop_frequency + trip_purpose + trip_destination + trip_purpose_and_destination + trip_scheduling_choice + trip_departure_choice + trip_mode_choice + parking_location_choice + write_trip_matrices .. note:: diff --git a/docs/dev-guide/components/initialize.md b/docs/dev-guide/components/initialize.md new file mode 100644 index 000000000..5b3429f11 --- /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_los.md b/docs/dev-guide/components/initialize_los.md new file mode 100644 index 000000000..032bcf21e --- /dev/null +++ b/docs/dev-guide/components/initialize_los.md @@ -0,0 +1,26 @@ +(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. + + + +## Implementation + +```{eval-rst} +.. autofunction:: initialize_los +``` 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/tour_mode_choice.md b/docs/dev-guide/components/tour_mode_choice.md new file mode 100644 index 000000000..a85893423 --- /dev/null +++ b/docs/dev-guide/components/tour_mode_choice.md @@ -0,0 +1,64 @@ +(component-tour-mode-choice)= +# Tour Mode Choice + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.tour_mode_choice.py +``` + +The mandatory, non-mandatory, and joint tour mode choice model assigns to each tour the "primary" mode that +is used to get from the origin to the primary destination. The tour-based modeling approach requires a reconsideration +of the conventional mode choice structure. Instead of a single mode choice model used in a four-step +structure, there are two different levels where the mode choice decision is modeled: (a) the +tour mode level (upper-level choice); and, (b) the trip mode level (lower-level choice conditional +upon the upper-level choice). + +The mandatory, non-mandatory, and joint tour mode level represents the decisions that apply to the entire tour, and +that will affect the alternatives available for each individual trip or joint trip. These decisions include the choice to use a private +car versus using public transit, walking, or biking; whether carpooling will be considered; and +whether transit will be accessed by car or by foot. Trip-level decisions correspond to details of +the exact mode used for each trip, which may or may not change over the trips in the tour. + +The mandatory, non-mandatory, and joint tour mode choice structure is a nested logit model which separates +similar modes into different nests to more accurately model the cross-elasticities between the alternatives. The +eighteen modes are incorporated into the nesting structure specified in the model settings file. The +first level of nesting represents the use a private car, non-motorized +means, or transit. In the second level of nesting, the auto nest is divided into vehicle occupancy +categories, and transit is divided into walk access and drive access nests. The final level splits +the auto nests into free or pay alternatives and the transit nests into the specific line-haul modes. + +The primary variables are in-vehicle time, other travel times, cost (the influence of which is derived +from the automobile in-vehicle time coefficient and the persons' modeled value of time), +characteristics of the destination zone, demographics, and the household's level of auto +ownership. + +The main interface to the mandatory, non-mandatory, and joint tour mode model is the +[tour_mode_choice_simulate](activitysim.abm.models.tour_mode_choice.tour_mode_choice_simulate) function. This function is +called in the Inject step [tour_mode_choice_simulate](tour_mode_choice_simulate) and is registered as an Inject step in the example Pipeline. +See [writing_logsums](writing_logsums) for how to write logsums for estimation. + +## Structure + +- *Configuration File*: `tour_mode_choice.yaml` +- *Core Table*: `tours` +- *Result Field*: `mode` +- *Skims Keys*: `TAZ, destination, start, end` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TourModeComponentSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/tour_mode_choice.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/tour_mode_choice.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: tour_mode_choice +``` 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..49ec91ee7 --- /dev/null +++ b/docs/dev-guide/components/transit_pass_ownership.md @@ -0,0 +1,49 @@ +(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. + +This model generates only True or False outcomes, and is structured as a binary +logit model. + +## Structure + +- *Configuration File*: `transit_pass_ownership.yaml` +- *Core Table*: `persons` +- *Result Field*: `transit_pass_ownership` +- *Skim Keys*: NA + + + + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TransitPassOwnershipSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [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 + +```{eval-rst} +.. autofunction:: transit_pass_ownership +``` 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..5f5b5fc25 --- /dev/null +++ b/docs/dev-guide/components/transit_pass_subsidy.md @@ -0,0 +1,45 @@ +(component-transit-pass-subsidy)= +# Transit Pass Subsidy + +```{eval-rst} +.. 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 +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 +``` diff --git a/docs/dev-guide/components/trip_purpose.md b/docs/dev-guide/components/trip_purpose.md index c8614755e..44e1b09f3 100644 --- a/docs/dev-guide/components/trip_purpose.md +++ b/docs/dev-guide/components/trip_purpose.md @@ -10,7 +10,7 @@ observed frequency distribution. The distribution is segmented by tour purpose, direction and person type. Work tours are also segmented by departure or arrival time period. The main interface to the trip purpose model is the -[trip_purpose](activitysim.abm.models.trip_purpose) +[trip_purpose](activitysim.abm.models.trip_purpose.trip_purpose) function. This function is registered as an Inject step in the example Pipeline. diff --git a/docs/dev-guide/components/trip_purpose_and_destination.md b/docs/dev-guide/components/trip_purpose_and_destination.md new file mode 100644 index 000000000..5607ceb3f --- /dev/null +++ b/docs/dev-guide/components/trip_purpose_and_destination.md @@ -0,0 +1,41 @@ +(component-trip-purpose-and-destination)= +# Trip Purpose and Destination + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.trip_purpose_and_destination.py +``` + +After running trip purpose and trip destination separately, the two model can be ran together in an iterative fashion on +the remaining failed trips (i.e. trips that cannot be assigned a destination). Each iteration uses new random numbers. + +The main interface to the trip purpose model is the +[trip_purpose_and_destination](activitysim.abm.models.trip_purpose_and_destination.trip_purpose_and_destination) +function. This function is registered as an Inject step in the example Pipeline. + + +## Structure + + +- *Core Table*: `trips` +- *Result Field*: `purpose, destination` +- *Skims Keys*: `origin, (tour primary) destination, dest_taz, trip_period` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: TripPurposeAndDestinationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/trip_purpose_and_destination.yaml) +- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/trip_purpose_and_destination.yaml) + + +## Implementation + +```{eval-rst} +.. autofunction:: trip_purpose_and_destination +``` From f415d4377e42027a4fc9f89294435fb6370075db Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Mon, 30 Oct 2023 13:53:02 -0500 Subject: [PATCH 2/5] Update vehicle allocation and build docs [makedocs] --- .../components/vehicle_allocation.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) create mode 100644 docs/dev-guide/components/vehicle_allocation.md diff --git a/docs/dev-guide/components/vehicle_allocation.md b/docs/dev-guide/components/vehicle_allocation.md new file mode 100644 index 000000000..e0fe08740 --- /dev/null +++ b/docs/dev-guide/components/vehicle_allocation.md @@ -0,0 +1,47 @@ +(component-vehicle_allocation)= +# Vehicle Allocation + +```{eval-rst} +.. currentmodule:: activitysim.abm.models.vehicle_allocation.py +``` + +The vehicle allocation model selects which vehicle would be used for a tour of given occupancy. The alternatives for the vehicle +allocation model consist of the vehicles owned by the household and an additional non household vehicle option. (Zero-auto +households would be assigned the non-household vehicle option since there are no owned vehicles in the household). +A vehicle is selected for each occupancy level set by the user such that different tour modes that have different occupancies could see different operating +characteristics. The output of the vehicle allocation model is appended to the tour table with column names [vehicle_occup_{occupancy}](vehicle_occup_{occupancy}) and the values are +the vehicle type selected. + +In [prototype_mtc_extended](prototype_mtc_extended), three occupancy levels are used: 1, 2, and 3.5. The auto operating cost +for occupancy level 1 is used in the drive alone mode and drive to transit modes. Occupancy levels 2 and 3.5 are used for shared +ride 2 and shared ride 3+ auto operating costs, respectively. Auto operating costs are selected in the mode choice pre-processors by selecting the allocated +vehicle type data from the vehicles table. If the allocated vehicle type was the non-household vehicle, the auto operating costs uses +the previous default value from [prototype_mtc](prototype_mtc). All trips and atwork subtours use the auto operating cost of the parent tour. Functionality +was added in tour and atwork subtour mode choice to annotate the tour table and create a ``selected_vehicle`` which denotes the actual vehicle used. +If the tour mode does not include a vehicle, then the ``selected_vehicle`` entry is left blank. + +The current implementation does not account for possible use of the household vehicles by other household members. Thus, it is possible for a +selected vehicle to be used in two separate tours at the same time. + +## Structure + +- *Configuration File*: `vehicle_allocation.yaml` +- *Result Field*: `vehicle_occup_{occupancy}` + +## Configuration + +```{eval-rst} +.. autopydantic_model:: VehicleAllocationSettings + :inherited-members: BaseModel, PydanticReadable + :show-inheritance: +``` + +### Examples + +- [Prototype MTC Extended](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc_extended/configs/vehicle_type_choice.yaml) + +## Implementation + +```{eval-rst} +.. autofunction:: vehicle_allocation +``` From b10c5382bff18b98b745a7bd115b06c3c3600a55 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Mon, 30 Oct 2023 15:12:40 -0500 Subject: [PATCH 3/5] documentation fixes [makedocs] --- docs/dev-guide/components/initialize.md | 6 +++--- docs/dev-guide/components/initialize_los.md | 6 +++--- docs/dev-guide/components/transit_pass_ownership.md | 9 ++------- docs/dev-guide/components/transit_pass_subsidy.md | 9 +++------ 4 files changed, 11 insertions(+), 19 deletions(-) diff --git a/docs/dev-guide/components/initialize.md b/docs/dev-guide/components/initialize.md index 5b3429f11..66dad9e39 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. diff --git a/docs/dev-guide/components/initialize_los.md b/docs/dev-guide/components/initialize_los.md index 032bcf21e..833003eda 100644 --- a/docs/dev-guide/components/initialize_los.md +++ b/docs/dev-guide/components/initialize_los.md @@ -9,11 +9,11 @@ The initialize LOS model isn't really a model, but rather a series of data proce 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 + * Loads network LOS inputs for transit virtual path building (see [transit_virtual_path_builder](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. diff --git a/docs/dev-guide/components/transit_pass_ownership.md b/docs/dev-guide/components/transit_pass_ownership.md index 49ec91ee7..0867c80d6 100644 --- a/docs/dev-guide/components/transit_pass_ownership.md +++ b/docs/dev-guide/components/transit_pass_ownership.md @@ -1,19 +1,18 @@ (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 +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,10 +23,6 @@ logit model. - *Configuration File*: `transit_pass_ownership.yaml` - *Core Table*: `persons` - *Result Field*: `transit_pass_ownership` -- *Skim Keys*: NA - - - ## Configuration 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 1f9316702350e968b9a53bec5850523ab973c598 Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Mon, 30 Oct 2023 15:23:00 -0500 Subject: [PATCH 4/5] minor fixes [makedocs] --- docs/dev-guide/components/atwork_subtour_destination.md | 2 +- docs/dev-guide/components/initialize_los.md | 1 - docs/dev-guide/components/trip_purpose.md | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/dev-guide/components/atwork_subtour_destination.md b/docs/dev-guide/components/atwork_subtour_destination.md index 8c2bf4533..ea4b62902 100644 --- a/docs/dev-guide/components/atwork_subtour_destination.md +++ b/docs/dev-guide/components/atwork_subtour_destination.md @@ -16,7 +16,7 @@ At-work subtour location choice for [multiple_zone_systems](multiple_zone_system The main interface to the at-work subtour destination model is the [atwork_subtour_destination](ctivitysim.abm.models.atwork_subtour_destination.atwork_subtour_destination) function. This function is registered as an Inject step in the example Pipeline. -[writing_logsums]`writing_logsums` for how to write logsums for estimation. +[writing_logsums](writing_logsums) for how to write logsums for estimation. ## Structure diff --git a/docs/dev-guide/components/initialize_los.md b/docs/dev-guide/components/initialize_los.md index 833003eda..5d5fdb227 100644 --- a/docs/dev-guide/components/initialize_los.md +++ b/docs/dev-guide/components/initialize_los.md @@ -14,7 +14,6 @@ The initialize LOS model does two things: 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. diff --git a/docs/dev-guide/components/trip_purpose.md b/docs/dev-guide/components/trip_purpose.md index 44e1b09f3..4acfedcf3 100644 --- a/docs/dev-guide/components/trip_purpose.md +++ b/docs/dev-guide/components/trip_purpose.md @@ -28,7 +28,7 @@ function. This function is registered as an Inject step in the example Pipeline :show-inheritance: ``` -### note:: +### Note Trip purpose and trip destination choice can be run iteratively together [trip_purpose_and_destination_model](activitysim.abm.models.trip_purpose_and_destination.py) ### Examples From ba2d16595cb76a79ace7aeff7736481412b1596a Mon Sep 17 00:00:00 2001 From: Vivek Yadav Date: Mon, 30 Oct 2023 18:03:51 -0500 Subject: [PATCH 5/5] Adding annotate_tables settings class --- activitysim/abm/models/initialize.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/activitysim/abm/models/initialize.py b/activitysim/abm/models/initialize.py index 131e81b6d..2aff9b6a5 100644 --- a/activitysim/abm/models/initialize.py +++ b/activitysim/abm/models/initialize.py @@ -46,7 +46,7 @@ def annotate_tables(state: workflow.State, model_settings, trace_label, chunk_si chunk_sizer.log_rss(trace_label) - annotate_tables = model_settings.get("annotate_tables", []) + annotate_tables = model_settings.annotate_tables if not annotate_tables: logger.warning( @@ -103,6 +103,8 @@ class InitializeLanduseSettings(PydanticReadable): Settings for the `initialize_landuse` component. """ + annotate_tables: list[str] | None = None + @workflow.step def initialize_landuse( @@ -133,11 +135,11 @@ def initialize_landuse( mandatory=True, ) - annotate_tables(state, model_settings, trace_label, chunk_sizer) + annotate_tables(state, model_settings, trace_label, chunk_sizer) - # instantiate accessibility (must be checkpointed to be be used to slice accessibility) - accessibility = state.get_dataframe("accessibility") - chunk_sizer.log_df(trace_label, "accessibility", accessibility) + # instantiate accessibility (must be checkpointed to be be used to slice accessibility) + accessibility = state.get_dataframe("accessibility") + chunk_sizer.log_df(trace_label, "accessibility", accessibility) @workflow.step