Skip to content

MTC Roadway Schemas

MTC-specific roadway network schemas.

Extends Network Wrangler base schemas with MTC-required fields and validation rules.

COUNTY_NAME_TO_CENTROID_START_NUM = {MTCCounty.SAN_FRANCISCO.value: 0, MTCCounty.SAN_MATEO.value: 100000, MTCCounty.SANTA_CLARA.value: 200000, MTCCounty.ALAMEDA.value: 300000, MTCCounty.CONTRA_COSTA.value: 400000, MTCCounty.SOLANO.value: 500000, MTCCounty.NAPA.value: 600000, MTCCounty.SONOMA.value: 700000, MTCCounty.MARIN.value: 800000} module-attribute

Mapping of county names to centroid ID starting ranges.

https://bayareametro.github.io/tm2py/input/network/#county-node-numbering-system

COUNTY_NAME_TO_NODE_START_NUM = {MTCCounty.SAN_FRANCISCO.value: 1000000, MTCCounty.SAN_MATEO.value: 1500000, MTCCounty.SANTA_CLARA.value: 2000000, MTCCounty.ALAMEDA.value: 2500000, MTCCounty.CONTRA_COSTA.value: 3000000, MTCCounty.SOLANO.value: 3500000, MTCCounty.NAPA.value: 4000000, MTCCounty.SONOMA.value: 4500000, MTCCounty.MARIN.value: 5000000, MTCCounty.EXTERNAL.value: 900001} module-attribute

Mapping of county names to node ID starting ranges.

Each county is assigned a range of node IDs to ensure unique, non-overlapping identification across the MTC network. External nodes start at 900,001.

https://bayareametro.github.io/tm2py/input/network/#county-node-numbering-system

MTC_COUNTIES = tuple(county for county in (COUNTY_NAME_TO_NODE_START_NUM.keys()) if county != MTCCounty.EXTERNAL.value) module-attribute

Tuple of MTC county names in node ID range order (excludes External).

Contains the nine Bay Area counties ordered by their node ID ranges: ('San Francisco', 'San Mateo', 'Santa Clara', 'Alameda', 'Contra Costa', 'Solano', 'Napa', 'Sonoma', 'Marin')

COUNTY_NAME_TO_NUM = {county: (i + 1) for i, county in (enumerate(MTC_COUNTIES))} module-attribute

Mapping of county names to sequential numbers (1-9).

Counties are numbered based on their node ID range order: 1=San Francisco, 2=San Mateo, 3=Santa Clara, 4=Alameda, 5=Contra Costa, 6=Solano, 7=Napa, 8=Sonoma, 9=Marin

MTCCounty

Bases: str, Enum

Nine Bay Area counties in the MTC region.

Source code in models/mtc_roadway_schema.py 
14
15
16
17
18
19
20
21
22
23
24
25
class MTCCounty(str, Enum):
    """Nine Bay Area counties in the MTC region."""
    ALAMEDA = "Alameda"
    CONTRA_COSTA = "Contra Costa"
    MARIN = "Marin"
    NAPA = "Napa"
    SAN_FRANCISCO = "San Francisco"
    SAN_MATEO = "San Mateo"
    SANTA_CLARA = "Santa Clara"
    SOLANO = "Solano"
    SONOMA = "Sonoma"
    EXTERNAL = "External"

ALAMEDA = 'Alameda' class-attribute instance-attribute

CONTRA_COSTA = 'Contra Costa' class-attribute instance-attribute

MARIN = 'Marin' class-attribute instance-attribute

NAPA = 'Napa' class-attribute instance-attribute

SAN_FRANCISCO = 'San Francisco' class-attribute instance-attribute

SAN_MATEO = 'San Mateo' class-attribute instance-attribute

SANTA_CLARA = 'Santa Clara' class-attribute instance-attribute

SOLANO = 'Solano' class-attribute instance-attribute

SONOMA = 'Sonoma' class-attribute instance-attribute

EXTERNAL = 'External' class-attribute instance-attribute

MTCFacilityType

Bases: IntEnum

Functional class (ft) codes for highway assignment.

These codes are used to assign volume delay functions (VDF) in tm2py.

Reference: MTC Network Rebuild Requirements

Code Facility Type Intention Speed Limit Example
1 Freeway Move vehicles across counties 50+ mph I-80
2 Expressway Connect freeways to other freeways or business districts 40-60 mph San Tomas Expressway
3 Ramp Connect arterials to freeways or expressways 20-45 mph Tassajara Road to I-580
4 Divided Arterial Move vehicles across cities 35-50 mph El Camino Real
5 Undivided Arterial Move vehicles across cities 35-45 mph Ashby Ave
6 Collector Collect traffic from local roads and deliver to arterials 25-40 mph Fruitvale Road
7 Local Connect roads to homes 20-35 mph Lance Drive
8 Connector Connects centroids; access/egress links for managed lanes ??
99 Not Assigned Service Road 20 mph Parking lot

Key Characteristics:

  • Controlled Access: Freeway (always), Expressway (sometimes), others (no)
  • Turn Pockets/Lanes: Freeway/Expressway/Ramp (always/N/A), Arterials (nearly always), Collectors (sometimes), Local/Dummy (never)
  • Physical Separation: Freeway/Expressway (always), Ramp/Divided Arterial (usually/nearly always), others (rarely/never)
  • On-street Parking: Never for Freeway/Expressway/Ramp, sometimes for Arterials, usually/always for Collector/Local/Dummy
  • Walkable: Never for Freeway/Ramp, rarely for Expressway, nearly always to always for Arterials/Collectors/Local/Dummy
Source code in models/mtc_roadway_schema.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class MTCFacilityType(IntEnum):
    """Functional class (ft) codes for highway assignment.

    These codes are used to assign volume delay functions (VDF) in tm2py.

    Reference: [MTC Network Rebuild Requirements](https://docs.google.com/document/d/17OeXT8jxIst-vmGLl6eZVXx5b20cmct1p1WOpAuhi0M/edit?usp=sharing)

    | Code | Facility Type       | Intention                                                      | Speed Limit      | Example                  |
    |------|---------------------|----------------------------------------------------------------|------------------|--------------------------|
    | 1    | Freeway             | Move vehicles across counties                                  | 50+ mph          | I-80                     |
    | 2    | Expressway          | Connect freeways to other freeways or business districts       | 40-60 mph        | San Tomas Expressway     |
    | 3    | Ramp                | Connect arterials to freeways or expressways                   | 20-45 mph        | Tassajara Road to I-580  |
    | 4    | Divided Arterial    | Move vehicles across cities                                    | 35-50 mph        | El Camino Real           |
    | 5    | Undivided Arterial  | Move vehicles across cities                                    | 35-45 mph        | Ashby Ave                |
    | 6    | Collector           | Collect traffic from local roads and deliver to arterials      | 25-40 mph        | Fruitvale Road           |
    | 7    | Local               | Connect roads to homes                                         | 20-35 mph        | Lance Drive              |
    | 8    | Connector           | Connects centroids; access/egress links for managed lanes      | ??               |                          |
    | 99   | Not Assigned        | Service Road                                                   | 20 mph           | Parking lot              |

    **Key Characteristics:**

    - **Controlled Access**: Freeway (always), Expressway (sometimes), others (no)
    - **Turn Pockets/Lanes**: Freeway/Expressway/Ramp (always/N/A), Arterials (nearly always), Collectors (sometimes), Local/Dummy (never)
    - **Physical Separation**: Freeway/Expressway (always), Ramp/Divided Arterial (usually/nearly always), others (rarely/never)
    - **On-street Parking**: Never for Freeway/Expressway/Ramp, sometimes for Arterials, usually/always for Collector/Local/Dummy
    - **Walkable**: Never for Freeway/Ramp, rarely for Expressway, nearly always to always for Arterials/Collectors/Local/Dummy
    """
    FREEWAY = 1
    EXPRESSWAY = 2
    RAMP = 3
    DIVIDED_ARTERIAL = 4
    UNDIVIDED_ARTERIAL = 5
    COLLECTOR = 6
    LOCAL = 7
    CONNECTOR = 8
    NOT_ASSIGNED = 99

FREEWAY = 1 class-attribute instance-attribute

EXPRESSWAY = 2 class-attribute instance-attribute

RAMP = 3 class-attribute instance-attribute

DIVIDED_ARTERIAL = 4 class-attribute instance-attribute

UNDIVIDED_ARTERIAL = 5 class-attribute instance-attribute

COLLECTOR = 6 class-attribute instance-attribute

LOCAL = 7 class-attribute instance-attribute

CONNECTOR = 8 class-attribute instance-attribute

NOT_ASSIGNED = 99 class-attribute instance-attribute

MTCUseClass

Bases: IntEnum

Vehicle-class restrictions classification codes.

Used to define link access restrictions (auto-only, HOV only, etc.) in highway assignment.

Source code in models/mtc_roadway_schema.py 
124
125
126
127
128
129
130
131
132
133
class MTCUseClass(IntEnum):
    """Vehicle-class restrictions classification codes.

    Used to define link access restrictions (auto-only, HOV only, etc.)
    in highway assignment.
    """
    GENERAL_PURPOSE = 0
    HOV2 = 2
    HOV3 = 3
    NO_TRUCKS = 4

GENERAL_PURPOSE = 0 class-attribute instance-attribute

HOV2 = 2 class-attribute instance-attribute

HOV3 = 3 class-attribute instance-attribute

NO_TRUCKS = 4 class-attribute instance-attribute

MTCRoadLinksTable

Bases: RoadLinksTable

MTC-specific roadway links table with additional required fields.

Extends the base RoadLinksTable from Network Wrangler with MTC-specific attributes required for Bay Area transportation modeling and highway assignment.

Additional Required Fields

county: County name (must be one of the 9 Bay Area counties) ft: Functional class (used to assign volume delay functions) useclass: Vehicle-class restrictions classification (auto-only, HOV only, etc.) tollbooth: Toll booth location indicator (bridge vs value toll) tollseg: Toll segment index for toll value lookups

Source code in models/mtc_roadway_schema.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
class MTCRoadLinksTable(RoadLinksTable):
    """MTC-specific roadway links table with additional required fields.

    Extends the base RoadLinksTable from Network Wrangler with MTC-specific
    attributes required for Bay Area transportation modeling and highway assignment.

    Additional Required Fields:
        county: County name (must be one of the 9 Bay Area counties)
        ft: Functional class (used to assign volume delay functions)
        useclass: Vehicle-class restrictions classification (auto-only, HOV only, etc.)
        tollbooth: Toll booth location indicator (bridge vs value toll)
        tollseg: Toll segment index for toll value lookups
    """

    # Required MTC fields
    county: Series[str] = Field(coerce=True, nullable=False)
    ft: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None)
    # TODO: Should this be automatically created from the access attribute in the RoadLinksTable?
    useclass: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None)
    tollbooth: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None)
    tollseg: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None)

    @pa.check("county")
    def check_valid_county(cls, county: Series) -> Series[bool]:
        """Validate that county values are valid MTCCounty enum values."""
        valid_counties = {e.value for e in MTCCounty}
        return county.isin(valid_counties)

    @pa.check("ft")
    def check_valid_ft(cls, ft: Series) -> Series[bool]:
        """Validate that ft values are valid MTCFacilityType enum values."""
        valid_fts = {e.value for e in MTCFacilityType}
        # Allow NaN for optional field
        return ft.isna() | ft.isin(valid_fts)

    @pa.check("useclass")
    def check_valid_useclass(cls, useclass: Series) -> Series[bool]:
        """Validate that useclass values are valid MTCUseClass enum values."""
        valid_useclasses = {e.value for e in MTCUseClass}
        # Allow NaN for optional field
        return useclass.isna() | useclass.isin(valid_useclasses)

    class Config(RoadLinksTable.Config):
        """Inherit parent configuration settings."""
        pass

county: Series[str] = Field(coerce=True, nullable=False) class-attribute instance-attribute

ft: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None) class-attribute instance-attribute

useclass: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None) class-attribute instance-attribute

tollbooth: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None) class-attribute instance-attribute

tollseg: Optional[Series[int]] = Field(coerce=True, nullable=True, default=None) class-attribute instance-attribute

Config

Bases: Config

Inherit parent configuration settings.

Source code in models/mtc_roadway_schema.py 
178
179
180
class Config(RoadLinksTable.Config):
    """Inherit parent configuration settings."""
    pass

check_valid_county(county: Series) -> Series[bool]

Validate that county values are valid MTCCounty enum values.

Source code in models/mtc_roadway_schema.py 
158
159
160
161
162
@pa.check("county")
def check_valid_county(cls, county: Series) -> Series[bool]:
    """Validate that county values are valid MTCCounty enum values."""
    valid_counties = {e.value for e in MTCCounty}
    return county.isin(valid_counties)

check_valid_ft(ft: Series) -> Series[bool]

Validate that ft values are valid MTCFacilityType enum values.

Source code in models/mtc_roadway_schema.py 
164
165
166
167
168
169
@pa.check("ft")
def check_valid_ft(cls, ft: Series) -> Series[bool]:
    """Validate that ft values are valid MTCFacilityType enum values."""
    valid_fts = {e.value for e in MTCFacilityType}
    # Allow NaN for optional field
    return ft.isna() | ft.isin(valid_fts)

check_valid_useclass(useclass: Series) -> Series[bool]

Validate that useclass values are valid MTCUseClass enum values.

Source code in models/mtc_roadway_schema.py 
171
172
173
174
175
176
@pa.check("useclass")
def check_valid_useclass(cls, useclass: Series) -> Series[bool]:
    """Validate that useclass values are valid MTCUseClass enum values."""
    valid_useclasses = {e.value for e in MTCUseClass}
    # Allow NaN for optional field
    return useclass.isna() | useclass.isin(valid_useclasses)

MTCRoadNodesTable

Bases: RoadNodesTable

MTC-specific roadway nodes table with additional required fields.

Extends the base RoadNodesTable from Network Wrangler with MTC-specific attributes required for Bay Area transportation modeling.

Additional Required Fields

county: County name (must be one of the 9 Bay Area counties) taz_centroid: Indicates if node is a TAZ (Traffic Analysis Zone) centroid maz_centroid: Indicates if node is a MAZ (Micro-zone) centroid

Source code in models/mtc_roadway_schema.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
class MTCRoadNodesTable(RoadNodesTable):
    """MTC-specific roadway nodes table with additional required fields.

    Extends the base RoadNodesTable from Network Wrangler with MTC-specific
    attributes required for Bay Area transportation modeling.

    Additional Required Fields:
        county: County name (must be one of the 9 Bay Area counties)
        taz_centroid: Indicates if node is a TAZ (Traffic Analysis Zone) centroid
        maz_centroid: Indicates if node is a MAZ (Micro-zone) centroid
    """

    # Required MTC fields
    county: Series[str] = Field(coerce=True, nullable=False)
    taz_centroid: Series[bool] = Field(coerce=True, nullable=False)
    maz_centroid: Series[bool] = Field(coerce=True, nullable=False)

    @pa.check("county")
    def check_valid_county(cls, county: Series) -> Series[bool]:
        """Validate that county values are valid MTCCounty enum values."""
        valid_counties = {e.value for e in MTCCounty}
        return county.isin(valid_counties)

    class Config(RoadNodesTable.Config):
        """Inherit parent configuration settings."""
        pass

county: Series[str] = Field(coerce=True, nullable=False) class-attribute instance-attribute

taz_centroid: Series[bool] = Field(coerce=True, nullable=False) class-attribute instance-attribute

maz_centroid: Series[bool] = Field(coerce=True, nullable=False) class-attribute instance-attribute

Config

Bases: Config

Inherit parent configuration settings.

Source code in models/mtc_roadway_schema.py 
206
207
208
class Config(RoadNodesTable.Config):
    """Inherit parent configuration settings."""
    pass

check_valid_county(county: Series) -> Series[bool]

Validate that county values are valid MTCCounty enum values.

Source code in models/mtc_roadway_schema.py 
200
201
202
203
204
@pa.check("county")
def check_valid_county(cls, county: Series) -> Series[bool]:
    """Validate that county values are valid MTCCounty enum values."""
    valid_counties = {e.value for e in MTCCounty}
    return county.isin(valid_counties)