mergeron 2024.738963.0__py3-none-any.whl → 2024.738973.0__py3-none-any.whl

mergeron/core/{guidelines_boundaries_specialized_functions.py → guidelines_boundary_functions_extra.py}

@@ -1,26 +1,26 @@
 """
 Specialized methods for defining and analyzing boundaries for Guidelines standards.
 
-These methods provide improved precision or demonstrate additional methods, but tend
-to have poor performance
+These methods (functions) provide rely on scipy of sympy for core computations,
+and may provide improved precision than core functions, but tend to have
+poor performance
 
 """
 
+from collections.abc import Callable
+from dataclasses import dataclass
 from importlib.metadata import version
 from typing import Literal
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
+from numpy.typing import NDArray
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
 from sympy import lambdify, simplify, solve, symbols
 
 from .. import _PKG_NAME  # noqa: TID252
-from .guidelines_boundaries import (
-    GuidelinesBoundary,
-    GuidelinesBoundaryCallable,
-    _shrratio_boundary_intcpt,
-    lerp,
-)
+from . import GuidelinesBoundary
+from .guidelines_boundary_functions import _shrratio_boundary_intcpt, lerp
 
 __version__ = version(_PKG_NAME)
 
@@ -29,7 +29,46 @@ mp.prec = 80
 mp.trap_complex = True
 
 
-def delta_hhi_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
+@dataclass(slots=True, frozen=True)
+class GuidelinesBoundaryCallable:
+    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
+    area: float
+    s_naught: float = 0
+
+
+def dh_area_quad(_dh_val: float = 0.01, /, *, prec: int = 9) -> float:
+    """
+    Area under the ΔHHI boundary.
+
+    When the given ΔHHI bound matches a Guidelines safeharbor,
+    the area under the boundary is half the intrinsic clearance rate
+    for the ΔHHI safeharbor.
+
+    Parameters
+    ----------
+    _dh_val
+        Merging-firms' ΔHHI bound.
+    prec
+        Specified precision in decimal places.
+
+    Returns
+    -------
+        Area under ΔHHI boundary.
+
+    """
+
+    _dh_val = mpf(f"{_dh_val}")
+    _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
+
+    return round(
+        float(
+            _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
+        ),
+        prec,
+    )
+
+
+def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
     """
     Generate the list of share combination on the ΔHHI boundary.
 

mergeron/gen/__init__.py

@@ -5,23 +5,21 @@ Defines constants and containers for industry data generation and testing
 
 from __future__ import annotations
 
-from importlib.metadata import version
-
-from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
-
-__version__ = version(_PKG_NAME)
-
-
 import enum
 from dataclasses import dataclass
-from typing import ClassVar, Literal, Protocol, TypeVar, Union
+from importlib.metadata import version
+from typing import ClassVar, Protocol, TypeVar
 
 import numpy as np
-from attrs import Attribute, define, field, validators
+from attrs import Attribute, define, field, frozen, validators
 from numpy.typing import NBitBase, NDArray
 
+from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
 
+__version__ = version(_PKG_NAME)
+
+
 EMPTY_ARRAY_DEFAULT = np.zeros(2)
 FCOUNT_WTS_DEFAULT = ((_nr := np.arange(1, 6)[::-1]) / _nr.sum()).astype(np.float64)
 
@@ -74,7 +72,7 @@ class SHRConstants(enum.StrEnum):
     """
 
 
-@define(slots=True, frozen=True)
+@frozen
 class ShareSpec:
     """Market share specification
 
@@ -152,7 +150,7 @@ class FM2Constants(enum.StrEnum):
     SYM = "symmetric"
 
 
-@define(slots=True, frozen=True)
+@frozen
 class PCMSpec:
     """Price-cost margin (PCM) specification
 
@@ -224,18 +222,9 @@ class SSZConstants(float, enum.ReprEnum):
     """When initial set of draws is not restricted in any way."""
 
 
-# Validators for selected attributes of MarketSampleSpec
-def _sample_size_validator(
-    _object: MarketSampleSpec, _attribute: Attribute[int], _value: int, /
-) -> None:
-    if _value < 10**6:
-        raise ValueError(
-            f"Sample size must be no less than {10**6:,d}; got, {_value:,d}."
-        )
-
-
+# Validators for selected attributes of MarketSpec
 def _share_spec_validator(
-    _instance: MarketSampleSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
+    _instance: MarketSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
 ) -> None:
     _r_bar = _value.recapture_rate
     if _r_bar and not (0 < _r_bar <= 1):
@@ -274,7 +263,7 @@ def _share_spec_validator(
 
 
 def _pcm_spec_validator(
-    _instance: MarketSampleSpec, _attribute: Attribute[PCMSpec], _value: PCMSpec, /
+    _instance: MarketSpec, _attribute: Attribute[PCMSpec], _value: PCMSpec, /
 ) -> None:
     if (
         _instance.share_spec.recapture_form == RECConstants.FIXED
@@ -308,15 +297,10 @@ def _pcm_spec_validator(
             )
 
 
-@define(slots=True, frozen=True)
-class MarketSampleSpec:
+@define(slots=False)
+class MarketSpec:
     """Parameter specification for market data generation."""
 
-    sample_size: int = field(
-        default=10**6, validator=(validators.instance_of(int), _sample_size_validator)
-    )
-    """sample size generated"""
-
     share_spec: ShareSpec = field(
         kw_only=True,
         default=ShareSpec(RECConstants.INOUT, 0.855, SHRConstants.UNI, None, None),
@@ -353,17 +337,16 @@ class INVResolution(enum.StrEnum):
     BOTH = "both"
 
 
-@define(slots=True, frozen=True)
+@frozen
 class UPPTestRegime:
     resolution: INVResolution = field(
         default=INVResolution.ENFT, validator=validators.instance_of(INVResolution)
     )
     guppi_aggregator: UPPAggrSelector = field(
-        default=UPPAggrSelector.MAX, validator=validators.instance_of(UPPAggrSelector)
+        default=UPPAggrSelector.MIN, validator=validators.instance_of(UPPAggrSelector)
     )
     divr_aggregator: UPPAggrSelector | None = field(
-        default=guppi_aggregator,
-        validator=validators.instance_of((UPPAggrSelector, type(None))),
+        default=None, validator=validators.instance_of((UPPAggrSelector, type(None)))
     )
 
 
@@ -469,7 +452,7 @@ class MarginDataSample:
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsRaw:
-    """arrays marking test failures and successes
+    """Container for arrays marking test failures and successes
 
     A test success is a draw ("market") that meeets the
     specified test criterion, and a test failure is
@@ -494,9 +477,9 @@ class UPPTestsRaw:
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsCounts:
-    """counts of markets resolved as specified
+    """Counts of markets resolved as specified
 
-    Resolution is specified in a UPPTestRegime object.
+    Resolution may be either "enforcement" or "clearance".
     """
 
     by_firm_count: NDArray[np.int64]

mergeron/gen/{_data_generation_functions_nonpublic.py → _data_generation_functions.py}

@@ -19,11 +19,12 @@ from ..core.pseudorandom_numbers import (  # noqa: TID252
     prng,
 )
 from . import (
+    EMPTY_ARRAY_DEFAULT,
     FCOUNT_WTS_DEFAULT,
     TF,
     FM2Constants,
     MarginDataSample,
-    MarketSampleSpec,
+    MarketSpec,
     PCMConstants,
     PriceDataSample,
     PRIConstants,
@@ -36,7 +37,8 @@ __version__ = version(_PKG_NAME)
 
 
 def _gen_share_data(
-    _mkt_sample_spec: MarketSampleSpec,
+    _sample_size: int,
+    _mkt_sample_spec: MarketSpec,
     _fcount_rng_seed_seq: SeedSequence | None,
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
@@ -66,7 +68,7 @@ def _gen_share_data(
         for _f in ("recapture_form", "dist_type", "dist_parms", "firm_counts_weights")
     )
 
-    _ssz = _mkt_sample_spec.sample_size
+    _ssz = _sample_size
 
     match _dist_type_mktshr:
         case SHRConstants.UNI:
@@ -396,24 +398,22 @@ def _gen_market_shares_dirichlet(
 def _gen_price_data(
     _frmshr_array: NDArray[np.float64],
     _nth_firm_share: NDArray[np.float64],
-    _mkt_sample_spec: MarketSampleSpec,
+    _mkt_sample_spec: MarketSpec,
     _seed_seq: SeedSequence | None = None,
     /,
 ) -> PriceDataSample:
-    _ssz = len(_frmshr_array)
-
     _hsr_filing_test_type = _mkt_sample_spec.hsr_filing_test_type
 
     _price_array, _price_ratio_array, _hsr_filing_test = (
         np.ones_like(_frmshr_array, np.float64),
         np.empty_like(_frmshr_array, np.float64),
-        np.empty(_ssz, bool),
+        np.empty(len(_frmshr_array), bool),
     )
 
     _pr_max_ratio = 5.0
     match _mkt_sample_spec.price_spec:
         case PRIConstants.SYM:
-            _nth_firm_price = np.ones((_ssz, 1))
+            _nth_firm_price = np.ones((len(_frmshr_array), 1))
         case PRIConstants.POS:
             _price_array, _nth_firm_price = (
                 np.ceil(_p * _pr_max_ratio) for _p in (_frmshr_array, _nth_firm_share)
@@ -477,14 +477,14 @@ def _gen_price_data(
             # del _nth_firm_rev, _rev_ratio_to_nth
         case _:
             # Otherwise, all draws meet the filing test
-            _hsr_filing_test = np.ones(_ssz, dtype=bool)
+            _hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
 
     return PriceDataSample(_price_array, _hsr_filing_test)
 
 
 def _gen_pcm_data(
     _frmshr_array: NDArray[np.floating[TF]],
-    _mkt_sample_spec: MarketSampleSpec,
+    _mkt_sample_spec: MarketSpec,
     _price_array: NDArray[np.floating[TF]],
     _aggregate_purchase_prob: NDArray[np.floating[TF]],
     _pcm_rng_seed_seq: SeedSequence,
@@ -504,27 +504,25 @@ def _gen_pcm_data(
     _mnl_test_array = np.empty((len(_frmshr_array), 2), dtype=int)
 
     _beta_min, _beta_max = [None] * 2  # placeholder
-    _dist_parms = np.ones(2, np.float64)
     if _dist_type_pcm == PCMConstants.EMPR:
         _pcm_array = resample_mgn_data(
             _pcm_array.shape,  # type: ignore
             seed_sequence=_pcm_rng_seed_seq,
         )
     else:
-        if _dist_type_pcm == PCMConstants.UNI:
-            _dist_parms = (
-                DIST_PARMS_DEFAULT if _dist_parms_pcm is None else _dist_parms_pcm
-            )
-        elif _dist_type_pcm == PCMConstants.BETA:
-            # Error-checking (could move to validators in definition of MarketSampleSpec)
-
+        if _dist_type_pcm == PCMConstants.BETA:
             if _dist_parms_pcm is None:
-                _dist_parms_pcm = _dist_parms
+                _dist_parms_pcm = np.ones(2, np.float64)
 
         elif _dist_type_pcm == PCMConstants.BETA_BND:  # Bounded beta
             if _dist_parms_pcm is None:
                 _dist_parms_pcm = np.array([0, 1, 0, 1], np.float64)
                 _dist_parms = beta_located_bound(_dist_parms_pcm)
+        else:
+            #  _dist_type_pcm == PCMConstants.UNI
+            _dist_parms = (
+                DIST_PARMS_DEFAULT if _dist_parms_pcm is None else _dist_parms_pcm
+            )
 
         _pcm_rng = MultithreadedRNG(
             _pcm_array,
@@ -564,6 +562,66 @@ def _gen_pcm_data(
     return MarginDataSample(_pcm_array, _mnl_test_array)
 
 
+def _gen_divr_array(
+    _recapture_form: RECConstants,
+    _recapture_rate: float | None,
+    _frmshr_array: NDArray[np.float64],
+    _aggregate_purchase_prob: NDArray[np.float64] = EMPTY_ARRAY_DEFAULT,
+    /,
+) -> NDArray[np.float64]:
+    """
+    Given merging-firm shares and related parameters, return diverion ratios.
+
+    If recapture is specified as "Outside-in" (RECConstants.OUTIN), then the
+    choice-probability for the outside good must be supplied.
+
+    Parameters
+    ----------
+    _recapture_form
+        Enum specifying Fixed (proportional), Inside-out, or Outside-in
+
+    _recapture_rate
+        If recapture is proportional or inside-out, the recapture rate
+        for the firm with the smaller share.
+
+    _frmshr_array
+        Merging-firm shares.
+
+    _aggregate_purchase_prob
+        1 minus probability that the outside good is chosen; converts
+        market shares to choice probabilities by multiplication.
+
+    Returns
+    -------
+        Merging-firm diversion ratios for mergers in the sample.
+
+    """
+
+    _divr_array: NDArray[np.float64]
+    if _recapture_form == RECConstants.FIXED:
+        _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
+
+    else:
+        _purchprob_array = _aggregate_purchase_prob * _frmshr_array
+        _divr_array = _purchprob_array[:, ::-1] / (1 - _purchprob_array)
+
+    _divr_assert_test = (
+        (np.round(np.einsum("ij->i", _frmshr_array), 15) == 1)
+        | (np.argmin(_frmshr_array, axis=1) == np.argmax(_divr_array, axis=1))
+    )[:, None]
+    if not all(_divr_assert_test):
+        raise ValueError(
+            "{} {} {} {}".format(
+                "Data construction fails tests:",
+                "the index of min(s_1, s_2) must equal",
+                "the index of max(d_12, d_21), for all draws.",
+                "unless frmshr_array sums to 1.00.",
+            )
+        )
+
+    return _divr_array
+
+
 def _beta_located(
     _mu: float | NDArray[np.float64], _sigma: float | NDArray[np.float64], /
 ) -> NDArray[np.float64]:

mergeron/gen/data_generation.py

@@ -7,7 +7,6 @@ from __future__ import annotations
 
 from importlib.metadata import version
 
-import attrs
 import numpy as np
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
@@ -17,12 +16,12 @@ from . import (
     EMPTY_ARRAY_DEFAULT,
     FM2Constants,
     MarketDataSample,
-    MarketSampleSpec,
+    MarketSpec,
     PRIConstants,
     SHRConstants,
     SSZConstants,
 )
-from ._data_generation_functions_nonpublic import (
+from ._data_generation_functions import (
     _gen_market_shares_dirichlet,  # noqa: F401 easter-egg for external modules
     _gen_market_shares_uniform,  # noqa: F401 easter-egg for external modules
     _gen_pcm_data,
@@ -34,9 +33,10 @@ __version__ = version(_PKG_NAME)
 
 
 def gen_market_sample(
-    _mkt_sample_spec: MarketSampleSpec,
+    _mkt_sample_spec: MarketSpec,
     /,
     *,
+    sample_size: int = 10**6,
     seed_seq_list: list[SeedSequence] | None = None,
     nthreads: int = 16,
 ) -> MarketDataSample:
@@ -59,6 +59,8 @@ def gen_market_sample(
     ----------
     _mkt_sample_spec
         class specifying parameters for data generation
+    sample_size
+        number of draws to generate
     seed_seq_list
         tuple of SeedSequences to ensure replicable data generation with
         appropriately independent random streams
@@ -72,7 +74,7 @@ def gen_market_sample(
 
     """
 
-    _mkt_sample_spec = _mkt_sample_spec or MarketSampleSpec()
+    _mkt_sample_spec = _mkt_sample_spec or MarketSpec()
 
     _recapture_form = _mkt_sample_spec.share_spec.recapture_form
     _recapture_rate = _mkt_sample_spec.share_spec.recapture_rate
@@ -89,19 +91,20 @@ def gen_market_sample(
         seed_seq_list, _dist_type_mktshr, _mkt_sample_spec.price_spec
     )
 
-    _shr_sample_size = 1.0 * _mkt_sample_spec.sample_size
+    _shr_sample_size = 1.0 * sample_size
     # Scale up sample size to offset discards based on specified criteria
     _shr_sample_size *= _hsr_filing_test_type
     if _dist_firm2_pcm == FM2Constants.MNL:
         _shr_sample_size *= SSZConstants.MNL_DEP
-    _mkt_sample_spec_here = attrs.evolve(
-        _mkt_sample_spec, sample_size=int(_shr_sample_size)
-    )
-    del _shr_sample_size
+    _shr_sample_size = int(_shr_sample_size)
 
     # Generate share data
     _mktshr_data = _gen_share_data(
-        _mkt_sample_spec_here, _fcount_rng_seed_seq, _mktshr_rng_seed_seq, nthreads
+        _shr_sample_size,
+        _mkt_sample_spec,
+        _fcount_rng_seed_seq,
+        _mktshr_rng_seed_seq,
+        nthreads,
     )
 
     _mktshr_array, _fcounts, _aggregate_purchase_prob, _nth_firm_share = (
@@ -116,7 +119,7 @@ def gen_market_sample(
 
     # Generate merging-firm price data
     _price_data = _gen_price_data(
-        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec_here, _pr_rng_seed_seq
+        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec, _pr_rng_seed_seq
     )
 
     _price_array, _hsr_filing_test = (
@@ -138,7 +141,7 @@ def gen_market_sample(
     # Generate margin data
     _pcm_data = _gen_pcm_data(
         _mktshr_array[:, :2],
-        _mkt_sample_spec_here,
+        _mkt_sample_spec,
         _price_array,
         _aggregate_purchase_prob,
         _pcm_rng_seed_seq,
@@ -148,7 +151,7 @@ def gen_market_sample(
         getattr(_pcm_data, _f) for _f in ("pcm_array", "mnl_test_array")
     )
 
-    _s_size = _mkt_sample_spec.sample_size  # originally-specified sample size
+    _s_size = sample_size  # originally-specified sample size
     if _dist_firm2_pcm == FM2Constants.MNL:
         _mktshr_array = _mktshr_array[_mnl_test_rows][:_s_size]
         _pcm_array = _pcm_array[_mnl_test_rows][:_s_size]

mergeron/gen/market_sample.py

@@ -0,0 +1,79 @@
+"""
+Methods to generate data for analyzing merger enforcement policy.
+
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import version
+
+from attrs import define
+from numpy.random import SeedSequence
+
+from .. import _PKG_NAME  # noqa: TID252
+from ..core import guidelines_boundaries as gbl  # noqa: TID252
+from . import MarketSpec, UPPTestRegime
+from .data_generation import gen_market_sample
+from .upp_tests import SaveData, invres_cnts, save_data_to_hdf5, sim_invres_cnts_ll
+
+__version__ = version(_PKG_NAME)
+
+
+@define(slots=False)
+class MarketSample(MarketSpec):
+    def generate_sample(
+        self,
+        /,
+        *,
+        sample_size: int = 10**6,
+        seed_seq_list: list[SeedSequence] | None,
+        nthreads: int,
+        save_data_to_file: SaveData = False,
+    ) -> None:
+        self.data = gen_market_sample(
+            self,
+            sample_size=sample_size,
+            seed_seq_list=seed_seq_list,
+            nthreads=nthreads,
+        )
+        _invalid_array_names = (
+            ("fcounts", "choice_prob_outgd", "nth_firm_share", "hhi_post")
+            if self.share_spec.dist_type == "Uniform"
+            else ()
+        )
+        if save_data_to_file:
+            save_data_to_hdf5(
+                self.data,
+                excluded_attrs=_invalid_array_names,
+                save_data_to_file=save_data_to_file,
+            )
+
+    def estimate_invres_counts(
+        self,
+        _invres_parm_vec: gbl.HMGThresholds,
+        _upp_test_regime: UPPTestRegime,
+        /,
+        *,
+        sample_size: int = 10**6,
+        seed_seq_list: list[SeedSequence] | None,
+        nthreads: int,
+        save_data_to_file: SaveData = False,
+    ) -> None:
+        if getattr(self, "market_data_sample", None) is None:
+            self.invres_counts = sim_invres_cnts_ll(
+                self,
+                _invres_parm_vec,
+                _upp_test_regime,
+                save_data_to_file=save_data_to_file,
+                sample_size=sample_size,
+                seed_seq_list=seed_seq_list,
+                nthreads=nthreads,
+            )
+        else:
+            self.invres_counts = invres_cnts(
+                self.data, _invres_parm_vec, _upp_test_regime
+            )
+            if save_data_to_file:
+                save_data_to_hdf5(
+                    self.invres_counts, save_data_to_file=save_data_to_file
+                )