mergeron 2024.738953.1__py3-none-any.whl → 2024.738972.0__py3-none-any.whl

mergeron/License.txt

@@ -1,7 +1,7 @@
 mergeron
 ========
 
-Copyright 2017-2023 S. Murthy Kambhampaty
+Copyright 2017-2024 S. Murthy Kambhampaty
 
 MIT License
 -----------

mergeron/core/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from importlib.metadata import version
 
-from attrs import Attribute, define, field, validators
+from attrs import Attribute, field, frozen, validators
 
 from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
 
@@ -38,7 +38,7 @@ def _rec_spec_validator(
         )
 
 
-@define(slots=True, frozen=True)
+@frozen
 class UPPBoundarySpec:
     share_ratio: float = field(
         kw_only=False,
@@ -54,7 +54,7 @@ class UPPBoundarySpec:
         default=UPPAggrSelector.MAX,
         validator=validators.instance_of(UPPAggrSelector),
     )
-    recapture_spec: RECConstants | None = field(
+    recapture_form: RECConstants | None = field(
         kw_only=True,
         default=RECConstants.INOUT,
         validator=(

mergeron/core/excel_helper.py

@@ -1,5 +1,5 @@
 """
-Routines for writing data from Python to fresh Excel workbooks using
+Methods for writing data from Python to fresh Excel workbooks using
 the third-party package, `xlsxwriter`.
 
 Includes a flexible system of defining cell formats.
@@ -27,6 +27,8 @@ __version__ = version(_PKG_NAME)
 class CFmtParent(dict[str, Any], enum.ReprEnum):  # type: ignore
     """Unique mappings defining xlsxwirter Workbook formats"""
 
+    ...
+
 
 class CFmt(CFmtParent):
     """

mergeron/core/ftc_merger_investigations_data.py

@@ -1,5 +1,5 @@
 """
-Routines to parse FTC Merger Investigations Data, downloading source documents
+Methods to parse FTC Merger Investigations Data, downloading source documents
 as necessary
 
 NOTES
@@ -16,7 +16,6 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import Any, NamedTuple, TypeAlias
 
-import fitz  # type: ignore
 import msgpack  # type: ignore
 import msgpack_numpy as m  # type: ignore
 import numpy as np
@@ -146,7 +145,7 @@ def construct_data(
                     )
         return MappingProxyType(_invdata)
 
-    _invdata = dict(parse_invdata())  # Convert immutable to mutable
+    _invdata = dict(_parse_invdata())  # Convert immutable to mutable
 
     # Add some data periods (
     #   only periods ending in 2011, others have few observations and
@@ -385,21 +384,9 @@ def _invdata_build_aggregate_table(
     )
 
 
-def parse_invdata(
-    _invdata_docnames: Sequence[str] = (
-        "040831horizmergersdata96-03.pdf",
-        "p035603horizmergerinvestigationdata1996-2005.pdf",
-        "081201hsrmergerdata.pdf",
-        "130104horizontalmergerreport.pdf",
-    ),
-) -> INVData:
+def _parse_invdata() -> INVData:
     """Parse FTC merger investigations data reports to structured data.
 
-    Parameters
-    ----------
-    _invdata_docnames
-        Names of PDF files reporting FTC merger investigations data.
-
     Returns
     -------
         Immutable dictionary of merger investigations data, keyed to
@@ -408,6 +395,16 @@ def parse_invdata(
         by range of HHI and ∆HHI.
 
     """
+    import fitz  # type: ignore
+    # user must install pymupdf to make this function operable
+
+    _invdata_docnames: Sequence[str] = (
+        "040831horizmergersdata96-03.pdf",
+        "p035603horizmergerinvestigationdata1996-2005.pdf",
+        "081201hsrmergerdata.pdf",
+        "130104horizontalmergerreport.pdf",
+    )
+
     _invdata: dict[str, dict[str, dict[str, INVTableData]]] = {}
 
     for _invdata_docname in _invdata_docnames:

mergeron/core/guidelines_boundaries.py

@@ -1,17 +1,16 @@
 """
-Routines for defining and analyzing boundaries for Guidelines standards,
+Methods for defining and analyzing boundaries for Guidelines standards,
 with a canvas on which to draw boundaries for Guidelines standards.
 
 """
 
 import decimal
-from collections.abc import Callable
 from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Any, Literal, TypeAlias
 
 import numpy as np
-from attrs import define, field
+from attrs import field, frozen
 from mpmath import mp, mpf  # type: ignore
 from numpy.typing import NDArray
 
@@ -24,7 +23,7 @@ __version__ = version(_PKG_NAME)
 mp.prec = 80
 mp.trap_complex = True
 
-HMGPubYear: TypeAlias = Literal[1992, 2010, 2023]
+HMGPubYear: TypeAlias = Literal[1992, 2004, 2010, 2023]
 
 
 @dataclass(slots=True, frozen=True)
@@ -43,25 +42,28 @@ class GuidelinesBoundary:
     area: float
 
 
-@dataclass(slots=True, frozen=True)
-class GuidelinesBoundaryCallable:
-    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
-    area: float
-    s_naught: float = 0
-
-
-@define(slots=True, frozen=True)
+@frozen
 class GuidelinesThresholds:
     """
     Guidelines threholds by Guidelines publication year
 
     ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
-    constructed from concentration standards.
+    constructed from concentration standards in Guidelines published in
+    1992, 2004, 2010, and 2023.
+
+    The 2004 Guidelines refernced here are the EU Commission
+    guidelines on assessment of horizontal mergers. These
+    guidelines also define a presumption for mergers with
+    post-merger HHI in [1000, 2000) and ΔHHI >= 250 points,
+    whi is not modeled here.
+
+    All other Guidelines modeled here are U.S. merger guidelines.
+
     """
 
     pub_year: HMGPubYear
     """
-    Year of publication of the U.S. Horizontal Merger Guidelines (HMG)
+    Year of publication of the Guidelines
     """
 
     safeharbor: HMGThresholds = field(kw_only=True, default=None)
@@ -99,6 +101,7 @@ class GuidelinesThresholds:
         _hhi_p, _dh_s, _dh_p = {
             1992: (0.18, 0.005, 0.01),
             2010: (0.25, 0.01, 0.02),
+            2004: (0.20, 0.015, 0.015),
             2023: (0.18, 0.01, 0.01),
         }[self.pub_year]
 
@@ -507,7 +510,7 @@ def boundary_plot(*, mktshares_plot_flag: bool = True) -> tuple[Any, ...]:
     return plt, _fig, _ax_out, _set_axis_def
 
 
-def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
+def dh_area(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
     R"""
     Area under the ΔHHI boundary.
 
@@ -530,7 +533,7 @@ def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
     ----------
     _dh_val
         Change in concentration.
-    dh_dps
+    prec
         Specified precision in decimal places.
 
     Returns
@@ -544,11 +547,11 @@ def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
 
     return round(
         float(_s_naught + (_dh_val / 2) * (mp.ln(1 - _s_naught) - mp.ln(_s_naught))),
-        dh_dps,
+        prec,
     )
 
 
-def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
+def dh_area_quad(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
     """
     Area under the ΔHHI boundary.
 
@@ -560,7 +563,7 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
     ----------
     _dh_val
         Merging-firms' ΔHHI bound.
-    dh_dps
+    prec
         Specified precision in decimal places.
 
     Returns
@@ -576,7 +579,7 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
         float(
             _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
         ),
-        dh_dps,
+        prec,
     )
 
 
@@ -590,7 +593,7 @@ def delta_hhi_boundary(
     ----------
     _dh_val:
         Merging-firms' ΔHHI bound.
-    dh_dps
+    prec
         Number of decimal places for rounding reported shares.
 
     Returns
@@ -620,7 +623,7 @@ def delta_hhi_boundary(
             np.array(_s_1_pts, np.float64),
             np.array(_s_2_pts, np.float64),
         )),
-        dh_area(_dh_val, dh_dps=prec),
+        dh_area(_dh_val, prec=prec),
     )
 
 
@@ -697,7 +700,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
             return shrratio_boundary_xact_avg(
                 _bdry_spec.share_ratio,
                 _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.MAX:
@@ -708,7 +711,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
             return shrratio_boundary_min(
                 _bdry_spec.share_ratio,
                 _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.DIS:
@@ -717,7 +720,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
                 _bdry_spec.rec,
                 agg_method="distance",
                 weighting=None,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case _:
@@ -738,7 +741,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
                 _bdry_spec.rec,
                 agg_method=_agg_method,  # type: ignore
                 weighting=_weighting,  # type: ignore
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
 
@@ -788,7 +791,7 @@ def shrratio_boundary_min(
     _r_val: float = 0.80,
     /,
     *,
-    recapture_spec: str = "inside-out",
+    recapture_form: str = "inside-out",
     prec: int = 10,
 ) -> GuidelinesBoundary:
     """
@@ -808,7 +811,7 @@ def shrratio_boundary_min(
         Margin-adjusted benchmark share ratio.
     _r_val
         Recapture ratio.
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -824,7 +827,7 @@ def shrratio_boundary_min(
     _s_intcpt = mpf("1.00")
     _s_mid = _delta_star / (1 + _delta_star)
 
-    if recapture_spec == "inside-out":
+    if recapture_form == "inside-out":
         # ## Plot envelope of GUPPI boundaries with r_k = r_bar if s_k = min(_s_1, _s_2)
         # ## See (s_i, s_j) in equation~(44), or thereabouts, in paper
         _smin_nr = _delta_star * (1 - _r_val)
@@ -857,7 +860,7 @@ def shrratio_boundary_wtd_avg(
     *,
     agg_method: Literal["arithmetic", "geometric", "distance"] = "arithmetic",
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
 ) -> GuidelinesBoundary:
     """
@@ -874,7 +877,7 @@ def shrratio_boundary_wtd_avg(
         Whether "arithmetic", "geometric", or "distance".
     weighting
         Whether "own-share" or "cross-product-share"  (or None for simple, unweighted average).
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -895,7 +898,7 @@ def shrratio_boundary_wtd_avg(
         g_val, r_val, m_val = 0.06, 0.80, 0.30
         delta_star = g_val / (r_val * m_val)
 
-        # recapture_spec == "inside-out"
+        # recapture_form == "inside-out"
         oswag = solve(
             s_1 * s_2 / (1 - s_1)
             + s_2 * s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1))
@@ -920,7 +923,7 @@ def shrratio_boundary_wtd_avg(
             ylabel=s_2
         )
 
-        # recapture_spec == "proportional"
+        # recapture_form == "proportional"
         oswag = solve(
             s_1 * s_2 / (1 - s_1)
             + s_2 * s_1 / (1 - s_2)
@@ -973,7 +976,7 @@ def shrratio_boundary_wtd_avg(
             _de_1 = _s_2 / (1 - _s_1)
             _de_2 = (
                 _s_1 / (1 - lerp(_s_1, _s_2, _r_val))
-                if recapture_spec == "inside-out"
+                if recapture_form == "inside-out"
                 else _s_1 / (1 - _s_2)
             )
 
@@ -1025,7 +1028,7 @@ def shrratio_boundary_wtd_avg(
         _s_1_pre,
         _delta_star,
         _r_val,
-        recapture_spec=recapture_spec,
+        recapture_form=recapture_form,
         agg_method=agg_method,
         weighting=weighting,
     )
@@ -1063,7 +1066,7 @@ def shrratio_boundary_xact_avg(
     _r_val: float = 0.80,
     /,
     *,
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
 ) -> GuidelinesBoundary:
     """
@@ -1082,7 +1085,7 @@ def shrratio_boundary_xact_avg(
         g_val, r_val, m_val = 0.06, 0.80, 0.30
         d_hat = g_val / (r_val * m_val)
 
-        # recapture_spec = "inside-out"
+        # recapture_form = "inside-out"
         sag = solve(
             (s_2 / (1 - s_1))
             + (s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1)))
@@ -1095,7 +1098,7 @@ def shrratio_boundary_xact_avg(
             ylabel=s_2
         )
 
-        # recapture_spec = "proportional"
+        # recapture_form = "proportional"
         sag = solve((s_2/(1 - s_1)) + (s_1/(1 - s_2)) - 2 * d_hat, s_2)[0]
         symplot(
             sag,
@@ -1109,7 +1112,7 @@ def shrratio_boundary_xact_avg(
         Margin-adjusted benchmark share ratio.
     _r_val
         Recapture ratio
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -1127,14 +1130,14 @@ def shrratio_boundary_xact_avg(
 
     _gbdry_points_start = np.array([(_s_mid, _s_mid)])
     _s_1 = np.array(mp.arange(_s_mid - _gbd_step_sz, 0, -_gbd_step_sz), np.float64)
-    if recapture_spec == "inside-out":
+    if recapture_form == "inside-out":
         _s_intcpt = mp.fdiv(
             mp.fsub(
                 2 * _delta_star * _r_val + 1, mp.fabs(2 * _delta_star * _r_val - 1)
             ),
             2 * mpf(f"{_r_val}"),
         )
-        _nr_t1 = 1 + 2 * _delta_star * _r_val * (1 - _s_1) - _s_1 * (1 - _r_val)  # type: ignore
+        _nr_t1 = 1 + 2 * _delta_star * _r_val * (1 - _s_1) - _s_1 * (1 - _r_val)
 
         _nr_sqrt_mdr = 4 * _delta_star * _r_val
         _nr_sqrt_mdr2 = _nr_sqrt_mdr * _r_val
@@ -1159,7 +1162,7 @@ def shrratio_boundary_xact_avg(
 
         _nr_t2_s1 = _nr_sqrt_s1sq + _nr_sqrt_s1 + _nr_sqrt_nos1
 
-        if not np.isclose(  # type: ignore
+        if not np.isclose(
             np.einsum("i->", _nr_t2_mdr.astype(np.float64)),
             np.einsum("i->", _nr_t2_s1.astype(np.float64)),
             rtol=0,
@@ -1167,7 +1170,7 @@ def shrratio_boundary_xact_avg(
         ):
             raise RuntimeError(
                 "Calculation of sq. root term in exact average GUPPI"
-                f"with recapture spec, {f'"{recapture_spec}"'} is incorrect."
+                f"with recapture spec, {f'"{recapture_form}"'} is incorrect."
             )
 
         _s_2 = (_nr_t1 - np.sqrt(_nr_t2_s1)) / (2 * _r_val)
@@ -1223,7 +1226,7 @@ def _shrratio_boundary_intcpt(
     _r_val: mpf,
     /,
     *,
-    recapture_spec: Literal["inside-out", "proportional"],
+    recapture_form: Literal["inside-out", "proportional"],
     agg_method: Literal["arithmetic", "geometric", "distance"],
     weighting: Literal["cross-product-share", "own-share"] | None,
 ) -> float:
@@ -1234,7 +1237,7 @@ def _shrratio_boundary_intcpt(
             _s_intcpt = mpf("1.0")
         case None if agg_method == "distance":
             _s_intcpt = _delta_star * mp.sqrt("2")
-        case None if agg_method == "arithmetic" and recapture_spec == "inside-out":
+        case None if agg_method == "arithmetic" and recapture_form == "inside-out":
             _s_intcpt = mp.fdiv(
                 mp.fsub(
                     2 * _delta_star * _r_val + 1, mp.fabs(2 * _delta_star * _r_val - 1)

mergeron/core/guidelines_boundaries_specialized_functions.py

@@ -1,26 +1,24 @@
 """
-Specialized routines for defining and analyzing boundaries for Guidelines standards.
+Specialized methods for defining and analyzing boundaries for Guidelines standards.
 
-These routines provide improved precision or demonstrate additional methods, but tend
+These methods provide improved precision or demonstrate additional methods, but tend
 to have poor performance
 
 """
 
+from collections.abc import Callable
+from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Literal
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
+from numpy.typing import NDArray
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
 from sympy import lambdify, simplify, solve, symbols
 
 from .. import _PKG_NAME  # noqa: TID252
-from .guidelines_boundaries import (
-    GuidelinesBoundary,
-    GuidelinesBoundaryCallable,
-    _shrratio_boundary_intcpt,
-    lerp,
-)
+from .guidelines_boundaries import GuidelinesBoundary, _shrratio_boundary_intcpt, lerp
 
 __version__ = version(_PKG_NAME)
 
@@ -29,7 +27,14 @@ mp.prec = 80
 mp.trap_complex = True
 
 
-def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable:
+@dataclass(slots=True, frozen=True)
+class GuidelinesBoundaryCallable:
+    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
+    area: float
+    s_naught: float = 0
+
+
+def delta_hhi_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
     """
     Generate the list of share combination on the ΔHHI boundary.
 
@@ -37,8 +42,6 @@ def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable
     ----------
     _dh_val:
         Merging-firms' ΔHHI bound.
-    prec
-        Number of decimal places for rounding reported shares.
 
     Returns
     -------
@@ -71,7 +74,7 @@ def shrratio_boundary_qdtr_wtd_avg(
     /,
     *,
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
 ) -> GuidelinesBoundaryCallable:
     """
     Share combinations for the share-weighted average GUPPI boundary with symmetric
@@ -85,7 +88,7 @@ def shrratio_boundary_qdtr_wtd_avg(
         recapture ratio
     weighting
         Whether "own-share" or "cross-product-share" (or None for simple, unweighted average)
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
 
@@ -109,7 +112,7 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - (_s_1 + _s_2) * _delta_star
@@ -118,7 +121,7 @@ def shrratio_boundary_qdtr_wtd_avg(
             _bdry_func = solve(_bdry_eqn, _s_2)[0]  # type: ignore
             _s_naught = (
                 float(solve(simplify(_bdry_eqn.subs({_s_2: 1 - _s_1})), _s_1)[0])  # type: ignore
-                if recapture_spec == "inside-out"
+                if recapture_form == "inside-out"
                 else 0
             )
             _bdry_area = float(
@@ -139,7 +142,7 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - (_s_1 + _s_2) * _d_star
@@ -167,7 +170,7 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - _delta_star
@@ -191,7 +194,7 @@ def shrratio_boundary_distance(
     *,
     agg_method: Literal["arithmetic", "distance"] = "arithmetic",
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
 ) -> GuidelinesBoundary:
     """
@@ -214,7 +217,7 @@ def shrratio_boundary_distance(
         Whether "arithmetic", "geometric", or "distance".
     weighting
         Whether "own-share" or "cross-product-share".
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -252,7 +255,7 @@ def shrratio_boundary_distance(
             _de_1 = _s_2 / (1 - _s_1)
             _de_2 = (
                 _s_1 / (1 - lerp(_s_1, _s_2, _r_val))
-                if recapture_spec == "inside-out"
+                if recapture_form == "inside-out"
                 else _s_1 / (1 - _s_2)
             )
 
@@ -310,7 +313,7 @@ def shrratio_boundary_distance(
         _s_1_pre,
         _delta_star,
         _r_val,
-        recapture_spec=recapture_spec,
+        recapture_form=recapture_form,
         agg_method=agg_method,
         weighting=weighting,
     )