fix some docstrings;

solvis/solution/solution_participation.py

@@ -6,7 +6,7 @@
 
 import pandas as pd
 
-from solvis.filter import FilterSubsectionIds
+from solvis.filter import FilterSubsectionIds, FilterParentFaultIds
 
 from .typing import InversionSolutionProtocol
 
@@ -34,8 +34,9 @@ class SolutionParticipation:
         ```
 
     Methods:
-        section_participation_rates:  get rates for the specified fault sections.
-        fault_participation_rates: get rates for specificed faults.
+        section_participation_rates:  get rates for fault sections.
+        fault_participation_rates: get rates for parent faults.
+        named_fault_participation_rates: get rates for named faults
     """
 
     def __init__(self, solution: InversionSolutionProtocol):
@@ -58,9 +59,9 @@ def section_participation_rates(
             rupture_ids: calculate participation using only these ruptures (aka `Conditional Participation`).
 
         Notes:
-         - Passing a non empty `subsection_ids` will not affect the rates, only the subsections for
+         - Passing a non empty `subsection_ids` does not affect the rates, only the subsections for
            which rates are returned.
-         - Passing a non empty `rupture_ids` will affect the rates, as only the specified ruptures
+         - Passing a non empty `rupture_ids` affects the rate calculation, as only the specified ruptures
            will be included in the sum.
            This is referred to as the `conditional participation rate` which might be used when you are
            only interested in the rates of e.g. ruptures in a particular magnitude range.
@@ -107,9 +108,9 @@ def fault_participation_rates(
             rupture_ids: calculate participation using only these ruptures (aka Conditional Participation).
 
         Notes:
-         - Passing `parent_fault_ids` will not affect the rate calculation, only the parent faults
+         - Passing `parent_fault_ids` does not affect the rate calculation, only the parent faults
            for which rates are returned.
-         - Passing `rupture_ids` will affect the rates, as only the specified ruptures
+         - Passing `rupture_ids` affects the rate calculation, as only the specified ruptures
            will be included in the sum.
            This is referred to as the `conditional participation rate` which might be used when you are
            only interested in e.g. the rates of ruptures in a particular magnitude range.
@@ -141,3 +142,34 @@ def fault_participation_rates(
             .agg('sum')
         )
         return cast('DataFrame[dataframe_models.ParentFaultParticipationSchema]', result)
+
+
+    def named_fault_participation_rates(
+        self, named_fault_names: Optional[Iterable[str]] = None, rupture_ids: Optional[Iterable[int]] = None
+    ) -> 'DataFrame[dataframe_models.ParentFaultParticipationSchema]':
+        """Calculate the 'participation rate' for parent faults.
+
+        Participation rate for each named fault is the the sum of rupture rates for the
+        ruptures involving that fault.
+
+        Args:
+            named_fault_names: the list of named_fault_names to include.
+            rupture_ids: calculate participation using only these ruptures (aka Conditional Participation).
+
+        Notes:
+         - Passing `named_fault_names` does not affect the rate calculation, only the faults
+           for which rates are returned.
+         - Passing `rupture_ids` affects the rate calculation, as only the specified ruptures
+           will be included in the sum.
+           This is referred to as the `conditional participation rate` which might be used when you are
+           only interested in e.g. the rates of ruptures in a particular magnitude range.
+
+        Returns:
+            pd.DataFrame: a participation rates dataframe
+        """
+        parent_fault_ids = FilterParentFaultIds(self._solution).for_named_fault_names(named_fault_names)
+
+        subsection_ids = (
+            FilterSubsectionIds(self._solution).for_parent_fault_ids(parent_fault_ids) if parent_fault_ids else None
+        )
+        raise NotImplementedError()