mergeron 2025.739439.10__py3-none-any.whl → 2025.739439.12__py3-none-any.whl

mergeron/gen/__init__.py

@@ -15,7 +15,7 @@ from attrs import Attribute, Converter, cmp_using, field, frozen
 from numpy.random import SeedSequence
 
 from .. import (  # noqa: TID252
-    DEFAULT_REC_RATIO,
+    DEFAULT_REC,
     VERSION,
     ArrayBIGINT,
     ArrayBoolean,
@@ -89,9 +89,9 @@ class SHRDistribution(str, Enameled):
     """Share distribution for merging-firm shares has a higher peak share
 
     By default, shape parameter for merging-firm-share is 2.5, and
-    1.0 for all others. Defining, :attr:`.ShareSpec.dist_parms`
+    1.0 for all others. Defining, :attr:`.MarketShareSpec.dist_parms`
     as a vector of shape parameters with length matching
-    that of :attr:`.ShareSpec.dist_parms` allows flexible specification
+    that of :attr:`.MarketShareSpec.dist_parms` allows flexible specification
     of Dirichlet-distributed share-data generation.
     """
 
@@ -104,7 +104,7 @@ class SHRDistribution(str, Enameled):
 
 
 def _fc_wts_conv(
-    _v: Sequence[float | int] | ArrayDouble | ArrayINT | None, _i: ShareSpec
+    _v: Sequence[float | int] | ArrayDouble | ArrayINT | None, _i: MarketShareSpec
 ) -> ArrayFloat | None:
     if _i.dist_type == SHRDistribution.UNI:
         return None
@@ -114,7 +114,7 @@ def _fc_wts_conv(
         return _tv if (_tv := np.asarray(_v, float)).sum() == 1 else _tv / _tv.sum()
 
 
-def _shr_dp_conv(_v: Sequence[float] | ArrayFloat | None, _i: ShareSpec) -> ArrayFloat:
+def _shr_dp_conv(_v: Sequence[float] | ArrayFloat | None, _i: MarketShareSpec) -> ArrayFloat:
     if _v is None or len(_v) == 0 or np.array_equal(_v, DEFAULT_DIST_PARMS):
         if _i.dist_type == SHRDistribution.UNI:
             return DEFAULT_DIST_PARMS
@@ -149,7 +149,7 @@ def _shr_dp_conv(_v: Sequence[float] | ArrayFloat | None, _i: ShareSpec) -> Arra
 
 
 @frozen
-class ShareSpec:
+class MarketShareSpec:
     """Market share specification.
 
     A salient feature of market-share specification in this package is that
@@ -163,7 +163,7 @@ class ShareSpec:
     -----
     If :attr:`.dist_type` == :attr:`.SHRDistribution.UNI`, it is then infeasible that
     :attr:`.recapture_form` == :attr:`mergeron.RECForm.OUTIN`.
-    In other words, recapture ratios cannot be estimated using
+    In other words, recapture rates cannot be estimated using
     outside-good choice probabilities if the distribution of markets over firm-counts
     is unspecified.
     """
@@ -187,11 +187,11 @@ class ShareSpec:
     """
 
     @firm_counts_weights.default
-    def __fcwd(_i: ShareSpec) -> ArrayFloat | None:
+    def __fcwd(_i: MarketShareSpec) -> ArrayFloat | None:
         return _fc_wts_conv(None, _i)
 
     @firm_counts_weights.validator
-    def __fcv(_i: ShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
+    def __fcv(_i: MarketShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
         if _i.dist_type != SHRDistribution.UNI and not len(_v):
             raise ValueError(
                 f"Attribute, {'"firm_counts_weights"'} must be populated if the share distribution is "
@@ -212,13 +212,13 @@ class ShareSpec:
     """
 
     @dist_parms.default
-    def __dpd(_i: ShareSpec) -> ArrayFloat:
+    def __dpd(_i: MarketShareSpec) -> ArrayFloat:
         # converters run after defaults, and we
         # avoid redundancy and confusion here
         return _shr_dp_conv(None, _i)
 
     @dist_parms.validator
-    def __dpv(_i: ShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
+    def __dpv(_i: MarketShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
         if (
             _i.firm_counts_weights is not None
             and _v is not None
@@ -234,7 +234,7 @@ class ShareSpec:
     """See :class:`mergeron.RECForm`"""
 
     @recapture_form.validator
-    def __rfv(_i: ShareSpec, _a: Attribute[RECForm], _v: RECForm) -> None:
+    def __rfv(_i: MarketShareSpec, _a: Attribute[RECForm], _v: RECForm) -> None:
         if _i.dist_type == SHRDistribution.UNI and _v == RECForm.OUTIN:
             raise ValueError(
                 "Outside-good choice probabilities cannot be generated if the "
@@ -243,15 +243,15 @@ class ShareSpec:
                 "firm-counts unspecified."
             )
 
-    recapture_ratio: float | None = field(kw_only=True)
+    recapture_rate: float | None = field(kw_only=True)
     """A value between 0 and 1.
 
     :code:`None` if market share specification requires direct generation of
     outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
 
-    The recapture ratio is usually calibrated to the numbers-equivalent of the
+    The recapture rate is usually calibrated to the numbers-equivalent of the
     HHI threshold for the presumption of harm from unilateral competitive effects
-    in published merger guidelines. Accordingly, the recapture ratio rounded to
+    in published merger guidelines. Accordingly, the recapture rate rounded to
     the nearest 5% is:
 
     * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1992, 2023
@@ -264,21 +264,21 @@ class ShareSpec:
     presumptions no harm.)
 
     ALERT: If diversion ratios are estimated by specifying a choice probability for the
-    outside good, the recapture ratio is set to None, overriding any user-specified value.
+    outside good, the recapture rate is set to None, overriding any user-specified value.
     """
 
-    @recapture_ratio.default
-    def __rrd(_i: ShareSpec) -> float | None:
-        return None if _i.recapture_form == RECForm.OUTIN else DEFAULT_REC_RATIO
+    @recapture_rate.default
+    def __rrd(_i: MarketShareSpec) -> float | None:
+        return None if _i.recapture_form == RECForm.OUTIN else DEFAULT_REC
 
-    @recapture_ratio.validator
-    def __rrv(_i: ShareSpec, _a: Attribute[float], _v: float) -> None:
+    @recapture_rate.validator
+    def __rrv(_i: MarketShareSpec, _a: Attribute[float], _v: float) -> None:
         if _v and not (0 < _v <= 1):
-            raise ValueError("Recapture ratio must lie in the interval, [0, 1).")
+            raise ValueError("Recapture rate must lie in the interval, [0, 1).")
         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 includes a recapture ratio in the "
+                "the market sample specification includes a recapture rate in the "
                 "interval [0, 1)."
             )
 
@@ -455,7 +455,7 @@ class SSZConstant(float, Enameled):
 
 
 @frozen
-class MarketSampleData:
+class MarketsData:
     """Container for generated market sample dataset."""
 
     frmshr_array: ArrayDouble = field(eq=cmp_using(np.array_equal))
@@ -467,7 +467,7 @@ class MarketSampleData:
     price_array: ArrayDouble = field(eq=cmp_using(np.array_equal))
     """Merging-firms' price-cost margins (PCM)"""
 
-    divr_array: ArrayDouble = field(eq=cmp_using(np.array_equal))
+    divratio_array: ArrayDouble = field(eq=cmp_using(np.array_equal))
     """Diversion ratio between the merging firms"""
 
     hhi_delta: ArrayDouble = field(eq=cmp_using(np.array_equal))
@@ -481,7 +481,7 @@ class MarketSampleData:
     """
 
     @aggregate_purchase_prob.default
-    def __appd(_i: MarketSampleData) -> ArrayDouble:
+    def __appd(_i: MarketsData) -> ArrayDouble:
         retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
         retval.fill(np.nan)
         return retval
@@ -490,7 +490,7 @@ class MarketSampleData:
     """Number of firms in market"""
 
     @fcounts.default
-    def __fcd(_i: MarketSampleData) -> ArrayINT:
+    def __fcd(_i: MarketsData) -> ArrayINT:
         return np.zeros_like(_i.frmshr_array[:, :1], np.uint8)
 
     nth_firm_share: ArrayDouble = field(eq=cmp_using(np.array_equal))
@@ -501,7 +501,7 @@ class MarketSampleData:
     """
 
     @nth_firm_share.default
-    def __nfsd(_i: MarketSampleData) -> ArrayDouble:
+    def __nfsd(_i: MarketsData) -> ArrayDouble:
         retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
         retval.fill(np.nan)
         return retval
@@ -510,7 +510,7 @@ class MarketSampleData:
     """Post-merger contribution to Herfindahl-Hirschman Index (HHI)"""
 
     @hhi_post.default
-    def __hpd(_i: MarketSampleData) -> ArrayDouble:
+    def __hpd(_i: MarketsData) -> ArrayDouble:
         retval: ArrayDouble = np.empty_like(_i.frmshr_array[:, :1], float)
         retval.fill(np.nan)
         return retval
@@ -530,7 +530,7 @@ class MarketSampleData:
     @classmethod
     def from_h5f(
         cls, _hfh: io.BufferedReader | zipfile.ZipExtFile | IO[bytes]
-    ) -> MarketSampleData:
+    ) -> MarketsData:
         """Load market sample data from HDF5 file."""
         with h5py.File(_hfh, "r") as _h5f:
             _retval = cls(**{_a: _h5f[_a][:] for _a in _h5f})
@@ -538,7 +538,7 @@ class MarketSampleData:
 
 
 @frozen
-class ShareSampleData:
+class MarketSharesData:
     """Container for generated market shares.
 
     Includes related measures of market structure
@@ -559,7 +559,7 @@ class ShareSampleData:
 
 
 @frozen
-class PriceSampleData:
+class PricesData:
     """Container for generated price array, and related."""
 
     price_array: ArrayDouble
@@ -570,19 +570,19 @@ class PriceSampleData:
 
 
 @frozen
-class MarginSampleData:
+class MarginsData:
     """Container for generated margin array and related MNL test array."""
 
     pcm_array: ArrayDouble
     """Merging-firms' PCMs"""
 
-    mnl_test_array: ArrayBoolean
+    mnl_test: ArrayBoolean
     """Flags infeasible observations as False and rest as True
 
     Applying restrictions from Bertrand-Nash oligopoly with MNL demand results
     in some draws of Firm 2 PCM falling outside the feasible interval, :math:`[0, 1]`
     for certain combinations of merging firms shares as initially drawn. Such draws
-    are flagged as infeasible (False) in :code:`mnl_test_array` while draws with
+    are flagged as infeasible (False) in :code:`mnl_test` while draws with
     feaseible PCM values flagged True. This array is used to exclude infeasible draws
     when imposing MNL demand in simulations.
     """
@@ -658,5 +658,5 @@ class UPPTestsCounts:
     """
 
 
-for _typ in (SeedSequenceData, ShareSpec, PCMSpec, UPPTestsCounts, UPPTestRegime):
+for _typ in (SeedSequenceData, MarketShareSpec, PCMSpec, UPPTestsCounts, UPPTestRegime):
     yamelize_attrs(_typ)

mergeron/gen/data_generation.py

@@ -24,22 +24,22 @@ from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from ..core.guidelines_boundaries import HMGThresholds  # noqa: TID252
 from . import (
     INVResolution,  # noqa: F401
-    MarketSampleData,
+    MarketsData,
     PCMDistribution,
     PCMRestriction,
     PCMSpec,
     PriceSpec,
     SeedSequenceData,
-    ShareSpec,
+    MarketShareSpec,
     SHRDistribution,
     SSZConstant,
     UPPTestRegime,
     UPPTestsCounts,
 )
 from .data_generation_functions import (
-    gen_divr_array,
-    gen_margin_price_data,
-    gen_share_data,
+    diversion_ratios_builder,
+    prices_sampler,
+    market_share_sampler,
 )
 from .upp_tests import compute_upp_test_counts
 
@@ -82,11 +82,11 @@ def _seed_data_conv(_v: SeedSequenceData | None, _i: MarketSample) -> SeedSequen
 class MarketSample:
     """Parameter specification for market data generation."""
 
-    share_spec: ShareSpec = field(
-        default=ShareSpec(SHRDistribution.UNI),
-        validator=validators.instance_of(ShareSpec),
+    share_spec: MarketShareSpec = field(
+        default=MarketShareSpec(SHRDistribution.UNI),
+        validator=validators.instance_of(MarketShareSpec),
     )
-    """Market-share specification, see :class:`ShareSpec`"""
+    """Market-share specification, see :class:`MarketShareSpec`"""
 
     pcm_spec: PCMSpec = field(
         default=PCMSpec(PCMDistribution.UNI), validator=validators.instance_of(PCMSpec)
@@ -101,7 +101,7 @@ class MarketSample:
         ):
             raise ValueError(
                 f'Specification of "PCMSpec.pcm_restriction", as {PCMRestriction.MNL!r} '
-                f'requires that "ShareSpec.recapture_form" be {RECForm.INOUT!r} '
+                f'requires that "MarketShareSpec.recapture_form" be {RECForm.INOUT!r} '
                 f"or {RECForm.OUTIN!r}, not {RECForm.FIXED!r} as presently specified"
             )
 
@@ -153,13 +153,13 @@ class MarketSample:
     nthreads: int = field(default=NTHREADS, validator=validators.instance_of(int))
     """number of parallel threads to use"""
 
-    dataset: MarketSampleData | None = field(default=None, init=False)
+    dataset: MarketsData | None = field(default=None, init=False)
 
     enf_counts: UPPTestsCounts | None = field(default=None, init=False)
 
-    def _gen_market_sample(
+    def _markets_sampler(
         self, /, *, sample_size: int, seed_data: SeedSequenceData, nthreads: int
-    ) -> MarketSampleData:
+    ) -> MarketsData:
         """
         Generate share, diversion ratio, price, and margin data for MarketSpec.
 
@@ -181,7 +181,7 @@ class MarketSample:
         shr_sample_size = int(shr_sample_size)
 
         # Generate share data
-        mktshr_data = gen_share_data(
+        mktshr_data = market_share_sampler(
             shr_sample_size,
             self.share_spec,
             seed_data.fcounts,
@@ -195,7 +195,7 @@ class MarketSample:
         del mktshr_data
 
         # Generate merging-firm price and PCM data
-        margin_data, price_data = gen_margin_price_data(
+        margin_data, price_data = prices_sampler(
             mktshr_array_[:, :2],
             nth_firm_share_,
             aggregate_purchase_prob_,
@@ -210,7 +210,7 @@ class MarketSample:
         price_array_ = price_data.price_array
 
         if shr_sample_size > sample_size:
-            mnl_test_rows = margin_data.mnl_test_array * price_data.hsr_filing_test
+            mnl_test_rows = margin_data.mnl_test * price_data.hsr_filing_test
 
             mktshr_array_ = mktshr_array_[mnl_test_rows][:sample_size]
             pcm_array_ = margin_data.pcm_array[mnl_test_rows][:sample_size]
@@ -224,18 +224,18 @@ class MarketSample:
             del mnl_test_rows
 
         # Calculate diversion ratios
-        divr_array = gen_divr_array(
+        divratio_array = diversion_ratios_builder(
             self.share_spec.recapture_form,
-            self.share_spec.recapture_ratio,
+            self.share_spec.recapture_rate,
             mktshr_array_[:, :2],
             aggregate_purchase_prob_,
         )
 
-        return MarketSampleData(
+        return MarketsData(
             mktshr_array_[:, :2],
             pcm_array_,
             price_array_,
-            divr_array,
+            divratio_array,
             np.einsum("ij,ij->i", mktshr_array_[:, :2], mktshr_array_[:, [1, 0]])[
                 :, None
             ],
@@ -256,7 +256,7 @@ class MarketSample:
         None
 
         """
-        self.dataset = self._gen_market_sample(
+        self.dataset = self._markets_sampler(
             seed_data=self.seed_data,
             sample_size=self.sample_size,
             nthreads=self.nthreads,
@@ -299,7 +299,7 @@ class MarketSample:
             UPPTestCounts object with  of test counts by firm count, ΔHHI and concentration zone
 
         """
-        market_data_sample = self._gen_market_sample(
+        market_data_sample = self._markets_sampler(
             sample_size=sample_size, seed_data=seed_data, nthreads=nthreads
         )
 
@@ -343,11 +343,11 @@ class MarketSample:
 
         if (
             self.share_spec.recapture_form != RECForm.OUTIN
-            and self.share_spec.recapture_ratio != _enf_parm_vec.rec
+            and self.share_spec.recapture_rate != _enf_parm_vec.rec
         ):
             raise ValueError(
                 "{} {} {}".format(
-                    f"Recapture ratio from market sample spec, {self.share_spec.recapture_ratio}",
+                    f"Recapture rate from market sample spec, {self.share_spec.recapture_rate}",
                     f"must match the value, {_enf_parm_vec.rec}",
                     "the guidelines thresholds vector.",
                 )
@@ -488,7 +488,7 @@ class MarketSample:
                 if _dt:
                     with _dp.open("rb") as _hfh:
                         object.__setattr__(
-                            market_sample_, "dataset", MarketSampleData.from_h5f(_hfh)
+                            market_sample_, "dataset", MarketsData.from_h5f(_hfh)
                         )
                 if _et:
                     object.__setattr__(