API Reference

Data layer

Loads and caches raw fault model data, exposing enriched subsections/ruptures tables that every other layer builds on.

parserf.models

Data access layer for earthquake rupture forecast fault model datasets.

class FaultModel(*values)[source]

Bases: IntEnum

Fault model identifiers with shorthand integer values.

Variables:

  • NSHMP_2023 – USGS NSHM CONUS v6.0.0.

  • UCERF3_31 – UCERF3 fault model 3.1 (USGS v5.3-maint).

  • UCERF3_32 – UCERF3 fault model 3.2 (USGS v5.3-maint).

class FaultModelDataset(model)[source]

Bases: object

Data access layer for earthquake rupture forecast fault model datasets.

Provides cached access to earthquake rupture forecast data files for different fault models including NSHMP 2023, UCERF3 v3.1, and UCERF3 v3.2. Handles file loading and provides structured access to parent IDs, fault subsections, and rupture scenarios.

Parameters:

model (FaultModel) – The fault model version.

Variables:

  • parent_ids – DataFrame with columns parent_id (int) and parent_name (str).

  • subsections – DataFrame of fault subsections indexed by index (int) with columns for geometry, dimensions, and parent fault info.

  • ruptures – Rupture data with parsed subsection indices as sets of integers.

  • grid – DataFrame of background gridded seismicity with columns lon, lat, ss_wt, r_wt, n_wt, and magnitude bin annual rates.

Examples

>>> from parserf.models import FaultModel, FaultModelDataset
>>> dataset = FaultModelDataset(FaultModel.UCERF3_31)
>>> parent_ids = dataset.parent_ids
>>> subsections = dataset.subsections
>>> ruptures = dataset.ruptures
property parent_ids: DataFrame

Load parent IDs for the selected fault model.

property grid: DataFrame

Background gridded seismicity rates for the selected fault model.

property ruptures: DataFrame

Scenario ruptures with parsed subsection indices as integer sets.

Zero-rate ruptures are dropped. The DataFrame index preserves the row number from the source ruptures.csv file, which serves as the rupture id; this means the index can have gaps where zero-rate rows were removed.

property subsections: DataFrame

Fault subsections with computed dimensions and parent fault names.

A DataFrame indexed by subsection index (int) containing all columns from the raw GeoJSON sections plus computed length_km, width_km, area_km2, and looked-up parent_name. Built once per dataset and shared across view objects.

get_parent_fault_id(*, name)[source]

Return the integer parent fault ID for a given parent fault name.

Parameters:

name (str) – The parent fault name (e.g., “Airport Lake”).

Returns:

The integer parent fault ID.

Raises:

ValueError – If the parent fault name is not found in the dataset.

Return type:

int

Spatial queries

Standalone functions that take a dataset and a coordinate: find the nearest subsection, list nearby subsections/parents, or pull ruptures near a site.

parserf.queries

Spatial and rupture query functions for earthquake rupture forecast datasets.

get_nearest_subsection_index(dataset, *, lat, lon)[source]

Return the subsection index closest to a geographic coordinate.

Distance is measured to each subsection’s map-view footprint (the dipping surface projected to the ground), not just its surface trace — see _distances_km(). A coordinate over the hanging wall of a dipping fault can therefore resolve to that fault even far from its trace.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset to query.

  • lat (float) – Latitude in decimal degrees.

  • lon (float) – Longitude in decimal degrees.

Returns:

The integer index of the nearest fault subsection.

Return type:

int

get_subsections_list(dataset, *, lat, lon, dist_km)[source]

Return subsection indices within a distance of a geographic coordinate.

Distance is measured to each subsection’s map-view footprint (the dipping surface projected to the ground), not just its surface trace — see _distances_km(). A coordinate over the hanging wall of a dipping fault is within range even far from its trace.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset to query.

  • lat (float) – Latitude in decimal degrees.

  • lon (float) – Longitude in decimal degrees.

  • dist_km (float) – Search radius in kilometers.

Returns:

List of subsection indices within dist_km, sorted by distance (nearest first).

Return type:

list[int]

get_parents_list(dataset, *, lat, lon, dist_km)[source]

Return parent fault IDs within a distance of a geographic coordinate.

Distance is measured to each child subsection’s map-view footprint (the dipping surface projected to the ground), not just its surface trace — see _distances_km().

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset to query.

  • lat (float) – Latitude in decimal degrees.

  • lon (float) – Longitude in decimal degrees.

  • dist_km (float) – Search radius in kilometers.

Returns:

List of unique parent fault IDs whose nearest child subsection is within dist_km, sorted by the distance of their closest child (nearest first).

Return type:

list[int]

get_ruptures_near(dataset, *, lat, lon, dist_km)[source]

Return enriched ruptures involving any subsection within a distance of a coordinate.

Distance is measured to each subsection’s map-view footprint (the dipping surface projected to the ground), not just its surface trace — see _distances_km().

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset to query.

  • lat (float) – Latitude in decimal degrees.

  • lon (float) – Longitude in decimal degrees.

  • dist_km (float) – Search radius in kilometers.

Returns:

4326) with one row per rupture: merged geometry, length_km, area_km2, and a contributions column (a list of (parent_id, area_pct) tuples, summing to 100, for every parent the rupture touches). Call rups.explode("contributions") for one row per (rupture, parent).

Return type:

GeoDataFrame (EPSG

Subsection & parent views

Facades over a single fault subsection or parent fault, each exposing .data (attributes) and .ruptures (participation + MFDs).

parserf.subsection

Fault subsection view objects for earthquake rupture forecast datasets.

class FaultSubsectionData(dataset, *, index)[source]

Bases: object

Dataset-backed view of a single subsection’s local attributes.

All values are read from the dataset’s internal subsection cache; nothing is recomputed.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • index (int) – The subsection index within the fault model.

Variables:

  • fault_model – The fault model enum value.

  • index – Subsection index.

  • name – Subsection name (e.g., “Airport Lake (0)”).

  • parent_id – Integer ID of the parent fault.

  • parent_name – Name of the parent fault.

  • upper_depth_km – Upper seismogenic depth in km.

  • lower_depth_km – Lower seismogenic depth in km.

  • dip – Fault dip angle in degrees.

  • dip_direction – Dip direction in degrees.

  • aseismicity – Aseismicity factor (0 to 1).

  • geometry – Shapely LineString of the surface trace (EPSG:4326).

  • geometry_3d – Shapely PolygonZ of the dipping fault surface (EPSG:4326).

  • length_km – Geodesic length of the surface trace in km.

  • width_km – Down-dip width in km.

  • area_km2 – Fault area in km².

property fault_model: FaultModel

The fault model enum value.

property index: int

Subsection index.

property name: str

Subsection name (e.g., “Airport Lake (0)”).

property parent_id: int

Integer ID of the parent fault.

property parent_name: str

Name of the parent fault.

property upper_depth_km: float

Upper seismogenic depth in km.

property lower_depth_km: float

Lower seismogenic depth in km.

property dip: float

Fault dip angle in degrees.

property dip_direction: float

Dip direction in degrees.

property aseismicity: float

Aseismicity factor (0 to 1).

property geometry

4326).

Type:

Shapely LineString of the surface trace (EPSG

property geometry_3d

4326).

The surface trace is hung down-dip to its lower seismogenic depth: each trace vertex forms the top edge at upper_depth_km, offset down-dip (geodesically, along dip_direction) and dropped to lower_depth_km for the bottom edge. Coordinates are (lon, lat, depth_km) with depth positive-down.

The surface is generally non-planar (the trace may bend), so Shapely’s 2D .area and .length are not meaningful on it; use area_km2 and length_km instead.

Returns:

4326).

Return type:

Shapely PolygonZ of the dipping surface (EPSG

Type:

Shapely PolygonZ of the dipping fault surface (EPSG

property length_km: float

Geodesic length of the surface trace in kilometers.

property width_km: float

Down-dip width in kilometers.

property area_km2: float

Area in square kilometers (length times width).

class FaultSubsectionRuptures(dataset, *, index)[source]

Bases: object

Dataset-backed view of a single subsection’s rupture participation.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • index (int) – The subsection index within the fault model.

Variables:

participating_ruptures – GeoDataFrame of ruptures involving this subsection.

property cumulative_mfd: DataFrame

Cumulative magnitude frequency distribution for participating ruptures.

Returns a DataFrame with columns magnitude (sorted ascending) and cumulative_rate (exceedance rate, i.e. sum of rates for all ruptures at or above each magnitude).

property participating_ruptures: GeoDataFrame

GeoDataFrame of ruptures involving this subsection.

Returns a GeoDataFrame (EPSG:4326) with one row per rupture, plus merged geometry, length_km, area_km2, and a contributions column. contributions is a list of (parent_id, area_pct) tuples for every parent the rupture touches (summing to 100); rate is the full rupture rate, so attributed rate is rate * area_pct / 100. Call rups.explode("contributions") for one row per (rupture, parent).

class FaultSubsection(dataset, *, index)[source]

Bases: object

Thin facade over a single fault subsection.

Validates that the subsection index exists in the dataset, then exposes .data for subsection-local attributes and .ruptures for rupture-query logic.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • index (int) – The subsection index within the fault model.

Raises:

ValueError – If the subsection index is not found in the dataset.

Examples

>>> from parserf.models import FaultModel, FaultModelDataset
>>> from parserf.subsection import FaultSubsection
>>> ds = FaultModelDataset(FaultModel.UCERF3_31)
>>> sub = FaultSubsection(ds, index=0)
>>> sub.data.name
'Airport Lake (0)'
>>> sub.data.length_km  # geodesic length in km
7.8...
property index: int

Subsection index.

property data: FaultSubsectionData

Subsection-local attributes and geometry.

property ruptures: FaultSubsectionRuptures

Rupture participation data.

parserf.parent

Parent fault view objects for earthquake rupture forecast datasets.

class ParentFaultData(dataset, *, parent_id)[source]

Bases: object

Dataset-backed view of a parent fault’s subsection attributes.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • parent_id (int) – The parent fault integer ID.

Variables:

  • fault_model – The fault model enum value.

  • name – Parent fault name.

  • parent_id – Integer ID of the parent fault.

  • subsections – DataFrame of all child subsection attributes.

  • geometry – Merged, right-hand-rule oriented surface trace (Shapely LineString).

  • geometry_3d – Merged dipping fault surface (Shapely PolygonZ).

property fault_model: FaultModel

The fault model enum value.

property name: str

Parent fault name.

property parent_id: int

Integer ID of the parent fault.

property subsections: DataFrame

DataFrame of all child subsection attributes.

Columns include index, name, dip, dip_direction, upper_depth_km, lower_depth_km, aseismicity, length_km, width_km, area_km2, and geometry.

property geometry

Oriented 2D surface trace of the parent fault as a Shapely LineString.

Mirrors FaultSubsectionData.geometry: the parent’s coordinates as a single LineString. The child subsection traces are merged and oriented such that, when walking along the trace, the dip direction is to your right (right-hand rule). For vertical faults (dip ~ 90 degrees), the original order is preserved.

Per-subsection scalars (dip, depths, areas, etc.) are not aggregated here; read them from subsections and aggregate as needed.

Returns:

4326).

Return type:

LineString of the merged, oriented surface trace (EPSG

property geometry_3d

Merged dipping fault surface of the parent as a single Shapely PolygonZ.

The 3D counterpart to geometry: the child subsection surfaces are stitched along the merged, right-hand-rule oriented trace into a single closed PolygonZ. Each vertex is hung down-dip from upper_depth_km to lower_depth_km using its own subsection’s dip and dip_direction. Coordinates are (lon, lat, depth_km) with depth positive-down.

Child subsections are contiguous, so this is always a single hole-free PolygonZ. The surface is generally non-planar, so Shapely’s 2D .area and .length are not meaningful on it.

Returns:

4326).

Return type:

Shapely PolygonZ of the merged dipping surface (EPSG

class ParentFaultRuptures(dataset, *, parent_id)[source]

Bases: object

Dataset-backed view of rupture participation across a parent fault’s subsections.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • parent_id (int) – The parent fault integer ID.

property participating_ruptures: GeoDataFrame

GeoDataFrame of ruptures involving any child subsection of this parent fault.

Returns a GeoDataFrame (EPSG:4326) with one row per rupture, including a contributions column: a list of (parent_id, area_pct) tuples for every parent the rupture touches (not just this one), summing to 100. rate is the full rupture rate, so a parent’s attributed rate is rate * area_pct / 100. Call rups.explode("contributions") for one row per (rupture, parent), then filter on parent_id to isolate this parent’s rows.

property cumulative_mfds: DataFrame

Cumulative magnitude frequency distributions for all child subsections.

Returns a DataFrame with columns index (subsection index), magnitude, and cumulative_rate, ordered by ascending subsection index.

class ParentFault(dataset, *, name)[source]

Bases: object

Thin facade over a parent fault and its child subsections.

Validates that the parent fault name exists in the dataset, then exposes .data for subsection attributes and .ruptures for rupture-query logic.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • name (str) – The parent fault name (e.g., “Airport Lake”).

Raises:

ValueError – If the parent fault name is not found in the dataset.

Examples

>>> from parserf.models import FaultModel, FaultModelDataset
>>> from parserf.parent import ParentFault
>>> ds = FaultModelDataset(FaultModel.UCERF3_31)
>>> flt = ParentFault(ds, name="Airport Lake")
>>> flt.data.name
'Airport Lake'
>>> flt.data.subsections
...
property data: ParentFaultData

Parent fault attributes and child subsection data.

property ruptures: ParentFaultRuptures

Rupture participation data across child subsections.

Batch selection

Batch access for downstream source-model building: many parent faults’ subsections and ruptures in one rupture-table scan, plus background gridded seismicity near a site.

parserf.selection

Parent fault selection for batch earthquake rupture forecast queries.

class ParentSelection(dataset, parent_ids)[source]

Bases: object

Scoped view of a dataset for a set of parent faults.

Provides efficient batch access to subsection attributes, parent summaries, and enriched rupture data for all subsections belonging to the selected parents.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • parent_ids (list[int]) – Ordered list of parent fault IDs to include. Duplicates are de-duplicated, preserving first-occurrence order.

Raises:

ValueError – If any parent fault ID is not found in the dataset.

Examples

>>> from parserf.models import FaultModel, FaultModelDataset
>>> from parserf.queries import get_parents_list
>>> from parserf.selection import ParentSelection
>>> ds = FaultModelDataset(FaultModel.UCERF3_31)
>>> pids = get_parents_list(ds, lat=35.77, lon=-117.60, dist_km=150)
>>> sel = ParentSelection(ds, pids)
>>> sel.parents
...
>>> sel.ruptures
...
property parent_ids: list[int]

Input parent fault IDs in their original order.

property subsections: DataFrame

All subsections for the selected parents (full extent).

Returns the subset of dataset.subsections whose parent_id is in the selection, preserving the original index and columns.

property parents: GeoDataFrame

Per-parent summary with oriented surface trace.

Returns a GeoDataFrame indexed by parent_id (in input order) with columns parent_name and geometry (oriented surface trace as LineString, EPSG:4326).

property ruptures: GeoDataFrame

Enriched ruptures for all subsections of the selected parents.

Returns a GeoDataFrame (EPSG:4326) with one row per rupture, indexed by rupture id. Columns: m, rate, geometry, length_km, area_km2, and contributions — a list of (parent_id, area_pct) tuples for every parent the rupture touches (not just parents in the selection), summing to 100. rate is the full rupture rate, so a parent’s attributed rate is rate * area_pct / 100.

Call rups.explode("contributions") for one row per (rupture, parent), then filter on parent_id to isolate specific parents.

class GridSelection(dataset, *, lat, lon, dist_km)[source]

Bases: object

Scoped view of background gridded seismicity within a radius of a site.

Filters dataset.grid to grid points within a geodesic distance of the given coordinate.

Parameters:

  • dataset (FaultModelDataset) – The fault model dataset backing this view.

  • lat (float) – Site latitude in decimal degrees.

  • lon (float) – Site longitude in decimal degrees.

  • dist_km (float) – Search radius in kilometers.

Examples

>>> from parserf.models import FaultModel, FaultModelDataset
>>> from parserf.selection import GridSelection
>>> ds = FaultModelDataset(FaultModel.UCERF3_31)
>>> gs = GridSelection(ds, lat=34.05, lon=-118.25, dist_km=50)
>>> gs.grid
...
property grid: DataFrame

Grid points within the search radius, sorted by distance (nearest first).

Returns the subset of dataset.grid with an additional dist_km column indicating geodesic distance from the site to each grid point.