rsqsim_api.catalogue.nshm_utilities

Utilities for reading and processing New Zealand NSHM inversion results.

Provides functions for computing overall rupture strike and resolved length from multi-segment traces, and the NshmInversion class for loading OpenSHA fault-system solution directories.

Classes

NshmInversion

Reader for an OpenSHA fault-system inversion solution directory.

Functions

overall_strike(rup)	Compute the length-weighted mean strike of a multi-segment rupture.
overall_strike_resolved_length(rup)	Compute the resolved length of a rupture along its mean strike direction.

Module Contents

rsqsim_api.catalogue.nshm_utilities.overall_strike(rup)

Compute the length-weighted mean strike of a multi-segment rupture.

Parameters:

rup (shapely.geometry.MultiLineString) – Rupture trace composed of one or more line segments.

Returns:

Weighted circular mean strike in degrees (0–180 convention as returned by calculate_strike()).

Return type:

float

rsqsim_api.catalogue.nshm_utilities.overall_strike_resolved_length(rup)

Compute the resolved length of a rupture along its mean strike direction.

Projects all rupture vertices onto the overall strike vector and returns the range (max minus min) of those projections.

Parameters:

rup (shapely.geometry.MultiLineString or LineString) – Rupture trace. A single LineString is automatically wrapped in a MultiLineString.

Returns:

Resolved rupture length in the same units as the input geometry (metres for NZTM).

Return type:

float

class rsqsim_api.catalogue.nshm_utilities.NshmInversion

Reader for an OpenSHA fault-system inversion solution directory.

Loads fault sections, rupture rates, properties, connectivity indices, and average slips from an NSHM inversion output directory in the standard OpenSHA CSV/GeoJSON layout.

fault_sections

GeoDataFrame of fault-section geometries (EPSG:2193).

Type:

geopandas.GeoDataFrame or None

rates

Annual occurrence rates for ruptures with rate > 0.

Type:

numpy.ndarray or None

properties

Rupture properties (area, length, magnitude) for non-zero-rate ruptures.

Type:

pandas.DataFrame or None

indices

Mapping of rupture ID to array of participating fault-section indices.

Type:

dict or None

num_sections

Number of sections per rupture.

Type:

list or None

rupture_ids

Indices of ruptures with non-zero annual rate.

Type:

numpy.ndarray or None

area

Rupture areas in m².

Type:

numpy.ndarray or None

length

Rupture lengths in m.

Type:

numpy.ndarray or None

mw

Moment magnitudes.

Type:

numpy.ndarray or None

average_slips

Average slip per rupture in m.

Type:

numpy.ndarray or None

fault_sections = None

rates = None

properties = None

indices = None

num_sections = None

rupture_ids = None

area = None

length = None

mw = None

average_slips = None

read_indices(indices_csv)

Read the rupture–section connectivity index file.

Parses a CSV where each row lists a rupture ID, the number of sections, and the section indices. Populates indices and num_sections.

Parameters:

indices_csv (str) – Path to ruptures/indices.csv inside the solution directory.

Raises:

AssertionError – If rupture_ids has not been set, or if the file does not exist.

read_nshm_inversion(directory)

Load an NSHM inversion solution from a directory.

Reads rates, fault sections, properties, connectivity indices, and average slips. Only ruptures with a positive annual rate are retained.

Parameters:

directory (str) – Path to the inversion solution directory, which must contain: solution/rates.csv, ruptures/fault_sections.geojson, ruptures/properties.csv, ruptures/indices.csv, and ruptures/average_slips.csv.

get_rupture_geometry(rupture_index)

Return the unary union geometry of all sections for a rupture.

Parameters:

rupture_index (int) – Rupture ID from rupture_ids.

Returns:

Union of all fault-section geometries participating in the specified rupture.

Return type:

shapely.geometry.base.BaseGeometry

ruptures_to_gdf()

Build a GeoDataFrame of all non-zero-rate ruptures.

For each rupture, computes the unary-union geometry of its sections, the resolved length along the mean strike, and assembles rate, area, length, magnitude, and average slip.

Returns:

GeoDataFrame (EPSG:2193) with one row per rupture and columns ["rate", "area", "length", "mw", "average_slip", "geometry", "resolved_length"]. resolved_length is in km.

Return type:

geopandas.GeoDataFrame

ruptures_to_geojson(filename)

Write all non-zero-rate ruptures to a GeoJSON file.

Parameters:

filename (str) – Output GeoJSON file path.