Merge pull request #14 from camsys/user-guide-doc-navjs

User guide documentation updates
ActivitySim · Dec 28, 2023 · aea3903 · aea3903
2 parents 03d53d6 + bc88594
commit aea3903
Show file tree

Hide file tree

Showing 10 changed files with 1,868 additions and 1,856 deletions.
diff --git a/docs/howitworks.rst b/docs/howitworks.rst
diff --git a/docs/images/run_select_components.png b/docs/images/run_select_components.png
diff --git a/docs/users-guide/example_models.rst b/docs/users-guide/example_models.rst
diff --git a/docs/users-guide/index.rst b/docs/users-guide/index.rst
@@ -32,10 +32,11 @@ Contents
 --------
 
 .. toctree::
-   :maxdepth: 4
-
+   :maxdepth: 2
+   
    modelsetup
    ways_to_run
+   run_primary_example
    model_anatomy
    ../howitworks
    model_dev

diff --git a/docs/users-guide/model_anatomy.rst b/docs/users-guide/model_anatomy.rst
@@ -1,17 +1,43 @@
 Anatomy of a Model
 ==================
 
+
+.. index:: constants
+.. index:: households
+.. index:: input store
+.. index:: land use
+.. index:: persons
+.. index:: size terms
+.. index:: time windows table
+.. index:: tours
+.. index:: trips
+
+
 Input Data
 ----------
 In order to run any model, the user needs the input files in the ``data`` folder as identified in the ``configs\settings.yaml``
 file and the ``configs\network_los.yaml`` file.
 
-Common inputs include
 
-* ``households`` - Synthetic households for the region.
-* ``persons`` - Synthetic population person records with socio-demographics details.
-* ``zone based land use data``: Includes total population, employments, area types, etc. data for the region.
-* ``skims``: OMX matrix file containing skim matrices for the zone system of the region.
+The following tables are currently implemented:
+
+  * households - household attributes for each household being simulated.  Index: ``household_id`` (see ``activitysim.abm.tables.households.py``)
+  * landuse - zonal land use (such as population and employment) attributes. Index: ``zone_id`` (see ``activitysim.abm.tables.landuse.py``)
+  * persons - person attributes for each person being simulated.  Index: ``person_id`` (see ``activitysim.abm.tables.persons.py``)
+  * time windows - manages person time windows throughout the simulation.  See :ref:`time_windows`.  Index:  ``person_id`` (see the person_windows table create decorator in ``activitysim.abm.tables.time_windows.py``)
+  * tours - tour attributes for each tour (mandatory, non-mandatory, joint, and atwork-subtour) being simulated.  Index:  ``tour_id`` (see ``activitysim.abm.models.util.tour_frequency.py``)
+  * trips - trip attributes for each trip being simulated.  Index: ``trip_id`` (see ``activitysim.abm.models.stop_frequency.py``)
+
+A few additional tables are also used, which are not really tables, but classes:
+
+  * input store - reads input data tables from the input data store
+  * constants - various constants used throughout the model system, such as person type codes
+  * shadow pricing - shadow price calculator and associated utility methods, see :ref:`shadow_pricing`
+  * size terms - created by reading the ``destination_choice_size_terms.csv`` input file.  Index - ``segment`` (see ``activitysim.abm.tables.size_terms.py``)
+  * skims - each model runs requires skims, but how the skims are defined can vary significantly depending on the ActivitySim implementation. The skims class defines Inject injectables to access the skim matrices. The skims class reads the skims from the omx_file on disk.
+  * table dictionary - stores which tables should be registered as random number generator channels for restartability of the pipeline
+
+
 
 .. _zone_systems :
 
@@ -344,10 +370,11 @@ Top Level Settings
 ------------------
 
 .. autosummary::
-    :toctree: _generated
+
     :template: autopydantic.rst
     :recursive:
 
+
     Settings
     InputTable
     OutputTable
@@ -360,7 +387,7 @@ File System
 -----------
 
 .. autosummary::
-    :toctree: _generated
+
     :template: autopydantic.rst
     :recursive:
 
@@ -371,7 +398,7 @@ Network Level of Service
 ------------------------
 
 .. autosummary::
-    :toctree: _generated
+
     :template: autopydantic.rst
     :recursive:
 

diff --git a/docs/users-guide/model_dev.rst b/docs/users-guide/model_dev.rst
@@ -36,15 +36,15 @@ Workflow
 
 The general workflow for estimating models is shown in the following figures and explained in more detail below.
 
-.. image:: images/estimation_tools.jpg
+.. image:: ../images/estimation_tools.jpg
 
 * The user converts their household travel survey into ActivitySim format households, persons, tours, joint tour participants, and trip tables.  The households and persons tables must have the same fields as the synthetic population input tables since the surveyed households and persons will be run through the same set of submodels as the simulated households and persons.
 * The ActivitySim estimation example ``scripts\infer.py`` module reads the ActivitySim format household travel survey files and checks for inconsistencies in the input tables versus the model design + calculates additional fields such as the household joint tour frequency based on the trips and joint tour participants table.  Survey households and persons observed choices much match the model design (i.e. a person cannot have more work tours than the model allows).
 * ActivitySim is then run in estimation mode to read the ActivitySim format household travel survey files, run the ActivitySim submodels to write estimation data bundles (EDB) that contains the model utility specifications, coefficients, chooser data, and alternatives data for each submodel.  Estimation mode runs single-processed and without destination sampling.
 * The relevant EDBs are read and transformed into the format required by the model estimation tool (i.e. larch) and then the coefficients are re-estimated. The ``activitysim.estimation.larch`` library is included for integration with larch and there is a Jupyter Notebook estimation example for each core submodel.  No changes to the model specification are made in the process.
 * The user can then update the ActivitySim model coefficients file(s) for the estimated submodel and re-run the model in simulation mode.  The user may want to use the restartable pipeline feature of ActivitySim to just run the submodel of interest.
 
-.. image:: images/estimation_example.jpg
+.. image:: ../images/estimation_example.jpg
 
 
 .. _estimation_example:

diff --git a/docs/users-guide/modelsetup.rst b/docs/users-guide/modelsetup.rst
@@ -17,8 +17,8 @@ used ActivitySim or has not used recent versions of ActivitySim. More detailed i
 and running ActivitySim are also available in this Users Guide.
 
 * Use the :ref:`Pre-packaged Installer`
+* :ref:`Run the Primary Example`
 * Placeholder (Edit model input files, configs, as needed)
-* Placeholder (Run from command line or Jupyter notebook)
 
 System Requirements
 -------------------
@@ -31,17 +31,16 @@ ________
 The computing hardware required to run a model implemented in the ActivitySim framework generally depends on:
 
 * The number of households to be simulated for disaggregate model steps
+   * In addition to the total number of households in the model region, runtime and hardware requirements can be reduced by sampling a subset of the households. The user can adjust the sampling rate for a particular run (see Settings.yaml).
 * The number of model zones (for each zone system) for aggregate model steps
 * The number and size of network skims by mode and time-of-day
 * The number of zone systems, see :ref:`Zone system`
 * The desired runtimes
 
 ActivitySim framework models use a significant amount of RAM since they store data in-memory to reduce
-data access time in order to minimize runtime.  For example, the prototype MTC example model has 2.7 million
-households, 7.5 million people, 1475 zones, 826 network skims and has been run between one hour and one day depending
-on the amount of RAM and number of processors allocated.  See :ref:`multiprocessing` and :ref:`chunk_size` for more information.
+data access time in order to minimize runtime.
 
-As an example, the SEMCOG ABM, a model that follows a 2-Zone system runs on a windows machine, with the minimum and recommended system specification as follows:
+For example, the SEMCOG ABM, a model that follows a 2-Zone system runs on a windows machine, with the minimum and recommended system specification as follows:
 
 * Minimum Specification:
    + Operating System: 64-bit Windows 7, 64-bit Windows 8 (8.1) or 64-bit Windows 10
@@ -55,6 +54,21 @@ As an example, the SEMCOG ABM, a model that follows a 2-Zone system runs on a wi
    + Memory: 256 GB RAM
    + Disk space: 150 GB
 
+As another example, the prototype MTC example model - which has 2.7 million households, 7.5 million people, 1475 zones, 826 network skims - has a runtime between one hour and one day depending on the amount of RAM and number of processors allocated.
+
+ActivitySim has features that makes it possible to customize model runs or improve model runtimes based on the available hardware resources and requirements. A few ways to do this are listed below:
+
+* :ref:`Chunking <chunking_ways_to_run>` allows the user to run eligible steps in parallel. This can be turned on/off.
+* :ref:`Multiprocessing <multi_proc_ways_to_run>` allows the user to segment processing into discrete sets of data. This will increase the runtime but allow for lower RAM requirements. This feature can also be turned on/off.
+* :ref:`Sharrow <sharrow_ways_to_run>` is a Python library designed to decrease run-time for ActivitySim models by creating an optimized compiled version of the model. This can also be turned on/off.
+* :ref:`Tracing <tracing_ways_to_run>` allows the user to access information throughout the model run for a specified number of households/persons/zones. Enabling this feature will increase run-time and memory usage. It is recommended that this feature be turned off for typical model application.
+* Optimization of data types including:
+   + Converting string variables to pandas categoricals. ActivitySim releases *<placeholder for version number>* and higher have this capability.
+   + Converting higher byte integer variables to lower byte integer variables (such as reducing ‘num tours’ from int64 to int8).
+   + Converting higher byte float variables to lower bytes. ActivitySim releases X.X.X and higher have this capability as a switch and defaults to turning this feature off.
+
+Steps for enabling/disabling these options are included in the :ref:`Advanced Configuration` sub-section, under :ref:`Ways to Run the Model` page of this Users’ Guide.
+
 
 .. note::
    In general, more CPU cores and RAM will result in faster run times.

diff --git a/docs/users-guide/other_examples.rst b/docs/users-guide/other_examples.rst
@@ -2,6 +2,66 @@
 Other Example Models
 ====================
 
+There are several example models available in `ActivitySim's GitHub repository <https://github.com/ActivitySim/activitysim/tree/main/activitysim/examples>`__. These example models are categorized into three types:
+
+
+* "production" examples are calibrated and validated by the relevant agency, and
+  are intended to be replicas of an "official" travel model used by that agency,
+  although generally we expect agencies to maintain independent repositories and
+  not rely on the Consortium maintained version as a single source for the model.
+  At this time there are no production examples in the consortium's collection,
+  but we expect that to change soon.
+* "prototype" examples are not representative of any "official" travel model
+  used by the relevant agency, but they are viewed as "ok" models by the
+  consortium: they are usually at least loosely calibrated and/or validated, and
+  typically contain at least some components or parameters specialized for the
+  relevant region. They may be in-development models that are not quite finished,
+  or consortium maintained models that are derived from but now different from
+  the official model of some region. They should not be used in place of
+  "official" models for policy analysis in any given region, but could serve as
+  a donor model for new users who want to implement ActivitySim somewhere new
+  (subject to all the caveats that go along with transferring models).
+* "placeholder" examples are computational testbeds that technically run but
+  have not been calibrated nor validated in any meaningful way. These examples
+  are early stage development models used for testing purposes, and users are
+  strongly cautioned not to use them for any policy or planning purpose.
+
+Some available examples include those listed in the table below.
+
+.. note::
+   Additional details on models provided below may not be complete or up-to-date.
+
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| Example                                   | Purpose                                                   | Zone Systems | Status               |
++===========================================+===========================================================+==============+======================+
+| :ref:`prototype_mtc`                      | Original ActivitySim Example, derived from MTC TM1        | 1            | Mature               |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| prototype_mtc_extended                    | Prototype MTC example with additional optional models     | 1            | In development       |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| example_estimation                        | Estimation example with prototype_mtc                     | 1            | Mature               |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| placeholder_multiple_zone                 | 2 or 3 zone system example using MTC data                 | 2 or 3       | Simple test example  |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| prototype_marin                           | 3 zone system example using Marin tour mode choice model  | 3            | Mature               |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| prototype_arc                             | ARC agency example                                        | 1            | In development       |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| :ref:`prototype_semcog`                   | SEMCOG agency example                                     | 1            | In production        |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| placeholder_psrc                          | PSRC agency example                                       | 2            | Future development   |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| placeholder_sandag                        | SANDAG agency example                                     | 3            | Future development   |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| prototype_sandag_xborder                  | SANDAG agency example                                     | 3            | In development       |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+| prototype_mwcog                           | MWCOG agency example                                      | 2            | In development       |
++-------------------------------------------+-----------------------------------------------------------+--------------+----------------------+
+
+.. note::
+   The `example_manifest.yaml <https://github.com/ActivitySim/activitysim/blob/main/activitysim/examples/example_manifest.yaml>`_
+   contains example commands to create and run several versions of the examples.  See also :ref:`adding_agency_examples` for more
+   information on agency example models.
+
 .. _prototype_mtc_extended :
 
 **prototype_mtc_extended**

diff --git a/docs/users-guide/visualization.rst b/docs/users-guide/visualization.rst
@@ -154,16 +154,16 @@ When Simwrapper launches, the dashboard is displayed in the scrollable field in
 two sets of navigation controls.  The left-hand sidebar contains a menu of the available simulation outputs you can access from the
 current directory, including a number of sample outputs:
 
-.. image:: images/viz_nav-1.png
+.. image:: ../images/viz_nav-1.png
 
 The header and tabs at the top of the page help you navigate within the simulation run that is currently being visualized:
 
-.. image:: images/viz_nav-2.png
+.. image:: ../images/viz_nav-2.png
 
 Clicking on ‘Details’ will switch from the visualizations view to a current directory listing to facilitate viewing and downloading of
 the code and raw data used to create the dashboard:
 
-.. image:: images/viz_nav-3.png
+.. image:: ../images/viz_nav-3.png
 
 Clicking on ‘Topsheet’ returns you to the visualization graphics page.  The three buttons in the lower left corner provide additional
 functionality to:
@@ -172,7 +172,7 @@ functionality to:
 2. toggle light theme vs. dark theme, and
 3. split the visualization window into two separate panels like this:
 
-.. image:: images/viz_nav-4.png
+.. image:: ../images/viz_nav-4.png
 
 Before starting the split-screen view, choose the model run that you want to appear in the right side pane (‘1-sf-run’ in the image above).
 Then, click on the split view button to divide the window into two visualization panels.  Finally, use the left-hand navigation pane to