mergeron 2025.739439.11__py3-none-any.whl → 2025.739439.13__py3-none-any.whl

mergeron/__init__.py

@@ -15,7 +15,7 @@ from ruamel import yaml
 
 _PKG_NAME: str = Path(__file__).parent.name
 
-VERSION = "2025.739439.11"
+VERSION = "2025.739439.13"
 
 __version__ = VERSION
 
@@ -30,7 +30,7 @@ created/reused.
 if not WORK_DIR.is_dir():
     WORK_DIR.mkdir(parents=False)
 
-DEFAULT_REC_RATIO = 0.85
+DEFAULT_REC = 0.85
 
 EMPTY_ARRAYDOUBLE = np.array([], float)
 EMPTY_ARRAYINT = np.array([], int)
@@ -172,19 +172,19 @@ class Enameled(enum.Enum):
 @this_yaml.register_class
 @enum.unique
 class RECForm(str, Enameled):
-    R"""For derivation of recapture ratio from market shares.
+    R"""For derivation of recapture rate from market shares.
 
     With :math:`\mathscr{N}` a set of firms, each supplying a
     single differentiated product, and :math:`\mathscr{M} \subset \mathscr{N}`
     a putative relevant product market, with
     :math:`d_{ij}` denoting diversion ratio from good :math:`i` to good :math:`j`,
     :math:`s_i` denoting market shares, and
-    :math:`\overline{r}` the default market recapture ratio,
-    market recapture ratios for the respective products may be specified
+    :math:`\overline{r}` the default market recapture rate,
+    market recapture rates for the respective products may be specified
     as having one of the following forms:
     """
 
-    FIXED = "proportional"
+    FIXED = "fixed"
     R"""Given, :math:`\overline{r}`,
 
     .. math::

mergeron/core/guidelines_boundaries.py

@@ -16,7 +16,7 @@ from attrs import Attribute, field, frozen, validators
 from mpmath import mp  # type: ignore
 
 from .. import (  # noqa: TID252
-    DEFAULT_REC_RATIO,
+    DEFAULT_REC,
     VERSION,
     ArrayDouble,
     HMGPubYear,
@@ -53,7 +53,7 @@ class GuidelinesThresholds:
     """
     Guidelines thresholds by Guidelines publication year.
 
-    ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
+    ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
     constructed from concentration standards in Guidelines published in
     1992, 2010, and 2023.
     """
@@ -68,7 +68,7 @@ class GuidelinesThresholds:
     """
     Negative presumption quantified on various measures.
 
-    ΔHHI safeharbor bound, default recapture ratio, GUPPI bound,
+    ΔHHI safeharbor bound, default recapture rate, GUPPI bound,
     diversion ratio limit, CMCR, and IPR.
     """
 
@@ -76,7 +76,7 @@ class GuidelinesThresholds:
     """
     Presumption of harm defined in HMG.
 
-    ΔHHI bound and corresponding default recapture ratio, GUPPI bound,
+    ΔHHI bound and corresponding default recapture rate, GUPPI bound,
     diversion ratio limit, CMCR, and IPR.
     """
 
@@ -85,7 +85,7 @@ class GuidelinesThresholds:
     Presumption of harm imputed from Guidelines.
 
     ΔHHI bound inferred from strict numbers-equivalent
-    of (post-merger) HHI presumption, and corresponding default recapture ratio,
+    of (post-merger) HHI presumption, and corresponding default recapture rate,
     GUPPI bound, diversion ratio limit, CMCR, and IPR.
     """
 
@@ -208,13 +208,13 @@ class ConcentrationBoundary:
 
 
 @frozen
-class DiversionRatioBoundary:
+class DiversionBoundary:
     """
     Diversion ratio specification, boundary coordinates, and area under boundary.
 
-    Along with the default diversion ratio and recapture ratio,
+    Along with the default diversion ratio and recapture rate,
     a diversion ratio boundary specification includes the recapture form --
-    whether fixed for both merging firms' products ("proportional") or
+    whether fixed for both merging firms' products ("fixed") or
     consistent with share-proportionality, i.e., "inside-out";
     the method of aggregating diversion ratios for the two products, and
     the precision for the estimate of area under the divertion ratio boundary
@@ -226,31 +226,26 @@ class DiversionRatioBoundary:
 
     @diversion_ratio.validator
     def _dvv(
-        _instance: DiversionRatioBoundary,
-        _attribute: Attribute[float],
-        _value: float,
-        /,
+        _instance: DiversionBoundary, _attribute: Attribute[float], _value: float, /
     ) -> None:
         if not (isinstance(_value, decimal.Decimal | float) and 0 <= _value <= 1):
             raise ValueError(
                 "Margin-adjusted benchmark diversion share must lie between 0 and 1."
             )
 
-    recapture_ratio: float = field(
-        kw_only=False,
-        default=DEFAULT_REC_RATIO,
-        validator=validators.instance_of(float),
+    recapture_rate: float = field(
+        kw_only=False, default=DEFAULT_REC, validator=validators.instance_of(float)
     )
 
     recapture_form: RECForm | None = field(kw_only=True, default=RECForm.INOUT)
     R"""
-    The form of the recapture ratio.
+    The form of the recapture rate.
 
-    When :attr:`mergeron.RECForm.INOUT`, the recapture ratio for
+    When :attr:`mergeron.RECForm.INOUT`, the recapture rate for
     he product having the smaller market-share is assumed to equal the default,
-    and the recapture ratio for the product with the larger market-share is
-    computed assuming MNL demand. Fixed recapture ratios are specified as
-    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture ratios be
+    and the recapture rate for the product with the larger market-share is
+    computed assuming MNL demand. Fixed recapture rates are specified as
+    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture rates be
     constructed from the generated purchase-probabilities for products in
     the market and for the outside good, specify :attr:`mergeron.RECForm.OUTIN`.)
 
@@ -270,19 +265,16 @@ class DiversionRatioBoundary:
 
     @recapture_form.validator
     def _rsv(
-        _instance: DiversionRatioBoundary,
-        _attribute: Attribute[RECForm],
-        _value: RECForm,
-        /,
+        _instance: DiversionBoundary, _attribute: Attribute[RECForm], _value: RECForm, /
     ) -> None:
         if _value and not (isinstance(_value, RECForm)):
             raise ValueError(f"Invalid recapture specification, {_value!r}.")
-        if _value == RECForm.OUTIN and _instance.recapture_ratio:
+        if _value == RECForm.OUTIN and _instance.recapture_rate:
             raise ValueError(
                 f"Invalid recapture specification, {_value!r}. "
                 "You may consider specifying `mergeron.RECForm.INOUT` here, and "
-                'assigning the default recapture ratio as attribute, "recapture_ratio" of '
-                "this `DiversionRatioBoundarySpec` object."
+                'assigning the default recapture rate as attribute, "recapture_rate" of '
+                "this `DiversionBoundarySpec` object."
             )
         if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
             raise ValueError(
@@ -325,7 +317,7 @@ class DiversionRatioBoundary:
     def __attrs_post_init__(self, /) -> None:
         """Initialize boundary and area based on other attributes."""
         share_ratio = critical_diversion_share(
-            self.diversion_ratio, r_bar=self.recapture_ratio
+            self.diversion_ratio, r_bar=self.recapture_rate
         )
 
         upp_agg_kwargs: gbfn.DiversionShareBoundaryKeywords = {"dps": self.precision}
@@ -367,17 +359,13 @@ class DiversionRatioBoundary:
 
                 upp_agg_kwargs |= {"agg_method": aggregator_, "weighting": wgt_type}
 
-        boundary_ = upp_agg_fn(share_ratio, self.recapture_ratio, **upp_agg_kwargs)  # type: ignore
+        boundary_ = upp_agg_fn(share_ratio, self.recapture_rate, **upp_agg_kwargs)  # type: ignore
         object.__setattr__(self, "area", boundary_.area)
         object.__setattr__(self, "coordinates", boundary_.coordinates)
 
 
 def guppi_from_delta(
-    _delta_bound: float = 0.01,
-    /,
-    *,
-    m_star: float = 1.00,
-    r_bar: float = DEFAULT_REC_RATIO,
+    _delta_bound: float = 0.01, /, *, m_star: float = 1.00, r_bar: float = DEFAULT_REC
 ) -> float:
     """
     Translate ∆HHI bound to GUPPI bound.
@@ -389,11 +377,11 @@ def guppi_from_delta(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture ratio.
+        Default recapture rate.
 
     Returns
     -------
-        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture ratio.
+        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture rate.
 
     """
     return gbfn.round_cust(
@@ -421,26 +409,22 @@ def critical_diversion_share(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture ratio.
+        Default recapture rate.
 
     Returns
     -------
         Critical diversion share (diversion share bound) corresponding to the GUPPI bound
-        for given margin and recapture ratio.
+        for given margin and recapture rate.
 
     """
     return gbfn.round_cust(_guppi_bound / (m_star * r_bar), frac=frac)
 
 
 def share_from_guppi(
-    _guppi_bound: float = 0.065,
-    /,
-    *,
-    m_star: float = 1.00,
-    r_bar: float = DEFAULT_REC_RATIO,
+    _guppi_bound: float = 0.065, /, *, m_star: float = 1.00, r_bar: float = DEFAULT_REC
 ) -> float:
     """
-    Symmetric-firm share for given GUPPI, margin, and recapture ratio.
+    Symmetric-firm share for given GUPPI, margin, and recapture rate.
 
     Parameters
     ----------
@@ -449,13 +433,13 @@ def share_from_guppi(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture ratio.
+        Default recapture rate.
 
     Returns
     -------
     float
         Symmetric firm market share on GUPPI boundary, for given margin and
-        recapture ratio.
+        recapture rate.
 
     """
     return gbfn.round_cust(
@@ -472,7 +456,7 @@ if __name__ == "__main__":
 
 for _typ in (
     ConcentrationBoundary,
-    DiversionRatioBoundary,
+    DiversionBoundary,
     GuidelinesThresholds,
     HMGThresholds,
 ):

mergeron/core/guidelines_boundary_functions.py

@@ -15,13 +15,7 @@ import matplotlib.ticker as mpt
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
 
-from .. import (  # noqa: TID252
-    _PKG_NAME,
-    DEFAULT_REC_RATIO,
-    VERSION,
-    ArrayBIGINT,
-    ArrayDouble,
-)
+from .. import _PKG_NAME, DEFAULT_REC, VERSION, ArrayDouble  # noqa: TID252
 from . import GuidelinesBoundary, MPFloat
 
 __version__ = VERSION
@@ -33,7 +27,7 @@ mp.trap_complex = True
 class DiversionShareBoundaryKeywords(TypedDict, total=False):
     """Keyword arguments for functions generating share ratio boundaries."""
 
-    recapture_form: Literal["inside-out", "proportional"]
+    recapture_form: Literal["inside-out", "fixed"]
     dps: int
     agg_method: Literal["arithmetic mean", "geometric mean", "distance"]
     weighting: Literal["own-share", "cross-product-share", None]
@@ -213,14 +207,14 @@ def hhi_post_contrib_boundary(
 # hand-rolled root finding
 def diversion_share_boundary_wtd_avg(
     _delta_star: float = 0.075,
-    _r_val: float = DEFAULT_REC_RATIO,
+    _r_val: float = DEFAULT_REC,
     /,
     *,
     agg_method: Literal[
         "arithmetic mean", "geometric mean", "distance"
     ] = "arithmetic mean",
     weighting: Literal["own-share", "cross-product-share", None] = "own-share",
-    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "fixed"] = "inside-out",
     dps: int = 5,
 ) -> GuidelinesBoundary:
     R"""
@@ -231,14 +225,14 @@ def diversion_share_boundary_wtd_avg(
     _delta_star
         Diversion share, :math:`\overline{d} / \overline{r}` or :math:`\overline{g} / (m^* \cdot \overline{r})`.
     _r_val
-        Recapture ratio.
+        Recapture rate.
     agg_method
         Whether "arithmetic mean", "geometric mean", or "distance".
     weighting
         Whether "own-share" or "cross-product-share"  (or None for simple, unweighted average).
     recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
+        Whether recapture rate is share-proportional ("inside-out") or has fixed
+        value for both merging firms ("fixed").
     dps
         Number of decimal places for rounding returned shares and area.
 
@@ -281,7 +275,7 @@ def diversion_share_boundary_wtd_avg(
             (s_1, 0.0, d_hat / (1 + d_hat)), ylabel=s_2
         )
 
-        # recapture_form == "proportional"
+        # recapture_form == "fixed"
         oswag = solve(
             s_1 * s_2 / (1 - s_1)
             + s_2 * s_1 / (1 - s_2)
@@ -417,10 +411,10 @@ def diversion_share_boundary_wtd_avg(
 
 def diversion_share_boundary_xact_avg(
     _delta_star: float = 0.075,
-    _r_val: float = DEFAULT_REC_RATIO,
+    _r_val: float = DEFAULT_REC,
     /,
     *,
-    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "fixed"] = "inside-out",
     dps: int = 5,
 ) -> GuidelinesBoundary:
     R"""
@@ -451,7 +445,7 @@ def diversion_share_boundary_xact_avg(
             ylabel=s_2
         )
 
-        # recapture_form = "proportional"
+        # recapture_form = "fixed"
         sag = solve((s_2/(1 - s_1)) + (s_1/(1 - s_2)) - 2 * d_hat, s_2)[0]
         symplot(
             sag,
@@ -464,10 +458,10 @@ def diversion_share_boundary_xact_avg(
     _delta_star
         Diversion share, :math:`\overline{d} / \overline{r}` or :math:`\overline{g} / (m^* \cdot \overline{r})`.
     _r_val
-        Recapture ratio.
+        Recapture rate.
     recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
+        Whether recapture rate is share-proportional ("inside-out") or has fixed
+        value for both merging firms ("fixed").
     dps
         Number of decimal places for rounding returned shares.
 
@@ -572,10 +566,10 @@ def diversion_share_boundary_xact_avg(
 
 def diversion_share_boundary_min(
     _delta_star: float = 0.075,
-    _r_val: float = DEFAULT_REC_RATIO,
+    _r_val: float = DEFAULT_REC,
     /,
     *,
-    recapture_form: str = "inside-out",
+    recapture_form: Literal["inside-out", "fixed"] = "inside-out",
     dps: int = 10,
 ) -> GuidelinesBoundary:
     R"""
@@ -593,10 +587,10 @@ def diversion_share_boundary_min(
     _delta_star
         Diversion share, :math:`\overline{d} / \overline{r}` or :math:`\overline{g} / (m^* \cdot \overline{r})`.
     _r_val
-        Recapture ratio.
+        Recapture rate.
     recapture_form
-        Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
-        value for both merging firms ("proportional").
+        Whether recapture rate is share-proportional ("inside-out") or has fixed
+        value for both merging firms ("fixed").
     dps
         Number of decimal places for rounding returned shares.
 
@@ -627,7 +621,7 @@ def diversion_share_boundary_min(
 
 
 def diversion_share_boundary_max(
-    _delta_star: float = 0.075, _: float = DEFAULT_REC_RATIO, /, *, dps: int = 10
+    _delta_star: float = 0.075, _: float = DEFAULT_REC, /, *, dps: int = 10
 ) -> GuidelinesBoundary:
     R"""
     Share combinations on the minimum diversion-ratio/share-ratio boundary.
@@ -637,7 +631,7 @@ def diversion_share_boundary_max(
     _delta_star
         Diversion share, :math:`\overline{d} / \overline{r}` or :math:`\overline{g} / (m^* \cdot \overline{r})`.
     _
-        Placeholder for recapture ratio included for consistency with other
+        Placeholder for recapture rate included for consistency with other
         share-ratio boundary functions.
     dps
         Number of decimal places for rounding returned shares.
@@ -664,7 +658,7 @@ def _diversion_share_boundary_intcpt(
     _r_val: MPFloat,
     /,
     *,
-    recapture_form: Literal["inside-out", "proportional"],
+    recapture_form: Literal["inside-out", "fixed"],
     agg_method: Literal["arithmetic mean", "geometric mean", "distance"],
     weighting: Literal["cross-product-share", "own-share", None],
 ) -> float:
@@ -682,9 +676,7 @@ def _diversion_share_boundary_intcpt(
                 ),
                 2 * mpf(f"{_r_val}"),
             )
-        case None if (
-            agg_method == "arithmetic mean" and recapture_form == "proportional"
-        ):
+        case None if agg_method == "arithmetic mean" and recapture_form == "fixed":
             _s_intcpt = mp.fsub(_delta_star + 1 / 2, mp.fabs(_delta_star - 1 / 2))
         case _:
             _s_intcpt = s_2_pre
@@ -692,7 +684,7 @@ def _diversion_share_boundary_intcpt(
     return _s_intcpt
 
 
-def lerp[LerpT: (float, MPFloat, ArrayDouble, ArrayBIGINT)](
+def lerp[LerpT: (float, MPFloat, ArrayDouble)](
     _x1: LerpT, _x2: LerpT, _r: float | MPFloat = 0.25, /
 ) -> LerpT:
     R"""

mergeron/core/pseudorandom_numbers.py

@@ -66,7 +66,7 @@ def prng(_s: SeedSequence | None = None, /) -> np.random.Generator:
 )
 
 
-def gen_seed_seq_list_default(
+def seed_sequencer(
     _len: int = 3, /, *, generated_entropy: Sequence[int] | None = None
 ) -> tuple[SeedSequence, ...]:
     R"""