Skip to content

Commit 25bf422

Browse files
bstablerbstabler
committed
updates to documentation for phase 5 work except multiple zone systems
1 parent a132342 commit 25bf422

File tree

10 files changed

+252
-99
lines changed

10 files changed

+252
-99
lines changed

‎MANIFEST.in‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
include ez_setup.py
22
include README.rst
3+
graft notebooks
4+
graft activitysim/examples
5+
6+
# required for test system
7+
38
include activitysim\abm\test\data\mtc_asim.h5
49
include activitysim\abm\test\data\skims.omx
510
include activitysim\abm\test\data\households.csv
611
include activitysim\abm\test\data\persons.csv
712
include activitysim\abm\test\data\land_use.csv
813
include activitysim\abm\test\data\override_hh_ids.csv
9-
graft notebooks
10-
graft activitysim/examples

‎docs/abmexample.rst‎

Lines changed: 118 additions & 16 deletions
Large diffs are not rendered by default.

‎docs/core.rst‎

Lines changed: 32 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -138,8 +138,7 @@ introduction to expressions. ActivitySim provides two ways to evaluate expressi
138138
* Simple table expressions are evaluated using ``DataFrame.eval()``. `pandas' eval <http://pandas.pydata.org/pandas-docs/stable/generated/pandas.eval.html>`__ operates on the current table.
139139
* Python expressions, denoted by beginning with ``@``, are evaluated with `Python's eval() <https://docs.python.org/2/library/functions.html#eval>`__.
140140

141-
Simple table expressions can only refer to columns in the current DataFrame. Python expressions can refer to any Python objects
142-
urrently in memory.
141+
Simple table expressions can only refer to columns in the current DataFrame. Python expressions can refer to any Python objects currently in memory.
143142

144143
Conventions
145144
~~~~~~~~~~~
@@ -159,52 +158,50 @@ Example Expressions File
159158

160159
An expressions file has the following basic form:
161160

162-
+---------------------------------+-------------------------------+-----------+----------+
163-
| Description | Expression | cars0 | cars1 |
164-
+=================================+===============================+===========+==========+
165-
| 2 Adults (age 16+) | drivers==2 | 0 | 3.0773 |
166-
+---------------------------------+-------------------------------+-----------+----------+
167-
| Persons age 35-34 | num_young_adults | 0 | -0.4849 |
168-
+---------------------------------+-------------------------------+-----------+----------+
169-
| Number of workers, capped at 3 | @df.workers.clip(upper=3) | 0 | 0.2936 |
170-
+---------------------------------+-------------------------------+-----------+----------+
171-
| Distance, from 0 to 1 miles | @skims['DIST'].clip(1) | -3.2451 | -0.9523 |
172-
+---------------------------------+-------------------------------+-----------+----------+
161+
+---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+
162+
| Label | Description | Expression | cars0 | cars1 |
163+
+=================================+=================================+===============================+===========+=================================+
164+
| util_drivers_2 | 2 Adults (age 16+) | drivers==2 | | coef_cars1_drivers_2 |
165+
+---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+
166+
| util_persons_25_34 | Persons age 25-34 | num_young_adults | | coef_cars1_persons_25_34 |
167+
+---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+
168+
| util_num_workers_clip_3 | Number of workers, capped at 3 | @df.workers.clip(upper=3) | | coef_cars1_num_workers_clip_3 |
169+
+---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+
170+
| util_dist_0_1 | Distance, from 0 to 1 miles | @skims['DIST'].clip(1) | | coef_dist_0_1 |
171+
+---------------------------------+---------------------------------+-------------------------------+-----------+---------------------------------+
172+
173+
In the :ref:`tour_mode_choice` model expression file example shown below, the ``@c_ivt*(@odt_skims['SOV_TIME'] + dot_skims['SOV_TIME'])``
174+
expression is travel time for the tour origin to destination at the tour start time plus the tour destination to tour origin at the tour end time.
175+
The ``odt_skims`` and ``dot_skims`` objects are setup ahead-of-time to refer to the relevant skims for this model. The ``@c_ivt`` comes from the
176+
tour mode choice coefficient file. The tour mode choice model is a nested logit (NL) model and the nesting structure (including nesting
177+
coefficients) is specified in the YAML settings file.
178+
179+
+-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+
180+
| Label | Description | Expression | DRIVEALONEFREE | DRIVEALONEPAY |
181+
+===========================================================+========================================================+================================================+=================+===============+
182+
| util_DRIVEALONEFREE_Unavailable | DRIVEALONEFREE - Unavailable | sov_available == False | -999 | |
183+
+-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+
184+
| util_DRIVEALONEFREE_In_vehicle_time | DRIVEALONEFREE - In-vehicle time | odt_skims['SOV_TIME'] + dot_skims['SOV_TIME'] | coef_ivt | |
185+
+-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+
186+
| util_DRIVEALONEFREE_Unavailable_for_persons_less_than_16 | DRIVEALONEFREE - Unavailable for persons less than 16 | age < 16 | -999 | |
187+
+-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+
188+
| util_DRIVEALONEFREE_Unavailable_for_joint_tours | DRIVEALONEFREE - Unavailable for joint tours | is_joint == True | -999 | |
189+
+-----------------------------------------------------------+--------------------------------------------------------+------------------------------------------------+-----------------+---------------+
173190

174191
* Rows are vectorized expressions that will be calculated for every record in the current table being operated on
192+
* The Label column is the unique expression name (used for model estimation integration)
175193
* The Description column describes the expression
176194
* The Expression column contains a valid vectorized Python/pandas/numpy expression. In the example above, ``drivers`` is a column in the current table. Use ``@`` to refer to data outside the current table
177-
* There is a column for each alternative and its relevant coefficient
195+
* There is a column for each alternative and its relevant coefficient from the submodel coefficient file
178196

179197
There are some variations on this setup, but the functionality is similar. For example,
180198
in the example destination choice model, the size terms expressions file has market segments as rows and employment type
181199
coefficients as columns. Broadly speaking, there are currently four types of model expression configurations:
182200

183201
* Simple :ref:`simulate` choice model - select from a fixed set of choices defined in the specification file, such as the example above.
184202
* :ref:`simulate_with_interaction` choice model - combine the choice expressions with the choice alternatives files since the alternatives are not listed in the expressions file. The :ref:`non_mandatory_tour_destination_choice` model implements this approach.
185-
* Complex choice model - an expressions file, a coefficients file, and a YAML settings file with model structural definition. The :ref:`tour_mode_choice` models are examples of this and are illustrated below.
186203
* Combinatorial choice model - first generate a set of alternatives based on a combination of alternatives across choosers, and then make choices. The :ref:`cdap` model implements this approach.
187204

188-
The :ref:`tour_mode_choice` model is a complex choice model since the expressions file is structured a little bit differently, as shown below.
189-
Each row is an expression for one of the alternatives, and each column contains either -999, 1, or blank. The coefficients for each expression
190-
is in a separate file, with a separate column for each alternative. In the example below, the ``@c_ivt*(@odt_skims['SOV_TIME'] + dot_skims['SOV_TIME'])``
191-
expression is travel time for the tour origin to desination at the tour start time plus the tour destination to tour origin at the tour end time.
192-
The ``odt_skims`` and ``dot_skims`` objects are setup ahead-of-time to refer to the relevant skims for this model. The ``@c_ivt`` comes from the
193-
tour mode choice coefficient file. The tour mode choice model is a nested logit (NL) model and the nesting structure (including nesting
194-
coefficients) is specified in the YAML settings file.
195-
196-
+----------------------------------------+----------------------------------------------------------+-----------------+---------------+
197-
| Description | Expression | DRIVEALONEFREE | DRIVEALONEPAY |
198-
+========================================+==========================================================+=================+===============+
199-
|DA - Unavailable | sov_available == False | -999 | |
200-
+----------------------------------------+----------------------------------------------------------+-----------------+---------------+
201-
|DA - In-vehicle time | @c_ivt*(odt_skims['SOV_TIME'] + dot_skims['SOV_TIME']) | 1 | |
202-
+----------------------------------------+----------------------------------------------------------+-----------------+---------------+
203-
|DAP - Unavailable for age less than 16 | age < 16 | | -999 |
204-
+----------------------------------------+----------------------------------------------------------+-----------------+---------------+
205-
|DAP - Unavailable for joint tours | is_joint == True | | -999 |
206-
+----------------------------------------+----------------------------------------------------------+-----------------+---------------+
207-
208205
Sampling with Interaction
209206
~~~~~~~~~~~~~~~~~~~~~~~~~
210207

‎docs/development.rst‎

Lines changed: 69 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -156,10 +156,10 @@ our GitHub workflow are:
156156
* The master branch contains the latest working/release version of the ActivitySim resources
157157
* The master branch is protected and therefore can only be written to by the `Travis <https://travis-ci.org/>`__ CI system
158158
* Work is done in an issue/feature branch (or a fork) and then pushed to a new branch
159-
* The test system automatically runs the tests for a subset of the model (a subset of zones, households, and models) on the new branch
159+
* The test system automatically runs the tests on the new branch
160160
* If the tests pass, then a manual pull request can be approved to merge into master
161-
* The repository administrator handles the pull request and makes sure that related resources such as the wiki, documentation, issues, etc. are updated. The repository administrator handles the pull request and makes sure that related resources such as the wiki, documentation, issues, etc. are updated. The repository manager also runs the full scale model (all zones, households, and models) to ensure the example model runs successfully.
162-
* Every time a merge is made to master, the version is incremented and a new package posted to `Python Package Index <https://pypi.org/>`__
161+
* The repository administrator handles the pull request and makes sure that related resources such as the wiki, documentation, issues, etc. are updated. See :ref:`release_steps` for more information.
162+
163163

164164
Versioning
165165
~~~~~~~~~~
@@ -170,7 +170,7 @@ ActivitySim uses the following `versioning convention <http://the-hitchhikers-gu
170170

171171
MAJOR.MINOR
172172

173-
* where MAJOR designates a major revision number for the software, like 2 or 3 for Python. Usually, raising a major revision number means that you are adding a lot of features, breaking backward-compatibility or drastically changing the APIs or ABIs.
173+
* where MAJOR designates a major revision number for the software, like 2 or 3 for Python. Usually, raising a major revision number means that you are adding a lot of features, breaking backward-compatibility or drastically changing the APIs (Application Program Interface) or ABIs (Application Binary Interface).
174174
* MINOR usually groups moderate changes to the software like bug fixes or minor improvements. Most of the time, end users can upgrade with no risks their software to a new minor release. In case an API changes, the end users will be notified with deprecation warnings. In other words, API and ABI stability is usually a promise between two minor releases.
175175

176176
Testing
@@ -210,7 +210,7 @@ the tests.
210210
Profiling
211211
~~~~~~~~~
212212

213-
A good way to profile ActivitySim model runs is to use `snakeviz <https://jiffyclub.github.io/snakeviz/>`__.
213+
A handy way to profile ActivitySim model runs is to use `snakeviz <https://jiffyclub.github.io/snakeviz/>`__.
214214
To do so, first install snakeviz and then run ActivitySim with the Python profiler (cProfile) to create
215215
a profiler file. Then run snakeviz on the profiler file to interactively explore the component runtimes.
216216

@@ -238,7 +238,7 @@ Next, build the documentation in html format with the following command run from
238238

239239
If the activitysim package is installed, then the documentation will be built from that version of
240240
the source code instead of the git repo version. Make sure to ``pip uninstall activitysim`` before
241-
bulding the documentation if needed.
241+
building the documentation if needed.
242242

243243
When pushing revisions to the repo, the documentation is automatically built by Travis after
244244
successfully passing the tests. The documents are built with the ``bin/build_docs.sh`` script.
@@ -248,17 +248,76 @@ The script does the following:
248248
* runs ``make html``
249249
* copies the ``master`` branch ``../activitysim/docs/_build/html/*`` pages to the ``gh-pages`` branch
250250

251-
GitHub automagically publishes the gh-pages branch at https://activitysim.github.io/activitysim.
251+
GitHub automatically publishes the gh-pages branch at https://activitysim.github.io/activitysim.
252+
253+
.. _release_steps :
252254

253255
Releases
254256
~~~~~~~~
255257

258+
Before releasing a new version of ActivitySim, the following release checklist should be consulted:
259+
260+
* Create the required Anaconda environment
261+
* Run all the examples, including the full scale example
262+
* Build the package
263+
* Install and run the package in a new Anaconda environment
264+
* Build the documentation
265+
* Run the tests
266+
* Run pycodestyle
267+
* Increment the package version number
268+
* Update any necessary web links, such as switching from the develop branch to the master branch
269+
256270
ActivitySim releases are manually uploaded to the `Python Package Index <https://pypi.python.org/pypi/activitysim>`__
257271
(pypi) and also tagged as GitHub `releases <https://github.com/ActivitySim/activitysim/releases>`__.
258272

259-
Issues
260-
~~~~~~
273+
Issues and Support
274+
~~~~~~~~~~~~~~~~~~
275+
276+
Issue tracking and support is done through GitHub `issues <https://github.com/ActivitySim/activitysim/issues>`__.
277+
278+
License
279+
~~~~~~~
261280

262-
Issue tracking is done through GitHub `issues <https://github.com/ActivitySim/activitysim/issues>`__.
263281
ActivitySim is provided "as is." See the
264282
`License <https://github.com/ActivitySim/activitysim/blob/master/LICENSE.txt>`__ for more information.
283+
284+
Contribution Review Criteria
285+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
286+
287+
When contributing to ActivitySim, the set of questions below will be asked of the contribution. Make sure to also
288+
review the documentation above before making a submittal. The automated test system also provides some helpful
289+
information where identified.
290+
291+
To submit a contribution for review, issue a pull request with a comment introducing your contribution. The comment
292+
should include a brief overview, responses to the questions, and pointers to related information. The entire submittal
293+
should ideally be self contained so any additional documentation should be in the pull request as well.
294+
The `PMC <https://github.com/ActivitySim/activitysim/wiki/Governance#project-management-committee-pmc>`__ and/or its Contractor will handle the review request, comment on each
295+
question, complete the feedback form, and reply to the pull request. If accepted, the commit(s) will
296+
be `squashed and merged <https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-request-merges#squash-and-merge-your-pull-request-commits>`__.
297+
Its a good idea to setup a pre-submittal meeting to discuss questions and better understand expectations.
298+
299+
**Review Criteria**
300+
301+
1. Does it contain all the required elements, including a runnable example, documentation, and tests?
302+
2. Does it implement good methods (i.e. is it consistent with good practices in travel modeling)?
303+
3. Are the runtimes reasonable and does it provide documentation justifying this claim?
304+
4. Does it include non-Python code, such as C/C++? If so, does it compile on any OS and are compilation instructions included?
305+
5. Is it licensed with the ActivitySim license that allows the code to be freely distributed and modified and includes attribution so that the provenance of the code can be tracked? Does it include an official release of ownership from the funding agency if applicable?
306+
6. Does it appropriately interact with the data pipeline (i.e. it doesn't create new ways of managing data)?
307+
7. Does it include regression tests to enable checking that consistent results will be returned when updates are made to the framework?
308+
8. Does it include sufficient test coverage and test data for existing and proposed features?
309+
9. Any other comments or suggestions for improving the developer experience?
310+
311+
**Feedback**
312+
313+
The PMC and/or its Contractor will provide feedback for each review criteria above and tag each submittal category as follows:
314+
315+
+-----------------------------------+-------------+-------------------+-------------------+
316+
| Status | Code | Documentation | Tests/Examples |
317+
+===================================+=============+===================+===================+
318+
| Accept | | | |
319+
+-----------------------------------+-------------+-------------------+-------------------+
320+
| Accept but recommend revisions | | | |
321+
+-----------------------------------+-------------+-------------------+-------------------+
322+
| Do not accept | | | |
323+
+-----------------------------------+-------------+-------------------+-------------------+

‎docs/estimation.rst‎

Lines changed: 0 additions & 14 deletions
This file was deleted.

0 commit comments

Comments
 (0)