You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: develop/_sources/dev-guide/changes.md.txt
+25Lines changed: 25 additions & 0 deletions
Original file line number
Diff line number
Diff line change
@@ -14,6 +14,31 @@ branch (i.e., the main branch on GitHub), but not yet released in a stable versi
14
14
of ActivitySim. See below under the various version headings for changes in
15
15
released versions.
16
16
17
+
### Skipping Failed Choices
18
+
19
+
A new feature is introduced to ActivitySim to skip failed choices during model execution.
20
+
By default, ActivitySim will skip any failed choices during a model run, i.e., `skip_failed_choices` is set to `True`.
21
+
A failed choice occurs when the computed utilities for all alternatives are zero, or infinite, or nan, which can happen due to
22
+
data issues or model specification problems. A warning message is logged when a failed choice is encountered,
23
+
and the corresponding household (along with its persons, vehicles, tours, trips, etc) will be excluded from further model steps.
24
+
At the end of the model run, a summary of all skipped households is provided in the log file for user reference. Users can set
25
+
a threshold for the maximum allowed percentage of skipped households `fraction_of_failed_choices_allowed`,
26
+
and if the percentage of skipped households exceeds this threshold,
27
+
the model run will be terminated with an error. The default threshold is set to `0.001`, 0.1% of households.
28
+
29
+
This feature helps to ensure that the model can continue running even in the presence of data or specification issues,
30
+
while also providing visibility into such issues that need to be addressed.
31
+
See more information in ActivitySim's users guide "Skip Failed Choices" and code updates in [PR #1023](https://github.com/ActivitySim/activitysim/pull/1023)
32
+
33
+
##### Potential Impact on Existing Model Runs:
34
+
35
+
With `skip_failed_choices` defaulted to `True` and an allowed failure threshold defaulted as 0.1% of households,
36
+
failures that were previously silently masked will now generate warnings, be explicitly skipped, and counted toward the threshold.
37
+
As a result, model runs that previously completed "successfully" may now fail earlier,
38
+
surfacing underlying specification or data issues that require attention rather than being silently absorbed. If an agency does not
39
+
want to address the underlying issues immediately, they can set `skip_failed_choices` to `False` to maintain the previous model results,
40
+
but it is recommended to review the log file for any warnings about failed choices and address them as soon as possible to ensure model quality.
41
+
17
42
### Shadow Price Zones Reopening
18
43
19
44
We fixed an issue with reopening work and school zones during iterative shadow pricing using the
Copy file name to clipboardExpand all lines: develop/_sources/users-guide/model_anatomy.rst.txt
+8-181Lines changed: 8 additions & 181 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -52,7 +52,7 @@ indicators (e.g. skims), the model uses different spatial resolutions for differ
52
52
modeling burden and model runtimes. The typical multiple zone system setup is a TAZ zone system for auto travel, a MAZ zone
53
53
system for non-motorized travel, and optionally a transit access points (TAPs) zone system for transit.
54
54
55
-
The three versions of multiple zone systems are one-zone, two-zone, and three-zone.
55
+
The two versions of zone systems are one-zoneand two-zone.
56
56
57
57
* **One-zone**: This version is based on TM1 and supports only TAZs. All origins and
58
58
destinations are represented at the TAZ level, and all skims including auto, transit,
@@ -65,51 +65,17 @@ The three versions of multiple zone systems are one-zone, two-zone, and three-zo
65
65
walk access and egress times with times specified in the MAZ file by transit mode.
66
66
Careful pre-calculation of the assumed transit walk access and egress time by MAZ
67
67
and transit mode is required depending on the network scenario.
68
-
* **Three-zone**: This version is based on the SANDAG generation of CT-RAMP models.
69
-
Origins and destinations are represented at the MAZ level. Impedance for walk or
70
-
bike all-the-way from the origin to the destination can be specified at the MAZ
71
-
level for close together origins and destinations, and at the TAZ level for further
72
-
origins and destinations, just like the two-zone system. TAZs are used for auto
73
-
times and costs. The difference between this system and the two-zone system is that
74
-
transit times and costs are represented between Transit Access Points (TAPs), which
75
-
are essentially dummy zones that represent transit stops or clusters of stops.
76
-
Transit skims are built between TAPs, since there are typically too many MAZs to
77
-
build skims between them. Often multiple sets of TAP to TAP skims (local bus only,
78
-
all modes, etc.) are created and input to the demand model for consideration. Walk
79
-
access and egress times are also calculated between the MAZ and the TAP, and total
80
-
transit path utilities are assembled from their respective components - from MAZ to
81
-
first boarding TAP, from first boarding to final alighting TAP, and from alighting
82
-
TAP to destination MAZ. This assembling is done via the
83
-
:ref:`transit_virtual_path_builder` (TVPB), which considers all possible
84
-
combinations of nearby boarding and alighting TAPs for each origin destination MAZ
85
-
pair.
86
68
87
69
.. caution::
88
-
The ActivitySim consortium is moving away from the three-zone approach, in favor of
89
-
to the one- or two-zone approaches. The code for the three-zone approach remains
90
-
available for users who have already implemented it, but it is recommended that
91
-
users consider the one- or two-zone approaches for new implementations.
92
-
The three-zone system may be formally deprecated and removed in the future.
70
+
Historically, there was also a three-zone option. The three-zone system has been
71
+
removed as of version 1.5.2.
93
72
94
73
Regions that have an interest in more precise transit and non-motorized forecasts
95
74
may wish to adopt the two-zone approach, while other regions may adopt the one or two-zone approach. The
96
75
microzone version requires coding households and land use at the microzone level.
97
76
Typically an all-streets network is used for representation of non-motorized impedances.
98
77
This requires a routable all-streets network, with centroids and connectors for
99
-
microzones. If the three-zone system is adopted, procedures need to be developed to
100
-
code TAPs from transit stops and populate the all-street network with TAP centroids
101
-
and centroid connectors. A model with transit virtual path building takes longer to
102
-
run than a traditional TAZ only model, but it provides a much richer framework for
103
-
transit modeling.
104
-
105
-
.. note::
106
-
The two and three zone system test examples are simple test examples developed from the TM1 example. To develop the two zone system
107
-
example, TM1 TAZs were labeled MAZs, each MAZ was assigned a TAZ, and MAZ to MAZ impedance files were created from the
108
-
TAZ to TAZ impedances. To develop the three zone example system example, the TM1 TAZ model was further transformed
109
-
so select TAZs also became TAPs and TAP to TAP skims and MAZ to TAP impedances files were created. While sufficient for
110
-
initial development, these examples were insufficient for validation and performance testing of the new software. As a result,
111
-
the :ref:`prototype_marin` example was created.
112
-
78
+
microzones.
113
79
114
80
.. _omx_skims :
115
81
@@ -268,153 +234,14 @@ MAZ data, MAZ to MAZ impedances, and TAZ to TAZ impedances.
268
234
Three Zone
269
235
^^^^^^^^^^
270
236
271
-
In addition to the extra two zone system settings and inputs above, the following additional settings and inputs are required for a three zone system model. Examples values are illustrated below.
272
-
273
-
In ``settings.yaml``:
274
-
275
-
* ``models`` - add initialize_los and initialize_tvpb to load network LOS inputs / skims and pre-compute TAP to TAP utilities for TVPB. See :ref:`initialize_los`.
276
-
* ``want_dest_choice_presampling`` - enable presampling for multizone systems, which means first select a TAZ using the sampling model and then select a microzone within the TAZ based on the microzone share of TAZ size term.
277
-
278
-
::
279
-
280
-
models:
281
-
- initialize_landuse
282
-
- compute_accessibility
283
-
- initialize_households
284
-
# ---
285
-
- initialize_los
286
-
- initialize_tvpb
287
-
# ---
288
-
- school_location
289
-
- workplace_location
290
-
291
-
In ``network_los.yaml``:
292
-
293
-
* ``zone_system`` - set to 3 for three zone system
294
-
* ``rebuild_tvpb_cache`` - rebuild and overwrite existing pre-computed TAP to TAP utilities cache
295
-
* ``trace_tvpb_cache_as_csv`` - write a CSV version of TVPB cache for tracing
296
-
* ``tap_skims`` - TAP to TAP skims OMX file name. The time period for the matrix must be represented at the end of the matrix name and be seperated by a double_underscore (e.g. BUS_IVT__AM indicates base skim BUS_IVT with a time period of AM).
297
-
* ``tap`` - TAPs table
298
-
* ``tap_lines`` - table of transit line names served for each TAP. This file is used to trimmed the set of nearby TAP for each MAZ so only TAPs that are further away and serve new service are included in the TAP set for consideration. It is a very important file to include as it can considerably reduce runtimes.
299
-
* ``maz_to_tap`` - list of MAZ to TAP access/egress impedance files by user defined mode. Examples include walk and drive. The file also includes MAZ to TAP impedances.
300
-
* ``maz_to_tap:{walk}:max_dist`` - max distance from MAZ to TAP to consider TAP
301
-
* ``maz_to_tap:{walk}:tap_line_distance_col`` - MAZ to TAP data field to use for TAP lines distance filter
302
-
* ``demographic_segments`` - list of user defined demographic_segments for pre-computed TVPB impedances. Each chooser is coded with a user defined demographic segment.
303
-
* ``TVPB_SETTINGS:units`` - specify the units for calculations, e.g. utility or time.
304
-
* ``TVPB_SETTINGS:path_types`` - user defined set of TVPB path types to be calculated and available to the mode choice models. Examples include walk transit walk (WTW), drive transit walk (DTW), and walk transit drive (WTD).
305
-
* ``TVPB_SETTINGS:path_types:{WTW}:access`` - access mode for the path type
306
-
* ``TVPB_SETTINGS:path_types:{WTW}:egress`` - egress mode for the path type
307
-
* ``TVPB_SETTINGS:path_types:{WTW}:max_paths_across_tap_sets`` - max paths to keep across all skim sets, for example, 3 TAP to TAP pairs per origin MAZ destination MAZ pair
308
-
* ``TVPB_SETTINGS:path_types:{WTW}:max_paths_per_tap_set`` - max paths to keep per skim set, for example 1 per skim set - all transit submodes, local bus only, etc.
309
-
310
-
Unlike the one and two zone system approach, the three zone system approach requires additional expression files for the TVPB. The additional expression files for the TVPB are:
311
-
312
-
* ``TVPB_SETTINGS:tap_tap_settings:SPEC`` - TAP to TAP expressions, e.g. tvpb_utility_tap_tap.csv
313
-
* ``TVPB_SETTINGS:tap_tap_settings:PREPROCESSOR:SPEC`` - TAP to TAP chooser preprocessor, e.g. tvpb_utility_tap_tap_annotate_choosers_preprocessor.csv
314
-
* ``TVPB_SETTINGS:maz_tap_settings:walk:SPEC`` - MAZ to TAP {walk} expressions, e.g. tvpb_utility_walk_maz_tap.csv
315
-
* ``TVPB_SETTINGS:maz_tap_settings:drive:SPEC`` - MAZ to TAP {drive} expressions, e.g. tvpb_utility_drive_maz_tap.csv
316
-
* ``TVPB_SETTINGS:accessibility:tap_tap_settings:SPEC`` - TAP to TAP expressions for the accessibility calculator, e.g. tvpb_accessibility_tap_tap.csv
317
-
* ``TVPB_SETTINGS:accessibility:maz_tap_settings:walk:SPEC`` - MAz to TAP {walk} expressions for the accessibility calculator, e.g. tvpb_accessibility_walk_maz_tap.csv
318
-
319
-
Additional settings to configure the TVPB are:
320
-
321
-
* ``TVPB_SETTINGS:tap_tap_settings:attribute_segments:demographic_segment`` - TVPB pre-computes TAP to TAP total utilities for demographic segments. These are defined using the attribute_segments keyword. In the example below, the segments are demographic_segment (household income bin), tod (time-of-day), and access_mode (drive, walk).
322
-
* ``TVPB_SETTINGS:maz_tap_settings:{walk}:CHOOSER_COLUMNS`` - input impedance columns to expose for TVPB calculations.
323
-
* ``TVPB_SETTINGS:maz_tap_settings:{walk}:CONSTANTS`` - constants for TVPB calculations.
324
-
* ``accessibility:...`` - for the accessibility model step, the same basic set of TVPB configurations are available.
0 commit comments