Merge pull request #12 from camsys/cfg-documentation-navjs

Model Documentation Updates and minor bug fixes

docs/dev-guide/components/index.rst

@@ -13,6 +13,14 @@ Components
    telecommute_frequency
    cdap
    mandatory_tour_frequency
+   school_escorting
+   joint_tour_composition 
+   joint_tour_participation
+   joint_tour_destination   
+   joint_tour_scheduling
+   non_mandatory_tour_frequency
+   non_mandatory_destination
+   non_mandatory_scheduling  
    mandatory_scheduling
    disaggregate_accessibility
    free_parking   

docs/dev-guide/components/joint_tour_composition.md

@@ -0,0 +1,42 @@
+(component-joint-tour-composition)=
+# Joint Tour Composition
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.joint_tour_composition
+```
+In the joint tour party composition model, the makeup of the travel party (adults, children, or
+mixed - adults and children) is determined for each joint tour.  The party composition determines the
+general makeup of the party of participants in each joint tour in order to allow the micro-simulation
+to faithfully represent the prevalence of adult-only, children-only, and mixed joint travel tours
+for each purpose while permitting simplicity in the subsequent person participation model.
+
+The main interface to the joint tour composition model is the
+[joint_tour_composition](activitysim.abm.models.joint_tour_composition.joint_tour_composition)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+
+## Structure
+
+- *Configuration File*: `joint_tour_composition.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `composition`
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: JointTourCompositionSettings
+    :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_mtc/configs/joint_tour_composition.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: joint_tour_composition
+```

docs/dev-guide/components/joint_tour_destination.md

@@ -0,0 +1,60 @@
+(component-joint-tour-destination)=
+# Joint Tour Destination
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.joint_tour_destination
+```
+
+The joint tour destination choice model operate similarly to the usual work and
+school location choice model, selecting the primary destination for travel tours. The only
+procedural difference between the models is that the usual work and school location choice
+model selects the usual location of an activity whether or not the activity is undertaken during the
+travel day, while the joint tour destination choice model selects the location for an
+activity which has already been generated.
+
+The tour's primary destination is the location of the activity that is assumed to provide the greatest
+impetus for engaging in the travel tour. In the household survey, the primary destination was not asked, but
+rather inferred from the pattern of stops in a closed loop in the respondents' travel diaries. The
+inference was made by weighing multiple criteria including a defined hierarchy of purposes, the
+duration of activities, and the distance from the tour origin. The model operates in the reverse
+direction, designating the primary purpose and destination and then adding intermediate stops
+based on spatial, temporal, and modal characteristics of the inbound and outbound journeys to
+the primary destination.
+
+The joint tour 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.
+
+Joint tour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default.
+
+The main interface to the model is the [joint_tour_destination](activitysim.abm.models.joint_tour_destination.joint_tour_destination)
+function.  This function 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*: `joint_tour_destination.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `destination`
+- *Skims Keys*: `TAZ, alt_dest, MD time period`
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: JointTourDestinationSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MWCOG](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mwcog/configs/joint_tour_destination.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_destination.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: joint_tour_destination
+```

docs/dev-guide/components/joint_tour_participation.md

@@ -0,0 +1,46 @@
+(component-joint-tour-participation)=
+# Joint Tour Participation
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.joint_tour_participation
+```
+In the joint tour person participation model, each eligible person sequentially makes a
+choice to participate or not participate in each joint tour.  Since the party composition model
+determines what types of people are eligible to join a given tour, the person participation model
+can operate in an iterative fashion, with each household member choosing to join or not to join
+a travel party independent of the decisions of other household members. In the event that the
+constraints posed by the result of the party composition model are not met, the person
+participation model cycles through the household members multiple times until the required
+types of people have joined the travel party.
+
+This step also creates the ``joint_tour_participants`` table in the pipeline, which stores the
+person ids for each person on the tour.
+
+The main interface to the joint tour participation model is the
+[joint_tour_participation](activitysim.abm.models.joint_tour_participation.joint_tour_participation)
+function.  This function is registered as an Inject step in the example Pipeline.
+## Structure
+
+- *Configuration File*: `joint_tour_participation.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `number_of_participants, person_id (for the point person)`
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: JointTourParticipationSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/joint_tour_participation.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_participation.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: joint_tour_participation
+```

docs/dev-guide/components/joint_tour_scheduling.md

@@ -0,0 +1,46 @@
+(component-joint-tour-scheduling)=
+# Joint Tour Scheduling
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.joint_tour_scheduling
+```
+
+The joint tour scheduling model selects a tour departure and duration period (and therefore a start and end
+period as well) for each joint tour.  This model uses person [time_windows](time_windows). The primary drivers in the
+models are accessibility-based parameters such
+as the auto travel time for the departure/arrival hour combination, demographics, and time
+pattern characteristics such as the time windows available from previously scheduled tours.
+The joint tour scheduling model does not use mode choice logsums.
+
+The main interface to the joint tour purpose scheduling model is the
+[joint_tour_scheduling](activitysim.abm.models.joint_tour_scheduling.joint_tour_scheduling)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `joint_tour_scheduling.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `start, end, duration`
+- *Skims Keys*: ` TAZ, destination, MD time period, MD time period`
+
+
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: JointTourSchedulingSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/joint_tour_scheduling.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/joint_tour_scheduling.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: joint_tour_scheduling
+```

docs/dev-guide/components/non_mandatory_destination.md

@@ -0,0 +1,43 @@
+(component-non-mandatory-destination)=
+# Non-Mandatory Destination Choice
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.non_mandatory_destination
+```
+
+The non-mandatory tour destination choice model chooses a destination zone for
+non-mandatory tours.  The three step (sample, logsums, final choice) process also used for
+mandatory tour destination choice is used for non-mandatory tour destination choice.
+
+Non-mandatory tour location choice for [multiple_zone_systems](multiple_zone_systems) models uses [presampling](presampling) by default.
+
+The main interface to the non-mandatory tour destination choice model is the
+[non_mandatory_tour_destination](activitysim.abm.models.non_mandatory_destination.non_mandatory_tour_destination)
+function.  This function is registered as an Inject step in the example Pipeline.  See :ref:`writing_logsums`
+for how to write logsums for estimation.
+
+## Structure
+
+- *Configuration File*: `non_mandatory_tour_destination.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `destination`
+- *Skims Keys*: `TAZ, alt_dest, MD time period, MD time period`
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: NonMandatoryDestinationSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/non_mandatory_tour_destination.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_destination.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: non_mandatory_tour_destination
+```

docs/dev-guide/components/non_mandatory_scheduling.md

@@ -0,0 +1,40 @@
+(component-non-mandatory-scheduling)=
+# Non-Mandatory Tour Scheduling
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.non_mandatory_scheduling
+```
+The non-mandatory tour scheduling model selects a tour departure and duration period (and therefore a start and end
+period as well) for each non-mandatory tour.  This model uses person [time_windows](time_windows).  Includes support
+for [representative_logsums](representative_logsums).
+
+The main interface to the non-mandatory tour purpose scheduling model is the
+[non_mandatory_tour_scheduling](activitysim.abm.models.non_mandatory_scheduling.non_mandatory_tour_scheduling)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `non_mandatory_tour_scheduling.yaml`
+- *Core Table*: `tours`
+- *Result Field*: `start, end, duration`
+- *Skims Keys*: `TAZ, destination, MD time period, MD time period`
+
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: NonMandatorySchedulingSettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_scheduling.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: non_mandatory_tour_scheduling
+```

docs/dev-guide/components/non_mandatory_tour_frequency.md

@@ -0,0 +1,45 @@
+(component-non-mandatory-tour-frequency)=
+# Non-Mandatory Tour Frequency
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.non_mandatory_tour_frequency
+```
+
+The non-mandatory tour frequency model selects the number of non-mandatory tours made by each person on the simulation day.
+It also adds non-mandatory tours to the tours in the data pipeline. The individual non-mandatory tour frequency model
+operates in two stages:
+
+  * A choice is made using a random utility model between combinations of tours containing zero, one, and two or more escort tours, and between zero and one or more tours of each other purpose.
+  * Up to two additional tours of each purpose are added according to fixed extension probabilities.
+
+The main interface to the non-mandatory tour purpose frequency model is the
+[non_mandatory_tour_frequency](activitysim.abm.models.non_mandatory_tour_frequency.non_mandatory_tour_frequency)
+function.  This function is registered as an Inject step in the example Pipeline.
+
+## Structure
+
+- *Configuration File*: `non_mandatory_tour_frequency.yaml`
+- *Core Table*: `persons`
+- *Result Field*: `non_mandatory_tour_frequency`
+
+
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: NonMandatoryTourFrequencySettings
+    :inherited-members: BaseModel, PydanticReadable
+    :show-inheritance:
+```
+
+### Examples
+
+- [Prototype MTC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_mtc/configs/non_mandatory_tour_frequency.yaml)
+- [Prototype ARC](https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/prototype_arc/configs/non_mandatory_tour_frequency.yaml)
+
+## Implementation
+
+```{eval-rst}
+.. autofunction:: non_mandatory_tour_frequency
+```

docs/dev-guide/components/school_escorting.md

@@ -0,0 +1,55 @@
+(component-school-escorting)=
+# School Escorting
+
+```{eval-rst}
+.. currentmodule:: activitysim.abm.models.school_escorting
+```
+The school escort model determines whether children are dropped-off at or picked-up from school,
+simultaneously with the chaperone responsible for chauffeuring the children,
+which children are bundled together on half-tours, and the type of tour (pure escort versus rideshare).
+The model is run after work and school locations have been chosen for all household members,
+and after work and school tours have been generated and scheduled.
+The model labels household members of driving age as potential ‘chauffeurs’ and children with school tours as potential ‘escortees’.
+The model then attempts to match potential chauffeurs with potential escortees in a choice model whose alternatives
+consist of ‘bundles’ of escortees with a chauffeur for each half tour.
+
+School escorting is a household level decision – each household will choose an alternative from the ``school_escorting_alts.csv`` file,
+with the first alternative being no escorting. This file contains the following columns:
+
+
+| Syntax      | Description |
+| ----------- | ----------- |
+| Header      | Title       |
+| Paragraph   | Text        |
+
+
+## Structure
+
+- *Configuration File*: `free_parking.yaml`
+- *Core Table*: `persons`
+- *Result Field*: `free_parking_at_work`
+| Syntax      | Description |
+| ----------- | ----------- |
+| Header      | Title       |
+| Paragraph   | Text        |
+
+
+
+## Configuration
+
+```{eval-rst}
+.. autopydantic_model:: SchoolEscortingSettings
+    :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:: school_escorting
+```