mergeron 2024.738953.1__tar.gz → 2024.738972.0__tar.gz

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.738953.1
+Version: 2024.738972.0
 Summary: Analysis of standards defined in Horizontal Merger Guidelines
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
@@ -51,43 +51,58 @@ Intrinsic clearance and enforcement rates are distinguished from *observed* clea
 Modules of primary interest
 ---------------------------
 
-Routines for downloading and organizing FTC merger investigtions data published in 2004, 2007, 2008, and 2013. Includes a routine for constructing investigations data for non-overlapping periods, and other partitions on the data, subject to the constraints of the reported data.
 
-    mergeron.core.ftc_merger_investigations_data
 
-Routines for plotting boundaries of (sets of mergers falling within) specified concentration and diversion ratio boundaries and for calibrating GUPPI thresholds to concentration (ΔHHI) thresholds, and vice-versa.
+Methods for plotting boundaries of (sets of mergers falling within) specified concentration and share-ratio boundaries, are in :code:`mergeron.core.guidelines_boundaries`, where share-ratio, :math:`\delta_{ij}` is defined as :math:`\delta_{ij} = d_{ij} / r_i` with :math:`d_{ij}, r_i` a diversion ratio and recapture rate. This module also includes functions for calibrating GUPPI thresholds to concentration (ΔHHI) thresholds, and vice-versa.
 
-    mergeron.core.guidelines_boundaries
+Methods for generating industry data under various distributions of shares, prices, and margins are included in, :code:`mergeron.gen.data_generation`. The user can specify whether rates are specified as, "proportional", "inside-out" (i.e., consistent with merging-firms' in-market shares and a default recapture rate), or "outside-in", (i.e., purchase probabilities are drawn at random for :math:`n+1` goods, from which are derived market shares and recapture rates for the :math:`n` goods in the putative market). Price-cost-margins may be specified as symmetric, i.i.d, or consistent with equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand. Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified. Two alternative approaches for modeling statutory filing requirements (HSR filing thresholds) are implemented.
 
-Routines for generating industry data under various distributions of shares, prices, and margins. The user can specify whether rates are specified as, "proportional", "inside-out" (i.e., consistent with merging-firms' in-market shares and a default recapture rate), or "outside-in", (i.e., purchase probabilities are drawn at random for :math:`n+1` goods, from which are derived market shares and recapture rates for the :math:`n` goods in the putative market). Price-cost-margins may be specified as symmetric, i.i.d, or consistent with equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand. Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified. Two alternative approaches for modeling statutory filing requirements (HSR filing thresholds) are implemented.
+Methods for testing generated industry data against criteria on diversion ratio, gross upward pricing pressure ("GUPPI"), critical marginal cost reduction ("CMCR"), and indicative price rise ("IPR")/partial merger simulation are included in the module, :code:`mergeron.gen.guidelines_tests`. Test data are constructed in parallel and the user can specify number of `threads` and sub-sample size for each thread to manage CPU and memory utilization.
 
-    mergeron.gen.data_generation
+FTC investigations data and test data are printed to screen or rendered in LaTex to text files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.investigations_stats`.
 
-Routines for testing generated industry data against criteria on diversion ratio, gross upward pricing pressure ("GUPPI"), critical marginal cost reduction ("CMCR"), and indicative price rise ("IPR")/partial merger simulation. Test data are constructed in parallel and the user can specify number of `threads` and sub-sample size for each thread to manage CPU and memory utilization.
+Programs demonstrating the analysis and reporting facilites provided by the sub-package, :code:`mergeron.examples`.
 
-    mergeron.gen.guidelines_tests
+This package exposes methods employed for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. To access these directly:
 
-FTC investigations data and test data are printed to screen or rendered in LaTex to text files (for processing into publication-quality tables) using routines provided in :code:`mergeron.gen.investigations_stats`.
-
-Programs demonstrating the analysis and reporting facilites provided by the package.
-
-    mergeron.examples
-
-This package exposes routines employed for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. To access these directly:
+.. code-block:: python
 
     import mergeron.core.pseudorandom_numbers as prng
 
-Also included are routines for estimating confidence intervals for proportions and for contrasts (differences) in proportions. (Although coded from scratch using the source literature, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/).) To access these directly:
+Also included are methods for estimating confidence intervals for proportions and for contrasts (differences) in proportions. (Although coded from scratch using the source literature, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/).) To access these directly:
+
+.. code-block:: python
 
     import mergeron.core.proportions_tests as prci
 
 A recent version of Paul Tol's python module, :code:`tol_colors.py` is redistributed within this package. Other than re-formatting and type annotation, the :code:`tol_colors` module is re-distributed as downloaded from, https://personal.sron.nl/~pault/data/tol_colors.py. The tol_colors.py module is distributed under the Standard 3-clause BSD license. To access the tol_colors module directly:
 
+.. code-block:: python
+
     import mergeron.ext.tol_colors
 
 Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
 
+.. code-block:: python
+
     import mergeron.core.data_generation as dgl
 
     help(dgl.gen_market_sample)
 
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :alt: Poetry
+   :target: https://python-poetry.org/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+

mergeron-2024.738972.0/README.rst

@@ -0,0 +1,64 @@
+mergeron: Merger Policy Analysis with Python
+============================================
+
+Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations during 1996 to 2011. Model the sets of mergers conforming to various U.S. Horizontal Merger Guidelines standards. Analyze intrinsic clearance rates and intrinsic enforcement rates under Guidelines standards using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions impled by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand.
+
+Intrinsic clearance and enforcement rates are distinguished from *observed* clearance and enforcement rates in that the former do not reflect the effects of screening and deterrence as do the latter.
+
+Modules of primary interest
+---------------------------
+
+
+
+Methods for plotting boundaries of (sets of mergers falling within) specified concentration and share-ratio boundaries, are in :code:`mergeron.core.guidelines_boundaries`, where share-ratio, :math:`\delta_{ij}` is defined as :math:`\delta_{ij} = d_{ij} / r_i` with :math:`d_{ij}, r_i` a diversion ratio and recapture rate. This module also includes functions for calibrating GUPPI thresholds to concentration (ΔHHI) thresholds, and vice-versa.
+
+Methods for generating industry data under various distributions of shares, prices, and margins are included in, :code:`mergeron.gen.data_generation`. The user can specify whether rates are specified as, "proportional", "inside-out" (i.e., consistent with merging-firms' in-market shares and a default recapture rate), or "outside-in", (i.e., purchase probabilities are drawn at random for :math:`n+1` goods, from which are derived market shares and recapture rates for the :math:`n` goods in the putative market). Price-cost-margins may be specified as symmetric, i.i.d, or consistent with equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand. Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified. Two alternative approaches for modeling statutory filing requirements (HSR filing thresholds) are implemented.
+
+Methods for testing generated industry data against criteria on diversion ratio, gross upward pricing pressure ("GUPPI"), critical marginal cost reduction ("CMCR"), and indicative price rise ("IPR")/partial merger simulation are included in the module, :code:`mergeron.gen.guidelines_tests`. Test data are constructed in parallel and the user can specify number of `threads` and sub-sample size for each thread to manage CPU and memory utilization.
+
+FTC investigations data and test data are printed to screen or rendered in LaTex to text files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.investigations_stats`.
+
+Programs demonstrating the analysis and reporting facilites provided by the sub-package, :code:`mergeron.examples`.
+
+This package exposes methods employed for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+Also included are methods for estimating confidence intervals for proportions and for contrasts (differences) in proportions. (Although coded from scratch using the source literature, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/).) To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.proportions_tests as prci
+
+A recent version of Paul Tol's python module, :code:`tol_colors.py` is redistributed within this package. Other than re-formatting and type annotation, the :code:`tol_colors` module is re-distributed as downloaded from, https://personal.sron.nl/~pault/data/tol_colors.py. The tol_colors.py module is distributed under the Standard 3-clause BSD license. To access the tol_colors module directly:
+
+.. code-block:: python
+
+    import mergeron.ext.tol_colors
+
+Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
+
+.. code-block:: python
+
+    import mergeron.core.data_generation as dgl
+
+    help(dgl.gen_market_sample)
+
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :alt: Poetry
+   :target: https://python-poetry.org/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "mergeron"
 # See ./get_version_str.py
-version = "2024.738953.1"
+version = "2024.738972.0"
 description = "Analysis of standards defined in Horizontal Merger Guidelines"
 keywords = [
     "merger policy analysis",

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/src/mergeron/License.txt

@@ -1,7 +1,7 @@
 mergeron
 ========
 
-Copyright 2017-2023 S. Murthy Kambhampaty
+Copyright 2017-2024 S. Murthy Kambhampaty
 
 MIT License
 -----------

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/src/mergeron/core/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from importlib.metadata import version
 
-from attrs import Attribute, define, field, validators
+from attrs import Attribute, field, frozen, validators
 
 from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
 
@@ -38,7 +38,7 @@ def _rec_spec_validator(
         )
 
 
-@define(slots=True, frozen=True)
+@frozen
 class UPPBoundarySpec:
     share_ratio: float = field(
         kw_only=False,
@@ -54,7 +54,7 @@ class UPPBoundarySpec:
         default=UPPAggrSelector.MAX,
         validator=validators.instance_of(UPPAggrSelector),
     )
-    recapture_spec: RECConstants | None = field(
+    recapture_form: RECConstants | None = field(
         kw_only=True,
         default=RECConstants.INOUT,
         validator=(

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/src/mergeron/core/excel_helper.py

@@ -1,5 +1,5 @@
 """
-Routines for writing data from Python to fresh Excel workbooks using
+Methods for writing data from Python to fresh Excel workbooks using
 the third-party package, `xlsxwriter`.
 
 Includes a flexible system of defining cell formats.
@@ -27,6 +27,8 @@ __version__ = version(_PKG_NAME)
 class CFmtParent(dict[str, Any], enum.ReprEnum):  # type: ignore
     """Unique mappings defining xlsxwirter Workbook formats"""
 
+    ...
+
 
 class CFmt(CFmtParent):
     """

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/src/mergeron/core/ftc_merger_investigations_data.py

@@ -1,5 +1,5 @@
 """
-Routines to parse FTC Merger Investigations Data, downloading source documents
+Methods to parse FTC Merger Investigations Data, downloading source documents
 as necessary
 
 NOTES
@@ -16,7 +16,6 @@ from pathlib import Path
 from types import MappingProxyType
 from typing import Any, NamedTuple, TypeAlias
 
-import fitz  # type: ignore
 import msgpack  # type: ignore
 import msgpack_numpy as m  # type: ignore
 import numpy as np
@@ -146,7 +145,7 @@ def construct_data(
                     )
         return MappingProxyType(_invdata)
 
-    _invdata = dict(parse_invdata())  # Convert immutable to mutable
+    _invdata = dict(_parse_invdata())  # Convert immutable to mutable
 
     # Add some data periods (
     #   only periods ending in 2011, others have few observations and
@@ -385,21 +384,9 @@ def _invdata_build_aggregate_table(
     )
 
 
-def parse_invdata(
-    _invdata_docnames: Sequence[str] = (
-        "040831horizmergersdata96-03.pdf",
-        "p035603horizmergerinvestigationdata1996-2005.pdf",
-        "081201hsrmergerdata.pdf",
-        "130104horizontalmergerreport.pdf",
-    ),
-) -> INVData:
+def _parse_invdata() -> INVData:
     """Parse FTC merger investigations data reports to structured data.
 
-    Parameters
-    ----------
-    _invdata_docnames
-        Names of PDF files reporting FTC merger investigations data.
-
     Returns
     -------
         Immutable dictionary of merger investigations data, keyed to
@@ -408,6 +395,16 @@ def parse_invdata(
         by range of HHI and ∆HHI.
 
     """
+    import fitz  # type: ignore
+    # user must install pymupdf to make this function operable
+
+    _invdata_docnames: Sequence[str] = (
+        "040831horizmergersdata96-03.pdf",
+        "p035603horizmergerinvestigationdata1996-2005.pdf",
+        "081201hsrmergerdata.pdf",
+        "130104horizontalmergerreport.pdf",
+    )
+
     _invdata: dict[str, dict[str, dict[str, INVTableData]]] = {}
 
     for _invdata_docname in _invdata_docnames:

{mergeron-2024.738953.1 → mergeron-2024.738972.0}/src/mergeron/core/guidelines_boundaries.py

@@ -1,17 +1,16 @@
 """
-Routines for defining and analyzing boundaries for Guidelines standards,
+Methods for defining and analyzing boundaries for Guidelines standards,
 with a canvas on which to draw boundaries for Guidelines standards.
 
 """
 
 import decimal
-from collections.abc import Callable
 from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Any, Literal, TypeAlias
 
 import numpy as np
-from attrs import define, field
+from attrs import field, frozen
 from mpmath import mp, mpf  # type: ignore
 from numpy.typing import NDArray
 
@@ -24,7 +23,7 @@ __version__ = version(_PKG_NAME)
 mp.prec = 80
 mp.trap_complex = True
 
-HMGPubYear: TypeAlias = Literal[1992, 2010, 2023]
+HMGPubYear: TypeAlias = Literal[1992, 2004, 2010, 2023]
 
 
 @dataclass(slots=True, frozen=True)
@@ -43,25 +42,28 @@ class GuidelinesBoundary:
     area: float
 
 
-@dataclass(slots=True, frozen=True)
-class GuidelinesBoundaryCallable:
-    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
-    area: float
-    s_naught: float = 0
-
-
-@define(slots=True, frozen=True)
+@frozen
 class GuidelinesThresholds:
     """
     Guidelines threholds by Guidelines publication year
 
     ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
-    constructed from concentration standards.
+    constructed from concentration standards in Guidelines published in
+    1992, 2004, 2010, and 2023.
+
+    The 2004 Guidelines refernced here are the EU Commission
+    guidelines on assessment of horizontal mergers. These
+    guidelines also define a presumption for mergers with
+    post-merger HHI in [1000, 2000) and ΔHHI >= 250 points,
+    whi is not modeled here.
+
+    All other Guidelines modeled here are U.S. merger guidelines.
+
     """
 
     pub_year: HMGPubYear
     """
-    Year of publication of the U.S. Horizontal Merger Guidelines (HMG)
+    Year of publication of the Guidelines
     """
 
     safeharbor: HMGThresholds = field(kw_only=True, default=None)
@@ -99,6 +101,7 @@ class GuidelinesThresholds:
         _hhi_p, _dh_s, _dh_p = {
             1992: (0.18, 0.005, 0.01),
             2010: (0.25, 0.01, 0.02),
+            2004: (0.20, 0.015, 0.015),
             2023: (0.18, 0.01, 0.01),
         }[self.pub_year]
 
@@ -507,7 +510,7 @@ def boundary_plot(*, mktshares_plot_flag: bool = True) -> tuple[Any, ...]:
     return plt, _fig, _ax_out, _set_axis_def
 
 
-def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
+def dh_area(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
     R"""
     Area under the ΔHHI boundary.
 
@@ -530,7 +533,7 @@ def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
     ----------
     _dh_val
         Change in concentration.
-    dh_dps
+    prec
         Specified precision in decimal places.
 
     Returns
@@ -544,11 +547,11 @@ def dh_area(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
 
     return round(
         float(_s_naught + (_dh_val / 2) * (mp.ln(1 - _s_naught) - mp.ln(_s_naught))),
-        dh_dps,
+        prec,
     )
 
 
-def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
+def dh_area_quad(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
     """
     Area under the ΔHHI boundary.
 
@@ -560,7 +563,7 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
     ----------
     _dh_val
         Merging-firms' ΔHHI bound.
-    dh_dps
+    prec
         Specified precision in decimal places.
 
     Returns
@@ -576,7 +579,7 @@ def dh_area_quad(_dh_val: float = 0.01, /, *, dh_dps: int = 9) -> float:
         float(
             _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
         ),
-        dh_dps,
+        prec,
     )
 
 
@@ -590,7 +593,7 @@ def delta_hhi_boundary(
     ----------
     _dh_val:
         Merging-firms' ΔHHI bound.
-    dh_dps
+    prec
         Number of decimal places for rounding reported shares.
 
     Returns
@@ -620,7 +623,7 @@ def delta_hhi_boundary(
             np.array(_s_1_pts, np.float64),
             np.array(_s_2_pts, np.float64),
         )),
-        dh_area(_dh_val, dh_dps=prec),
+        dh_area(_dh_val, prec=prec),
     )
 
 
@@ -697,7 +700,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
             return shrratio_boundary_xact_avg(
                 _bdry_spec.share_ratio,
                 _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.MAX:
@@ -708,7 +711,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
             return shrratio_boundary_min(
                 _bdry_spec.share_ratio,
                 _bdry_spec.rec,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case UPPAggrSelector.DIS:
@@ -717,7 +720,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
                 _bdry_spec.rec,
                 agg_method="distance",
                 weighting=None,
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
         case _:
@@ -738,7 +741,7 @@ def shrratio_boundary(_bdry_spec: UPPBoundarySpec) -> GuidelinesBoundary:
                 _bdry_spec.rec,
                 agg_method=_agg_method,  # type: ignore
                 weighting=_weighting,  # type: ignore
-                recapture_spec=_bdry_spec.recapture_spec.value,  # type: ignore
+                recapture_form=_bdry_spec.recapture_form.value,  # type: ignore
                 prec=_bdry_spec.precision,
             )
 
@@ -788,7 +791,7 @@ def shrratio_boundary_min(
     _r_val: float = 0.80,
     /,
     *,
-    recapture_spec: str = "inside-out",
+    recapture_form: str = "inside-out",
     prec: int = 10,
 ) -> GuidelinesBoundary:
     """
@@ -808,7 +811,7 @@ def shrratio_boundary_min(
         Margin-adjusted benchmark share ratio.
     _r_val
         Recapture ratio.
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -824,7 +827,7 @@ def shrratio_boundary_min(
     _s_intcpt = mpf("1.00")
     _s_mid = _delta_star / (1 + _delta_star)
 
-    if recapture_spec == "inside-out":
+    if recapture_form == "inside-out":
         # ## Plot envelope of GUPPI boundaries with r_k = r_bar if s_k = min(_s_1, _s_2)
         # ## See (s_i, s_j) in equation~(44), or thereabouts, in paper
         _smin_nr = _delta_star * (1 - _r_val)
@@ -857,7 +860,7 @@ def shrratio_boundary_wtd_avg(
     *,
     agg_method: Literal["arithmetic", "geometric", "distance"] = "arithmetic",
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
 ) -> GuidelinesBoundary:
     """
@@ -874,7 +877,7 @@ def shrratio_boundary_wtd_avg(
         Whether "arithmetic", "geometric", or "distance".
     weighting
         Whether "own-share" or "cross-product-share"  (or None for simple, unweighted average).
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -895,7 +898,7 @@ def shrratio_boundary_wtd_avg(
         g_val, r_val, m_val = 0.06, 0.80, 0.30
         delta_star = g_val / (r_val * m_val)
 
-        # recapture_spec == "inside-out"
+        # recapture_form == "inside-out"
         oswag = solve(
             s_1 * s_2 / (1 - s_1)
             + s_2 * s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1))
@@ -920,7 +923,7 @@ def shrratio_boundary_wtd_avg(
             ylabel=s_2
         )
 
-        # recapture_spec == "proportional"
+        # recapture_form == "proportional"
         oswag = solve(
             s_1 * s_2 / (1 - s_1)
             + s_2 * s_1 / (1 - s_2)
@@ -973,7 +976,7 @@ def shrratio_boundary_wtd_avg(
             _de_1 = _s_2 / (1 - _s_1)
             _de_2 = (
                 _s_1 / (1 - lerp(_s_1, _s_2, _r_val))
-                if recapture_spec == "inside-out"
+                if recapture_form == "inside-out"
                 else _s_1 / (1 - _s_2)
             )
 
@@ -1025,7 +1028,7 @@ def shrratio_boundary_wtd_avg(
         _s_1_pre,
         _delta_star,
         _r_val,
-        recapture_spec=recapture_spec,
+        recapture_form=recapture_form,
         agg_method=agg_method,
         weighting=weighting,
     )
@@ -1063,7 +1066,7 @@ def shrratio_boundary_xact_avg(
     _r_val: float = 0.80,
     /,
     *,
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
 ) -> GuidelinesBoundary:
     """
@@ -1082,7 +1085,7 @@ def shrratio_boundary_xact_avg(
         g_val, r_val, m_val = 0.06, 0.80, 0.30
         d_hat = g_val / (r_val * m_val)
 
-        # recapture_spec = "inside-out"
+        # recapture_form = "inside-out"
         sag = solve(
             (s_2 / (1 - s_1))
             + (s_1 / (1 - (r_val * s_2 + (1 - r_val) * s_1)))
@@ -1095,7 +1098,7 @@ def shrratio_boundary_xact_avg(
             ylabel=s_2
         )
 
-        # recapture_spec = "proportional"
+        # recapture_form = "proportional"
         sag = solve((s_2/(1 - s_1)) + (s_1/(1 - s_2)) - 2 * d_hat, s_2)[0]
         symplot(
             sag,
@@ -1109,7 +1112,7 @@ def shrratio_boundary_xact_avg(
         Margin-adjusted benchmark share ratio.
     _r_val
         Recapture ratio
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
     prec
@@ -1127,14 +1130,14 @@ def shrratio_boundary_xact_avg(
 
     _gbdry_points_start = np.array([(_s_mid, _s_mid)])
     _s_1 = np.array(mp.arange(_s_mid - _gbd_step_sz, 0, -_gbd_step_sz), np.float64)
-    if recapture_spec == "inside-out":
+    if recapture_form == "inside-out":
         _s_intcpt = mp.fdiv(
             mp.fsub(
                 2 * _delta_star * _r_val + 1, mp.fabs(2 * _delta_star * _r_val - 1)
             ),
             2 * mpf(f"{_r_val}"),
         )
-        _nr_t1 = 1 + 2 * _delta_star * _r_val * (1 - _s_1) - _s_1 * (1 - _r_val)  # type: ignore
+        _nr_t1 = 1 + 2 * _delta_star * _r_val * (1 - _s_1) - _s_1 * (1 - _r_val)
 
         _nr_sqrt_mdr = 4 * _delta_star * _r_val
         _nr_sqrt_mdr2 = _nr_sqrt_mdr * _r_val
@@ -1159,7 +1162,7 @@ def shrratio_boundary_xact_avg(
 
         _nr_t2_s1 = _nr_sqrt_s1sq + _nr_sqrt_s1 + _nr_sqrt_nos1
 
-        if not np.isclose(  # type: ignore
+        if not np.isclose(
             np.einsum("i->", _nr_t2_mdr.astype(np.float64)),
             np.einsum("i->", _nr_t2_s1.astype(np.float64)),
             rtol=0,
@@ -1167,7 +1170,7 @@ def shrratio_boundary_xact_avg(
         ):
             raise RuntimeError(
                 "Calculation of sq. root term in exact average GUPPI"
-                f"with recapture spec, {f'"{recapture_spec}"'} is incorrect."
+                f"with recapture spec, {f'"{recapture_form}"'} is incorrect."
             )
 
         _s_2 = (_nr_t1 - np.sqrt(_nr_t2_s1)) / (2 * _r_val)
@@ -1223,7 +1226,7 @@ def _shrratio_boundary_intcpt(
     _r_val: mpf,
     /,
     *,
-    recapture_spec: Literal["inside-out", "proportional"],
+    recapture_form: Literal["inside-out", "proportional"],
     agg_method: Literal["arithmetic", "geometric", "distance"],
     weighting: Literal["cross-product-share", "own-share"] | None,
 ) -> float:
@@ -1234,7 +1237,7 @@ def _shrratio_boundary_intcpt(
             _s_intcpt = mpf("1.0")
         case None if agg_method == "distance":
             _s_intcpt = _delta_star * mp.sqrt("2")
-        case None if agg_method == "arithmetic" and recapture_spec == "inside-out":
+        case None if agg_method == "arithmetic" and recapture_form == "inside-out":
             _s_intcpt = mp.fdiv(
                 mp.fsub(
                     2 * _delta_star * _r_val + 1, mp.fabs(2 * _delta_star * _r_val - 1)