Traveler
Loading the Full MTC Dataset#
Traveler includes a compact MTC dataset in the repository so that examples and tests run quickly. For performance experiments and larger demonstrations, the companion mtc package can instead load the full regional dataset.
This walkthrough downloads that dataset into a local cache, assembles its tables into a typed Traveler store, and inspects the main dimensions of the resulting model data. The first run requires a network connection and enough disk space for the archive; later runs reuse the cached files.
Load the regional data#
The public mtc.full loader handles the complete workflow: locating cached files, downloading and unpacking missing data, converting source CSV files to Parquet, loading the typed tables, and creating a small set of synthetic tours for demonstration.
import mtc
store = mtc.full(download=True)
store
/Users/jpn/Git/traveler/packages/mtc/src/mtc/tables/skims.py:66: ZoneReindexWarning: Zones length does not match OMX file shape, will reindex.
return OmxSkims(
<Store with keys households, persons, land_use, skims, time_periods, tours>
The returned Store keeps the related land-use, household, person, tour, and skim data together. Its typed table definitions let downstream model steps validate fields and navigate relationships without repeatedly rebuilding indexes.
Inspect the regional geography#
Travel-time, distance, and cost matrices are held in the skims dataset. The full MTC skims cover 1,454 traffic analysis zones and include both two-dimensional and time-dependent arrays.
store.skims.info()
<Skims>
- DISTWALK (1454, 1454) float32
- HOV2TOLL_BTOLL (1454, 1454, 5) float32
- HOV2TOLL_DIST (1454, 1454, 5) float32
- HOV2TOLL_TIME (1454, 1454, 5) float32
- HOV2_BTOLL (1454, 1454, 5) float32
- HOV2_DIST (1454, 1454, 5) float32
- HOV2_TIME (1454, 1454, 5) float32
- HOV3TOLL_BTOLL (1454, 1454, 5) float32
- HOV3TOLL_DIST (1454, 1454, 5) float32
- HOV3TOLL_TIME (1454, 1454, 5) float32
- HOV3_BTOLL (1454, 1454, 5) float32
- HOV3_DIST (1454, 1454, 5) float32
- HOV3_TIME (1454, 1454, 5) float32
- SOVTOLL_BTOLL (1454, 1454, 5) float32
- SOVTOLL_DIST (1454, 1454, 5) float32
- SOVTOLL_TIME (1454, 1454, 5) float32
- SOV_BTOLL (1454, 1454, 5) float32
- SOV_DIST (1454, 1454, 5) float32
- SOV_TIME (1454, 1454, 5) float32
- otaz (1454,) categorical: (1454 categories)
- dtaz (1454,) categorical: (1454 categories)
The land-use table uses the same zone system. Each row describes one TAZ with population, employment, acreage, parking, enrollment, and other zonal attributes used by model expressions.
store.land_use.info()
<JaxTable id_col=TAZ>
- DISTRICT (1454,) int8
- SD (1454,) int8
- TOTHH (1454,) int32
- TOTPOP (1454,) int32
- TOTACRE (1454,) float32
- RESACRE (1454,) float32
- CIACRE (1454,) float32
- TOTEMP (1454,) int32
- AGE0519 (1454,) int32
- RETEMPN (1454,) int32
- FPSEMPN (1454,) int32
- HEREMPN (1454,) int32
- OTHEMPN (1454,) int32
- AGREMPN (1454,) int32
- MWTEMPN (1454,) int32
- PRKCST (1454,) float32
- OPRKCST (1454,) float32
- area_type (1454,) int32
- HSENROLL (1454,) float32
- COLLFTE (1454,) float32
- COLLPTE (1454,) float32
- TOPOLOGY (1454,) int32
- TERMINAL (1454,) float32
- TAZ (1454,) int32
- county_id (1454,) int8
- _prng_key_ (1454,) key<fry>
Inspect the synthetic population#
The full synthetic population contains roughly 2.8 million households. Household records carry home-zone, income, size, worker, and observed auto-ownership fields; later model steps can add derived fields to a returned store.
store.households.info()
<JaxTable id_col=household_id>
- household_id (2875192,) int32
- hhsize (2875192,) int8
- num_workers (2875192,) int8
- auto_ownership (2875192,) int8
- TAZ (2875192,) int32
- HHT (2875192,) int8
- income (2875192,) int32
- home_zone_id (2875192,) categorical: (1454 categories)
- _prng_key_ (2875192,) key<fry>
Those households contain roughly 7.5 million people. The loader also creates the household index used to align every person with the corresponding household row, allowing model code to move between the two tables efficiently.
store.persons.info()
<JaxTable id_col=person_id>
- person_id (7566527,) int32
- household_id (7566527,) int32
- age (7566527,) int32
- PNUM (7566527,) int32
- sex (7566527,) int32
- pemploy (7566527,) int32
- pstudent (7566527,) int32
- ptype (7566527,) int32
- _prng_key_ (7566527,) key<fry>
- _household_idx_ (7566527,) int32
Where to go next#
At this point the full regional inputs have the same typed interface as the bundled mini data, so the model walkthroughs can use either store without changing their core expressions. Use the mini loader while developing and testing; switch to this full loader when the objective is a realistic scale or performance measurement.