rsqsim_api.catalogue.nshm_utilities
===================================

.. py:module:: rsqsim_api.catalogue.nshm_utilities

.. autoapi-nested-parse::

   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 :class:`NshmInversion` class
   for loading OpenSHA fault-system solution directories.



Classes
-------

.. autoapisummary::

   rsqsim_api.catalogue.nshm_utilities.NshmInversion


Functions
---------

.. autoapisummary::

   rsqsim_api.catalogue.nshm_utilities.overall_strike
   rsqsim_api.catalogue.nshm_utilities.overall_strike_resolved_length


Module Contents
---------------

.. py:function:: overall_strike(rup)

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

   :param rup: Rupture trace composed of one or more line segments.
   :type rup: shapely.geometry.MultiLineString

   :returns: Weighted circular mean strike in degrees (0–180 convention as
             returned by :func:`~rsqsim_api.fault.utilities.calculate_strike`).
   :rtype: float


.. py:function:: 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.

   :param rup: Rupture trace.  A single ``LineString`` is automatically wrapped
               in a ``MultiLineString``.
   :type rup: shapely.geometry.MultiLineString or LineString

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


.. py:class:: 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.

   .. attribute:: fault_sections

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

      :type: geopandas.GeoDataFrame or None

   .. attribute:: rates

      Annual occurrence rates for ruptures with rate > 0.

      :type: numpy.ndarray or None

   .. attribute:: properties

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

      :type: pandas.DataFrame or None

   .. attribute:: indices

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

      :type: dict or None

   .. attribute:: num_sections

      Number of sections per rupture.

      :type: list or None

   .. attribute:: rupture_ids

      Indices of ruptures with non-zero annual rate.

      :type: numpy.ndarray or None

   .. attribute:: area

      Rupture areas in m².

      :type: numpy.ndarray or None

   .. attribute:: length

      Rupture lengths in m.

      :type: numpy.ndarray or None

   .. attribute:: mw

      Moment magnitudes.

      :type: numpy.ndarray or None

   .. attribute:: average_slips

      Average slip per rupture in m.

      :type: numpy.ndarray or None


   .. py:attribute:: fault_sections
      :value: None



   .. py:attribute:: rates
      :value: None



   .. py:attribute:: properties
      :value: None



   .. py:attribute:: indices
      :value: None



   .. py:attribute:: num_sections
      :value: None



   .. py:attribute:: rupture_ids
      :value: None



   .. py:attribute:: area
      :value: None



   .. py:attribute:: length
      :value: None



   .. py:attribute:: mw
      :value: None



   .. py:attribute:: average_slips
      :value: None



   .. py:method:: 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 :attr:`indices`
      and :attr:`num_sections`.

      :param indices_csv: Path to ``ruptures/indices.csv`` inside the solution
                          directory.
      :type indices_csv: str

      :raises AssertionError: If :attr:`rupture_ids` has not been set, or if the file
          does not exist.



   .. py:method:: 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.

      :param directory: 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``.
      :type directory: str



   .. py:method:: get_rupture_geometry(rupture_index)

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

      :param rupture_index: Rupture ID from :attr:`rupture_ids`.
      :type rupture_index: int

      :returns: Union of all fault-section geometries participating in the
                specified rupture.
      :rtype: shapely.geometry.base.BaseGeometry



   .. py:method:: 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.
      :rtype: geopandas.GeoDataFrame



   .. py:method:: ruptures_to_geojson(filename)

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

      :param filename: Output GeoJSON file path.
      :type filename: str