Community Fault Model Support

[lispandfound]

This pull request adds the ability to read the New Zealand Community Fault Model, and provides a function to estimate the most likely nodal plane of a GCMT solution based on nearby faults in the community model.

An Example of the Solution Classification

>>> from pathlib import Path
>>> model = get_community_fault_model()
>>> centroid = np.array([-45.1929,166.83])
>>> nodal_plane_1 = NodalPlane(strike=20, dip=35, rake=79)
>>> nodal_plane_2 = NodalPlane(strike=213, dip=56, rake=98)
>>> most_likely_plane = most_likely_nodal_plane(model, centroid, nodal_plane_1, nodal_plane_2)
>>> print(most_likely_plane)
NodalPlane(strike=20, dip=35, rake=79)

Reading the Community Fault Model

The model is stored with the package as data, and can be loaded with community_fault_model.get_community_fault_model(). This loads all 880 faults as an array and parses every field of the model into a list of CommunityFault objects. All of the magic numbers in the fault model have been turned to into documented human-readable enumerations. The trace of the fault is turned into a shapely geometry and can be used to compute distances to points, etc. The nodal plane model makes use of this to select the closest points.

>>> from source_modelling import community_fault_model
>>> model = community_fault_model.get_community_fault_model()
>>> model[0]
CommunityFault(trace=<LINESTRING (5249579.297 1448649.963, 5258710.518 1459206.154, 5267525.404 1...>, fault_status=<FaultStatus.ACTIVE_SEISOGENIC: 1>, name='Alpine: Kaniere to Springs Junction', 
domain=<NeotectonicDomain.ALPINE_FAULT: 15>, dip_range=(40.0, 60, 60.0), dip_dir=<CompassDirection.SE: 135>, sense=<MovementSense.DEXTRAL|REVERSE: 3>, secondary_sense=None, rake_range=(115, 135, 1
55), slip_rate=(13.0, 15.0, 17.0), slip_rate_timeframe_pref=None, slip_rate_timeframe_unit=1000, down_dip_depth90=19.4, down_dip_depth_dfc=23.4, down_dip_depth90_method=<DipMethod.ELLIS2021: 1>, d
own_dip_dfc_method=<DipMethod.ELLIS2021: 1>, up_dip_depth=(0.0, 0.0, 0.0), quality_code=1, reference='Litchfield et al. 2013, 2014; Howarth et al. 2018, 2021; Berryman et al. 1992; Yetton 1998, 20
02; Langridge et al. 2010', comments=None)

Load as a GeoPandas Dataframe

>>> from source_modelling import community_fault_model
>>> gdf = community_fault_model.community_fault_model_as_geodataframe()
>>> gdf
                                                                                 trace  ...                                           comments
name                                                                                    ...                                                   
Alpine: Kaniere to Springs Junction  LINESTRING (1448649.963 5249579.297, 1459206.1...  ...                                               None
Awatere: Southwest                   LINESTRING (1628396.718 5347290.144, 1607768.2...  ...  Linework modified to intersect Shingle Peak. S...
Barefell                             LINESTRING (1616103.233 5339229.068, 1614714.9...  ...                                               None
Browning Pass                        LINESTRING (1480098.2 5258937.076, 1478272.534...  ...                                               None
Cheeseman                            LINESTRING (1500504.485 5227109.03, 1500038.81...  ...                                               None
...                                                                                ...  ...                                                ...
Kohaihai South                       LINESTRING (1526112.274 5408185.468, 1527144.0...  ...             added from  Ghisetti et al. CFM update
Leader: South                        LINESTRING (1613661.578 5278037.454, 1619143.5...  ...                                               None
Leader: North                        LINESTRING (1620535.246 5295766.742, 1622334.7...  ...                                               None
Hikurangi                            LINESTRING (1682675.56 5269886.106, 1690639.83...  ...  Single line representation of the Hikurangi de...
Warea                                LINESTRING (1664624.48 5653876.438, 1667765.66...  ...  Fault defined in seismic reflection offsetting...

[880 rows x 19 columns]
>>> gdf.loc['Cheeseman']
trace                       LINESTRING (1500504.4850000003 5227109.0301, 1...
fault_status                                    FaultStatus.ACTIVE_SEISOGENIC
domain                                   NeotectonicDomain.CENTRAL_CANTERBURY
dip_range                                                    (45.0, 60, 70.0)
dip_dir                                                   CompassDirection.NW
sense                                             (((MovementSense.REVERSE)))
secondary_sense                                                          None
rake_range                                                      (70, 90, 110)
slip_rate                                                     (0.1, 0.2, 0.8)
slip_rate_timeframe_pref                                                 None
slip_rate_timeframe_unit                                              10000.0
down_dip_depth90                                                         13.6
down_dip_depth_dfc                                                       18.8
down_dip_depth90_method                                   DipMethod.ELLIS2021
down_dip_dfc_method                                       DipMethod.ELLIS2021
up_dip_depth                                                  (0.0, 0.0, 0.0)
quality_code                                                                3
reference                   Barrell 2013; Cox and Barrell 2007; Pettinga e...
comments                                                                 None
Name: Cheeseman, dtype: object

Testing

The test_community_fault_model.py file contains two tests: first to load the model and check it read all 880 faults, and the second to evaluate the model and ensure it correctly classifies at least 75 of the 99 nodal planes in the solution set. In practice, the model correctly classifies around 80.

[AndrewRidden-Harper]

Looks great. I just left one small text suggestion