mergeron 2024.739127.1__py3-none-any.whl → 2024.739145.0__py3-none-any.whl

mergeron/__init__.py

@@ -8,7 +8,7 @@ from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739127.1"
+VERSION = "2024.739145.0"
 
 __version__ = VERSION
 
@@ -21,14 +21,11 @@ If the subdirectory doesn't exist, it is created on package invocation.
 if not DATA_DIR.is_dir():
     DATA_DIR.mkdir(parents=False)
 
-np.set_printoptions(precision=18)
-
-
-type ArrayINT = NDArray[np.intp]
-type ArrayFloat = NDArray[np.half | np.single | np.double]
-
+np.set_printoptions(precision=24, floatmode="fixed")
 
 type ArrayBoolean = NDArray[np.bool_]
+type ArrayFloat = NDArray[np.half | np.single | np.double]
+type ArrayINT = NDArray[np.intp]
 
 type ArrayDouble = NDArray[np.double]
 type ArrayBIGINT = NDArray[np.int64]
@@ -38,7 +35,7 @@ DEFAULT_REC_RATE = 0.85
 
 @enum.unique
 class RECForm(enum.StrEnum):
-    """For derivation of recapture rate from market shares."""
+    """For derivation of recapture ratio from market shares."""
 
     INOUT = "inside-out"
     OUTIN = "outside-in"

mergeron/core/__init__.py

@@ -1,3 +1,8 @@
+from mpmath import mp  # type: ignore
+
 from .. import VERSION  # noqa: TID252
 
 __version__ = VERSION
+
+type MPFloat = mp.mpf  # pyright: ignore
+type MPMatrix = mp.matrix  # pyright: ignore

mergeron/core/{damodaran_margin_data.py → empirical_margin_distribution.py}

@@ -2,6 +2,9 @@
 Functions to parse margin data compiled by
 Prof. Aswath Damodaran, Stern School of Business, NYU.
 
+Provides :func:`mgn_data_resampler` for generating margin data
+from an estimated Gaussian KDE from the source (margin) data.
+
 Data are downloaded or reused from a local copy, on demand.
 
 For terms of use of Prof. Damodaran's data, please see:
@@ -103,7 +106,7 @@ def mgn_data_getter(  # noqa: PLR0912
             if not _mgn_path.is_file():
                 with resources.as_file(
                     resources.files(f"{_PKG_NAME}.data").joinpath(
-                        "damodaran_margin_data.xls"
+                        "empirical_margin_distribution.xls"
                     )
                 ) as _mgn_data_archive_path:
                     shutil.copy2(_mgn_data_archive_path, _mgn_path)
@@ -129,7 +132,7 @@ def mgn_data_getter(  # noqa: PLR0912
         _xl_row[1] = int(_xl_row[1])
         _mgn_dict[_xl_row[0]] = dict(zip(_mgn_row_keys[1:], _xl_row[1:], strict=True))
 
-    _ = _data_archive_path.write_bytes(msgpack.packb(_mgn_dict))
+    _ = _data_archive_path.write_bytes(msgpack.packb(_mgn_dict))  # pyright: ignore
 
     return MappingProxyType(_mgn_dict)
 
@@ -218,7 +221,7 @@ def mgn_data_resampler(
     _x, _w, _ = mgn_data_builder(mgn_data_getter())
 
     _mgn_kde = stats.gaussian_kde(_x, weights=_w, bw_method="silverman")
-    _mgn_kde.set_bandwidth(bw_method=_mgn_kde.factor / 3.0)
+    _mgn_kde.set_bandwidth(bw_method=_mgn_kde.factor / 3.0)  # pyright: ignore
 
     if isinstance(_sample_size, int):
         return np.array(

mergeron/core/ftc_merger_investigations_data.py

@@ -96,10 +96,11 @@ class INVTableData(NamedTuple):
 
 
 type INVData = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
+type _INVData_in = dict[str, dict[str, dict[str, INVTableData]]]
 
 
 def construct_data(
-    _archive_path: Path | None = None,
+    _archive_path: Path = INVDATA_ARCHIVE_PATH,
     *,
     flag_backward_compatibility: bool = True,
     flag_pharma_for_exclusion: bool = True,
@@ -134,11 +135,11 @@ def construct_data(
         A dictionary of merger investigations data keyed to reporting periods
 
     """
-    _archive_path = _archive_path or INVDATA_ARCHIVE_PATH
+
     if _archive_path.is_file() and not rebuild_data:
         _archived_data = msgpack.unpackb(_archive_path.read_bytes(), use_list=False)
 
-        _invdata: dict[str, dict[str, dict[str, INVTableData]]] = {}
+        _invdata: _INVData_in = {}
         for _period in _archived_data:
             _invdata[_period] = {}
             for _table_type in _archived_data[_period]:
@@ -149,7 +150,7 @@ def construct_data(
                     )
         return MappingProxyType(_invdata)
 
-    _invdata = dict(_parse_invdata())  # Convert immutable to mutable
+    _invdata = dict(_parse_invdata())  # type: ignore # Convert immutable to mutable
 
     # Add some data periods (
     #   only periods ending in 2011, others have few observations and
@@ -197,12 +198,12 @@ def construct_data(
                 )
             }
 
-    _ = INVDATA_ARCHIVE_PATH.write_bytes(msgpack.packb(_invdata))
+    _ = INVDATA_ARCHIVE_PATH.write_bytes(msgpack.packb(_invdata))  # pyright: ignore
 
     return MappingProxyType(_invdata)
 
 
-def _construct_no_evidence_data(_invdata: INVData, _data_period: str, /) -> None:
+def _construct_no_evidence_data(_invdata: _INVData_in, _data_period: str, /) -> None:
     _invdata_ind_grp = "All Markets"
     _table_nos_map = dict(
         zip(
@@ -231,18 +232,20 @@ def _construct_no_evidence_data(_invdata: INVData, _data_period: str, /) -> None
             _stn0 = "Table 4.1" if _stats_grp == "ByFirmCount" else "Table 3.1"
             _stn1, _stn2 = (_dtn.replace(".X", f".{_i}") for _i in ("1", "2"))
 
-            _invdata_sub_evid_cond_conc[_dtn] = INVTableData(
-                _invdata_ind_grp,
-                _invdata_evid_cond,
-                np.column_stack((
-                    _invdata_sub_evid_cond_conc[_stn0].data_array[:, :2],
-                    (
-                        _invdata_sub_evid_cond_conc[_stn0].data_array[:, 2:]
-                        - _invdata_sub_evid_cond_conc[_stn1].data_array[:, 2:]
-                        - _invdata_sub_evid_cond_conc[_stn2].data_array[:, 2:]
-                    ),
-                )),
-            )
+            _invdata_sub_evid_cond_conc |= {
+                _dtn: INVTableData(
+                    _invdata_ind_grp,
+                    _invdata_evid_cond,
+                    np.column_stack((
+                        _invdata_sub_evid_cond_conc[_stn0].data_array[:, :2],
+                        (
+                            _invdata_sub_evid_cond_conc[_stn0].data_array[:, 2:]
+                            - _invdata_sub_evid_cond_conc[_stn1].data_array[:, 2:]
+                            - _invdata_sub_evid_cond_conc[_stn2].data_array[:, 2:]
+                        ),
+                    )),
+                )
+            }
 
 
 def _construct_new_period_data(
@@ -494,7 +497,7 @@ def _parse_invdata() -> INVData:
 
 
 def _parse_page_blocks(
-    _invdata: INVData, _data_period: str, _doc_pg_blocks: Sequence[Sequence[Any]], /
+    _invdata: _INVData_in, _data_period: str, _doc_pg_blocks: Sequence[Sequence[Any]], /
 ) -> None:
     if _data_period != "1996-2011":
         _parse_table_blocks(_invdata, _data_period, _doc_pg_blocks)
@@ -521,7 +524,7 @@ def _parse_page_blocks(
 
 
 def _parse_table_blocks(
-    _invdata: INVData, _data_period: str, _table_blocks: Sequence[Sequence[str]], /
+    _invdata: _INVData_in, _data_period: str, _table_blocks: Sequence[Sequence[str]], /
 ) -> None:
     _invdata_evid_cond = "Unrestricted on additional evidence"
     _table_num, _table_ser, _table_type = _identify_table_type(

mergeron/core/guidelines_boundaries.py

@@ -20,12 +20,13 @@ from .. import (  # noqa: TID252
     RECForm,
     UPPAggrSelector,
 )
+from . import MPFloat
 from . import guidelines_boundary_functions as gbfn
 
 __version__ = VERSION
 
 
-mp.prec = 80
+mp.dps = 32
 mp.trap_complex = True
 
 type HMGPubYear = Literal[1992, 2004, 2010, 2023]
@@ -47,7 +48,7 @@ class GuidelinesThresholds:
     """
     Guidelines threholds by Guidelines publication year
 
-    ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
+    ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
     constructed from concentration standards in Guidelines published in
     1992, 2004, 2010, and 2023.
 
@@ -70,7 +71,7 @@ class GuidelinesThresholds:
     """
     Negative presumption quantified on various measures
 
-    ΔHHI safeharbor bound, default recapture rate, GUPPI bound,
+    ΔHHI safeharbor bound, default recapture ratio, GUPPI bound,
     diversion ratio limit, CMCR, and IPR
     """
 
@@ -78,7 +79,7 @@ class GuidelinesThresholds:
     """
     Presumption of harm defined in HMG
 
-    ΔHHI bound and corresponding default recapture rate, GUPPI bound,
+    ΔHHI bound and corresponding default recapture ratio, GUPPI bound,
     diversion ratio limit, CMCR, and IPR
     """
 
@@ -87,7 +88,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 rate,
+    of (post-merger) HHI presumption, and corresponding default recapture ratio,
     GUPPI bound, diversion ratio limit, CMCR, and IPR
     """
 
@@ -162,38 +163,40 @@ class GuidelinesThresholds:
         )
 
 
-def _concentration_threshold_validator(
-    _instance: ConcentrationBoundary, _attribute: Attribute[float], _value: float, /
-) -> None:
-    if not 0 <= _value <= 1:
-        raise ValueError("Concentration threshold must lie between 0 and 1.")
-
-
-def _concentration_measure_name_validator(
-    _instance: ConcentrationBoundary, _attribute: Attribute[str], _value: str, /
-) -> None:
-    if _value not in ("ΔHHI", "Combined share", "Pre-merger HHI", "Post-merger HHI"):
-        raise ValueError(f"Invalid name for a concentration measure, {_value!r}.")
-
-
 @frozen
 class ConcentrationBoundary:
     """Concentration parameters, boundary coordinates, and area under concentration boundary."""
 
-    threshold: float = field(
-        kw_only=False,
-        default=0.01,
-        validator=(validators.instance_of(float), _concentration_threshold_validator),
-    )
-    precision: int = field(
-        kw_only=False, default=5, validator=validators.instance_of(int)
-    )
     measure_name: Literal[
         "ΔHHI", "Combined share", "Pre-merger HHI", "Post-merger HHI"
     ] = field(
         kw_only=False,
-        default="ΔHHI",
-        validator=(validators.instance_of(str), _concentration_measure_name_validator),
+        default="ΔHHI",  # pyright: ignore
+    )
+
+    @measure_name.validator  # pyright: ignore
+    def __mnv(
+        _instance: ConcentrationBoundary, _attribute: Attribute[str], _value: str, /
+    ) -> None:
+        if _value not in (
+            "ΔHHI",
+            "Combined share",
+            "Pre-merger HHI",
+            "Post-merger HHI",
+        ):
+            raise ValueError(f"Invalid name for a concentration measure, {_value!r}.")
+
+    threshold: float = field(kw_only=False, default=0.01)
+
+    @threshold.validator  # pyright: ignore
+    def __tv(
+        _instance: ConcentrationBoundary, _attribute: Attribute[float], _value: float, /
+    ) -> None:
+        if not 0 <= _value <= 1:
+            raise ValueError("Concentration threshold must lie between 0 and 1.")  # pyright: ignore
+
+    precision: int = field(
+        kw_only=False, default=5, validator=validators.instance_of(int)
     )
 
     coordinates: ArrayDouble = field(init=False, kw_only=True)
@@ -213,45 +216,17 @@ class ConcentrationBoundary:
             case "Post-merger HHI":
                 _conc_fn = gbfn.hhi_post_contrib_boundary
 
-        _boundary = _conc_fn(self.threshold, prec=self.precision)
+        _boundary = _conc_fn(self.threshold, dps=self.precision)
         object.__setattr__(self, "coordinates", _boundary.coordinates)
         object.__setattr__(self, "area", _boundary.area)
 
 
-def _divr_value_validator(
-    _instance: DiversionRatioBoundary, _attribute: Attribute[float], _value: float, /
-) -> None:
-    if not 0 <= _value <= 1:
-        raise ValueError(
-            "Margin-adjusted benchmark share ratio must lie between 0 and 1."
-        )
-
-
-def _rec_spec_validator(
-    _instance: DiversionRatioBoundary,
-    _attribute: Attribute[RECForm],
-    _value: RECForm,
-    /,
-) -> None:
-    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 rate as attribute, "recapture_rate" of '
-            "this `DiversionRatioBoundarySpec` object."
-        )
-    if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
-        raise ValueError(
-            f"Specified aggregation method, {_instance.agg_method} requires a recapture specification."
-        )
-
-
 @frozen
 class DiversionRatioBoundary:
     """
     Diversion ratio specification, boundary coordinates, and area under boundary.
 
-    Along with the default diversion ratio and recapture rate,
+    Along with the default diversion ratio and recapture ratio,
     a diversion ratio boundary specification includes the recapture form --
     whether fixed for both merging firms' products ("proportional") or
     consistent with share-proportionality, i.e., "inside-out";
@@ -261,29 +236,33 @@ class DiversionRatioBoundary:
 
     """
 
-    diversion_ratio: float = field(
-        kw_only=False,
-        default=0.065,
-        validator=(validators.instance_of(float), _divr_value_validator),
-    )
-
-    recapture_rate: float = field(
+    diversion_ratio: float = field(kw_only=False, default=0.065)
+
+    @diversion_ratio.validator  # pyright: ignore
+    def __dvv(
+        _instance: DiversionRatioBoundary,
+        _attribute: Attribute[float],
+        _value: float,
+        /,
+    ) -> None:
+        if not 0 <= _value <= 1:
+            raise ValueError(
+                "Margin-adjusted benchmark share ratio must lie between 0 and 1."
+            )
+
+    recapture_ratio: float = field(
         kw_only=False, default=DEFAULT_REC_RATE, validator=validators.instance_of(float)
     )
 
-    recapture_form: RECForm | None = field(
-        kw_only=True,
-        default=RECForm.INOUT,
-        validator=(validators.instance_of((type(None), RECForm)), _rec_spec_validator),
-    )
+    recapture_form: RECForm | None = field(kw_only=True, default=RECForm.INOUT)
     """
-    The form of the recapture rate.
+    The form of the recapture ratio.
 
-    When :attr:`mergeron.RECForm.INOUT`, the recapture rate for
+    When :attr:`mergeron.RECForm.INOUT`, the recapture ratio for
     he product having the smaller market-share is assumed to equal the default,
-    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
+    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
     constructed from the generated purchase-probabilities for products in
     the market and for the outside good, specify :attr:`mergeron.RECForm.OUTIN`.)
 
@@ -296,6 +275,27 @@ class DiversionRatioBoundary:
 
     """
 
+    @recapture_form.validator  # pyright: ignore
+    def __rsv(
+        _instance: DiversionRatioBoundary,
+        _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:
+            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."
+            )
+        if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
+            raise ValueError(
+                f"Specified aggregation method, {_instance.agg_method} requires a recapture specification."
+            )
+
     agg_method: UPPAggrSelector = field(
         kw_only=True,
         default=UPPAggrSelector.MAX,
@@ -331,11 +331,11 @@ class DiversionRatioBoundary:
 
     def __attrs_post_init__(self, /) -> None:
         _share_ratio = critical_share_ratio(
-            self.diversion_ratio, r_bar=self.recapture_rate
+            self.diversion_ratio, r_bar=self.recapture_ratio
         )
         _upp_agg_kwargs: gbfn.ShareRatioBoundaryKeywords = {
             "recapture_form": getattr(self.recapture_form, "value", "inside-out"),
-            "prec": self.precision,
+            "dps": self.precision,
         }
         match self.agg_method:
             case UPPAggrSelector.DIS:
@@ -345,10 +345,10 @@ class DiversionRatioBoundary:
                 _upp_agg_fn = gbfn.shrratio_boundary_xact_avg  # type: ignore
             case UPPAggrSelector.MAX:
                 _upp_agg_fn = gbfn.shrratio_boundary_max  # type: ignore
-                _upp_agg_kwargs = {"prec": 10}  # replace here
+                _upp_agg_kwargs = {"dps": 10}  # replace here
             case UPPAggrSelector.MIN:
                 _upp_agg_fn = gbfn.shrratio_boundary_min  # type: ignore
-                _upp_agg_kwargs |= {"prec": 10}  # update here
+                _upp_agg_kwargs |= {"dps": 10}  # update here
             case _:
                 _upp_agg_fn = gbfn.shrratio_boundary_wtd_avg
 
@@ -370,7 +370,7 @@ class DiversionRatioBoundary:
 
                 _upp_agg_kwargs |= {"agg_method": _aggregator, "weighting": _wgt_type}
 
-        _boundary = _upp_agg_fn(_share_ratio, self.recapture_rate, **_upp_agg_kwargs)
+        _boundary = _upp_agg_fn(_share_ratio, self.recapture_ratio, **_upp_agg_kwargs)  # pyright: ignore  # TypedDict redefinition
         object.__setattr__(self, "coordinates", _boundary.coordinates)
         object.__setattr__(self, "area", _boundary.area)
 
@@ -392,11 +392,11 @@ def guppi_from_delta(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
-        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture rate.
+        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture ratio.
 
     """
     return gbfn.round_cust(
@@ -413,7 +413,7 @@ def critical_share_ratio(
     m_star: float = 1.00,
     r_bar: float = 1.00,
     frac: float = 1e-16,
-) -> mpf:
+) -> MPFloat:
     """
     Corollary to GUPPI bound.
 
@@ -424,12 +424,12 @@ def critical_share_ratio(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
         Critical share ratio (share ratio bound) corresponding to the GUPPI bound
-        for given margin and recapture rate.
+        for given margin and recapture ratio.
 
     """
     return gbfn.round_cust(
@@ -445,7 +445,7 @@ def share_from_guppi(
     r_bar: float = DEFAULT_REC_RATE,
 ) -> float:
     """
-    Symmetric-firm share for given GUPPI, margin, and recapture rate.
+    Symmetric-firm share for given GUPPI, margin, and recapture ratio.
 
     Parameters
     ----------
@@ -454,13 +454,13 @@ def share_from_guppi(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
     float
         Symmetric firm market share on GUPPI boundary, for given margin and
-        recapture rate.
+        recapture ratio.
 
     """