mergeron 2025.739290.5__tar.gz → 2025.739290.6__tar.gz

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mergeron
-Version: 2025.739290.5
+Version: 2025.739290.6
 Summary: Analyze merger enforcement policy using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/pyproject.toml

@@ -13,7 +13,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2025.739290.5"
+version = "2025.739290.6"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [
@@ -68,11 +68,11 @@ pendulum = ">=3.0.0"
 ruff = ">=0.5"
 poetry-plugin-export = "^1.8.0"
 pytest = ">=8.0"
-Sphinx = ">=7.2, <8.0"
+sphinx = ">8.2"
 semver = ">=3.0"
 sphinx-autodoc-typehints = ">=2.0.0"
-sphinx-autoapi = ">=3.0"
-sphinx-immaterial = ">=0.11"
+sphinx-autoapi = ">=3.6.0"
+sphinx-immaterial = ">0.11"
 pipdeptree = ">=2.15.1"
 types-openpyxl = ">=3.0.0"
 virtualenv = ">=20.28.0"

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/src/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.6"
 
 __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-2025.739290.5 → mergeron-2025.739290.6}/src/mergeron/core/__init__.py

@@ -61,14 +61,14 @@ type INVData_in = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
 
 
 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)}

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/src/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-2025.739290.5 → mergeron-2025.739290.6}/src/mergeron/core/ftc_merger_investigations_data.py

@@ -13,7 +13,6 @@ from __future__ import annotations
 import re
 import shutil
 from collections.abc import Sequence
-from importlib import resources
 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")
@@ -442,12 +431,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 +698,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-2025.739290.5 → mergeron-2025.739290.6}/src/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]
@@ -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).
 
     """
 

mergeron-2025.739290.6/src/mergeron/data/__init__.py

@@ -0,0 +1,57 @@
+"""
+Data useful for empirical analysis of merger enforcement policy
+
+These data are processed for further analysis within relevant
+submodules of the parent package. Thus, direct access is
+unnecessary in routine use of this package.
+"""
+
+from importlib import resources
+
+from .. import _PKG_NAME, VERSION  # noqa: TID252
+
+__version__ = VERSION
+
+
+DAMODARAN_MARGIN_WORKBOOK = resources.files(f"{_PKG_NAME}.data").joinpath(
+    "damodaran_margin_data.xls"
+)
+"""
+Python object pointing to included copy of Prof. Damodaran's margin data
+
+Only used as a fallback, in case direct download from source fails.
+
+NOTES
+-----
+Source data are from Prof. Aswath Damodaran, Stern School of Business, NYU; available online
+at https://pages.stern.nyu.edu/~adamodar/pc/datasets/margin.xls
+
+
+Use as, for example:
+
+.. code-block:: python
+
+    from mergeron.data import DAMODARAN_MARGIN_WORKBOOK
+
+    shutil.copy2(DAMODARAN_MARGIN_WORKBOOK, Path.home() / f"{DAMODARAN_MARGIN_WORKBOOK.name}")
+"""
+
+FTC_MERGER_INVESTIGATIONS_DATA = resources.files(f"{_PKG_NAME}.data").joinpath(
+    "ftc_merger_investigations_data.zip"
+)
+"""
+FTC merger investigtions data published in 2004, 2007, 2008, and 2013
+
+NOTES
+-----
+Raw data tables published by the FTC are loaded into a nested distionary, organized by
+data period, table type, and table number. Each table is stored as a numerical array
+(:module:`numpy` arrray), with additonal attrubutes for the industry group and additonal
+evidence noted in the source data.
+
+Data for additonal data periods (time spans) not reported in the  source data,
+e.g., 2004-2011, are constructed by subtracting counts in the base data from counts
+in the cumulative data, by table, for "enforced" mergers and "closed" mergers, when
+the cumulative data for the longer period are consistent with the base data for
+a sub-period.
+"""

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/src/mergeron/demo/visualize_empirical_margin_distribution.py

@@ -13,9 +13,12 @@ from numpy.random import PCG64DXSM, Generator, SeedSequence
 from scipy import stats  # type: ignore
 
 import mergeron.core.empirical_margin_distribution as emd
-from mergeron import DATA_DIR
+from mergeron import WORK_DIR as PKG_WORK_DIR
 from mergeron.core.guidelines_boundary_functions import boundary_plot
 
+WORK_DIR = globals().get("WORK_DIR", PKG_WORK_DIR)
+"""Redefined, in case the user defines WORK_DIR betweeen module imports."""
+
 SAMPLE_SIZE = 10**6
 BIN_COUNT = 25
 margin_data_obs, margin_data_wts, margin_data_stats = emd.margin_data_builder()
@@ -85,4 +88,4 @@ mgn_ax.set_xlabel("Price Cost Margin", fontsize=10)
 mgn_ax.set_ylabel("Relative Frequency", fontsize=10)
 
 mgn_fig.tight_layout()
-plt.savefig(DATA_DIR / f"{Path(__file__).stem}.pdf")
+plt.savefig(WORK_DIR / f"{Path(__file__).stem}.pdf")

{mergeron-2025.739290.5 → mergeron-2025.739290.6}/src/mergeron/gen/__init__.py

@@ -11,7 +11,7 @@ import io
 from collections.abc import Sequence
 from operator import attrgetter
 
-import h5py
+import h5py  # type: ignore
 import numpy as np
 from attrs import Attribute, Converter, cmp_using, field, frozen, validators
 from numpy.random import SeedSequence
@@ -255,7 +255,7 @@ class ShareSpec:
     in published merger guidelines. Accordingly, the recapture ratio rounded to
     the nearest 5% is:
 
-    * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1982, 1984, 1992, 2023
+    * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1992, 2023
     * 0.80, 5-to-4 merger from symmetry
     * 0.80, **5-to-4 merger to symmetry**; US Guidelines, 2010
 
@@ -470,7 +470,9 @@ class MarketSampleData:
 
     @aggregate_purchase_prob.default
     def __appd(_i: MarketSampleData) -> ArrayDouble:
-        return np.nan * np.empty_like(_i.frmshr_array[:, :1], float)
+        retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
+        retval.fill(np.nan)
+        return retval
 
     fcounts: ArrayINT = field(eq=cmp_using(np.array_equal))
     """Number of firms in market"""
@@ -488,14 +490,18 @@ class MarketSampleData:
 
     @nth_firm_share.default
     def __nfsd(_i: MarketSampleData) -> ArrayDouble:
-        return np.nan * np.empty_like(_i.frmshr_array[:, :1], float)
+        retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
+        retval.fill(np.nan)
+        return retval
 
     hhi_post: ArrayDouble = field(eq=cmp_using(np.array_equal))
     """Post-merger change in Herfindahl-Hirschmann Index (HHI)"""
 
     @hhi_post.default
     def __hpd(_i: MarketSampleData) -> ArrayDouble:
-        return np.nan * np.empty_like(_i.frmshr_array[:, :1], float)
+        retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
+        retval.fill(np.nan)
+        return retval
 
     def to_h5bin(self) -> bytes:
         """Save market sample data to HDF5 file."""

mergeron-2025.739290.5/src/mergeron/demo/__init__.py

@@ -1,3 +0,0 @@
-from .. import VERSION  # noqa: TID252
-
-__version__ = VERSION