Epic Feature: enhanced participation rate options

[chrisbc]

ref (GNS-Science/solvis-graphql-api#46 (comment))
and GNS-Science/kororaa#455

Our support for participation rate can be improved/formalisedrounded so that the various use cases for this concept are all supported, clearly defined and named well.

We want to be able to filter for fault participation rate. This is the combined rate for all subsections on that "parent" fault (i.e. the highest cumulative MFD rate for all subsections of the fault)`

Overview

There are 3) levels where we want to calculate and use Participation Rate values:

1. at the subsection level
2. at the fault level (aka ParentFault) level
3. at the named-fault level - where named faults is a mapping from each fault (by name) to a parent named-fault
   NB this one needs the mapping data, which is not included in the NSHM_1.* inversion solutions.

And, there are two options when calculating rates:

• A. the participation rate including all ruptures within the solution (i.e. the entire fault system )
  NB this option may be used as a filter criteria itself
• B. the participation rate for a given set up ruptures - where the user had narrowed these down using some criteria. eg. i) just those ruptures intersecting a given a polygon, or ii) ruptures exceeding some magnitude, or iii) involving some particular fault.

see discussion in GNS-Science/solvis-graphql-api#59 where B is called the "Conditional Participation Rate" and A) the "Participation Rate"

Done Criteria

• provide a dataframe series/function for each permutation of the discussion above:
  • subsection_participation_rate
  • fault_participation_rate
  • subsection_conditional_participation_rate
  • fault_conditional_participation_rate
• update solvis documentation to explain all this
• use caching where applicable to maximise performance

split out to new tickets

• feature use 'normalised_rate_name` so that the different series names for FSS vs IS are handled transparently. #47
• Feature: named_fault_participation_rate #49
• Feature: named_conditional_fault_participation_rate #50
• Feature: make FilterParentFaultIds a ChainableSet subclass #51
• Feature: reorg inversion_solution modules #52

Related tickets:

• Feature: participation rate filter kororaa#455
• Feature: provide parent fault participation rate filter solvis-graphql-api#46
• Feature: differentiate Participation Rate (system) vs Conditional Participation Rate  solvis-graphql-api#59
• EPIC: migrate solvis-graphql-api features  #30
• Feature Request: Co-rupture multi-rupture solvis-graphql-api#31 which is dependent on the participation rate

[chrisbc]

NamedFaults

The Rupture Set RmlsZToxMDAwODc= is used in all NSHM_V1.0.* crustal Inversion Solutions. This rupture set used the
fault_model: CFM_1_0A_DOM_SANSTVZ

and it looks like this is defined here: https://github.com/GNS-Science/nzshm-opensha/blob/main/src/main/resources/faultModels/cfm_1_0A_no_tvz.xml.FaultsByNameAlt.txt

TODO:

• check that all the fault names in current NSHM model align wiht this mapping, and then ...
• include this mapping in solvis (as a workaround to support the historic solutions)
• ask for the mapping to be included in future opensha solutions