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

Updated Model Component Documentation

docs/dev-guide/components/cdap.md

@@ -0,0 +1,53 @@
+(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 [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 [cdap](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
+```

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
+```

docs/dev-guide/components/index.rst

@@ -4,19 +4,22 @@ Components
 
 .. toctree::
     :maxdepth: 1
-
    initialize
    initialize_los
    initialize_tours
    accessibility
    auto_ownership
+   vehicle_type_choice
+   telecommute_frequency
+   cdap
+   mandatory_tour_frequency
+   mandatory_scheduling
    disaggregate_accessibility
-   free_parking
+   free_parking   
    school_location_choice
    transit_pass_ownership
    transit_pass_subsidy
    trip_destination
-   free_parking
    school_location_choice
    work_from_home
    work_location_choice

docs/dev-guide/components/initialize.md

@@ -1,5 +1,5 @@
 (component-initialize)=
-# Initialize
+# Initialize 
 
 ```{eval-rst}
 .. currentmodule:: activitysim.abm.models.initialize

docs/dev-guide/components/initialize_los.md

@@ -11,13 +11,11 @@ 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 [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}

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
+[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
+
+- *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
+```

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
+[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
+
+- *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
+```

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 [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
+days per week (0 days, 1 day, 2 to 3 days, 4+ days).
+
+The main interface to the work from home model is the
+[telecommute_frequency](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
+```

docs/dev-guide/components/transit_pass_ownership.md

@@ -1,6 +1,5 @@
 (component-transit-pass-ownership)=
 # Transit Pass Ownership
-
 ```{eval-rst}
 .. currentmodule:: activitysim.abm.models.transit_pass_ownership
 ```