mergeron 2024.739104.1__py3-none-any.whl → 2024.739105.2__py3-none-any.whl

mergeron/__init__.py

@@ -9,7 +9,7 @@ from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739104.1"
+VERSION = "2024.739105.2"
 
 __version__ = VERSION
 
@@ -36,7 +36,7 @@ ArrayBIGINT: TypeAlias = NDArray[np.int64]
 
 
 @enum.unique
-class RECTypes(enum.StrEnum):
+class RECForm(enum.StrEnum):
     """Recapture rate - derivation methods."""
 
     INOUT = "inside-out"

mergeron/core/guidelines_boundaries.py

@@ -13,7 +13,7 @@ import numpy as np
 from attrs import Attribute, field, frozen, validators
 from mpmath import mp, mpf  # type: ignore
 
-from .. import VERSION, ArrayDouble, RECTypes, UPPAggrSelector  # noqa: TID252
+from .. import VERSION, ArrayDouble, RECForm, UPPAggrSelector  # noqa: TID252
 from . import guidelines_boundary_functions as gbfn
 
 __version__ = VERSION
@@ -223,14 +223,14 @@ def _divr_value_validator(
 
 def _rec_spec_validator(
     _instance: DiversionRatioBoundary,
-    _attribute: Attribute[RECTypes],
-    _value: RECTypes,
+    _attribute: Attribute[RECForm],
+    _value: RECForm,
     /,
 ) -> None:
-    if _value == RECTypes.OUTIN and _instance.recapture_rate:
+    if _value == RECForm.OUTIN and _instance.recapture_rate:
         raise ValueError(
             f"Invalid recapture specification, {_value!r}. "
-            "You may consider specifying `mergeron.RECTypes.INOUT` here, and "
+            "You may consider specifying `mergeron.RECForm.INOUT` here, and "
             'assigning the default recapture rate as attribute, "recapture_rate" of '
             "this `DiversionRatioBoundarySpec` object."
         )
@@ -265,24 +265,24 @@ class DiversionRatioBoundary:
         kw_only=False, default=0.85, validator=validators.instance_of(float)
     )
 
-    recapture_form: RECTypes | None = field(
+    recapture_form: RECForm | None = field(
         kw_only=True,
-        default=RECTypes.INOUT,
+        default=RECForm.INOUT,
         validator=(
-            validators.instance_of((type(None), RECTypes)),
+            validators.instance_of((type(None), RECForm)),
             _rec_spec_validator,
         ),
     )
     """
     The form of the recapture rate.
 
-    When :attr:`mergeron.RECTypes.INOUT`, the recapture rate for
+    When :attr:`mergeron.RECForm.INOUT`, the recapture rate for
     he product having the smaller market-share is assumed to equal the default,
     and the recapture rate for the product with the larger market-share is
     computed assuming MNL demand. Fixed recapture rates are specified as
-    :attr:`mergeron.RECTypes.FIXED`. (To specify that recapture rates be
+    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture rates be
     constructed from the generated purchase-probabilities for products in
-    the market and for the outside good, specify :attr:`mergeron.RECTypes.OUTIN`.)
+    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)`,

mergeron/gen/__init__.py

@@ -21,7 +21,7 @@ from .. import (  # noqa: TID252
     ArrayDouble,
     ArrayFloat,
     ArrayINT,
-    RECTypes,
+    RECForm,
     UPPAggrSelector,
 )
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
@@ -57,7 +57,7 @@ class PriceSpec(tuple[bool, str | None], enum.ReprEnum):
 
 
 @enum.unique
-class SHRDistributions(enum.StrEnum):
+class SHRDistribution(enum.StrEnum):
     """Market share distributions."""
 
     UNI = "Uniform"
@@ -98,26 +98,26 @@ class ShareSpec:
     A key feature of market-share specification in this package is that
     the draws represent markets with multiple different firm-counts.
     Firm-counts are unspecified if the share distribution is
-    :attr:`mergeron.SHRDistributions.UNI`, for Dirichlet-distributed market-shares,
+    :attr:`mergeron.SHRDistribution.UNI`, for Dirichlet-distributed market-shares,
     the default specification is that firm-counts  vary between
     2 and 7 firms with each value equally likely.
 
     Notes
     -----
-    If :attr:`mergeron.gen.ShareSpec.dist_type`:code:` == `:attr:`mergeron.gen.SHRDistributions.UNI`,
+    If :attr:`mergeron.gen.ShareSpec.dist_type`:code:` == `:attr:`mergeron.gen.SHRDistribution.UNI`,
     then it is infeasible that
-    :attr:`mergeron.gen.ShareSpec.recapture_form`:code:` == `:attr:`mergeron.RECTypes.OUTIN`.
+    :attr:`mergeron.gen.ShareSpec.recapture_form`:code:` == `:attr:`mergeron.RECForm.OUTIN`.
     In other words, if firm-counts are unspecified, the recapture rate cannot be
     estimated using outside good choice probabilities.
 
     For a sample with explicit firm counts, market shares must
     be specified as having a supported Dirichlet distribution
-    (see :class:`mergeron.gen.SHRDistributions`).
+    (see :class:`mergeron.gen.SHRDistribution`).
 
     """
 
-    dist_type: SHRDistributions
-    """See :class:`SHRDistributions`"""
+    dist_type: SHRDistribution
+    """See :class:`SHRDistribution`"""
 
     dist_parms: ArrayDouble | None = field(
         default=None, eq=cmp_using(eq=np.array_equal)
@@ -143,22 +143,22 @@ class ShareSpec:
 
     @firm_counts_weights.validator
     def _check_fcw(_i: ShareSpec, _a: Attribute[ArrayDouble], _v: ArrayDouble) -> None:
-        if _v is not None and _i.dist_type == SHRDistributions.UNI:
+        if _v is not None and _i.dist_type == SHRDistribution.UNI:
             raise ValueError(
                 "Generated data for markets with specified firm-counts or "
                 "varying firm counts are not feasible for market shares "
                 "with Uniform distribution. Consider revising the "
-                r"distribution type to {SHRDistributions.DIR_FLAT}, which gives "
+                r"distribution type to {SHRDistribution.DIR_FLAT}, which gives "
                 "uniformly distributed draws on the :math:`n+1` simplex "
                 "for firm-count, :math:`n`."
             )
 
-    recapture_form: RECTypes = field(default=RECTypes.INOUT)
-    """See :class:`mergeron.RECTypes`"""
+    recapture_form: RECForm = field(default=RECForm.INOUT)
+    """See :class:`mergeron.RECForm`"""
 
     @recapture_form.validator
-    def _check_rf(_i: ShareSpec, _a: Attribute[RECTypes], _v: RECTypes) -> None:
-        if _v == RECTypes.OUTIN and _i.dist_type == SHRDistributions.UNI:
+    def _check_rf(_i: ShareSpec, _a: Attribute[RECForm], _v: RECForm) -> None:
+        if _v == RECForm.OUTIN and _i.dist_type == SHRDistribution.UNI:
             raise ValueError(
                 "Market share specification requires estimation of recapture rate from "
                 "generated data. Either delete recapture rate specification or set it to None."
@@ -168,7 +168,7 @@ class ShareSpec:
     """A value between 0 and 1, typically 0.8.
 
     :code:`None` if market share specification requires direct generation of
-    outside good choice probabilities (:attr:`mergeron.RECTypes.OUTIN`).
+    outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
 
     The recapture rate is usually calibrated to the numbers-equivalent of the
     HHI threshold for the presumtion of harm from unilateral competitive effects
@@ -191,7 +191,7 @@ class ShareSpec:
     def _check_rr(_i: ShareSpec, _a: Attribute[float], _v: float) -> None:
         if _v and not (0 < _v <= 1):
             raise ValueError("Recapture rate must lie in the interval, [0, 1).")
-        elif _v is None and _i.recapture_form != RECTypes.OUTIN:
+        elif _v is None and _i.recapture_form != RECForm.OUTIN:
             raise ValueError(
                 f"Recapture specification, {_i.recapture_form!r} requires that "
                 "the market sample specification inclues a recapture rate in the "
@@ -200,7 +200,7 @@ class ShareSpec:
 
 
 @enum.unique
-class PCMDistributions(enum.StrEnum):
+class PCMDistribution(enum.StrEnum):
     """Margin distributions."""
 
     UNI = "Uniform"
@@ -210,7 +210,7 @@ class PCMDistributions(enum.StrEnum):
 
 
 @enum.unique
-class FM2Constants(enum.StrEnum):
+class FM2Constraint(enum.StrEnum):
     """Firm 2 margins - derivation methods."""
 
     IID = "i.i.d"
@@ -234,8 +234,8 @@ class PCMSpec:
 
     """
 
-    dist_type: PCMDistributions = field(kw_only=False, default=PCMDistributions.UNI)
-    """See :class:`PCMDistributions`"""
+    dist_type: PCMDistribution = field(kw_only=False, default=PCMDistribution.UNI)
+    """See :class:`PCMDistribution`"""
 
     dist_parms: ArrayDouble | None = field(kw_only=False, default=None)
     """Parameter specification for tailoring PCM distribution
@@ -260,9 +260,9 @@ class PCMSpec:
                     "are not valid with margin distribution, {_dist_type_pcm!r}"
                 )
             elif (
-                _i.dist_type == PCMDistributions.BETA and len(_v) != len(("a", "b"))
+                _i.dist_type == PCMDistribution.BETA and len(_v) != len(("a", "b"))
             ) or (
-                _i.dist_type == PCMDistributions.BETA_BND
+                _i.dist_type == PCMDistribution.BETA_BND
                 and len(_v) != len(("mu", "sigma", "max", "min"))
             ):
                 raise ValueError(
@@ -270,18 +270,18 @@ class PCMSpec:
                     f'for PCM with distribution, "{_i.dist_type}" is incorrect.'
                 )
 
-        elif _i.dist_type == PCMDistributions.EMPR and _v is not None:
+        elif _i.dist_type == PCMDistribution.EMPR and _v is not None:
             raise ValueError(
                 f"Empirical distribution does not require additional parameters; "
                 f'"given value, {_v!r} is ignored."'
             )
 
-    firm2_pcm_constraint: FM2Constants = field(kw_only=False, default=FM2Constants.IID)
-    """See :class:`FM2Constants`"""
+    firm2_pcm_constraint: FM2Constraint = field(kw_only=False, default=FM2Constraint.IID)
+    """See :class:`FM2Constraint`"""
 
 
 @enum.unique
-class SSZConstants(float, enum.ReprEnum):
+class SSZConstant(float, enum.ReprEnum):
     """
     Scale factors to offset sample size reduction.
 

mergeron/gen/data_generation.py

@@ -13,18 +13,18 @@ from attrs import Attribute, define, field, validators
 from joblib import Parallel, cpu_count, delayed  # type: ignore
 from numpy.random import SeedSequence
 
-from .. import VERSION, RECTypes  # noqa: TID252  # noqa
+from .. import VERSION, RECForm  # noqa: TID252  # noqa
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from ..core.guidelines_boundaries import HMGThresholds  # noqa: TID252
 from . import (
-    FM2Constants,
+    FM2Constraint,
     MarketDataSample,
-    PCMDistributions,
+    PCMDistribution,
     PCMSpec,
     PriceSpec,
     ShareSpec,
-    SHRDistributions,
-    SSZConstants,
+    SHRDistribution,
+    SSZConstant,
     UPPTestRegime,
     UPPTestsCounts,
 )
@@ -40,7 +40,7 @@ __version__ = VERSION
 
 
 class SamplingFunctionKWArgs(TypedDict, total=False):
-    "Keyword arguments of function, :func:`MarketSample.sim_enf_cnts`"
+    "Keyword arguments of sampling methods defined below"
 
     sample_size: int
     """number of draws to generate"""
@@ -73,26 +73,26 @@ class MarketSample:
 
     share_spec: ShareSpec = field(
         kw_only=True,
-        default=ShareSpec(SHRDistributions.UNI, None, None, RECTypes.INOUT, 0.8),
+        default=ShareSpec(SHRDistribution.UNI, None, None, RECForm.INOUT, 0.8),
         validator=validators.instance_of(ShareSpec),
     )
     """Market-share specification, see :class:`ShareSpec`"""
 
     pcm_spec: PCMSpec = field(
-        kw_only=True, default=PCMSpec(PCMDistributions.UNI, None, FM2Constants.IID)
+        kw_only=True, default=PCMSpec(PCMDistribution.UNI, None, FM2Constraint.IID)
     )
     """Margin specification, see :class:`PCMSpec`"""
 
     @pcm_spec.validator
     def _check_pcm(self, _a: Attribute[PCMSpec], _v: PCMSpec, /) -> None:
         if (
-            self.share_spec.recapture_form == RECTypes.FIXED
-            and _v.firm2_pcm_constraint == FM2Constants.MNL
+            self.share_spec.recapture_form == RECForm.FIXED
+            and _v.firm2_pcm_constraint == FM2Constraint.MNL
         ):
             raise ValueError(
                 f'Specification of "recapture_form", "{self.share_spec.recapture_form}" '
                 "requires Firm 2 margin must have property, "
-                f'"{FM2Constants.IID}" or "{FM2Constants.SYM}".'
+                f'"{FM2Constraint.IID}" or "{FM2Constraint.SYM}".'
             )
 
     price_spec: PriceSpec = field(
@@ -100,12 +100,12 @@ class MarketSample:
     )
     """Price specification, see :class:`PriceSpec`"""
 
-    hsr_filing_test_type: SSZConstants = field(
+    hsr_filing_test_type: SSZConstant = field(
         kw_only=True,
-        default=SSZConstants.ONE,
-        validator=validators.instance_of(SSZConstants),
+        default=SSZConstant.ONE,
+        validator=validators.instance_of(SSZConstant),
     )
-    """Method for modeling HSR filing threholds, see :class:`SSZConstants`"""
+    """Method for modeling HSR filing threholds, see :class:`SSZConstant`"""
 
     data: MarketDataSample = field(default=None)
 
@@ -124,7 +124,7 @@ class MarketSample:
         """
         Generate share, diversion ratio, price, and margin data for MarketSpec.
 
-        see :attr:`SamplingFunctionKWArgs` for description of parameters
+        see :attr:`SamplingFunctionKWArgs` for description of keyord parameters
 
         Returns
         -------
@@ -149,8 +149,8 @@ class MarketSample:
         _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
+        if _dist_firm2_pcm == FM2Constraint.MNL:
+            _shr_sample_size *= SSZConstant.MNL_DEP
         _shr_sample_size = int(_shr_sample_size)
 
         # Generate share data
@@ -195,7 +195,7 @@ class MarketSample:
 
         _mnl_test_rows = _mnl_test_rows * _hsr_filing_test
         _s_size = sample_size  # originally-specified sample size
-        if _dist_firm2_pcm == FM2Constants.MNL:
+        if _dist_firm2_pcm == FM2Constraint.MNL:
             _mktshr_array = _mktshr_array[_mnl_test_rows][:_s_size]
             _pcm_array = _pcm_array[_mnl_test_rows][:_s_size]
             _price_array = _price_array[_mnl_test_rows][:_s_size]
@@ -240,13 +240,21 @@ class MarketSample:
         self,
         /,
         *,
-        sample_size: int = 10**6,
-        seed_seq_list: list[SeedSequence] | None,
+        sample_size: int,
+        seed_seq_list: Sequence[SeedSequence],
         nthreads: int,
-        save_data_to_file: SaveData = False,
-        saved_array_name_suffix: str = "",
+        save_data_to_file: SaveData,
+        saved_array_name_suffix: str,
     ) -> None:
-        """Generate market data"""
+        """Populate :attr:`data` with generated data
+
+        see :attr:`SamplingFunctionKWArgs` for description of keyord parameters
+
+        Returns
+        -------
+        None
+
+        """
 
         self.data = self.gen_market_sample(
             sample_size=sample_size, seed_seq_list=seed_seq_list, nthreads=nthreads
@@ -389,7 +397,8 @@ class MarketSample:
 
         Returns
         -------
-            Arrays of UPPTestCounts
+            Arrays of enforcement counts or clearance counts by firm count,
+            ΔHHI and concentration zone
 
         """
         _sample_sz = sample_size
@@ -400,7 +409,7 @@ class MarketSample:
         _thread_count = cpu_count()
 
         if (
-            self.share_spec.recapture_form != RECTypes.OUTIN
+            self.share_spec.recapture_form != RECForm.OUTIN
             and self.share_spec.recapture_rate != _enf_parm_vec.rec
         ):
             raise ValueError(
@@ -458,12 +467,12 @@ class MarketSample:
         /,
         *,
         sample_size: int = 10**6,
-        seed_seq_list: list[SeedSequence] | None,
-        nthreads: int,
+        seed_seq_list: Sequence[SeedSequence] | None = None,
+        nthreads: int = 16,
         save_data_to_file: SaveData = False,
         saved_array_name_suffix: str = "",
     ) -> None:
-        """Estimate enforcement counts
+        """Populate :attr:`enf_counts` etimated test counts.
 
         Parameters
         ----------
@@ -478,16 +487,16 @@ class MarketSample:
             merging firms
 
         sample_size
-            Size of the market sample drawn
+            Number of draws to simulate
 
         seed_seq_list
-            List of :code:`numpy.random.SeedSequence` objects
+            List of seed sequences, to assure independent samples in each thread
 
         nthreads
-            Number of threads to use
+            Number of parallel processes to use
 
         save_data_to_file
-            Save data to given HDF5 file, at specified group node
+            Whether to save data to an HDF5 file, and where to save it
 
         saved_array_name_suffix
             Suffix to add to the array names in the HDF5 file

mergeron/gen/data_generation_functions.py

@@ -11,7 +11,7 @@ import numpy as np
 from attrs import evolve
 from numpy.random import SeedSequence
 
-from .. import VERSION, ArrayBIGINT, ArrayDouble, RECTypes  # noqa: TID252
+from .. import VERSION, ArrayBIGINT, ArrayDouble, RECForm  # noqa: TID252
 from ..core.damodaran_margin_data import mgn_data_resampler  # noqa: TID252
 from ..core.pseudorandom_numbers import (  # noqa: TID252
     DIST_PARMS_DEFAULT,
@@ -21,17 +21,17 @@ from ..core.pseudorandom_numbers import (  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
     FCOUNT_WTS_DEFAULT,
-    FM2Constants,
+    FM2Constraint,
     MarginDataSample,
-    PCMDistributions,
+    PCMDistribution,
     PCMSpec,
     PriceDataSample,
     PriceSpec,
     SeedSequenceData,
     ShareDataSample,
     ShareSpec,
-    SHRDistributions,
-    SSZConstants,
+    SHRDistribution,
+    SSZConstant,
 )
 
 __version__ = VERSION
@@ -71,7 +71,7 @@ def gen_share_data(
 
     _ssz = _sample_size
 
-    if _dist_type_mktshr == SHRDistributions.UNI:
+    if _dist_type_mktshr == SHRDistribution.UNI:
         _mkt_share_sample = gen_market_shares_uniform(
             _ssz, _dist_parms_mktshr, _mktshr_rng_seed_seq, _nthreads
         )
@@ -101,7 +101,7 @@ def gen_share_data(
     # If recapture_form == "inside-out", recalculate _aggregate_purchase_prob
     _frmshr_array = _mkt_share_sample.mktshr_array[:, :2]
     _r_bar = _share_spec.recapture_rate or 0.8
-    if _recapture_form == RECTypes.INOUT:
+    if _recapture_form == RECForm.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
             _mkt_share_sample.fcounts,
@@ -177,8 +177,8 @@ def gen_market_shares_uniform(
 
 def gen_market_shares_dirichlet_multimarket(
     _s_size: int = 10**6,
-    _recapture_form: RECTypes = RECTypes.INOUT,
-    _dist_type_dir: SHRDistributions = SHRDistributions.DIR_FLAT,
+    _recapture_form: RECForm = RECForm.INOUT,
+    _dist_type_dir: SHRDistribution = SHRDistribution.DIR_FLAT,
     _dist_parms_dir: ArrayDouble | None = None,
     _firm_count_wts: ArrayDouble | None = None,
     _fcount_rng_seed_seq: SeedSequence | None = None,
@@ -227,7 +227,7 @@ def gen_market_shares_dirichlet_multimarket(
     )
 
     _min_choice_wt = (
-        0.03 if _dist_type_dir == SHRDistributions.DIR_FLAT_CONSTR else 0.00
+        0.03 if _dist_type_dir == SHRDistribution.DIR_FLAT_CONSTR else 0.00
     )
     _fcount_keys, _choice_wts = zip(
         *(
@@ -246,10 +246,10 @@ def gen_market_shares_dirichlet_multimarket(
     _dir_alphas_full = (
         [1.0] * _fc_max if _dist_parms_dir is None else _dist_parms_dir[:_fc_max]
     )
-    if _dist_type_dir == SHRDistributions.DIR_ASYM:
+    if _dist_type_dir == SHRDistribution.DIR_ASYM:
         _dir_alphas_full = [2.0] * 6 + [1.5] * 5 + [1.25] * min(7, _fc_max)
 
-    if _dist_type_dir == SHRDistributions.DIR_COND:
+    if _dist_type_dir == SHRDistribution.DIR_COND:
 
         def _gen_dir_alphas(_fcv: int) -> ArrayDouble:
             _dat = [2.5] * 2
@@ -322,7 +322,7 @@ def gen_market_shares_dirichlet_multimarket(
 def gen_market_shares_dirichlet(
     _dir_alphas: ArrayDouble,
     _s_size: int = 10**6,
-    _recapture_form: RECTypes = RECTypes.INOUT,
+    _recapture_form: RECForm = RECForm.INOUT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
     /,
@@ -338,8 +338,8 @@ def gen_market_shares_dirichlet(
         sample size to be drawn
 
     _recapture_form
-        r_1 = r_2 if RECTypes.FIXED, otherwise MNL-consistent. If
-        RECTypes.OUTIN; the number of columns in the output share array
+        r_1 = r_2 if RECForm.FIXED, otherwise MNL-consistent. If
+        RECForm.OUTIN; the number of columns in the output share array
         is len(_dir_alphas) - 1.
 
     _mktshr_rng_seed_seq
@@ -357,7 +357,7 @@ def gen_market_shares_dirichlet(
     if not isinstance(_dir_alphas, np.ndarray):
         _dir_alphas = np.array(_dir_alphas)
 
-    if _recapture_form == RECTypes.OUTIN:
+    if _recapture_form == RECForm.OUTIN:
         _dir_alphas = np.concatenate((_dir_alphas, _dir_alphas[-1:]))
 
     _mktshr_seed_seq_ch = (
@@ -391,7 +391,7 @@ def gen_market_shares_dirichlet(
 
     # If recapture_form == 'inside_out', further calculations downstream
     _aggregate_purchase_prob = np.nan * np.empty((_s_size, 1))
-    if _recapture_form == RECTypes.OUTIN:
+    if _recapture_form == RECForm.OUTIN:
         _aggregate_purchase_prob = 1 - _mktshr_array[:, [-1]]
         _mktshr_array = _mktshr_array[:, :-1] / _aggregate_purchase_prob
 
@@ -404,7 +404,7 @@ def gen_market_shares_dirichlet(
 
 
 def gen_divr_array(
-    _recapture_form: RECTypes,
+    _recapture_form: RECForm,
     _recapture_rate: float | None,
     _frmshr_array: ArrayDouble,
     _aggregate_purchase_prob: ArrayDouble = EMPTY_ARRAY_DEFAULT,
@@ -413,7 +413,7 @@ def gen_divr_array(
     """
     Given merging-firm shares and related parameters, return diverion ratios.
 
-    If recapture is specified as :attr:`mergeron.RECTypes.OUTIN`, then the
+    If recapture is specified as :attr:`mergeron.RECForm.OUTIN`, then the
     choice-probability for the outside good must be supplied.
 
     Parameters
@@ -445,7 +445,7 @@ def gen_divr_array(
     """
 
     _divr_array: ArrayDouble
-    if _recapture_form == RECTypes.FIXED:
+    if _recapture_form == RECForm.FIXED:
         _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
 
     else:
@@ -475,7 +475,7 @@ def gen_margin_price_data(
     _aggregate_purchase_prob: ArrayDouble,
     _pcm_spec: PCMSpec,
     _price_spec: PriceSpec,
-    _hsr_filing_test_type: SSZConstants,
+    _hsr_filing_test_type: SSZConstant,
     _pcm_rng_seed_seq: SeedSequence,
     _pr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
@@ -505,7 +505,7 @@ def gen_margin_price_data(
 
     _hsr_filing_test_type
         Enum specifying restriction, if any, to impose on market data sample
-        to model HSR filing requirements; see :class:`mergeron.gen.SSZConstants`.
+        to model HSR filing requirements; see :class:`mergeron.gen.SSZConstant`.
 
     _pcm_rng_seed_seq
         Seed sequence for generating margin data.
@@ -552,7 +552,7 @@ def gen_margin_price_data(
             # generate the margin data
             # generate price and margin data
             _frmshr_array_plus = np.hstack((_frmshr_array, _nth_firm_share))
-            _pcm_spec_here = evolve(_pcm_spec, firm2_pcm_constraint=FM2Constants.IID)
+            _pcm_spec_here = evolve(_pcm_spec, firm2_pcm_constraint=FM2Constraint.IID)
             _margin_data = _gen_margin_data(
                 _frmshr_array_plus,
                 np.ones_like(_frmshr_array_plus, np.float64),
@@ -569,7 +569,7 @@ def gen_margin_price_data(
             _price_array_here = 1 / (1 - _pcm_array)
             _price_array = _price_array_here[:, :2]
             _nth_firm_price = _price_array_here[:, [-1]]
-            if _pcm_spec.firm2_pcm_constraint == FM2Constants.MNL:
+            if _pcm_spec.firm2_pcm_constraint == FM2Constraint.MNL:
                 # Generate i.i.d. PCMs then take PCM0 and construct PCM1
                 # Regenerate MNL test
                 _purchase_prob_array = _aggregate_purchase_prob * _frmshr_array
@@ -616,7 +616,7 @@ def gen_margin_price_data(
     _test_rev_ratio, _test_rev_ratio_inv = 10, 1 / 10
 
     match _hsr_filing_test_type:
-        case SSZConstants.HSR_TEN:
+        case SSZConstant.HSR_TEN:
             # See, https://www.ftc.gov/enforcement/premerger-notification-program/
             #   -> Procedures For Submitting Post-Consummation Filings
             #    -> Key Elements to Determine Whether a Post Consummation Filing is Required
@@ -627,7 +627,7 @@ def gen_margin_price_data(
             _rev_ratio = (_rev_array.min(axis=1) / _rev_array.max(axis=1)).round(4)
             _hsr_filing_test = _rev_ratio >= _test_rev_ratio_inv
             # del _rev_array, _rev_ratio
-        case SSZConstants.HSR_NTH:
+        case SSZConstant.HSR_NTH:
             # To get around the 10-to-1 ratio restriction, specify that the nth firm test:
             # if the smaller merging firm matches or exceeds the n-th firm in size, and
             # the larger merging firm has at least 10 times the size of the nth firm,
@@ -642,12 +642,15 @@ def gen_margin_price_data(
                     dtype=np.int64,
                 )
                 == _rev_ratio_to_nth.shape[1]
-            ) | (_frmshr_array.min(axis=1) >= _test_rev_ratio_inv)
+            )
 
             # del _nth_firm_rev, _rev_ratio_to_nth
         case _:
             # Otherwise, all draws meet the filing test
             _hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
+    _hsr_filing_test = _hsr_filing_test | (
+        _frmshr_array.min(axis=1) >= _test_rev_ratio_inv
+    )
 
     return _margin_data, PriceDataSample(_price_array, _hsr_filing_test)
 
@@ -669,28 +672,28 @@ def _gen_margin_data(
     _dist_type: Literal["Beta", "Uniform"]
     _pcm_array = (
         np.empty((len(_frmshr_array), 1), dtype=np.float64)
-        if _pcm_spec.firm2_pcm_constraint == FM2Constants.SYM
+        if _pcm_spec.firm2_pcm_constraint == FM2Constraint.SYM
         else np.empty_like(_frmshr_array, dtype=np.float64)
     )
 
     _beta_min, _beta_max = [None] * 2  # placeholder
-    if _dist_type_pcm == PCMDistributions.EMPR:
+    if _dist_type_pcm == PCMDistribution.EMPR:
         _pcm_array = mgn_data_resampler(
             _pcm_array.shape,  # type: ignore
             seed_sequence=_pcm_rng_seed_seq,
         )
     else:
-        _dist_type = "Uniform" if _dist_type_pcm == PCMDistributions.UNI else "Beta"
-        if _dist_type_pcm == PCMDistributions.BETA:
+        _dist_type = "Uniform" if _dist_type_pcm == PCMDistribution.UNI else "Beta"
+        if _dist_type_pcm == PCMDistribution.BETA:
             if _dist_parms_pcm is None:
                 _dist_parms_pcm = np.ones(2, np.float64)
 
-        elif _dist_type_pcm == PCMDistributions.BETA_BND:  # Bounded beta
+        elif _dist_type_pcm == PCMDistribution.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 == PCMDistributions.UNI
+            #  _dist_type_pcm == PCMDistribution.UNI
             _dist_parms = (
                 DIST_PARMS_DEFAULT if _dist_parms_pcm is None else _dist_parms_pcm
             )
@@ -705,20 +708,20 @@ def _gen_margin_data(
         _pcm_rng.fill()
         del _pcm_rng
 
-    if _dist_type_pcm == PCMDistributions.BETA_BND:
+    if _dist_type_pcm == PCMDistribution.BETA_BND:
         _beta_min, _beta_max = _dist_parms_pcm[2:]
         _pcm_array = (_beta_max - _beta_min) * _pcm_array + _beta_min
         del _beta_min, _beta_max
 
-    if _dist_firm2_pcm == FM2Constants.SYM:
+    if _dist_firm2_pcm == FM2Constraint.SYM:
         _pcm_array = np.column_stack((_pcm_array,) * _frmshr_array.shape[1])
-    if _dist_firm2_pcm == FM2Constants.MNL:
+    if _dist_firm2_pcm == FM2Constraint.MNL:
         # Impose FOCs from profit-maximization with MNL demand
-        if _dist_type_pcm == PCMDistributions.EMPR:
+        if _dist_type_pcm == PCMDistribution.EMPR:
             print(
                 "NOTE: Estimated Firm 2 parameters will not be consistent with "
                 "the empirical distribution of margins in the source data. For "
-                "consistency, respecify pcm_spec.firm2_pcm_constraint = FM2Constants.IID."
+                "consistency, respecify pcm_spec.firm2_pcm_constraint = FM2Constraint.IID."
             )
         _purchase_prob_array = _aggregate_purchase_prob * _frmshr_array
 
@@ -800,7 +803,7 @@ def beta_located_bound(_dist_parms: ArrayDouble, /) -> ArrayDouble:
 
 def parse_seed_seq_list(
     _sseq_list: Sequence[SeedSequence] | None,
-    _mktshr_dist_type: SHRDistributions,
+    _mktshr_dist_type: SHRDistribution,
     _price_spec: PriceSpec,
     /,
 ) -> SeedSequenceData:
@@ -841,7 +844,7 @@ def parse_seed_seq_list(
             else (None, SeedSequence(pool_size=8))
         )
 
-    _seed_count = 2 if _mktshr_dist_type == SHRDistributions.UNI else 3
+    _seed_count = 2 if _mktshr_dist_type == SHRDistribution.UNI else 3
 
     if _sseq_list:
         if len(_sseq_list) < _seed_count:

mergeron/gen/enforcement_stats.py

@@ -33,7 +33,7 @@ __version__ = VERSION
 
 
 @enum.unique
-class INDGRPConstants(enum.StrEnum):
+class IndustryGroup(enum.StrEnum):
     ALL = "All Markets"
     GRO = "Grocery Markets"
     OIL = "Oil Markets"
@@ -47,7 +47,7 @@ class INDGRPConstants(enum.StrEnum):
 
 
 @enum.unique
-class EVIDENConstants(enum.StrEnum):
+class OtherEvidence(enum.StrEnum):
     HD = "Hot Documents Identified"
     CC = "Strong Customer Complaints"
     NE = "No Entry Evidence"
@@ -236,8 +236,8 @@ ZONE_VALS = np.unique(
 def enf_stats_output(
     _data_array_dict: fid.INVData,
     _data_period: str = "1996-2003",
-    _table_ind_group: INDGRPConstants = INDGRPConstants.ALL,
-    _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
+    _table_ind_group: IndustryGroup = IndustryGroup.ALL,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
     _stats_group: StatsGrpSelector = StatsGrpSelector.FC,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
@@ -293,8 +293,8 @@ def enf_stats_output(
 def enf_stats_listing_by_group(
     _invdata_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
     _study_period: str,
-    _table_ind_grp: INDGRPConstants,
-    _table_evid_cond: EVIDENConstants,
+    _table_ind_grp: IndustryGroup,
+    _table_evid_cond: OtherEvidence,
     _stats_group: StatsGrpSelector,
     _enf_spec: INVResolution,
     /,
@@ -329,8 +329,8 @@ def enf_stats_listing_by_group(
 def enf_cnts_listing_byfirmcount(
     _data_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
     _data_period: str = "1996-2003",
-    _table_ind_group: INDGRPConstants = INDGRPConstants.ALL,
-    _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
+    _table_ind_group: IndustryGroup = IndustryGroup.ALL,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
 ) -> ArrayBIGINT:
@@ -365,8 +365,8 @@ def enf_cnts_listing_byfirmcount(
 def enf_cnts_listing_byhhianddelta(
     _data_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
     _data_period: str = "1996-2003",
-    _table_ind_group: INDGRPConstants = INDGRPConstants.ALL,
-    _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
+    _table_ind_group: IndustryGroup = IndustryGroup.ALL,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
 ) -> ArrayBIGINT:
@@ -400,8 +400,8 @@ def enf_cnts_listing_byhhianddelta(
 
 def table_no_lku(
     _data_array_dict_sub: Mapping[str, fid.INVTableData],
-    _table_ind_group: INDGRPConstants = INDGRPConstants.ALL,
-    _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
+    _table_ind_group: IndustryGroup = IndustryGroup.ALL,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
     /,
 ) -> str:
     if _table_ind_group not in (

mergeron/gen/upp_tests.py

@@ -20,7 +20,7 @@ from .. import (  # noqa
     ArrayDouble,
     ArrayFloat,
     ArrayINT,
-    RECTypes,
+    RECForm,
     UPPAggrSelector,
 )
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
@@ -94,24 +94,23 @@ def enf_cnts(
 
     _stats_rowlen = 6
     # Clearance/enforcement counts --- by firm count
-    _firm_counts_list = np.unique(_fcounts)
-    if _firm_counts_list is not None and np.all(_firm_counts_list >= 0):
-        # _max_firm_count = len(_firm_counts_list)
-        _max_firm_count = max(_firm_counts_list)
+    _firmcounts_list = np.unique(_fcounts)
+    if _firmcounts_list is not None and np.all(_firmcounts_list >= 0):
+        _max_firmcount = max(_firmcounts_list)
 
         _enf_cnts_sim_byfirmcount_array = -1 * np.ones(_stats_rowlen, np.int64)
-        for _firm_cnt in 1 + np.arange(1, _max_firm_count):
-            _firm_count_test = _fcounts == _firm_cnt
+        for _firmcount in np.arange(2, _max_firmcount + 1):
+            _firmcount_test = _fcounts == _firmcount
 
             _enf_cnts_sim_byfirmcount_array = np.vstack((
                 _enf_cnts_sim_byfirmcount_array,
                 np.array([
-                    _firm_cnt,
-                    np.einsum("ij->", 1 * _firm_count_test),
+                    _firmcount,
+                    np.einsum("ij->", 1 * _firmcount_test),
                     *[
                         np.einsum(
                             "ij->",
-                            1 * (_firm_count_test & getattr(_upp_test_arrays, _f)),
+                            1 * (_firmcount_test & getattr(_upp_test_arrays, _f)),
                         )
                         for _f in _upp_test_arrays.__dataclass_fields__
                     ],

mergeron-2024.739105.2.dist-info/METADATA

@@ -0,0 +1,115 @@
+Metadata-Version: 2.1
+Name: mergeron
+Version: 2024.739105.2
+Summary: Merger Policy Analysis 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 :: 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: google-re2 (>=1.1)
+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: numpy (>=1.26,<2)
+Requires-Dist: scipy (>=1.12)
+Requires-Dist: sympy (>=1.12)
+Requires-Dist: tables (>=3.8)
+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 using Python
+=============================================
+
+Analyze the sets of mergers conforming to concentration and diversion ratio bounds. Analyze intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions implied by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and 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.
+
+Here, enforcement rates derived with merger enforcement as being exogenous to firm conduct are defined as intrinsic enforcement rates, and similarly intrinsic clearance rates. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement; and, by definition, the observed clearance rate is 1 minus the observed enforcement rate.
+
+Introduction
+------------
+
+Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`..core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`..core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area. This module also includes a function for generating plots of concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+
+Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) estimating enforcement or clearance rates under specified enforcement regimes given a method of aggregating diversion ratio or GUPPI estimates for the firms in a merger (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
+and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
+
+By default, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution, with specified shape parameters (see :code:`.gen.data_generation.MarketSample.ShareSpec`, and, specifically, :code:`.gen.SHRDistribution`). When drawing shares from the Dirichlet distribution, the user passes, using :code:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights`, a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If :code:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.ShareSpec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
+
+Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`.RECForm`. The "inside-out" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) yields diversion ratios from purchase probabilities 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 (see, :code:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`.gen.data_generation.MarketSample.ShareSpec.dist_type`:code:` ==`:code:`.gen.ShareDistributions.UNI`, thus raising a :code:`ValueError` exception. The "proportional" form (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" form. See, for example, Coate (2011).
+
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or an empirical distribution (see, :code:`.gen.PCMSpec`). The empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin (:code:`.gen.data_generation.MarketSample.PCMSpec.firm2_pcm_constraint`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
+
+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 (see, :code:`.gen.PriceSpec`). Prices may also be defined by imposing cost symmetry on firms in the sample, with fixed unit marginal costs normalized to 1 unit, such that price equal :math:`1 / (1 - \pmb{m})`, where :math:`\pmb{m}` represents the array of margins for firms in the sample.
+
+The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the lower HSR size threshold ($10 million, as adjusted) and the larger of the two merging firms meets the size test if it's share is no less than 10 times the share of the smaller firm. In the other, the :math:`n`-th firm's size is maintained as $10 million, as adjusted (see, :code:`.gen.SSZConstant`), and a merger meets the HSR filing test if either, (a.) the smaller merging firm is no smaller than the n-th firm and the larger merging firm is at 10-times as large as the n-th firm, or (b.) the smaller merging firm's market share is in excess of 10%; in effect this version of the test maintains that if the smaller merging firm's market share exceeds 10%, the value of the transaction exceeds $200 million, as adjusted, and the size-of-person test is eliminated (see, FTC (2008, p. 12); the above are simplifications of the statutory HSR filing requirements). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
+
+The full specification of a market sample is given in a :code:`.gen.data_generation.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`.gen.data_generation.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`.gen.data_generation.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`.gen.data_generation.MarketSample.estimate_enf_counts` on a :code:`.gen.data_generation.MarketSample` object without first invoking :code:`.gen.data_generation.MarketSample.generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the performance penalty is slight, but can be considerable if saving to SATA storage).
+
+Enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`.gen.enforcement_stats`.
+
+Programs demonstrating the use of this package are included in the sub-package, :code:`.demo`.
+
+This package includes  a class, :code:`.core.pseudorandom_numbers.MulithreadedRNG` 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. This class is an adaptation from the documentation of the :code:`numpy` package, from the discussion on `multithreaded random-number generation <https://numpy.org/doc/stable/reference/random/multithreading.html>_`; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+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.market_sample as market_sample
+
+    help(market_sample.MarketSample)
+
+.. rubric:: References
+
+.. _coate2011:
+
+Coate, M. B. (2011). Benchmarking the upward pricing pressure model with Federal Trade
+Commission evidence. Journal of Competition Law & Economics, 7(4), 825--846. URL: https://doi.org/10.1093/joclec/nhr014.
+
+.. _ftc_premerger_guide2:
+
+FTC Premerger Notification Office. “To File or Not to File: When You Must File a Premerger Notification Report Form”. 2008 (September, revised). URL: https://www.ftc.gov/sites/default/files/attachments/premerger-introductory-guides/guide2.pdf
+
+
+.. 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.739104.1.dist-info → mergeron-2024.739105.2.dist-info}/RECORD

@@ -1,9 +1,9 @@
 mergeron/License.txt,sha256=7iX-y0EyjkbVJKJLS4ZKzuuE1wd0lryfsD_IytLG8lQ,1246
-mergeron/__init__.py,sha256=MXow5RSpGz49ggTHygQKv5TIJd5iRpTKyQyT9sYGdm4,1455
+mergeron/__init__.py,sha256=-fDaCixxfelCFaf-M1R1psq0eeqYLG5m3YlXNbwgqoM,1454
 mergeron/core/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/core/damodaran_margin_data.py,sha256=rMrgN1Qtw572a0ftY97OOj4otq8ldlLrcOi-bcE-org,8554
 mergeron/core/ftc_merger_investigations_data.py,sha256=qGAjjXEyqwS1PKKxvJGsSkr0sfI--4oyLss9I1qCNR4,28247
-mergeron/core/guidelines_boundaries.py,sha256=Iu7MBg3WzaRUALOobNmzmv_g7l-Njk1k7Y-esLBZBbk,15541
+mergeron/core/guidelines_boundaries.py,sha256=EQ-T-Q94xKhGFp0Y5xheLUS4gptmyRInXfOEaeMHTAA,15530
 mergeron/core/guidelines_boundary_functions.py,sha256=gohb7Uj1AjJQtD5ew7bVZZjGhJEYCjNNAPB1o6TsA9M,29683
 mergeron/core/guidelines_boundary_functions_extra.py,sha256=t84dMsaMKnYUNuvvGrMCP6vI8MDn88PJOgGZlNe1Zts,11280
 mergeron/core/pseudorandom_numbers.py,sha256=cJEWDTfy9CUTzR_di6Fm1Vl1Le6xWoU8wFHbYVMEuLI,9225
@@ -20,12 +20,12 @@ mergeron/data/jinja2_LaTeX_templates/mergeron_table_collection_template.tex.jinj
 mergeron/data/jinja2_LaTeX_templates/setup_tikz_tables.tex,sha256=1hw3RINDtBrh9ZEToMIiNFIu9rozcPwRly69-5O_0UQ,3207
 mergeron/demo/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/demo/visualize_empirical_margin_distribution.py,sha256=v1xFJumBX2Ooye82kSSgly-_GpFVkYSDqBwM__rcmZY,2363
-mergeron/gen/__init__.py,sha256=A-co8RQL-QTsgfErF2O6qC3zcYYR56F6m9PBjH_M1kk,16564
-mergeron/gen/data_generation.py,sha256=_sjFm426uIj0MkoMIWQyL8hq3P4XbBIKe0kMUy7aVps,16449
-mergeron/gen/data_generation_functions.py,sha256=Pglv9rzeb2mG1SKp01AtkILJdvggDQvDnK-u90019po,28505
-mergeron/gen/enforcement_stats.py,sha256=ANnviFnoSUAwZOM5cMG1WrZwbkjuUohplRn5fQmd8Bs,27410
-mergeron/gen/upp_tests.py,sha256=iDtfy-lc7uSnBK37f_AxDIz3mO7Gf7-G5tHbX3QRDI0,12647
+mergeron/gen/__init__.py,sha256=bAimsNd7c8lQBBxzSiXyQXXxNRH-wHUe39l1aS1-EkE,16541
+mergeron/gen/data_generation.py,sha256=yEoBYjO6NnGiMEy8QQg1DcbS4E5ytcPNUBONDuzjNns,16720
+mergeron/gen/data_generation_functions.py,sha256=8vWDlmJjvRkBbMC_JQVyc5AVsr3Urvkvi2pVvk4hukc,28531
+mergeron/gen/enforcement_stats.py,sha256=4YQYOeU3dqrOLejhK4chGZMO9ZoID9ZiJZ1V95eSboQ,27370
+mergeron/gen/upp_tests.py,sha256=yzEwWK1bVfjtBYMwXnL5uEWWRiR0_9y0wmjNMB-O3rU,12589
 mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-mergeron-2024.739104.1.dist-info/METADATA,sha256=A4K7HcIzkIoT7KUmlNOqUic42V1psF1kxNgtIih5l68,10922
-mergeron-2024.739104.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-mergeron-2024.739104.1.dist-info/RECORD,,
+mergeron-2024.739105.2.dist-info/METADATA,sha256=kCnvZdz_tS8xmbuVO7KDhSoQDVU-wqGFav1zicjyUcE,13911
+mergeron-2024.739105.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+mergeron-2024.739105.2.dist-info/RECORD,,

mergeron-2024.739104.1.dist-info/METADATA

@@ -1,102 +0,0 @@
-Metadata-Version: 2.1
-Name: mergeron
-Version: 2024.739104.1
-Summary: Merger Policy Analysis 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 :: 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: google-re2 (>=1.1)
-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: numpy (>=1.26,<2)
-Requires-Dist: scipy (>=1.12)
-Requires-Dist: sympy (>=1.12)
-Requires-Dist: tables (>=3.8)
-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 using Python
-=============================================
-
-Analyze the sets of mergers conforming to concentration and diversion ratio bounds. Analyze intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions implied by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and 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.
-
-Here, enforcement rates derived with merger enforcement as being exogenous to firm conduct are defined as intrinsic enforcement rates, and similarly intrinsic clearance rates. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement; and, by definition, the observed clearance rate is 1 minus the observed enforcement rate.
-
-Introduction
-------------
-
-Module :code:`mergeron.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`mergeron.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`mergeron.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area. This module also includes a function for generating plots of concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
-
-Module :code:`mergeron.gen.market_sample` includes the :code:`mergeron.gen.market_sample.MarketSample` with methods for, (i) generating sample data under a rich specification of shares, diversion ratios, margins, prices, and HSR filing requirements, and (ii) for estimating enforcement or clearance rates under specified enforcement regimes given a method of aggregating diversion ratio or GUPPI estimates for the firms in a merger. Notably. share are generated not just for markets with a fixed number of firms, but for markets with multiple firm-count weights, which may be left unspecified or explicitly specified.
-
-Unless otherwise specified, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution, with specified shape parameters (see :code:`mergeron.gen.ShareConstants`. When drawing shares from the Dirichlet distribution, the user passes, using :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights`, a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights` is not assigned a value when defining :code:`mergeron.gen.MarketSpec.ShareSpec` (which has type, :code:`mergeron.gen.ShareSpec`), the default values is used, with results in a sample of markets with 2 to 6 firms with equal relative frequency.
-
-Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`mergeron.RECConstants`. The "inside-out" specification results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification yields diversion ratios from purchase probabilities 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 (see, :code:`mergeron.gen.DiversionRatioSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`mergeron.gen.MarketSpec.ShareSpec.dist_type ==`:code:`mergeron.gen.ShareConstants.UNI`.
-
-Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or an empirical distribution. The empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (see, :code:`mergeron.gen.PCMSpec`).
-
-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 (see, :code:`mergeron.gen.PriceSpec`).
-
-The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the HSR filing threshold for the smaller (acquired) firm. In the other, the :math:`n`-th firm's size matches the size requirement for the smaller merging firm (see, :code:`mergeron.gen.SSZConstants`). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
-
-The full specification of a market sample is given in a :code:`mergeron.gen.market_sample.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`mergeron.gen.market_sample.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`mergeron.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`mergeron.gen.market_sample.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`mergeron.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`estimate_enf_counts` on a :code:`mergeron.gen.market_sample.MarketSample` object without first invoking :code:`generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the performance penalty is slight, but can be considerable if saving to SATA storage).
-
-Enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.enforcement_stats`.
-
-Programs demonstrating the use of this package are included in the sub-package, :code:`mergeron.demo`.
-
-This package includes  a class, :code:`mergeron.core.pseudorandom_numbers.MulithreadedRNG` 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. This class is an adaptation from the documentation of the :code:`numpy` package, from the discussion on `multithreaded random-number generation <https://numpy.org/doc/stable/reference/random/multithreading.html>_`; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
-
-.. code-block:: python
-
-    import mergeron.core.pseudorandom_numbers as prng
-
-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.market_sample as market_sample
-
-    help(market_sample.MarketSample)
-
-.. 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
-
-