mergeron 2025.739319.2__py3-none-any.whl → 2025.739341.8__py3-none-any.whl

mergeron/gen/data_generation_functions.py

@@ -1,6 +1,4 @@
-"""
-Non-public functions called in data_generation.py
-"""
+"""Non-public functions called in data_generation.py."""
 
 from __future__ import annotations
 
@@ -28,13 +26,13 @@ from ..core.pseudorandom_numbers import (  # noqa: TID252
 from . import (
     DEFAULT_BETA_BND_DIST_PARMS,
     DEFAULT_FCOUNT_WTS,
-    PCMRestriction,
-    MarginDataSample,
+    MarginSampleData,
     PCMDistribution,
+    PCMRestriction,
     PCMSpec,
-    PriceDataSample,
+    PriceSampleData,
     PriceSpec,
-    ShareDataSample,
+    ShareSampleData,
     ShareSpec,
     SHRDistribution,
     SSZConstant,
@@ -50,8 +48,8 @@ def gen_share_data(
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int,
     /,
-) -> ShareDataSample:
-    """Helper function for generating share data.
+) -> ShareSampleData:
+    """Generate share data.
 
     Parameters
     ----------
@@ -66,10 +64,9 @@ def gen_share_data(
 
     Returns
     -------
-        Arrays representing shares, diversion ratios, etc. structured as a :ShareDataSample:
+        Arrays representing shares, diversion ratios, etc. structured as a :ShareSampleData:
 
     """
-
     dist_type_mktshr, firm_count_prob_wts, dist_parms_mktshr, recapture_form = (
         getattr(_share_spec, _f)
         for _f in ("dist_type", "firm_counts_weights", "dist_parms", "recapture_form")
@@ -101,7 +98,7 @@ def gen_share_data(
     frmshr_array = mkt_share_sample.mktshr_array[:, :2]
     r_bar_ = _share_spec.recapture_ratio or DEFAULT_REC_RATIO
     if recapture_form == RECForm.INOUT:
-        mkt_share_sample = ShareDataSample(
+        mkt_share_sample = ShareSampleData(
             mkt_share_sample.mktshr_array,
             mkt_share_sample.fcounts,
             mkt_share_sample.nth_firm_share,
@@ -117,7 +114,7 @@ def gen_market_shares_uniform(
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int,
     /,
-) -> ShareDataSample:
+) -> ShareSampleData:
     """Generate merging-firm shares from Uniform distribution on the 3-D simplex.
 
     Parameters
@@ -136,7 +133,6 @@ def gen_market_shares_uniform(
         market shares and other market statistics for each draw (market)
 
     """
-
     frmshr_array: ArrayDouble = np.empty((_s_size, 2), float)
 
     MultithreadedRNG(
@@ -170,7 +166,7 @@ def gen_market_shares_uniform(
     nth_firm_share_.fill(np.nan)
     aggregate_purchase_prob_.fill(np.nan)
 
-    return ShareDataSample(
+    return ShareSampleData(
         mktshr_array_, fcounts_, nth_firm_share_, aggregate_purchase_prob_
     )
 
@@ -185,7 +181,7 @@ def _gen_market_shares_dirichlet_multimarket(
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int = NTHREADS,
     /,
-) -> ShareDataSample:
+) -> ShareSampleData:
     """Dirichlet-distributed shares with multiple firm-counts.
 
     Firm-counts may be specified as having Uniform distribution over the range
@@ -221,7 +217,6 @@ def _gen_market_shares_dirichlet_multimarket(
         array of market shares and other market statistics
 
     """
-
     _firm_count_wts = (
         DEFAULT_FCOUNT_WTS
         if _firm_count_wts is None or not len(_firm_count_wts)
@@ -310,7 +305,7 @@ def _gen_market_shares_dirichlet_multimarket(
             )
         )
 
-    return ShareDataSample(
+    return ShareSampleData(
         mktshr_array_, fcounts_, nth_firm_share_, aggregate_purchase_prob_
     )
 
@@ -322,7 +317,7 @@ def gen_market_shares_dirichlet(
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int,
     /,
-) -> ShareDataSample:
+) -> ShareSampleData:
     """Dirichlet-distributed shares with fixed firm-count.
 
     Parameters
@@ -349,7 +344,6 @@ def gen_market_shares_dirichlet(
         array of market shares and other market statistics
 
     """
-
     if not isinstance(_dir_alphas, np.ndarray):
         _dir_alphas = np.array(_dir_alphas)
 
@@ -394,7 +388,7 @@ def gen_market_shares_dirichlet(
         aggregate_purchase_prob_ = 1 - mktshr_array[:, [-1]]  # type: ignore
         mktshr_array = mktshr_array[:, :-1] / aggregate_purchase_prob_
 
-    return ShareDataSample(
+    return ShareSampleData(
         mktshr_array,
         (mktshr_array.shape[-1] * np.ones((_s_size, 1))).astype(np.int64),
         mktshr_array[:, [-1]],
@@ -410,7 +404,7 @@ def gen_divr_array(
     /,
 ) -> ArrayDouble:
     """
-    Given merging-firm shares and related parameters, return diverion ratios.
+    Given merging-firm shares and related parameters, return diversion ratios.
 
     If recapture is specified as :attr:`mergeron.RECForm.OUTIN`, then the
     choice-probability for the outside good must be supplied.
@@ -442,7 +436,6 @@ def gen_divr_array(
         Merging-firm diversion ratios for mergers in the sample.
 
     """
-
     divr_array: ArrayDouble
     if _recapture_form == RECForm.FIXED:
         divr_array = _recapture_ratio * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
@@ -468,7 +461,7 @@ def gen_divr_array(
     return divr_array
 
 
-def gen_margin_price_data(  # noqa: PLR0914
+def gen_margin_price_data(
     _frmshr_array: ArrayDouble,
     _nth_firm_share: ArrayDouble,
     _aggregate_purchase_prob: ArrayDouble,
@@ -479,7 +472,7 @@ def gen_margin_price_data(  # noqa: PLR0914
     _pr_rng_seed_seq: SeedSequence | None,
     _nthreads: int,
     /,
-) -> tuple[MarginDataSample, PriceDataSample]:
+) -> tuple[MarginSampleData, PriceSampleData]:
     """Generate margin and price data for mergers in the sample.
 
     Parameters
@@ -519,8 +512,7 @@ def gen_margin_price_data(  # noqa: PLR0914
     -------
         Simulated margin- and price-data arrays for mergers in the sample.
     """
-
-    margin_data = MarginDataSample(
+    margin_data = MarginSampleData(
         np.empty_like(_frmshr_array), np.ones(len(_frmshr_array)) == 0
     )
 
@@ -590,7 +582,7 @@ def gen_margin_price_data(  # noqa: PLR0914
                 )
                 mnl_test_array = (pcm_array[:, [1]] >= 0) & (pcm_array[:, [1]] <= 1)
 
-            margin_data = MarginDataSample(pcm_array[:, :2], mnl_test_array)
+            margin_data = MarginSampleData(pcm_array[:, :2], mnl_test_array)
             del price_array_here
         case _:
             raise ValueError(
@@ -649,11 +641,11 @@ def gen_margin_price_data(  # noqa: PLR0914
             # Otherwise, all draws meet the filing test
             hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
 
-    # Assume that if minimum mergeing-firm share is 10%, merger filing required
+    # Assume that if minimum merging-firm share is 10%, merger filing required
     # under value-of-transactions test or merger triggers post-consummation review
     hsr_filing_test |= _frmshr_array.min(axis=1) >= test_rev_ratio_inv
 
-    return margin_data, PriceDataSample(price_array, hsr_filing_test)
+    return margin_data, PriceSampleData(price_array, hsr_filing_test)
 
 
 def _gen_margin_data(
@@ -664,10 +656,9 @@ def _gen_margin_data(
     _pcm_rng_seed_seq: SeedSequence,
     _nthreads: int,
     /,
-) -> MarginDataSample:
-    dist_type_pcm, dist_parms_pcm, dist_firm2_pcm = (
-        getattr(_pcm_spec, _f)
-        for _f in ("dist_type", "dist_parms", "pcm_restriction")
+) -> MarginSampleData:
+    dist_type_pcm, dist_parms_pcm, pcm_restriction_ = (
+        getattr(_pcm_spec, _f) for _f in ("dist_type", "dist_parms", "pcm_restriction")
     )
 
     pcm_array = (
@@ -680,7 +671,10 @@ def _gen_margin_data(
     beta_min, beta_max = [0.0] * 2  # placeholder
     if dist_type_pcm == PCMDistribution.EMPR:
         pcm_array = margin_data_resampler(
-            dist_parms_pcm, sample_size=pcm_array.shape, seed_sequence=_pcm_rng_seed_seq, nthreads=_nthreads
+            dist_parms_pcm,
+            sample_size=pcm_array.shape,
+            seed_sequence=_pcm_rng_seed_seq,
+            nthreads=_nthreads,
         )
     else:
         dist_type_: Literal["Beta", "Uniform"]
@@ -721,16 +715,10 @@ def _gen_margin_data(
         pcm_array = (beta_max - beta_min) * pcm_array + beta_min
         del beta_min, beta_max
 
-    if dist_firm2_pcm == PCMRestriction.SYM:
+    if pcm_restriction_ == PCMRestriction.SYM:
         pcm_array = np.hstack((pcm_array,) * _frmshr_array.shape[1])
-    if dist_firm2_pcm == PCMRestriction.MNL:
+    if pcm_restriction_ == PCMRestriction.MNL:
         # Impose FOCs from profit-maximization with MNL demand
-        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.pcm_restriction = PCMRestriction.IID."
-            )
         purchase_prob_array = _aggregate_purchase_prob * _frmshr_array
 
         pcm_array[:, [1]] = np.divide(
@@ -749,14 +737,14 @@ def _gen_margin_data(
     else:
         mnl_test_array = np.ones(len(pcm_array), dtype=bool)
 
-    return MarginDataSample(pcm_array, mnl_test_array)
+    return MarginSampleData(pcm_array, mnl_test_array)
 
 
 def _beta_located(
     _mu: float | ArrayDouble, _sigma: float | ArrayDouble, /
 ) -> ArrayDouble:
     """
-    Given mean and stddev, return shape parameters for corresponding Beta distribution
+    Given mean and stddev, return shape parameters for corresponding Beta distribution.
 
     Solve the first two moments of the standard Beta to get the shape parameters.
 
@@ -772,20 +760,18 @@ def _beta_located(
         shape parameters for Beta distribution
 
     """
-
     mul = -1 + _mu * (1 - _mu) / _sigma**2
     return np.array([_mu * mul, (1 - _mu) * mul], float)
 
 
 def beta_located_bound(_dist_parms: ArrayDouble, /) -> ArrayDouble:
     R"""
-    Return shape parameters for a non-standard beta, given the mean, stddev, range
-
+    Return shape parameters for a non-standard beta, given mean, stddev, and range.
 
     Recover the r.v.s as
     :math:`\min + (\max - \min) \cdot \symup{Β}(a, b)`,
     with `a` and `b` calculated from the specified mean (:math:`\mu`) and
-    variance (:math:`\sigma`). [8]_
+    variance (:math:`\sigma`). [#]_
 
     Parameters
     ----------
@@ -802,8 +788,7 @@ def beta_located_bound(_dist_parms: ArrayDouble, /) -> ArrayDouble:
 
     References
     ----------
-    .. [8] NIST, Beta Distribution. https://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm
+    .. [#] NIST, Beta Distribution. https://www.itl.nist.gov/div898/handbook/eda/section3/eda366h.htm
     """  # noqa: RUF002
-
     bmu, bsigma, bmin, bmax = _dist_parms
     return _beta_located((bmu - bmin) / (bmax - bmin), bsigma / (bmax - bmin))

mergeron/gen/enforcement_stats.py

@@ -1,7 +1,4 @@
-"""
-Methods to format and print summary statistics on merger enforcement patterns.
-
-"""
+"""Methods to format and print summary statistics on merger enforcement patterns."""
 
 import enum
 from collections.abc import Mapping
@@ -19,6 +16,8 @@ __version__ = VERSION
 @this_yaml.register_class
 @enum.unique
 class IndustryGroup(str, Enameled):
+    """Industry group of reported markets."""
+
     ALL = "All Markets"
     GRO = "Grocery Markets"
     OIL = "Oil Markets"
@@ -34,21 +33,25 @@ class IndustryGroup(str, Enameled):
 @this_yaml.register_class
 @enum.unique
 class OtherEvidence(str, Enameled):
-    UR = "Unrestricted on additional evidence"
-    HD = "Hot Documents Identified"
-    HN = "No Hot Documents Identified"
-    HU = "No Evidence on Hot Documents"
-    CN = "No Strong Customer Complaints"
-    CS = "Strong Customer Complaints"
-    CU = "No Evidence on Customer Complaints"
-    ED = "Entry Difficult"
-    EE = "Entry Easy"
-    NE = "No Entry Evidence"
+    """Additional evidence available, if any, for reported markets."""
+
+    HOT = "Hot Documents Identified"
+    NHT = "No Hot Documents Identified"
+    HTU = "No Evidence on Hot Documents"
+    NCC = "No Strong Customer Complaints"
+    SCC = "Strong Customer Complaints"
+    CCU = "No Evidence on Customer Complaints"
+    END = "Entry Difficult"
+    EEY = "Entry Easy"
+    EEU = "No Entry Evidence"
+    UNR = "Unrestricted on additional evidence"
 
 
 @this_yaml.register_class
 @enum.unique
 class StatsGrpSelector(str, Enameled):
+    """Measure used to summarize investigations data."""
+
     FC = "ByFirmCount"
     HD = "ByHHIandDelta"
     DL = "ByDelta"
@@ -58,6 +61,8 @@ class StatsGrpSelector(str, Enameled):
 @this_yaml.register_class
 @enum.unique
 class StatsReturnSelector(str, Enameled):
+    """Statistics to report on investigations data."""
+
     CNT = "count"
     RPT = "rate, point"
     RIN = "rate, interval"
@@ -66,6 +71,8 @@ class StatsReturnSelector(str, Enameled):
 @this_yaml.register_class
 @enum.unique
 class SortSelector(str, Enameled):
+    """Sort order for reporting investigations data."""
+
     UCH = "unchanged"
     REV = "reversed"
 
@@ -128,7 +135,7 @@ ZONE_DETAIL_STRINGS_DELTA = {
 
 
 def enf_cnts_obs_by_group(
-    _invdata_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
+    _invdata_array_dict: fid.INVData,
     _study_period: str,
     _table_ind_grp: IndustryGroup,
     _table_evid_cond: OtherEvidence,
@@ -136,6 +143,28 @@ def enf_cnts_obs_by_group(
     _enf_spec: INVResolution,
     /,
 ) -> ArrayBIGINT:
+    """Summarize investigations data by reporting group.
+
+    Parameters
+    ----------
+    _invdata_array_dict
+        raw investigations data
+    _study_period
+        study period
+    _table_ind_grp
+        industry group
+    _table_evid_cond
+        additional evidence
+    _stats_group
+        grouping measure
+    _enf_spec
+        enforcement specification (see, :class:`mergeron.gen.INVResolution`)
+
+    Returns
+    -------
+    ArrayBIGINT
+        Counts of markets resolved as enforced, cleared, or both, respectively.
+    """
     if _stats_group == StatsGrpSelector.HD:
         raise ValueError(
             f"Clearance/enforcement statistics, '{_stats_group}' not valied here."
@@ -164,13 +193,34 @@ def enf_cnts_obs_by_group(
 
 
 def enf_cnts_obs_byfirmcount(
-    _data_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
+    _data_array_dict: fid.INVData,
     _data_period: str = "1996-2003",
     _table_ind_group: IndustryGroup = IndustryGroup.ALL,
-    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
-    _enf_spec: INVResolution = INVResolution.CLRN,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UNR,
+    _enf_spec: INVResolution = INVResolution.ENFT,
     /,
 ) -> ArrayBIGINT:
+    """Summarize investigations data by firm count.
+
+    Parameters
+    ----------
+    _data_array_dict
+        raw investigations data
+    _data_period
+        data period
+    _table_ind_group
+        industry group
+    _table_evid_cond
+        additional evidence
+    _enf_spec
+        enforcement specification (see, :class:`mergeron.gen.INVResolution`)
+
+    Returns
+    -------
+    ArrayBIGINT
+        Counts of markets resolved as enforced, cleared, or both, respectively,
+        reported by number of pre-merger firms.
+    """
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -197,13 +247,34 @@ def enf_cnts_obs_byfirmcount(
 
 
 def enf_cnts_obs_byhhianddelta(
-    _data_array_dict: Mapping[str, Mapping[str, Mapping[str, fid.INVTableData]]],
+    _data_array_dict: fid.INVData,
     _data_period: str = "1996-2003",
     _table_ind_group: IndustryGroup = IndustryGroup.ALL,
-    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
-    _enf_spec: INVResolution = INVResolution.CLRN,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UNR,
+    _enf_spec: INVResolution = INVResolution.ENFT,
     /,
 ) -> ArrayBIGINT:
+    """Summarize investigations data by HHI and ΔHHI.
+
+    Parameters
+    ----------
+    _data_array_dict
+        raw investigations data
+    _data_period
+        data period
+    _table_ind_group
+        industry group
+    _table_evid_cond
+        additional evidence
+    _enf_spec
+        enforcement specification (see, :class:`mergeron.gen.INVResolution`)
+
+    Returns
+    -------
+    ArrayBIGINT
+        Counts of markets resolved as enforced, cleared, or both, respectively,
+        reported by HHI and ΔHHI.
+    """
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -232,9 +303,19 @@ def enf_cnts_obs_byhhianddelta(
 def table_no_lku(
     _data_array_dict_sub: Mapping[str, fid.INVTableData],
     _table_ind_group: IndustryGroup = IndustryGroup.ALL,
-    _table_evid_cond: OtherEvidence = OtherEvidence.UR,
+    _table_evid_cond: OtherEvidence = OtherEvidence.UNR,
     /,
 ) -> str:
+    """Lookup table number based on industry group and additional evidence."""
+    if _table_evid_cond not in (
+        _egl := [
+            _data_array_dict_sub[_v].additional_evidence for _v in _data_array_dict_sub
+        ]
+    ):
+        raise ValueError(
+            f"Invalid value for additional evidence, {f'"{_table_evid_cond}"'}."
+            f"Must be one of {_egl!r}"
+        )
     if _table_ind_group not in (
         _igl := [_data_array_dict_sub[_v].industry_group for _v in _data_array_dict_sub]
     ):
@@ -256,6 +337,18 @@ def table_no_lku(
 
 
 def enf_cnts_byfirmcount(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
+    """Summarize investigations data by firm count.
+
+    Parameters
+    ----------
+    _cnts_array
+        raw investigations data array
+
+    Returns
+    -------
+    ArrayBIGINT
+        Subtotals for columns other than the first, grouped by the first column.
+    """
     if not _cnts_array[:, 0].any():
         return np.array([], int)
 
@@ -272,6 +365,20 @@ def enf_cnts_byfirmcount(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
 
 
 def enf_cnts_bydelta(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
+    """Summarize investigations data by ΔHHI.
+
+    Parameters
+    ----------
+    _cnts_array
+        raw investigations data array
+
+    Returns
+    -------
+    ArrayBIGINT
+        Subtotals for columns higher than the second, grouped by the second column.
+    """
+    if not _cnts_array[:, 1].any():
+        return np.array([], int)
     ndim_in = 2
     return np.vstack([
         np.concatenate([
@@ -285,9 +392,23 @@ def enf_cnts_bydelta(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
 
 
 def enf_cnts_byconczone(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
+    """Summarize investigations data by concentration zone, as defined in the Guidelines.
+
+    Includes sub-total detail for "Moderately Concentrated" and "Unconcentrated" markets.
+
+    Parameters
+    ----------
+    _cnts_array
+        raw investigations data array
+
+    Returns
+    -------
+    ArrayBIGINT
+        Subtotals range of HHI and ΔHHI, with detail
+    """
     if not _cnts_array[:, 0].any() or np.isnan(_cnts_array[:, 0]).all():
         return np.array([], int)
-    # Step 1: Tag and agg. from HHI-post and Delta to zone triple
+    # Step 1: Tag and agg. from HHI-post and ΔHHI to zone triple
     # NOTE: Although you could just map and not (partially) aggregate in this step,
     # the mapped array is a copy, and is larger without partial aggregation, so
     # aggregation reduces the footprint of this step in memory. Although this point
@@ -335,10 +456,13 @@ def enf_cnts_byconczone(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
         # Logical-and of multiple vectors:
         hhi_zone_test = (
             1
-            * np.stack([
-                cnts_byhhipostanddelta[:, _idx] == _val
-                for _idx, _val in enumerate(zone_val)
-            ], axis=1)
+            * np.stack(
+                [
+                    cnts_byhhipostanddelta[:, _idx] == _val
+                    for _idx, _val in enumerate(zone_val)
+                ],
+                axis=1,
+            )
         ).prod(axis=1) == 1
 
         cnts_byconczone = np.vstack((

mergeron/gen/upp_tests.py

@@ -1,8 +1,4 @@
-"""
-Methods to compute intrinsic clearance rates and intrinsic enforcement rates
-from generated market data.
-
-"""
+"""Methods to compute intrinsic enforcement/clearance rates from generated market data."""
 
 from collections.abc import Sequence
 from typing import TypedDict
@@ -28,20 +24,20 @@ __version__ = VERSION
 
 
 class INVRESCntsArgs(TypedDict, total=False):
-    "Keyword arguments of function, :code:`sim_enf_cnts`"
+    """Keyword arguments of function, :code:`sim_enf_cnts`."""
 
     sample_size: int
     seed_seq_list: Sequence[SeedSequence] | None
     nthreads: int
 
 
-def compute_upp_test_counts(  # noqa: PLR0914
+def compute_upp_test_counts(
     _market_data_sample: MarketSampleData,
     _upp_test_parms: gbl.HMGThresholds,
     _upp_test_regime: UPPTestRegime,
     /,
 ) -> UPPTestsCounts:
-    """Estimate enforcement and clearance counts from market data sample
+    """Estimate enforcement and clearance counts from market data sample.
 
     Parameters
     ----------
@@ -64,7 +60,6 @@ def compute_upp_test_counts(  # noqa: PLR0914
         Enforced and cleared counts
 
     """
-
     g_bar_, divr_bar_, cmcr_bar_, ipr_bar_ = (
         getattr(_upp_test_parms, _f) for _f in ("guppi", "divr", "cmcr", "ipr")
     )