Skip to content

Commit

Permalink
Merge branch 'cfg-documentation-vy' into cfg-documentation-navjs
Browse files Browse the repository at this point in the history
  • Loading branch information
vivekyadav26 authored Oct 31, 2023
2 parents b0e6131 + ba2d165 commit d5b24dd
Show file tree
Hide file tree
Showing 12 changed files with 362 additions and 16 deletions.
12 changes: 7 additions & 5 deletions activitysim/abm/models/initialize.py
Original file line number Diff line number Diff line change
Expand Up @@ -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(
Expand Down Expand Up @@ -103,6 +103,8 @@ class InitializeLanduseSettings(PydanticReadable):
Settings for the `initialize_landuse` component.
"""

annotate_tables: list[str] | None = None


@workflow.step
def initialize_landuse(
Expand Down Expand Up @@ -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
Expand Down
46 changes: 46 additions & 0 deletions docs/dev-guide/components/atwork_subtour_destination.md
Original file line number Diff line number Diff line change
@@ -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
```
48 changes: 48 additions & 0 deletions docs/dev-guide/components/atwork_subtour_frequency.md
Original file line number Diff line number Diff line change
@@ -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
```
41 changes: 41 additions & 0 deletions docs/dev-guide/components/atwork_subtour_mode_choice.md
Original file line number Diff line number Diff line change
@@ -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
```
50 changes: 50 additions & 0 deletions docs/dev-guide/components/atwork_subtour_scheduling.md
Original file line number Diff line number Diff line change
@@ -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
```
17 changes: 15 additions & 2 deletions docs/dev-guide/components/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,6 @@ Components

.. toctree::
:maxdepth: 1

initialize
initialize_los
initialize_tours
Expand All @@ -21,9 +20,23 @@ Components
transit_pass_ownership
transit_pass_subsidy
trip_destination
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::
Expand Down
5 changes: 1 addition & 4 deletions docs/dev-guide/components/initialize_los.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,16 +9,13 @@ 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 [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.



## Implementation

```{eval-rst}
Expand Down
64 changes: 64 additions & 0 deletions docs/dev-guide/components/tour_mode_choice.md
Original file line number Diff line number Diff line change
@@ -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
```
3 changes: 0 additions & 3 deletions docs/dev-guide/components/transit_pass_ownership.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
(component-transit-pass-ownership)=
# Transit Pass Ownership


```{eval-rst}
.. currentmodule:: activitysim.abm.models.transit_pass_ownership
```
Expand All @@ -25,7 +23,6 @@ logit model.
- *Core Table*: `persons`
- *Result Field*: `transit_pass_ownership`


## Configuration

```{eval-rst}
Expand Down
4 changes: 2 additions & 2 deletions docs/dev-guide/components/trip_purpose.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.


Expand All @@ -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
Expand Down
Loading

0 comments on commit d5b24dd

Please sign in to comment.