mergeron 2025.739290.6__tar.gz → 2025.739290.9__tar.gz

mergeron-2025.739290.9/PKG-INFO

@@ -0,0 +1,178 @@
+Metadata-Version: 2.3
+Name: mergeron
+Version: 2025.739290.9
+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
+Author: Murthy Kambhampaty
+Author-email: smk@capeconomics.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: aenum (>=3.1.15,<4.0.0)
+Requires-Dist: attrs (>=23.2)
+Requires-Dist: bs4 (>=0.0.1)
+Requires-Dist: certifi (>=2023.11.17)
+Requires-Dist: h5py (>=3.13.0,<4.0.0)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: joblib (>=1.3)
+Requires-Dist: matplotlib (>=3.8)
+Requires-Dist: mpmath (>=1.3)
+Requires-Dist: msgpack (>=1.0)
+Requires-Dist: msgpack-numpy (>=0.4)
+Requires-Dist: ruamel-yaml (>=0.18.10,<0.19.0)
+Requires-Dist: scipy (>=1.12)
+Requires-Dist: sympy (>=1.12)
+Requires-Dist: types-beautifulsoup4 (>=4.11.2)
+Requires-Dist: urllib3 (>=2.2.2,<3.0.0)
+Requires-Dist: xlrd (>=2.0.1,<3.0.0)
+Requires-Dist: xlsxwriter (>=3.1)
+Description-Content-Type: text/x-rst
+
+mergeron: Merger Policy Analysis with Python
+============================================
+
+Usage
+-----
+
+*Visualizing Guidelines boundaries*
+
+.. code:: python
+
+    %matplotlib inline
+    from mergeron.core import guidelines_boundaries as gbl
+    from mergeron.core import guidelines_boundary_functions as gbf
+    from math import sqrt
+
+    delta_bound = 0.01
+    conc_boundary = gbl.ConcentrationBoundary(delta_bound, "ΔHHI")
+    share_boundary = gbl.ConcentrationBoundary(2 * sqrt(delta_bound / 2), "Combined share")
+
+    divr_boundary_a = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.AVG
+    )
+
+    divr_boundary_i = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.MIN
+    )
+
+    divr_boundary_x = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.MAX
+    )
+
+
+Plots are written to PDF, typically, with ``backend="pgf"`` as the
+default backend in the function, ``gbf.boundary_plot``. Here, we set the
+backend to ``None`` to skip fine-tuning plots for PDF generation.
+
+.. code:: python
+
+    plt, fig, ax, layout_axis = gbf.boundary_plot(backend=None)
+
+    ax.set_title("Concentration and Diversion Ratio Boundaries")
+
+    ax.plot(conc_boundary.coordinates[:, 0], conc_boundary.coordinates[:, 1], color="black", linestyle="-", label="ΔHHI")
+    ax.plot(share_boundary.coordinates[:, 0], share_boundary.coordinates[:, 1], color="black", linestyle=":", label="Combined share")
+    ax.plot(divr_boundary_a.coordinates[:, 0], divr_boundary_a.coordinates[:, 1], "b-", label="Average Diversion Ratio")
+    ax.plot(divr_boundary_i.coordinates[:, 0], divr_boundary_i.coordinates[:, 1], "r-", label="Minimum Diversion Ratio")
+    ax.plot(divr_boundary_x.coordinates[:, 0], divr_boundary_x.coordinates[:, 1], "g-", label="Maximum Diversion Ratio")
+
+    _ = fig.legend(loc=(0.4, 0.7), frameon=False)
+
+
+
+.. image:: ./docs/readme_content/output_5_0.png
+
+
+*Analyzing FTC Merger Investigations Data*
+
+.. code:: python
+
+    from mergeron.core import ftc_merger_investigations_data as fid
+    import tabulate
+
+    inv_data = fid.construct_data(fid.INVDATA_ARCHIVE_PATH)
+
+
+We can now analyze counts of markets reported in the source data, by
+table number. Note that odd-numbered tables report FTC investigations
+data organized by HHI and ΔHHI, while even-numbered tables report by
+firm-count.
+
+.. code:: python
+
+    from mergeron.gen import enforcement_stats as esl
+
+    print("Enforcement Rates in Markets with Entry Barriers, 1996-2003 vs 2004-2011")
+    print()
+    counts_by_delta_1 = esl.enf_cnts_bydelta(
+        inv_data["1996-2003"]["ByHHIandDelta"]["Table 9.2"].data_array
+    )
+    counts_by_delta_2 = esl.enf_cnts_bydelta(
+        inv_data["2004-2011"]["ByHHIandDelta"]["Table 9.2"].data_array
+    )
+    observed_enforcement_rates = list(zip(
+        (
+            {_v: _k for _k, _v in fid.CONC_DELTA_DICT.items()}[i]
+            for i in counts_by_delta_1[:, 0]
+        ),
+        (
+            f"{_a[1] / _a[-1]: <12.2%}" if _a[-1] else "--"
+            for _a in counts_by_delta_1
+        ),
+        (
+            f"{_e[1] / _e[-1]: <12.2%}" if _e[-1] else "--"
+            for _e in counts_by_delta_2
+        ),
+    ))
+
+    observed_enforcement_rates.append([
+        "Total",
+        f"{counts_by_delta_1[:, 1].sum() / counts_by_delta_1[:, -1].sum(): <12.2%}",
+        f"{counts_by_delta_2[:, 1].sum() / counts_by_delta_2[:, -1].sum(): <12.2%}",
+    ])
+
+    print(tabulate.tabulate(
+        observed_enforcement_rates,
+        tablefmt="simple",
+        headers=("ΔHHI", "1996-2003", "2004-2011"),
+        stralign="center",
+        maxcolwidths=36,
+        maxheadercolwidths=36,
+    ))
+
+
+.. parsed-literal::
+
+    Enforcement Rates in Markets with Entry Barriers, 1996-2003 vs 2004-2011
+
+        ΔHHI        1996-2003    2004-2011
+    -------------  -----------  -----------
+       0 - 100         --         100.00%
+      100 - 200      33.33%       50.00%
+      200 - 300      33.33%       50.00%
+      300 - 500      75.00%       77.78%
+      500 - 800      59.09%       54.55%
+     800 - 1,200     93.33%       81.82%
+    1,200 - 2,500    90.91%       84.38%
+       2,500 +       96.00%       100.00%
+        Total        81.65%       82.86%
+
+
+Generating synthetic market data and analyzing enforcement rates
+
+
+

mergeron-2025.739290.9/README.rst

@@ -0,0 +1,136 @@
+mergeron: Merger Policy Analysis with Python
+============================================
+
+Usage
+-----
+
+*Visualizing Guidelines boundaries*
+
+.. code:: python
+
+    %matplotlib inline
+    from mergeron.core import guidelines_boundaries as gbl
+    from mergeron.core import guidelines_boundary_functions as gbf
+    from math import sqrt
+
+    delta_bound = 0.01
+    conc_boundary = gbl.ConcentrationBoundary(delta_bound, "ΔHHI")
+    share_boundary = gbl.ConcentrationBoundary(2 * sqrt(delta_bound / 2), "Combined share")
+
+    divr_boundary_a = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.AVG
+    )
+
+    divr_boundary_i = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.MIN
+    )
+
+    divr_boundary_x = gbl.DiversionRatioBoundary(
+        gbl.guppi_from_delta(delta_bound, m_star=1.0, r_bar=0.85),
+        agg_method=gbl.UPPAggrSelector.MAX
+    )
+
+
+Plots are written to PDF, typically, with ``backend="pgf"`` as the
+default backend in the function, ``gbf.boundary_plot``. Here, we set the
+backend to ``None`` to skip fine-tuning plots for PDF generation.
+
+.. code:: python
+
+    plt, fig, ax, layout_axis = gbf.boundary_plot(backend=None)
+
+    ax.set_title("Concentration and Diversion Ratio Boundaries")
+
+    ax.plot(conc_boundary.coordinates[:, 0], conc_boundary.coordinates[:, 1], color="black", linestyle="-", label="ΔHHI")
+    ax.plot(share_boundary.coordinates[:, 0], share_boundary.coordinates[:, 1], color="black", linestyle=":", label="Combined share")
+    ax.plot(divr_boundary_a.coordinates[:, 0], divr_boundary_a.coordinates[:, 1], "b-", label="Average Diversion Ratio")
+    ax.plot(divr_boundary_i.coordinates[:, 0], divr_boundary_i.coordinates[:, 1], "r-", label="Minimum Diversion Ratio")
+    ax.plot(divr_boundary_x.coordinates[:, 0], divr_boundary_x.coordinates[:, 1], "g-", label="Maximum Diversion Ratio")
+
+    _ = fig.legend(loc=(0.4, 0.7), frameon=False)
+
+
+
+.. image:: ./docs/readme_content/output_5_0.png
+
+
+*Analyzing FTC Merger Investigations Data*
+
+.. code:: python
+
+    from mergeron.core import ftc_merger_investigations_data as fid
+    import tabulate
+
+    inv_data = fid.construct_data(fid.INVDATA_ARCHIVE_PATH)
+
+
+We can now analyze counts of markets reported in the source data, by
+table number. Note that odd-numbered tables report FTC investigations
+data organized by HHI and ΔHHI, while even-numbered tables report by
+firm-count.
+
+.. code:: python
+
+    from mergeron.gen import enforcement_stats as esl
+
+    print("Enforcement Rates in Markets with Entry Barriers, 1996-2003 vs 2004-2011")
+    print()
+    counts_by_delta_1 = esl.enf_cnts_bydelta(
+        inv_data["1996-2003"]["ByHHIandDelta"]["Table 9.2"].data_array
+    )
+    counts_by_delta_2 = esl.enf_cnts_bydelta(
+        inv_data["2004-2011"]["ByHHIandDelta"]["Table 9.2"].data_array
+    )
+    observed_enforcement_rates = list(zip(
+        (
+            {_v: _k for _k, _v in fid.CONC_DELTA_DICT.items()}[i]
+            for i in counts_by_delta_1[:, 0]
+        ),
+        (
+            f"{_a[1] / _a[-1]: <12.2%}" if _a[-1] else "--"
+            for _a in counts_by_delta_1
+        ),
+        (
+            f"{_e[1] / _e[-1]: <12.2%}" if _e[-1] else "--"
+            for _e in counts_by_delta_2
+        ),
+    ))
+
+    observed_enforcement_rates.append([
+        "Total",
+        f"{counts_by_delta_1[:, 1].sum() / counts_by_delta_1[:, -1].sum(): <12.2%}",
+        f"{counts_by_delta_2[:, 1].sum() / counts_by_delta_2[:, -1].sum(): <12.2%}",
+    ])
+
+    print(tabulate.tabulate(
+        observed_enforcement_rates,
+        tablefmt="simple",
+        headers=("ΔHHI", "1996-2003", "2004-2011"),
+        stralign="center",
+        maxcolwidths=36,
+        maxheadercolwidths=36,
+    ))
+
+
+.. parsed-literal::
+
+    Enforcement Rates in Markets with Entry Barriers, 1996-2003 vs 2004-2011
+
+        ΔHHI        1996-2003    2004-2011
+    -------------  -----------  -----------
+       0 - 100         --         100.00%
+      100 - 200      33.33%       50.00%
+      200 - 300      33.33%       50.00%
+      300 - 500      75.00%       77.78%
+      500 - 800      59.09%       54.55%
+     800 - 1,200     93.33%       81.82%
+    1,200 - 2,500    90.91%       84.38%
+       2,500 +       96.00%       100.00%
+        Total        81.65%       82.86%
+
+
+Generating synthetic market data and analyzing enforcement rates
+
+

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

@@ -13,7 +13,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2025.739290.6"
+version = "2025.739290.9"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [

{mergeron-2025.739290.6 → mergeron-2025.739290.9}/src/mergeron/__init__.py

@@ -12,7 +12,7 @@ from ruamel import yaml
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2025.739290.6"
+VERSION = "2025.739290.9"
 
 __version__ = VERSION
 

{mergeron-2025.739290.6 → mergeron-2025.739290.9}/src/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,6 +78,16 @@ 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: dict[Any, Any] = {}
@@ -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-2025.739290.6 → mergeron-2025.739290.9}/src/mergeron/core/empirical_margin_distribution.py

@@ -238,7 +238,7 @@ def margin_data_resampler(
 
     """
 
-    seed_sequence_ = seed_sequence or SeedSequence(pool_size=8)
+    _seed = seed_sequence or SeedSequence(pool_size=8)
 
     _x, _w, _ = margin_data_builder(margin_data_getter())
 
@@ -247,16 +247,14 @@ def margin_data_resampler(
 
     if isinstance(_sample_size, int):
         return np.array(
-            margin_kde.resample(
-                _sample_size, seed=Generator(PCG64DXSM(seed_sequence_))
-            )[0]
+            margin_kde.resample(_sample_size, seed=Generator(PCG64DXSM(_seed)))[0]
         )
     elif isinstance(_sample_size, tuple) and len(_sample_size) == 2:
-        ssz, num_cols = _sample_size
-        ret_array = np.empty(_sample_size, np.float64)
-        for idx, seed_seq in enumerate(seed_sequence_.spawn(num_cols)):
+        _ssz, _ncol = _sample_size
+        ret_array = np.empty(_sample_size, float)
+        for idx, _col_seed in enumerate(_seed.spawn(_ncol)):
             ret_array[:, idx] = margin_kde.resample(
-                ssz, seed=Generator(PCG64DXSM(seed_seq))
+                _ssz, seed=Generator(PCG64DXSM(_col_seed))
             )[0]
         return ret_array
     else:

{mergeron-2025.739290.6 → mergeron-2025.739290.9}/src/mergeron/core/ftc_merger_investigations_data.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 import re
 import shutil
-from collections.abc import Sequence
+from collections.abc import Mapping, Sequence
 from operator import itemgetter
 from pathlib import Path
 from types import MappingProxyType
@@ -94,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,
     *,
@@ -239,7 +243,7 @@ def _construct_no_evidence_data(_invdata: INVData_in, _data_period: str, /) -> N
                 dtn: INVTableData(
                     invdata_ind_grp,
                     invdata_evid_cond,
-                    np.column_stack((
+                    np.hstack((
                         invdata_sub_evid_cond_conc[stn0].data_array[:, :2],
                         (
                             invdata_sub_evid_cond_conc[stn0].data_array[:, 2:]
@@ -373,10 +377,10 @@ def _construct_new_period_data(
                     np.zeros_like(invdata_array_bld_enfcls),
                 )).max(axis=0)
 
-            invdata_array_bld = np.column_stack((
+            invdata_array_bld = np.hstack((
                 invdata_cuml_array[:, :-3],
                 invdata_array_bld_enfcls,
-                np.einsum("ij->i", invdata_array_bld_enfcls),
+                np.einsum("ij->i", invdata_array_bld_enfcls)[:, None],
             ))
 
             data_typesubdict[table_no] = INVTableData(
@@ -397,7 +401,7 @@ def invdata_build_aggregate_table(
     return INVTableData(
         "Industries in Common",
         "Unrestricted on additional evidence",
-        np.column_stack((
+        np.hstack((
             _data_typesub[hdr_table_no].data_array[:, :-3],
             np.einsum(
                 "ijk->jk",

{mergeron-2025.739290.6 → mergeron-2025.739290.9}/src/mergeron/core/guidelines_boundaries.py

@@ -146,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",
@@ -165,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)
@@ -284,7 +284,7 @@ class DiversionRatioBoundary:
 
     agg_method: UPPAggrSelector = field(
         kw_only=True,
-        default=UPPAggrSelector.MAX,
+        default=UPPAggrSelector.MIN,
         validator=validators.instance_of(UPPAggrSelector),
     )
     """