mergeron 2025.739319.3__tar.gz → 2025.739341.8__tar.gz

mergeron-2025.739341.8/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.3
+Name: mergeron
+Version: 2025.739341.8
+Summary: Python for analyzing merger enforcement policy
+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
+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 :: Only
+Classifier: Programming Language :: Python :: 3.12
+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: linuxdoc (>=20240924,<20240925)
+Requires-Dist: lxml (>=5.3.1,<6.0.0)
+Requires-Dist: matplotlib (>=3.8)
+Requires-Dist: mpmath (>=1.3)
+Requires-Dist: python-calamine (>=0.3.1,<0.4.0)
+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)
+Project-URL: Documentation, https://capeconomics.github.io/mergeron/
+Project-URL: Repository, https://github.com/capeconomics/mergeron.git
+Description-Content-Type: text/x-rst
+
+mergeron: Python for analyzing merger enforcement policy
+========================================================
+
+
+.. image:: https://img.shields.io/pypi/v/mergeron
+   :alt: PyPI - Package Version
+   :target: https://pypi.python.org/pypi/mergeron/
+.. image:: https://img.shields.io/pypi/pyversions/mergeron
+   :alt: PyPI - Python Version
+   :target: https://pypi.python.org/pypi/mergeron/
+.. image:: https://img.shields.io/pypi/status/mergeron
+   :alt: PyPI - Package status
+   :target: https://pypi.python.org/pypi/mergeron/
+
+|
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :target: https://python-poetry.org/
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :target: https://github.com/astral-sh/ruff
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :target: https://mypy-lang.org/
+.. image:: https://img.shields.io/badge/code%20style-black-000000
+   :target: https://github.com/psf/black
+.. image:: https://img.shields.io/badge/License-MIT-yellow
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+
+
+*Visualize* the sets of mergers falling within specified concentration and diversion-ratio thresholds.  *Analyze* merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+*Generate* data under specified distributions of firm counts, market shares, price-cost margins, and prices, optionally imposing equilibrium conditions for Bertrand oligopoly with MNL demand and or restrictions implied by statutory filing thresholds. *Compute* intrinsic enforcement rates or
+intrinsic clearance rates using the generated data, given thresholds for
+concentration;
+diversion ratio;
+gross upward pricing pressure (GUPPI);
+critical marginal cost reduction (CMCR); and
+illustrative price rise (IPR).
+
+Installation
+------------
+
+To install the package, use the following shell command:
+
+.. code:: bash
+
+    pip install mergeron
+
+
+Documentation 
+-------------
+
+Usage guide and API reference available `here <https://capeconomics.github.io/mergeron/>`_.
+

mergeron-2025.739341.8/README.rst

@@ -0,0 +1,52 @@
+mergeron: Python for analyzing merger enforcement policy
+========================================================
+
+
+.. image:: https://img.shields.io/pypi/v/mergeron
+   :alt: PyPI - Package Version
+   :target: https://pypi.python.org/pypi/mergeron/
+.. image:: https://img.shields.io/pypi/pyversions/mergeron
+   :alt: PyPI - Python Version
+   :target: https://pypi.python.org/pypi/mergeron/
+.. image:: https://img.shields.io/pypi/status/mergeron
+   :alt: PyPI - Package status
+   :target: https://pypi.python.org/pypi/mergeron/
+
+|
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :target: https://python-poetry.org/
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :target: https://github.com/astral-sh/ruff
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :target: https://mypy-lang.org/
+.. image:: https://img.shields.io/badge/code%20style-black-000000
+   :target: https://github.com/psf/black
+.. image:: https://img.shields.io/badge/License-MIT-yellow
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+
+
+*Visualize* the sets of mergers falling within specified concentration and diversion-ratio thresholds.  *Analyze* merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+*Generate* data under specified distributions of firm counts, market shares, price-cost margins, and prices, optionally imposing equilibrium conditions for Bertrand oligopoly with MNL demand and or restrictions implied by statutory filing thresholds. *Compute* intrinsic enforcement rates or
+intrinsic clearance rates using the generated data, given thresholds for
+concentration;
+diversion ratio;
+gross upward pricing pressure (GUPPI);
+critical marginal cost reduction (CMCR); and
+illustrative price rise (IPR).
+
+Installation
+------------
+
+To install the package, use the following shell command:
+
+.. code:: bash
+
+    pip install mergeron
+
+
+Documentation 
+-------------
+
+Usage guide and API reference available `here <https://capeconomics.github.io/mergeron/>`_.

{mergeron-2025.739319.3 → mergeron-2025.739341.8}/pyproject.toml

@@ -1,7 +1,9 @@
-[tool.poetry]
+[project]
 name = "mergeron"
-authors = ["Murthy Kambhampaty <smk@capeconomics.com>"]
-description = "Analyze merger enforcement policy using Python"
+authors = [
+    { name = "Murthy Kambhampaty", email = "smk@capeconomics.com" },
+]
+description = "Python for analyzing merger enforcement policy"
 readme = "README.rst"
 license = "MIT"
 keywords = [
@@ -13,7 +15,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2025.739319.3"
+version = "2025.739341.8"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [
@@ -30,6 +32,14 @@ classifiers = [
     "Programming Language :: Python :: Implementation :: CPython",
 ]
 
+requires-python = ">=3.12"
+
+dynamic = ["dependencies"]
+
+[project.urls]
+Documentation = "https://capeconomics.github.io/mergeron/"
+Repository = "https://github.com/capeconomics/mergeron.git"
+
 [build-system]
 requires = ["poetry-core"]
 build-backend = "poetry.core.masonry.api"
@@ -45,37 +55,38 @@ jinja2 = ">=3.1"
 joblib = ">=1.3"
 matplotlib = ">=3.8"
 mpmath = ">=1.3"
-msgpack = ">=1.0"
-msgpack-numpy = ">=0.4"
 python = "^3.12"
 scipy = ">=1.12"
 sympy = ">=1.12"
-xlsxwriter = ">=3.1"
 certifi = ">=2023.11.17"
 types-beautifulsoup4 = ">=4.11.2"
-xlrd = "^2.0.1"                   # Needed to read margin data
 urllib3 = "^2.2.2"
 ruamel-yaml = "^0.18.10"
 h5py = "^3.13.0"
+linuxdoc = "^20240924"
+lxml = "^5.3.1"
+python-calamine = "^0.3.1"
 
 
 [tool.poetry.group.dev.dependencies]
-icecream = ">=2.1.0"
 jinja2 = ">=3.1.5"
 mypy = ">=1.8"
-openpyxl = ">=3.1.2"
-pendulum = ">=3.0.0"
 ruff = ">=0.5"
 poetry-plugin-export = "^1.8.0"
 pytest = ">=8.0"
-sphinx = ">8.2"
+sphinx = ">8.1"
 semver = ">=3.0"
 sphinx-autodoc-typehints = ">=2.0.0"
 sphinx-autoapi = ">=3.6.0"
 sphinx-immaterial = ">0.11"
 pipdeptree = ">=2.15.1"
-types-openpyxl = ">=3.0.0"
 virtualenv = ">=20.28.0"
+pytest-cov = "^6.0.0"
+pendulum = "^3.0.0"
+rstcheck = "^6.2.4"
+ipython-pygments-lexers = "^1.1.1"
+
+
 [tool.ruff]
 
 # Exclude a variety of commonly ignored directories.
@@ -112,8 +123,11 @@ indent-width = 4
 
 
 [tool.ruff.lint]
-# From, https://github.com/sphinx-doc/sphinx/blob/master/pyproject.toml
+# Borrowed primaryly from,
+#   https://github.com/sphinx-doc/sphinx/blob/master/pyproject.toml
+
 select = [
+    "D", # docstrings
     "E", # pycodestyle
     "F", # Pyflakes
     "I", # isort
@@ -139,13 +153,14 @@ ignore = [
     # flake-8 line length
     "E501",
     # pycodestyle
-    'E741',
+    "E741",
     # flake8-bugbear
-    'B006',
-    'B023',
+    "B006",
+    "B023",
     # flake8-bugbear opinionated (disabled by default in flake8)
-    'B904',
-    'B905',
+    "B904",
+    "B905",
+    "PLC2801", # unnecessary-dunder-call
     "PLR2004", # avoid magic values
     # RUF
     "RUF052",
@@ -160,6 +175,9 @@ ignore = [
 ]
 isort.split-on-trailing-comma = false
 
+[tool.ruff.lint.pydocstyle]
+convention = "numpy"
+
 [tool.ruff.format]
 quote-style = "double"
 indent-style = "space"
@@ -188,13 +206,17 @@ plugins = "numpy.typing.mypy_plugin"
 log_auto_indent = 4
 minversion = "8.0"
 testpaths = ["tests"]
-addopts = ["--import-mode=importlib"]
+addopts = [
+    "--import-mode=importlib",
+    "--cov=mergeron",
+    "--cov-report=html:../tests/cov_html",
+]
 filterwarnings = [
     "all",
     "ignore::DeprecationWarning:dateutil.tz.tz",
     "ignore::DeprecationWarning:jinja2.lexer",
     "ignore::DeprecationWarning:joblib._utils",
-    "ignore::DeprecationWarning:openpyxl.packaging.core",
+    "ignore::RuntimeWarning:mergeron.core.empirical_margin_distribution",
     "ignore::RuntimeWarning:mergeron.core.proportions_tests",
     "ignore::RuntimeWarning:mergeron.gen.enforcement_stats",
 ]

{mergeron-2025.739319.3 → mergeron-2025.739341.8}/src/mergeron/__init__.py

@@ -1,3 +1,5 @@
+"""Variables, types, objects and functions used throughout the package."""
+
 from __future__ import annotations
 
 import enum
@@ -6,13 +8,14 @@ from multiprocessing import cpu_count
 from pathlib import Path
 from typing import Any, Literal
 
+import attrs
 import numpy as np
 from numpy.typing import NDArray
 from ruamel import yaml
 
-_PKG_NAME: str = Path(__file__).parent.stem
+_PKG_NAME: str = Path(__file__).parent.name
 
-VERSION = "2025.739319.3"
+VERSION = "2025.739341.8"
 
 __version__ = VERSION
 
@@ -34,7 +37,7 @@ EMPTY_ARRAYINT = np.array([], int)
 
 NTHREADS = 2 * cpu_count()
 
-PKG_ATTRS_MAP: dict[str, object] = {}
+PKG_ATTRS_MAP: dict[str, type] = {}
 
 np.set_printoptions(precision=24, floatmode="fixed")
 
@@ -75,23 +78,21 @@ this_yaml.indent(mapping=2, sequence=4, offset=2)
 def yaml_rt_mapper(
     _c: yaml.constructor.RoundTripConstructor, _n: yaml.MappingNode
 ) -> Mapping[str, Any]:
-    """
-    Constructs a mapping from a mapping node with the RoundTripConstructor
-
-    """
+    """Construct mapping from a mapping node with the RoundTripConstructor."""
     data_: Mapping[str, Any] = yaml.constructor.CommentedMap()
     _c.construct_mapping(_n, maptyp=data_, deep=True)
     return data_
 
 
-def yamelize_attrs(
-    _typ: object, /, *, attr_map: Mapping[str, object] = PKG_ATTRS_MAP
-) -> None:
+def yamelize_attrs(_typ: type, /, *, attr_map: dict[str, type] = PKG_ATTRS_MAP) -> None:
     """Add yaml representer, constructor for attrs-defined class.
 
-    Applying this function, attributes with property, `init=False` are
-    not serialized to YAML.
+    Attributes with property, `init=False` are not serialized/deserialized
+    to YAML by the functions defined here. These attributes can, of course,
+    be dumped to stand-alone (YAML) representation, and deserialized from there.
     """
+    if not attrs.has(_typ):
+        raise ValueError(f"Object {_typ} is not attrs-defined")
 
     attr_map |= {_typ.__name__: _typ}
 
@@ -99,9 +100,6 @@ def yamelize_attrs(
         _typ,
         lambda _r, _d: _r.represent_mapping(
             f"!{_d.__class__.__name__}",
-            # construct mapping, rather than calling attrs.asdict(),
-            # to use yaml representers defined in this package for
-            # "upstream" objects
             {_a.name: getattr(_d, _a.name) for _a in _d.__attrs_attrs__ if _a.init},
         ),
     )
@@ -113,12 +111,13 @@ def yamelize_attrs(
 
 @this_yaml.register_class
 class Enameled(enum.Enum):
-    """Add YAML representer, constructor for enum.Enum"""
+    """Add YAML representer, constructor for enum.Enum."""
 
     @classmethod
     def to_yaml(
-        cls, _r: yaml.representer.RoundTripRepresenter, _d: object[enum.EnumType]
+        cls, _r: yaml.representer.RoundTripRepresenter, _d: enum.Enum
     ) -> yaml.ScalarNode:
+        """Serialize enumerations by .name, not .value."""
         return _r.represent_scalar(
             f"!{super().__getattribute__(cls, '__name__')}", f"{_d.name}"
         )
@@ -126,8 +125,10 @@ class Enameled(enum.Enum):
     @classmethod
     def from_yaml(
         cls, _c: yaml.constructor.RoundTripConstructor, _n: yaml.ScalarNode
-    ) -> object[enum.EnumType]:
-        return super().__getattribute__(cls, _n.value)
+    ) -> enum.EnumType:
+        """Deserialize enumeration."""
+        retval: enum.EnumType = super().__getattribute__(cls, _n.value)
+        return retval
 
 
 @this_yaml.register_class
@@ -181,10 +182,7 @@ class RECForm(str, Enameled):
 @this_yaml.register_class
 @enum.unique
 class UPPAggrSelector(str, Enameled):
-    """
-    Aggregator for GUPPI and diversion ratio estimates.
-
-    """
+    """Aggregator for GUPPI and diversion ratio estimates."""
 
     AVG = "average"
     CPA = "cross-product-share weighted average"

{mergeron-2025.739319.3 → mergeron-2025.739341.8}/src/mergeron/core/__init__.py

@@ -1,3 +1,5 @@
+"""Constants, types, objects and functions used within this sub-package."""
+
 from __future__ import annotations
 
 from collections.abc import Mapping
@@ -8,6 +10,7 @@ from typing import Any
 import mpmath  # type: ignore
 import numpy as np
 from attrs import cmp_using, field, frozen
+from numpy.random import PCG64DXSM
 
 from .. import (  # noqa: TID252
     VERSION,
@@ -20,13 +23,15 @@ from .. import (  # noqa: TID252
 
 __version__ = VERSION
 
+DEFAULT_BITGENERATOR = PCG64DXSM
+
 type MPFloat = mpmath.ctx_mp_python.mpf
-type MPMatrix = mpmath.matrix  # type: ignore
+type MPMatrix = mpmath.matrices.matrices._matrix
 
 
 @frozen
 class GuidelinesBoundary:
-    """Output of a Guidelines boundary function."""
+    """Represents Guidelines boundary analytically."""
 
     coordinates: ArrayDouble
     """Market-share pairs as Cartesian coordinates of points on the boundary."""
@@ -35,8 +40,19 @@ class GuidelinesBoundary:
     """Area under the boundary."""
 
 
+@frozen
+class GuidelinesBoundaryCallable:
+    """A function to generate Guidelines boundary points, along with area and knot."""
+
+    boundary_function: Callable[[ArrayDouble], ArrayDouble]
+    area: float
+    s_naught: float = 0
+
+
 @frozen
 class INVTableData:
+    """Represents individual table of FTC merger investigations data."""
+
     industry_group: str
     additional_evidence: str
     data_array: ArrayBIGINT = field(eq=cmp_using(eq=np.array_equal))
@@ -45,7 +61,7 @@ class INVTableData:
 type INVData = MappingProxyType[
     str, MappingProxyType[str, MappingProxyType[str, INVTableData]]
 ]
-type INVData_in = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
+type INVData_in = dict[str, dict[str, dict[str, INVTableData]]]
 
 yamelize_attrs(INVTableData)
 
@@ -91,14 +107,14 @@ _, _ = (
 
 def _dict_from_mapping(_p: Mapping[Any, Any], /) -> dict[Any, Any]:
     retval: dict[Any, Any] = {}
-    for _k, _v in _p.items():  # for subit in it:
+    for _k, _v in _p.items():
         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: dict[Any, Any] = {}
-    for _k, _v in _p.items():  # for subit in it:
+    for _k, _v in _p.items():
         retval |= (
             {_k: _mappingproxy_from_mapping(_v)}
             if isinstance(_v, Mapping)