mergeron 2025.739290.5__py3-none-any.whl → 2025.739290.7__py3-none-any.whl

mergeron/__init__.py

@@ -12,18 +12,20 @@ from ruamel import yaml
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2025.739290.5"
+VERSION = "2025.739290.7"
 
 __version__ = VERSION
 
-DATA_DIR: Path = Path.home() / _PKG_NAME
+WORK_DIR = globals().get("WORK_DIR", Path.home() / _PKG_NAME)
 """
-Defines a subdirectory named for this package in the user's home path.
+If defined, the global variable WORK_DIR is used as a data store.
 
-If the subdirectory doesn't exist, it is created on package invocation.
+If the user does not define WORK_DIR, a subdirectory in
+the user's home directory, named for this package, is
+created/reused.
 """
-if not DATA_DIR.is_dir():
-    DATA_DIR.mkdir(parents=False)
+if not WORK_DIR.is_dir():
+    WORK_DIR.mkdir(parents=False)
 
 DEFAULT_REC_RATIO = 0.85
 
@@ -36,14 +38,14 @@ PKG_ATTRS_MAP: dict[str, object] = {}
 
 np.set_printoptions(precision=24, floatmode="fixed")
 
-type HMGPubYear = Literal[1982, 1984, 1992, 2010, 2023]
+type HMGPubYear = Literal[1992, 2010, 2023]
 
 type ArrayBoolean = NDArray[np.bool_]
 type ArrayFloat = NDArray[np.floating]
-type ArrayINT = NDArray[np.unsignedinteger]
+type ArrayINT = NDArray[np.integer]
 
 type ArrayDouble = NDArray[np.float64]
-type ArrayBIGINT = NDArray[np.uint64]
+type ArrayBIGINT = NDArray[np.int64]
 
 
 this_yaml = yaml.YAML(typ="rt")
@@ -131,35 +133,47 @@ class Enameled(enum.Enum):
 @this_yaml.register_class
 @enum.unique
 class RECForm(str, Enameled):
-    """For derivation of recapture ratio from market shares."""
+    R"""For derivation of recapture ratio 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
+    as having one of the following forms:
+    """
 
-    INOUT = "inside-out"
-    R"""
-    Given, :math:`\overline{r}, s_i {\ } \forall {\ } i \in \set{1, 2, \ldots, m}`, with
-    :math:`s_{min} = \min(s_1, s_2)`,
+    FIXED = "proportional"
+    R"""Given, :math:`\overline{r}`,
 
     .. math::
 
-        REC_i = \frac{(1 - s_i) \overline{r}}{(1 - s_{min}) - (s_i - s_{min}) \overline{r}}
+        REC_i = \overline{r} {\ } \forall {\ } i \in \mathscr{M}
 
     """
 
-    OUTIN = "outside-in"
+    INOUT = "inside-out"
     R"""
-    Given, :math:`\pi_i {\ } \forall {\ } i \in N`,
+    Given, :math:`\overline{r}, s_i {\ } \forall {\ } i \in \mathscr{M}`, with
+    :math:`s_{min} = \min(s_1, s_2)`,
 
     .. math::
 
-        REC_i = \frac{\sum_{i \in M} \pi_i}{\sum_{j \in N} \pi_j}
+        REC_i = \frac{\overline{r} (1 - s_i)}{1 - (1 - \overline{r}) s_{min} - \overline{r} s_i}
+        {\ } \forall {\ } i \in \mathscr{M}
 
     """
 
-    FIXED = "proportional"
-    R"""Given, :math:`\overline{r}`,
+    OUTIN = "outside-in"
+    R"""
+    Given, :math:`d_{ij} {\ } \forall {\ } i, j \in \mathscr{M}, i \neq j`,
 
     .. math::
 
-        REC_i = \overline{r} {\ } \forall {\ } i \in M
+        REC_i = {\sum_{j \in \mathscr{M}}^{j \neq i} d_{ij}}
+        {\ } \forall {\ } i \in \mathscr{M}
 
     """
 

mergeron/core/__init__.py

@@ -9,7 +9,14 @@ import mpmath  # type: ignore
 import numpy as np
 from attrs import cmp_using, field, frozen
 
-from .. import VERSION, ArrayBIGINT, this_yaml, yaml_rt_mapper  # noqa: TID252
+from .. import (  # noqa: TID252
+    VERSION,
+    ArrayBIGINT,
+    ArrayDouble,
+    this_yaml,
+    yamelize_attrs,
+    yaml_rt_mapper,
+)
 
 __version__ = VERSION
 
@@ -17,6 +24,17 @@ type MPFloat = mpmath.ctx_mp_python.mpf
 type MPMatrix = mpmath.matrix  # type: ignore
 
 
+@frozen
+class GuidelinesBoundary:
+    """Output of a Guidelines boundary function."""
+
+    coordinates: ArrayDouble
+    """Market-share pairs as Cartesian coordinates of points on the boundary."""
+
+    area: float
+    """Area under the boundary."""
+
+
 @frozen
 class INVTableData:
     industry_group: str
@@ -29,6 +47,7 @@ type INVData = MappingProxyType[
 ]
 type INVData_in = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
 
+yamelize_attrs(INVTableData)
 
 (_, _) = (
     this_yaml.representer.add_representer(
@@ -59,16 +78,26 @@ type INVData_in = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
     ),
 )
 
+_, _ = (
+    this_yaml.representer.add_representer(
+        MappingProxyType,
+        lambda _r, _d: _r.represent_mapping("!mappingproxy", dict(_d.items())),
+    ),
+    this_yaml.constructor.add_constructor(
+        "!mappingproxy", lambda _c, _n: MappingProxyType(dict(**yaml_rt_mapper(_c, _n)))
+    ),
+)
+
 
 def _dict_from_mapping(_p: Mapping[Any, Any], /) -> dict[Any, Any]:
-    retval = {}
+    retval: dict[Any, Any] = {}
     for _k, _v in _p.items():  # for subit in it:
         retval |= {_k: _dict_from_mapping(_v)} if isinstance(_v, Mapping) else {_k: _v}
     return retval
 
 
 def _mappingproxy_from_mapping(_p: Mapping[Any, Any], /) -> MappingProxyType[Any, Any]:
-    retval = {}
+    retval: dict[Any, Any] = {}
     for _k, _v in _p.items():  # for subit in it:
         retval |= (
             {_k: _mappingproxy_from_mapping(_v)}
@@ -76,34 +105,3 @@ def _mappingproxy_from_mapping(_p: Mapping[Any, Any], /) -> MappingProxyType[Any
             else {_k: _v}
         )
     return MappingProxyType(retval)
-
-
-_, _ = (
-    this_yaml.representer.add_representer(
-        MappingProxyType,
-        lambda _r, _d: _r.represent_mapping("!mappingproxy", dict(_d.items())),
-    ),
-    this_yaml.constructor.add_constructor(
-        "!mappingproxy", lambda _c, _n: MappingProxyType(yaml_rt_mapper(_c, _n))
-    ),
-)
-
-
-for _typ in (INVTableData,):
-    _, _ = (
-        this_yaml.representer.add_representer(
-            _typ,
-            lambda _r, _d: _r.represent_mapping(
-                f"!{_d.__class__.__name__}",
-                {
-                    _a.name: getattr(_d, _a.name)
-                    for _a in _d.__attrs_attrs__
-                    if _a.name not in {"coordinates", "area"}
-                },
-            ),
-        ),
-        this_yaml.constructor.add_constructor(
-            f"!{_typ.__name__}",
-            lambda _c, _n: globals()[_n.tag.lstrip("!")](**yaml_rt_mapper(_c, _n)),
-        ),
-    )

mergeron/core/empirical_margin_distribution.py

@@ -39,7 +39,6 @@ price-cost margins fall in the interval :math:`[0, 1]`.
 import shutil
 import zipfile
 from collections.abc import Mapping
-from importlib import resources
 from pathlib import Path
 from types import MappingProxyType
 
@@ -49,12 +48,17 @@ from numpy.random import PCG64DXSM, Generator, SeedSequence
 from scipy import stats  # type: ignore
 from xlrd import open_workbook  # type: ignore
 
-from .. import _PKG_NAME, DATA_DIR, VERSION, ArrayDouble, this_yaml  # noqa: TID252
+from .. import VERSION, ArrayDouble, this_yaml  # noqa: TID252
+from .. import WORK_DIR as PKG_WORK_DIR  # noqa: TID252
+from .. import data as mdat  # noqa: TID252
 from . import _mappingproxy_from_mapping
 
 __version__ = VERSION
 
-MGNDATA_ARCHIVE_PATH = DATA_DIR / "damodaran_margin_data_serialized.zip"
+WORK_DIR = globals().get("WORK_DIR", PKG_WORK_DIR)
+"""Redefined, in case the user defines WORK_DIR betweeen module imports."""
+
+MGNDATA_ARCHIVE_PATH = WORK_DIR / "damodaran_margin_data_serialized.zip"
 
 
 u3pm = urllib3.PoolManager()
@@ -74,14 +78,14 @@ def margin_data_getter(  # noqa: PLR0912
     data_archive_path = data_archive_path or MGNDATA_ARCHIVE_PATH
     workbook_path = data_archive_path.parent / f"damodaran_{_table_name}_data.xls"
     if data_archive_path.is_file() and not data_download_flag:
-        # with data_archive_path_.open("r") as _yfh:
-        #     margin_data_dict: dict[str, dict[str, float | int]] = this_yaml.load(_yfh)
         with (
             zipfile.ZipFile(data_archive_path) as _yzip,
             _yzip.open(f"{data_archive_path.stem}.yaml") as _yfh,
         ):
-            margin_data_dict: dict[str, dict[str, float | int]] = this_yaml.load(_yfh)
-        return _mappingproxy_from_mapping(margin_data_dict)
+            margin_data_dict: MappingProxyType[
+                str, MappingProxyType[str, float | int]
+            ] = this_yaml.load(_yfh)
+        return margin_data_dict
     elif workbook_path.is_file():
         workbook_path.unlink()
         if data_archive_path.is_file():
@@ -116,19 +120,14 @@ def margin_data_getter(  # noqa: PLR0912
                 "Using bundled copy."
             )
             if not workbook_path.is_file():
-                with resources.as_file(
-                    resources.files(f"{_PKG_NAME}.data").joinpath(
-                        "empirical_margin_distribution.xls"
-                    )
-                ) as margin_data_archive_path:
-                    shutil.copy2(margin_data_archive_path, workbook_path)
+                shutil.copy2(mdat.DAMODARAN_MARGIN_WORKBOOK, workbook_path)
         else:
             raise error_
 
     xl_book = open_workbook(workbook_path, ragged_rows=True, on_demand=True)
     xl_sheet = xl_book.sheet_by_name("Industry Averages")
 
-    margin_dict: dict[str, dict[str, float | int]] = {}
+    margin_dict_in: dict[str, dict[str, float | int]] = {}
     row_keys: list[str] = []
     read_row_flag = False
     for _ridx in range(xl_sheet.nrows):
@@ -142,15 +141,16 @@ def margin_data_getter(  # noqa: PLR0912
             continue
 
         xl_row[1] = int(xl_row[1])
-        margin_dict[xl_row[0]] = dict(zip(row_keys[1:], xl_row[1:], strict=True))
+        margin_dict_in[xl_row[0]] = dict(zip(row_keys[1:], xl_row[1:], strict=True))
 
+    margin_dict = _mappingproxy_from_mapping(margin_dict_in)
     with (
         zipfile.ZipFile(data_archive_path, "w") as _yzip,
         _yzip.open(f"{data_archive_path.stem}.yaml", "w") as _yfh,
     ):
         this_yaml.dump(margin_dict, _yfh)
 
-    return _mappingproxy_from_mapping(margin_dict)
+    return margin_dict
 
 
 def margin_data_builder(

mergeron/core/ftc_merger_investigations_data.py

@@ -12,8 +12,7 @@ from __future__ import annotations
 
 import re
 import shutil
-from collections.abc import Sequence
-from importlib import resources
+from collections.abc import Mapping, Sequence
 from operator import itemgetter
 from pathlib import Path
 from types import MappingProxyType
@@ -26,14 +25,9 @@ import urllib3
 from bs4 import BeautifulSoup
 from numpy.testing import assert_array_equal
 
-from .. import (  # noqa: TID252
-    _PKG_NAME,
-    DATA_DIR,
-    EMPTY_ARRAYINT,
-    VERSION,
-    ArrayBIGINT,
-    this_yaml,
-)
+from .. import EMPTY_ARRAYINT, VERSION, ArrayBIGINT, this_yaml  # noqa: TID252
+from .. import WORK_DIR as PKG_WORK_DIR  # noqa: TID252
+from .. import data as mdat  # noqa: TID252
 from . import (
     INVData,
     INVData_in,
@@ -46,21 +40,16 @@ __version__ = VERSION
 
 m.patch()
 
-FTCDATA_DIR = DATA_DIR / "FTCData"
-if not FTCDATA_DIR.is_dir():
-    FTCDATA_DIR.mkdir(parents=True)
+WORK_DIR = globals().get("WORK_DIR", PKG_WORK_DIR)
+"""Redefined, in case the user defines WORK_DIR betweeen module imports."""
 
-INVDATA_ARCHIVE_PATH = DATA_DIR / "ftc_invdata.zip"
-if (
-    not INVDATA_ARCHIVE_PATH.is_file()
-    and (
-        _bundled_copy := resources.files(f"{_PKG_NAME}.data").joinpath(
-            INVDATA_ARCHIVE_PATH.name
-        )
-    ).is_file()
-):
-    with resources.as_file(_bundled_copy) as _bundled_copy_path:
-        shutil.copy2(_bundled_copy_path, INVDATA_ARCHIVE_PATH)
+FID_WORK_DIR = WORK_DIR / "FTCData"
+if not FID_WORK_DIR.is_dir():
+    FID_WORK_DIR.mkdir(parents=True)
+
+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)
 
 TABLE_NO_RE = re.compile(r"Table \d+\.\d+")
 TABLE_TYPES = ("ByHHIandDelta", "ByFirmCount")
@@ -105,6 +94,10 @@ CNT_FCOUNT_DICT = {
 }
 
 
+def reverse_map(_dict: Mapping[Any, Any]) -> Mapping[Any, Any]:
+    return {_v: _k for _k, _v in _dict.items()}
+
+
 def construct_data(
     _archive_path: Path = INVDATA_ARCHIVE_PATH,
     *,
@@ -442,12 +435,12 @@ def _parse_invdata() -> INVData:
     # )
     import pymupdf  # type: ignore  # noqa: PLC0415
 
-    invdata_docnames = _download_invdata(FTCDATA_DIR)
+    invdata_docnames = _download_invdata(FID_WORK_DIR)
 
     invdata: INVData_in = {}
 
     for invdata_docname in invdata_docnames:
-        invdata_pdf_path = FTCDATA_DIR.joinpath(invdata_docname)
+        invdata_pdf_path = FID_WORK_DIR.joinpath(invdata_docname)
 
         invdata_doc = pymupdf.open(invdata_pdf_path)
         invdata_meta = invdata_doc.metadata
@@ -709,7 +702,7 @@ def _process_table_blks_cnt_type(
     return invdata_array[np.argsort(invdata_array[:, 0])]
 
 
-def _download_invdata(_dl_path: Path = FTCDATA_DIR) -> tuple[str, ...]:
+def _download_invdata(_dl_path: Path = FID_WORK_DIR) -> tuple[str, ...]:
     if not _dl_path.is_dir():
         _dl_path.mkdir(parents=True)
 

mergeron/core/guidelines_boundaries.py

@@ -51,14 +51,12 @@ class GuidelinesThresholds:
 
     ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
     constructed from concentration standards in Guidelines published in
-    1982, 1984, 1992, 2010, and 2023.
+    1992, 2010, and 2023.
 
     """
 
     pub_year: HMGPubYear = field(
-        kw_only=False,
-        default=2023,
-        validator=validators.in_([1982, 1984, 1992, 2010, 2023]),
+        kw_only=False, default=2023, validator=validators.in_([1992, 2010, 2023])
     )
     """
     Year of publication of the Guidelines
@@ -97,9 +95,7 @@ class GuidelinesThresholds:
         # thus, here, the tentative delta safeharbor under
         # the 2023 Guidelines is 100 points
         hhi_p, dh_s, dh_p = {
-            1982: (_s1982 := (0.18, 0.005, 0.01)),
-            1984: _s1982,
-            1992: _s1982,
+            1992: (0.18, 0.005, 0.01),
             2010: (0.25, 0.01, 0.02),
             2023: (0.18, 0.01, 0.01),
         }[self.pub_year]
@@ -150,6 +146,15 @@ class GuidelinesThresholds:
 class ConcentrationBoundary:
     """Concentration parameters, boundary coordinates, and area under concentration boundary."""
 
+    threshold: float = field(kw_only=False, default=0.01)
+
+    @threshold.validator
+    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.")
+
     measure_name: Literal[
         "ΔHHI",
         "Combined share",
@@ -169,17 +174,8 @@ class ConcentrationBoundary:
         }:
             raise ValueError(f"Invalid name for a concentration measure, {_value!r}.")
 
-    threshold: float = field(kw_only=False, default=0.01)
-
-    @threshold.validator
-    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.")
-
     precision: int = field(
-        kw_only=False, default=5, validator=validators.instance_of(int)
+        kw_only=True, default=5, validator=validators.instance_of(int)
     )
 
     area: float = field(init=False, kw_only=True)
@@ -240,7 +236,7 @@ class DiversionRatioBoundary:
     )
 
     recapture_form: RECForm | None = field(kw_only=True, default=RECForm.INOUT)
-    """
+    R"""
     The form of the recapture ratio.
 
     When :attr:`mergeron.RECForm.INOUT`, the recapture ratio for
@@ -251,12 +247,17 @@ class DiversionRatioBoundary:
     constructed from the generated purchase-probabilities for products in
     the market and for the outside good, specify :attr:`mergeron.RECForm.OUTIN`.)
 
-    The GUPPI boundary is a continuum of diversion ratio boundaries conditional on
-    price-cost margins, :math:`d_{ij} = g_i * p_i / (m_j * p_j)`,
-    with :math:`d_{ij}` the diverion ratio from product :math:`i` to product :math:`j`;
+    The GUPPI boundary is a continuum of conditional diversion ratio boundaries,
+
+    .. math::
+
+        d_{ij} \vert_{p_i, p_j, m_j} \triangleq \frac{g_i p_i}{m_j p_j} = \overline{d}
+
+    with :math:`d_{ij}` the diversion ratio from product :math:`i` to product :math:`j`;
     :math:`g_i` the GUPPI for product :math:`i`;
-    :math:`m_j` the margin for product :math:`j`; and
-    :math:`p_i, p_j` the prices of goods :math:`i, j`, respectively.
+    :math:`m_j` the price-cost margin on product :math:`j`;
+    :math:`p_i, p_j` the prices of goods :math:`i, j`, respectively; and
+    :math:`\overline{d}` the diversion ratio threshold (i.e., bound).
 
     """
 
@@ -283,7 +284,7 @@ class DiversionRatioBoundary:
 
     agg_method: UPPAggrSelector = field(
         kw_only=True,
-        default=UPPAggrSelector.MAX,
+        default=UPPAggrSelector.MIN,
         validator=validators.instance_of(UPPAggrSelector),
     )
     """