Phase 6a Scope of Work - ActivitySim/activitysim GitHub Wiki

Table of Contents

Phase 6 of ActivitySim development will be performed during FY2021, ending June 2021, and includes two sub-phases, phase 6a and phase 6b. Phase 6a is focused on finishing version 1.0 of ActivitySim and is scheduled for July 2020 to December 2020. Phase 6b adds additional usability improvements and a design plan for version 2.0 and is scheduled for January 2021 to June 2021. This scope of work is for Phase 6a.

Task 1: Project Management

Consultant will manage the overall project, including invoicing and conference calls with the project team, and coordination with the ActivitySim Project Management Committee (PMC). All deliverables, including meeting notes, software, tests, documentation, and issue tracking will be managed through GitHub.

Deliverable(s): (Due 24 weeks from NTP)

  • Management of Bi-Weekly Meetings
  • Pre- and Post-Meeting Notes
  • Invoicing and Progress Reports
  • Client and Team Coordination

top

Task 2: Complete Estimation Mode

Consultant will complete implementation of estimation mode for all submodels to enable data exchange with estimation tools. Consultant will also implement a larch estimation example Jupyter notebook for each remaining submodel. The current version of ActivitySim implements estimation mode (i.e. writes estimation data bundles) up to the trip level models. In addition, example estimation integrations with larch have been implemented for work location, school location, auto ownership, and tour mode choice. A table summarizing the existing estimation capabilities by submodel is here. Support for model estimation in each submodel is done through four estimation recipes: simple_simulate, interaction_sample_simulate, interaction_simulate, and cdap_simulate. These existing recipes will be utilized (and updated if needed) to implement estimation mode for the remaining unimplemented submodels: stop_frequency, trip_destination, trip_scheduling, and trip_mode_choice. The trip_purpose model is a probability lookup table and is therefore not estimated.

The combination of writing an estimation data bundle for a submodel + a larch estimation notebook means users can easily re-estimate submodels. This combination of functionality means:

  • There is no duplication of model specifications. ActivitySim owns the specification and larch pivots off of it.
  • The estimation data bundle includes all the data and model structure information and the larch_asim module used by the example notebooks processes the estimation data bundle to setup and estimate the models.
  • Users are able to add zones, alternatives, new chooser data, new taz data, new modes, new coefficients, revise utilities, and revise nesting structures in ActivitySim and larch responds accordingly.

Eventually it may be desirable for ActivitySim to automatically write larch estimators (or ALOGIT estimators or other estimators), but for now the integration will be loosely coupled rather than tightly coupled in order to provide flexibility. Upon completion of this task, ActivitySim will be able to write estimation data bundles for every estimatable submodel and will include an example estimation tool integration for each submodel. The work steps in this task are:

  • Create example survey files for trips
  • Revise expression files for trip submodels to support estimation mode
  • Add trip submodels to infer module
  • Implement writing of estimation bundles for trip submodels
  • Implement larch estimation examples for all remaining submodels
  • Add tests and documentation
  • Additional tidying up of estimation integration as budget allows

Deliverable(s): (Due 12 weeks from NTP)

  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top

Task 3: Telecommute Model in Cooperation with SEMCOG

Consultant will add a person level telecommute model to ActivitySim. The task will work in cooperation with SEMCOG to design and develop the worker telecommute model as drafted below. SEMCOG plans to add this model in the summer/fall of 2020. Consultant and PMC will twice discuss design and coordination with the SEMCOG project team. Consultant will coordinate the initial and final meeting and prepare draft and final design memos before and after each meeting for review. The design will include a discussion of topics such as:

  • The policy or investment decisions the model is intended to inform
  • Upstream choices and downstream choices the model conditions or informs, for example how it relates the CDAP model
  • Survey data items / questions used to estimate this model for SEMCOG and their availability in other regions
  • Ease of policy / what-if analysis, for example doubling the telecommute rate

Consultant will implement an ActivitySim example version (on the Bay Area test data) of the SEMCOG example/design, reasonably calibrate/validate, and update tests and documentation. PMC will provide validation data.

Telecommute is a mobility choice model, and as such would run at the person level, between work/school location choice and daily activity pattern models, after other mobility models such as auto ownership and employer parking provision. It predicts the level of telecommuting for each worker. Alternatives in the model describe the frequency of telecommuting in days per week (0 days, 1 day, 2 days, 3 days, 4 days), for workers with a regular out-of-home workplace. Note that workers who do not have a usual out-of-home workplace are not ‘telecommuters’. Explanatory variables include household and person variables, including variables such as employment category, auto ownership, variables associated with accessibility of workplace to home location and characteristics of the workplace such as parking availability and employer-provided parking choice. The model can be used for scenario planning to test potential increases in telecommuting, either by adjusting global constants or worker-specific constants such as constants for certain occupation categories represented in the synthetic population or workers who work in key employment areas.

Deliverable(s): (Due 8 weeks from NTP)

  • Coordination of two design meetings with SEMCOG
  • Draft and final design memo for first meeting in cooperation with SEMCOG
  • Draft and final design memo for second meeting in cooperation with SEMCOG
  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top

Task 4: Transit Pass Ownership Model in Cooperation with SEMCOG

Consultant will add a person level transit pass ownership model to ActivitySim. The task will work in cooperation with SEMCOG to design and develop the transit pass ownership model as drafted below. SEMCOG plans to add this model in the summer/fall of 2020. Consultant and PMC will twice discuss design and coordination with the SEMCOG project team. Consultant will coordinate the initial and final meeting and prepare draft and final design memos before and after each meeting for review. The design will include a discussion of topics such as:

  • The policy or investment decisions the model is intended to inform
  • Upstream choices and downstream choices the model conditions or informs
  • Survey data items / questions used to estimate this model for SEMCOG and their availability in other regions
  • Ease of policy / what-if analysis, for example ability to easily test commonly understood types of passes (such as day, monthly, senior, etc.), doubling the pass ownership rate, assigning all students of a specific school/TAZ a pass
  • Transferability between regions with significantly different transit systems

Consultant will implement an ActivitySim example version (on the Bay Area test data) of the SEMCOG example/design, reasonably calibrate/validate, and update tests and documentation. PMC will provide validation data.

Transit pass ownership is a mobility choice model and would run at the person level, after work/school location choice and auto ownership. Two primary approaches to formulate this model are discussed below, with the later more transferable and therefore suggested at this time. The final approach will be decided upon in the design. For example, the specific type of transit pass could be modeled. However, this formulation would not be very transferable across regions and not all surveys collect this information. Furthermore, this formulation would not address cases where a worker’s transit fare is partially reimbursed by their employer. Alternatively, the amount of transit fare reimbursement available to the person could be modeled. In this case, the alternatives in the model would be full or partial, and if partial, the percent of reimbursement would be modeled. This formulation is similar to parking reimbursement models. Explanatory variables would include household and person characteristics, including accessibility information between home and the workplace for workers. Students of schools and major universities may have transit passes included in their tuition or via student ID, which can be represented in the model as well. We also suggest a variable describing the cost of transit, since increases in transit fare would likely result in increased numbers of persons who pay the full fare to switch to transit pass holding, but potentially decrease the overall numbers of transit pass holders and potentially decrease the number of employers who reimburse for transit. This would need to be explored in the data.

Deliverable(s): (Due 8 weeks from NTP)

  • Coordination of two design meetings with SEMCOG
  • Draft and final design memo for first meeting in cooperation with SEMCOG
  • Draft and final design memo for second meeting in cooperation with SEMCOG
  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top

Task 5: Performance Enhancements

Consultant will make enhancements to ActivitySim to improve model runtimes and lower memory usage for single and multiprocessing setups. Consultant will run profiling to identify low effort performance improvement issues and then resolve as task budget allows. Likely issues include:

  • Improve parallelization by taking advantage of updates to Python 3’s multiprocessing library since the core of ActivitySim parallelization is based on the Python 2 multiprocessing API.
  • Reduce expression solving time and memory needs by better handling string data as pandas categorical data.
  • Improve performance of multiple zone system related performance issues once the functionality starts to get some use and improvements are identified.
  • Auto-calculate and/or improve chunksize calculations for more optimized multiprocessing setups.

Deliverable(s): (Due 16 weeks from NTP)

  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top

Task 6: Prototype multiple models test system

The purpose of this task is to prototype a solution to provide additional assurances that future updates to ActivitySim will more easily work for existing users. This will be operationalized by expanding the test coverage for ActivitySim software beyond the existing MTC TM1 example. Consultant will design and implement improvements to the ActivitySim test system to include additional agency models. Consultant will propose a design that includes:

  • Review of the current test system, which includes the types of tests that are run, why these tests are defined as such, the conditions under which to evaluate different test outputs, and the acceptance criteria for passing these tests
  • The workflow and benefits for registering and testing additional agency models

As examples of agency models, Consultant will add working versions of the SEMCOG and ARC models as additional examples. SEMCOG and ARC will be responsible for providing versions of their models that work with the current software. Consultant will add the agency models to the activitysim_resources repository. When a contribution to ActivitySim is made, the test system will run the existing examples and the agency models. For now, Consultant will create two tests for checking the results of the agency models. The first will check that the model runs and produces the standard output tables. The second test will summarize results for reasonableness and will be a data summary such as trips by mode and district. Consultant will update the documentation to describe the updated test system.

Deliverable(s): (Due 16 weeks from NTP)

  • Draft improved test system design memo
  • Final improved test system design memo
  • SEMCOG and ARC example setups
  • Updated documentation
  • Updated tests

top

Task 7: Input checking and error handling and pipeline improvements

The purpose of this task is to make it easier to stand up and use an ActivitySim model by improving input checking, error handling, and data pipelining. Consultant will draft a list of potential related improvements and discuss with PMC before finalization and execution. The list of improvements to be considered will be informed by the Oregon DOT input checker, checks used in other agency models, and errors often encountered by model users, either when ingesting data or during model execution. Example improvements to be considered in the design discussion include:

  • Add checking of zone and synthetic population input data, such as each household belongs to a zone and each person belongs to a household.
  • Add checking of expression formatting and settings formatting, such as expressions can be successfully parsed by Python.
  • Add more error handling and smarter messages, logging, etc., such as when submodel yaml files cannot be found.
  • Add functionality for when no alternative is found to try and figure out why, such as which terms in the utility turn off all alternatives.
  • Make usability improvements to the pipelining, such as reduce/remove duplicate table fields and make use of categorical types to improve runtime and usability.
  • Improve the user documentation related to using the data pipeline.

Deliverable(s): (Due 24 weeks from NTP)

  • Draft usability enhancements memo
  • Final usability enhancements memo
  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top

Task 8: Maintenance and support

Consultant will provide maintenance and support services to ensure ActivitySim and PopulationSim are in good working order. Tasks include dealing with updates in dependent packages, maintaining the test system, examples, and documentation, assisting with pull requests, making improvements based on agency user feedback, supporting agency users with questions, and implementing agreed upon GitHub issues.

Deliverable(s): (Due 24 weeks from NTP)

  • Email and online support to agency user and pull requests
  • Updated source code
  • Updated examples
  • Updated documentation
  • Updated tests

top