mergeron 2025.739319.3__py3-none-any.whl → 2025.739341.9__py3-none-any.whl

mergeron/core/ftc_merger_investigations_data.py

@@ -1,8 +1,7 @@
 """
-Methods to parse FTC Merger Investigations Data, downloading source documents
-as necessary
+Methods to parse FTC Merger Investigations Data, downloading source documents as needed.
 
-NOTES
+Notes
 -----
 Reported row and column totals from source data are not stored.
 
@@ -19,7 +18,6 @@ from types import MappingProxyType
 from typing import Any
 from zipfile import ZIP_DEFLATED, ZipFile
 
-import msgpack_numpy as m  # type: ignore
 import numpy as np
 import urllib3
 from bs4 import BeautifulSoup
@@ -38,8 +36,6 @@ from . import (
 
 __version__ = VERSION
 
-m.patch()
-
 WORK_DIR = globals().get("WORK_DIR", PKG_WORK_DIR)
 """Redefined, in case the user defines WORK_DIR betweeen module imports."""
 
@@ -49,7 +45,7 @@ if not FID_WORK_DIR.is_dir():
 
 INVDATA_ARCHIVE_PATH = WORK_DIR / mdat.FTC_MERGER_INVESTIGATIONS_DATA.name
 if not INVDATA_ARCHIVE_PATH.is_file():
-    shutil.copy2(mdat.FTC_MERGER_INVESTIGATIONS_DATA, INVDATA_ARCHIVE_PATH)
+    shutil.copy2(mdat.FTC_MERGER_INVESTIGATIONS_DATA, INVDATA_ARCHIVE_PATH)  # type: ignore
 
 TABLE_NO_RE = re.compile(r"Table \d+\.\d+")
 TABLE_TYPES = ("ByHHIandDelta", "ByFirmCount")
@@ -95,6 +91,7 @@ CNT_FCOUNT_DICT = {
 
 
 def reverse_map(_dict: Mapping[Any, Any]) -> Mapping[Any, Any]:
+    """Reverse a mapping."""
     return {_v: _k for _k, _v in _dict.items()}
 
 
@@ -105,8 +102,7 @@ def construct_data(
     flag_pharma_for_exclusion: bool = True,
     rebuild_data: bool = False,
 ) -> INVData:
-    """Construct FTC merger investigations data for non-overlapping periods,
-    from reported data on cumulative periods.
+    """Construct FTC merger investigations data for added non-overlapping periods.
 
     FTC merger investigations data are reported in cumulative periods,
     e.g., 1996-2003 and 1996-2011, but the analyst may want data reported in
@@ -114,10 +110,7 @@ def construct_data(
     reported merger investigations data, the above example is the only instance
     in which the 1996-2003 data can be subtracted from the cumulative data to
     extract merger investigations data for the later period.
-    See also, Kwoka [1]_, Sec. 2.3.3.
-
-    .. [1] Kwoka, J., Greenfield, D., & Gu, C. (2015). Mergers, merger control,
-       and remedies: A retrospective analysis of U.S. policy. MIT Press.
+    See also, Kwoka, Sec. 2.3.3. [#]_
 
     Parameters
     ----------
@@ -133,8 +126,13 @@ def construct_data(
     -------
         A dictionary of merger investigations data keyed to reporting periods
 
-    """
+    References
+    ----------
 
+    .. [#] Kwoka, J., Greenfield, D., & Gu, C. (2015). Mergers, merger control,
+       and remedies: A retrospective analysis of U.S. policy. MIT Press.
+
+    """
     if _archive_path.is_file() and not rebuild_data:
         with (
             ZipFile(_archive_path, "r") as _yzh,
@@ -256,7 +254,7 @@ def _construct_no_evidence_data(_invdata: INVData_in, _data_period: str, /) -> N
 
 
 def _construct_new_period_data(
-    _invdata: INVData,
+    _invdata: INVData_in,
     _data_period: str,
     /,
     *,
@@ -396,6 +394,7 @@ def _construct_new_period_data(
 def invdata_build_aggregate_table(
     _data_typesub: dict[str, INVTableData], _aggr_table_list: Sequence[str]
 ) -> INVTableData:
+    """Aggregate selected FTC merger investigations data tables within a given time period."""
     hdr_table_no = _aggr_table_list[0]
 
     return INVTableData(
@@ -424,16 +423,16 @@ def _parse_invdata() -> INVData:
         by range of HHI and ∆HHI.
 
     """
-    # raise ValueError(
-    #     "This function is defined here as documentation.\n"
-    #     "NOTE: License for `pymupdf`, upon which this function depends,"
-    #     " may be incompatible with the MIT license,"
-    #     " under which this pacakge is distributed."
-    #     " Making this fumction operable requires the user to modify"
-    #     " the source code as well as to install an additional package"
-    #     " not distributed with this package or identified as a requirement."
-    # )
-    import pymupdf  # type: ignore  # noqa: PLC0415
+    raise ValueError(
+        "This function is defined here as documentation.\n"
+        "NOTE: License for `pymupdf`, upon which this function depends,"
+        " may be incompatible with the MIT license,"
+        " under which this pacakge is distributed."
+        " Making this fumction operable requires the user to modify"
+        " the source code as well as to install an additional package"
+        " not distributed with this package or identified as a requirement."
+    )
+    import pymupdf  # type: ignore
 
     invdata_docnames = _download_invdata(FID_WORK_DIR)
 
@@ -591,7 +590,7 @@ def _parse_table_blocks(
     )
 
     table_array = process_table_func(_table_blocks)
-    if not isinstance(table_array, np.ndarray) or table_array.dtype != np.uint64:
+    if not isinstance(table_array, np.ndarray) or table_array.dtype != int:
         print(table_num)
         print(_table_blocks)
         raise ValueError
@@ -612,7 +611,7 @@ def _process_table_blks_conc_type(
     conc_row_pat = re.compile(r"((?:0|\d,\d{3}) (?:- \d+,\d{3}|\+)|TOTAL)")
 
     col_titles_array = tuple(CONC_DELTA_DICT.values())
-    col_totals: ArrayBIGINT = np.zeros(len(col_titles_array), np.uint64)
+    col_totals: ArrayBIGINT = np.zeros(len(col_titles_array), int)
     invdata_array: ArrayBIGINT = np.array(None)
 
     for tbl_blk in _table_blocks:
@@ -620,7 +619,7 @@ def _process_table_blks_conc_type(
             row_list: list[str] = _blk_str.strip().split("\n")
             row_title: str = row_list.pop(0)
             row_key: int = CONC_HHI_DICT[row_title]
-            row_total = np.array(row_list.pop().replace(",", "").split("/"), np.uint64)
+            row_total = np.array(row_list.pop().replace(",", "").split("/"), int)
             row_array_list: list[list[int]] = []
             while row_list:
                 enfd_val, clsd_val = row_list.pop(0).split("/")
@@ -633,7 +632,7 @@ def _process_table_blks_conc_type(
                         int(enfd_val) + int(clsd_val),
                     ]
                 ]
-            row_array = np.array(row_array_list, np.uint64)
+            row_array = np.array(row_array_list, int)
             # Check row totals
             assert_array_equal(row_total, np.einsum("ij->j", row_array[:, 2:4]))
 
@@ -669,14 +668,12 @@ def _process_table_blks_cnt_type(
     cnt_row_pat = re.compile(r"(\d+ (?:to \d+|\+)|TOTAL)")
 
     invdata_array: ArrayBIGINT = np.array(None)
-    col_totals: ArrayBIGINT = np.zeros(3, np.uint64)  # "enforced", "closed", "total"
+    col_totals: ArrayBIGINT = np.zeros(3, int)  # "enforced", "closed", "total"
 
     for _tbl_blk in _table_blocks:
         if cnt_row_pat.match(_blk_str := _tbl_blk[-3]):
             row_list_s = _blk_str.strip().replace(",", "").split("\n")
-            row_list = np.array(
-                [CNT_FCOUNT_DICT[row_list_s[0]], *row_list_s[1:]], np.uint64
-            )
+            row_list = np.array([CNT_FCOUNT_DICT[row_list_s[0]], *row_list_s[1:]], int)
             del row_list_s
             if row_list[3] != row_list[1] + row_list[2]:
                 raise ValueError(
@@ -694,8 +691,7 @@ def _process_table_blks_cnt_type(
             continue
 
     if not np.array_equal(
-        np.array(list(col_totals[1:]), np.uint64),
-        np.einsum("ij->j", invdata_array[:, 1:]),
+        np.array(list(col_totals[1:]), int), np.einsum("ij->j", invdata_array[:, 1:])
     ):
         raise ValueError("Column totals don't compute.")
 

mergeron/core/guidelines_boundaries.py

@@ -1,6 +1,8 @@
 """
-Methods for defining and analyzing boundaries for Guidelines standards,
-with a canvas on which to draw boundaries for Guidelines standards.
+Methods for defining and analyzing boundaries for Guidelines standards.
+
+Includes function to create a canvas on which to draw boundaries for
+Guidelines standards.
 
 """
 
@@ -34,6 +36,8 @@ mp.trap_complex = True
 
 @frozen
 class HMGThresholds:
+    """Thresholds for Guidelines standards."""
+
     delta: float
     fc: float
     rec: float
@@ -47,53 +51,55 @@ class HMGThresholds:
 @frozen
 class GuidelinesThresholds:
     """
-    Guidelines threholds by Guidelines publication year
+    Guidelines thresholds by Guidelines publication year.
 
     ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
     constructed from concentration standards in Guidelines published in
     1992, 2010, and 2023.
-
     """
 
     pub_year: HMGPubYear = field(
         kw_only=False, default=2023, validator=validators.in_([1992, 2010, 2023])
     )
     """
-    Year of publication of the Guidelines
+    Year of publication of the Guidelines.
     """
-
     safeharbor: HMGThresholds = field(kw_only=True, default=None, init=False)
     """
-    Negative presumption quantified on various measures
+    Negative presumption quantified on various measures.
 
     ΔHHI safeharbor bound, default recapture ratio, GUPPI bound,
-    diversion ratio limit, CMCR, and IPR
+    diversion ratio limit, CMCR, and IPR.
     """
 
     presumption: HMGThresholds = field(kw_only=True, default=None, init=False)
     """
-    Presumption of harm defined in HMG
+    Presumption of harm defined in HMG.
 
     ΔHHI bound and corresponding default recapture ratio, GUPPI bound,
-    diversion ratio limit, CMCR, and IPR
+    diversion ratio limit, CMCR, and IPR.
     """
 
     imputed_presumption: HMGThresholds = field(kw_only=True, default=None, init=False)
     """
-    Presumption of harm imputed from guidelines
+    Presumption of harm imputed from Guidelines.
 
     ΔHHI bound inferred from strict numbers-equivalent
     of (post-merger) HHI presumption, and corresponding default recapture ratio,
-    GUPPI bound, diversion ratio limit, CMCR, and IPR
+    GUPPI bound, diversion ratio limit, CMCR, and IPR.
     """
 
     def __attrs_post_init__(self, /) -> None:
-        # In the 2023 Guidelines, the agencies do not define a
-        # negative presumption, or safeharbor. Practically speaking,
-        # given resource constraints and loss aversion, it is likely
-        # that staff only investigates mergers that meet the presumption;
-        # thus, here, the tentative delta safeharbor under
-        # the 2023 Guidelines is 100 points
+        """
+        Initialize Guidelines thresholds, based on Guidelines publication year.
+
+        In the 2023 Guidelines, the agencies do not define a
+        negative presumption, or safeharbor. Practically speaking,
+        given resource constraints and loss aversion, it is likely
+        that staff only investigates mergers that meet the presumption;
+        thus, here, the tentative delta safeharbor under
+        the 2023 Guidelines is 100 points.
+        """
         hhi_p, dh_s, dh_p = {
             1992: (0.18, 0.005, 0.01),
             2010: (0.25, 0.01, 0.02),
@@ -120,7 +126,7 @@ class GuidelinesThresholds:
 
         # imputed_presumption is relevant for presumptions implicating
         # mergers *to* symmetry in numbers-equivalent of post-merger HHI
-        # as in 2010 U.S.Guidelines
+        # as in 2010 U.S.Guidelines.
         object.__setattr__(
             self,
             "imputed_presumption",
@@ -185,6 +191,7 @@ class ConcentrationBoundary:
     """Market-share pairs as Cartesian coordinates of points on the concentration boundary."""
 
     def __attrs_post_init__(self, /) -> None:
+        """Initialize boundary and area based on other attributes."""
         match self.measure_name:
             case "ΔHHI":
                 conc_fn = gbfn.hhi_delta_boundary
@@ -316,6 +323,7 @@ class DiversionRatioBoundary:
     """Market-share pairs as Cartesian coordinates of points on the diversion ratio boundary."""
 
     def __attrs_post_init__(self, /) -> None:
+        """Initialize boundary and area based on other attributes."""
         share_ratio = critical_share_ratio(
             self.diversion_ratio, r_bar=self.recapture_ratio
         )
@@ -448,7 +456,6 @@ def share_from_guppi(
         recapture ratio.
 
     """
-
     return gbfn.round_cust(
         (_d0 := critical_share_ratio(_guppi_bound, m_star=m_star, r_bar=r_bar))
         / (1 + _d0)

mergeron/core/guidelines_boundary_functions.py

@@ -1,3 +1,5 @@
+"""Helper functions for defining and analyzing boundaries for Guidelines standards."""
+
 import decimal
 from collections.abc import Callable
 from typing import Literal, TypedDict
@@ -44,7 +46,7 @@ def dh_area(_delta_bound: float | MPFloat = 0.01, /, *, dps: int = 9) -> float:
 
     .. math::
 
-        2 s1 s_2 &= ΔHHI\\
+        2 s1 s_2 &= ΔHHI \\
         s_1 + s_2 &= 1
 
     Parameters
@@ -59,7 +61,6 @@ def dh_area(_delta_bound: float | MPFloat = 0.01, /, *, dps: int = 9) -> float:
         Area under ΔHHI boundary.
 
     """
-
     _delta_bound = mpf(f"{_delta_bound}")
     _s_naught = (1 - mp.sqrt(1 - 2 * _delta_bound)) / 2
 
@@ -89,7 +90,6 @@ def hhi_delta_boundary(
         Array of share-pairs, area under boundary.
 
     """
-
     _delta_bound = mpf(f"{_delta_bound}")
     _s_naught = 1 / 2 * (1 - mp.sqrt(1 - 2 * _delta_bound))
     _s_mid = mp.sqrt(_delta_bound / 2)
@@ -202,7 +202,7 @@ def hhi_post_contrib_boundary(
 
 
 # hand-rolled root finding
-def shrratio_boundary_wtd_avg(  # noqa: PLR0914
+def shrratio_boundary_wtd_avg(
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -214,13 +214,13 @@ def shrratio_boundary_wtd_avg(  # noqa: PLR0914
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
 ) -> GuidelinesBoundary:
-    """
+    R"""
     Share combinations on the share-weighted average diversion ratio boundary.
 
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`)
+        Share ratio (:math:`\overline{d} / \overline{r}`)
     _r_val
         recapture ratio
     agg_method
@@ -299,7 +299,6 @@ def shrratio_boundary_wtd_avg(  # noqa: PLR0914
 
 
     """
-
     _delta_star, _r_val = (mpf(f"{_v}") for _v in (_delta_star, _r_val))
     _s_mid = mp.fdiv(_delta_star, 1 + _delta_star)
 
@@ -407,7 +406,7 @@ def shrratio_boundary_wtd_avg(  # noqa: PLR0914
     )
 
 
-def shrratio_boundary_xact_avg(  # noqa: PLR0914
+def shrratio_boundary_xact_avg(
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -415,9 +414,8 @@ def shrratio_boundary_xact_avg(  # noqa: PLR0914
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
 ) -> GuidelinesBoundary:
-    """
-    Share combinations for the simple average GUPPI boundary with symmetric
-    merging-firm margins.
+    R"""
+    Share combinations for the exact average diversion/share-ratio boundary.
 
     Notes
     -----
@@ -455,7 +453,7 @@ def shrratio_boundary_xact_avg(  # noqa: PLR0914
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`).
+        Share ratio (:math:`\overline{d} / \overline{r}`).
     _r_val
         Recapture ratio
     recapture_form
@@ -469,7 +467,6 @@ def shrratio_boundary_xact_avg(  # noqa: PLR0914
         Array of share-pairs, area under boundary, area under boundary.
 
     """
-
     _delta_star, _r_val = (mpf(f"{_v}") for _v in (_delta_star, _r_val))
     _s_mid = _delta_star / (1 + _delta_star)
     _step_size = mp.power(10, -dps)
@@ -570,9 +567,8 @@ def shrratio_boundary_min(
     recapture_form: str = "inside-out",
     dps: int = 10,
 ) -> GuidelinesBoundary:
-    """
-    Share combinations on the minimum GUPPI boundary, with symmetric
-    merging-firm margins.
+    R"""
+    Share combinations on the minimum diversion-ratio/share-ratio boundary.
 
     Notes
     -----
@@ -584,7 +580,7 @@ def shrratio_boundary_min(
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`).
+        Share ratio (:math:`\overline{d} / \overline{r}`).
     _r_val
         Recapture ratio.
     recapture_form
@@ -598,7 +594,6 @@ def shrratio_boundary_min(
         Array of share-pairs, area under boundary.
 
     """
-
     _delta_star, _r_val = (mpf(f"{_v}") for _v in (_delta_star, _r_val))
     _s_intcpt = mpf("1.00")
     _s_mid = _delta_star / (1 + _delta_star)
@@ -623,14 +618,13 @@ def shrratio_boundary_min(
 def shrratio_boundary_max(
     _delta_star: float = 0.075, _: float = DEFAULT_REC_RATIO, /, *, dps: int = 10
 ) -> GuidelinesBoundary:
-    """
-    Share combinations on the minimum GUPPI boundary with symmetric
-    merging-firm margins.
+    R"""
+    Share combinations on the minimum diversion-ratio/share-ratio boundary.
 
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`).
+        Share ratio (:math:`\overline{d} / \overline{r}`).
     _
         Placeholder for recapture ratio included for consistency with other
         share-ratio boundary functions.
@@ -642,7 +636,6 @@ def shrratio_boundary_max(
         Array of share-pairs, area under boundary.
 
     """
-
     _delta_star = mpf(f"{_delta_star}")
     _s_intcpt = _delta_star
     _s_mid = _delta_star / (1 + _delta_star)
@@ -691,8 +684,8 @@ def _shrratio_boundary_intcpt(
 def lerp[LerpT: (float, MPFloat, ArrayDouble, ArrayBIGINT)](
     _x1: LerpT, _x2: LerpT, _r: float | MPFloat = 0.25, /
 ) -> LerpT:
-    """
-    From the function of the same name in the C++ standard [2]_
+    R"""
+    From the function of the same name in the C++ standard [#]_.
 
     Constructs the weighted average, :math:`w_1 x_1 + w_2 x_2`, where
     :math:`w_1 = 1 - r` and :math:`w_2 = r`.
@@ -707,7 +700,7 @@ def lerp[LerpT: (float, MPFloat, ArrayDouble, ArrayBIGINT)](
     Returns
     -------
         The linear interpolation, or weighted average,
-        :math:`x_1 + r \\cdot (x_1 - x_2) \\equiv (1 - r) \\cdot x_1 + r \\cdot x_2`.
+        :math:`x_1 + r \cdot (x_1 - x_2) \equiv (1 - r) \cdot x_1 + r \cdot x_2`.
 
     Raises
     ------
@@ -717,10 +710,9 @@ def lerp[LerpT: (float, MPFloat, ArrayDouble, ArrayBIGINT)](
     References
     ----------
 
-    .. [2] C++ Reference, https://en.cppreference.com/w/cpp/numeric/lerp
+    .. [#] C++ Reference, https://en.cppreference.com/w/cpp/numeric/lerp
 
     """
-
     if not 0 <= _r <= 1:
         raise ValueError("Specified interpolation weight must lie in [0, 1].")
     elif _r == 0:
@@ -739,7 +731,7 @@ def round_cust(
     rounding_mode: str = "ROUND_HALF_UP",
 ) -> float:
     """
-    Custom rounding, to the nearest 0.5% by default.
+    Round to given fraction; the nearest 0.5% by default.
 
     Parameters
     ----------
@@ -766,7 +758,6 @@ def round_cust(
     the specified precision, :code:`frac`.
 
     """
-
     if rounding_mode not in {
         decimal.ROUND_05UP,
         decimal.ROUND_CEILING,
@@ -793,11 +784,10 @@ def boundary_plot(
     mktshare_axes_flag: bool = True,
     backend: Literal["pgf"] | str | None = "pgf",
 ) -> tuple[mpl.pyplot, mpl.pyplot.Figure, mpl.axes.Axes, Callable[..., mpl.axes.Axes]]:
-    """Setup basic figure and axes for plots of safe harbor boundaries.
+    """Set up basic figure and axes for plots of safe harbor boundaries.
 
     See, https://matplotlib.org/stable/tutorials/text/pgf.html
     """
-
     if backend == "pgf":
         mpl.use("pgf")
 

mergeron/core/guidelines_boundary_functions_extra.py

@@ -16,8 +16,8 @@ from mpmath import mp, mpf  # type: ignore
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
 from sympy import lambdify, simplify, solve, symbols  # type: ignore
 
-from .. import DEFAULT_REC_RATIO, VERSION, ArrayDouble  # noqa: TID252
-from . import GuidelinesBoundary, MPFloat
+from .. import DEFAULT_REC_RATIO, VERSION  # noqa: TID252
+from . import GuidelinesBoundary, GuidelinesBoundaryCallable, MPFloat
 from . import guidelines_boundary_functions as gbf
 
 __version__ = VERSION
@@ -27,13 +27,6 @@ mp.dps = 32
 mp.trap_complex = True
 
 
-@frozen
-class GuidelinesBoundaryCallable:
-    boundary_function: Callable[[ArrayDouble], ArrayDouble]
-    area: float
-    s_naught: float = 0
-
-
 def dh_area_quad(_dh_val: float = 0.01, /) -> float:
     """
     Area under the ΔHHI boundary.
@@ -52,7 +45,6 @@ def dh_area_quad(_dh_val: float = 0.01, /) -> float:
         Area under ΔHHI boundary.
 
     """
-
     _dh_val = mpf(f"{_dh_val}")
     _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
 
@@ -79,7 +71,6 @@ def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCalla
         Callable to generate array of share-pairs, area under boundary.
 
     """
-
     _dh_val = mpf(f"{_dh_val}")
 
     _s_1, _s_2 = symbols("s_1, s_2", positive=True)
@@ -113,14 +104,13 @@ def shrratio_boundary_qdtr_wtd_avg(
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
 ) -> GuidelinesBoundaryCallable:
-    """
-    Share combinations for the share-weighted average GUPPI boundary with symmetric
-    merging-firm margins.
+    R"""
+    Share combinations for the share-weighted average share-ratio boundary.
 
     Parameters
     ----------
     _delta_star
-        corollary to GUPPI bound (:math:`\\overline{g} / (m^* \\cdot \\overline{r})`)
+        corollary to GUPPI bound (:math:`\overline{g} / (m^* \cdot \overline{r})`)
     _r_val
         recapture ratio
     weighting
@@ -134,7 +124,6 @@ def shrratio_boundary_qdtr_wtd_avg(
         Array of share-pairs, area under boundary.
 
     """
-
     _delta_star = mpf(f"{_delta_star}")
     _s_mid = _delta_star / (1 + _delta_star)
     s_naught = 0
@@ -222,7 +211,7 @@ def shrratio_boundary_qdtr_wtd_avg(
     )
 
 
-def shrratio_boundary_distance(  # noqa: PLR0914
+def shrratio_boundary_distance(
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -232,9 +221,8 @@ def shrratio_boundary_distance(  # noqa: PLR0914
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
 ) -> gbf.GuidelinesBoundary:
-    """
-    Share combinations for the GUPPI boundaries using various aggregators with
-    symmetric merging-firm margins.
+    R"""
+    Share combinations for the share-ratio boundaries using various aggregators.
 
     Reimplements the arithmetic-averages and distance estimations from function,
     `shrratio_boundary_wtd_avg` but uses the Minkowski-distance function,
@@ -245,7 +233,7 @@ def shrratio_boundary_distance(  # noqa: PLR0914
     Parameters
     ----------
     _delta_star
-        corollary to GUPPI bound (:math:`\\overline{g} / (m^* \\cdot \\overline{r})`)
+        corollary to GUPPI bound (:math:`\overline{g} / (m^* \cdot \overline{r})`)
     _r_val
         recapture ratio
     agg_method
@@ -263,7 +251,6 @@ def shrratio_boundary_distance(  # noqa: PLR0914
         Array of share-pairs, area under boundary.
 
     """
-
     _delta_star = mpf(f"{_delta_star}")
 
     # parameters for iteration
@@ -379,7 +366,7 @@ def shrratio_boundary_distance(  # noqa: PLR0914
     )
 
 
-def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
+def shrratio_boundary_xact_avg_mp(
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -387,7 +374,7 @@ def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
 ) -> gbf.GuidelinesBoundary:
-    """
+    R"""
     Share combinations along the simple average diversion-ratio boundary.
 
     Notes
@@ -426,7 +413,7 @@ def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`).
+        Share ratio (:math:`\overline{d} / \overline{r}`).
     _r_val
         Recapture ratio
     recapture_form
@@ -440,7 +427,6 @@ def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
         Array of share-pairs, area under boundary, area under boundary.
 
     """
-
     _delta_star = mpf(f"{_delta_star}")
     _s_mid = _delta_star / (1 + _delta_star)
     _bdry_step_sz = 10**-dps
@@ -534,7 +520,7 @@ def shrratio_boundary_xact_avg_mp(  # noqa: PLR0914
 
 # shrratio_boundary_wtd_avg_autoroot
 # this function is about half as fast as the manual one! ... and a touch less precise
-def _shrratio_boundary_wtd_avg_autoroot(  # noqa: PLR0914
+def _shrratio_boundary_wtd_avg_autoroot(
     _delta_star: float = 0.075,
     _r_val: float = DEFAULT_REC_RATIO,
     /,
@@ -546,13 +532,13 @@ def _shrratio_boundary_wtd_avg_autoroot(  # noqa: PLR0914
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     dps: int = 5,
 ) -> GuidelinesBoundary:
-    """
+    R"""
     Share combinations on the share-weighted average diversion ratio boundary.
 
     Parameters
     ----------
     _delta_star
-        Share ratio (:math:`\\overline{d} / \\overline{r}`)
+        Share ratio (:math:`\overline{d} / \overline{r}`)
     _r_val
         recapture ratio
     agg_method
@@ -631,7 +617,6 @@ def _shrratio_boundary_wtd_avg_autoroot(  # noqa: PLR0914
 
 
     """
-
     _delta_star, _r_val = (mpf(f"{_v}") for _v in (_delta_star, _r_val))
     _s_mid = mp.fdiv(_delta_star, 1 + _delta_star)