mergeron 2024.738953.1__py3-none-any.whl → 2024.738972.0__py3-none-any.whl

mergeron/gen/data_generation.py

@@ -1,5 +1,5 @@
 """
-Routines to generate data for analyzing merger enforcement policy.
+Methods to generate data for analyzing merger enforcement policy.
 
 """
 
@@ -7,7 +7,6 @@ from __future__ import annotations
 
 from importlib.metadata import version
 
-import attrs
 import numpy as np
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
@@ -15,19 +14,18 @@ from numpy.typing import NDArray
 from .. import _PKG_NAME, RECConstants  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
-    TF,
     FM2Constants,
     MarketDataSample,
-    MarketSampleSpec,
+    MarketSpec,
     PRIConstants,
     SHRConstants,
     SSZConstants,
 )
-from ._data_generation_functions_nonpublic import (
+from ._data_generation_functions import (
     _gen_market_shares_dirichlet,  # noqa: F401 easter-egg for external modules
     _gen_market_shares_uniform,  # noqa: F401 easter-egg for external modules
     _gen_pcm_data,
-    _gen_pr_data,
+    _gen_price_data,
     _gen_share_data,
 )
 
@@ -35,9 +33,10 @@ __version__ = version(_PKG_NAME)
 
 
 def gen_market_sample(
-    _mkt_sample_spec: MarketSampleSpec,
+    _mkt_sample_spec: MarketSpec,
     /,
     *,
+    sample_size: int = 10**6,
     seed_seq_list: list[SeedSequence] | None = None,
     nthreads: int = 16,
 ) -> MarketDataSample:
@@ -45,7 +44,7 @@ def gen_market_sample(
     Generate share, diversion ratio, price, and margin data based on supplied parameters
 
     Diversion ratios generated assuming share-proportionality, unless
-    `recapture_spec` = "proportional", in which case both firms' recapture rate
+    `recapture_form` = "proportional", in which case both firms' recapture rate
     is set to `r_bar`.
 
     The tuple of SeedSequences, if specified, is parsed in the following order
@@ -54,12 +53,14 @@ def gen_market_sample(
     2.) price-cost margins
     3.) firm-counts, from :code:`[2, 2 + len(firm_counts_weights)]`,
     weighted by :code:`firm_counts_weights`, where relevant
-    4.) prices, if :code:`pr_sym_spec == PRIConstants.ZERO`.
+    4.) prices, if :code:`price_spec == PRIConstants.ZERO`.
 
     Parameters
     ----------
     _mkt_sample_spec
         class specifying parameters for data generation
+    sample_size
+        number of draws to generate
     seed_seq_list
         tuple of SeedSequences to ensure replicable data generation with
         appropriately independent random streams
@@ -73,9 +74,10 @@ def gen_market_sample(
 
     """
 
-    _mkt_sample_spec = _mkt_sample_spec or MarketSampleSpec()
+    _mkt_sample_spec = _mkt_sample_spec or MarketSpec()
 
-    _recapture_spec = _mkt_sample_spec.share_spec.recapture_spec
+    _recapture_form = _mkt_sample_spec.share_spec.recapture_form
+    _recapture_rate = _mkt_sample_spec.share_spec.recapture_rate
     _dist_type_mktshr = _mkt_sample_spec.share_spec.dist_type
     _dist_firm2_pcm = _mkt_sample_spec.pcm_spec.firm2_pcm_constraint
     _hsr_filing_test_type = _mkt_sample_spec.hsr_filing_test_type
@@ -86,22 +88,23 @@ def gen_market_sample(
         _fcount_rng_seed_seq,
         _pr_rng_seed_seq,
     ) = parse_seed_seq_list(
-        seed_seq_list, _dist_type_mktshr, _mkt_sample_spec.pr_sym_spec
+        seed_seq_list, _dist_type_mktshr, _mkt_sample_spec.price_spec
     )
 
-    _shr_sample_size = 1.0 * _mkt_sample_spec.sample_size
+    _shr_sample_size = 1.0 * sample_size
     # Scale up sample size to offset discards based on specified criteria
     _shr_sample_size *= _hsr_filing_test_type
     if _dist_firm2_pcm == FM2Constants.MNL:
         _shr_sample_size *= SSZConstants.MNL_DEP
-    _mkt_sample_spec_here = attrs.evolve(
-        _mkt_sample_spec, sample_size=int(_shr_sample_size)
-    )
-    del _shr_sample_size
+    _shr_sample_size = int(_shr_sample_size)
 
     # Generate share data
     _mktshr_data = _gen_share_data(
-        _mkt_sample_spec_here, _fcount_rng_seed_seq, _mktshr_rng_seed_seq, nthreads
+        _shr_sample_size,
+        _mkt_sample_spec,
+        _fcount_rng_seed_seq,
+        _mktshr_rng_seed_seq,
+        nthreads,
     )
 
     _mktshr_array, _fcounts, _aggregate_purchase_prob, _nth_firm_share = (
@@ -115,8 +118,8 @@ def gen_market_sample(
     )
 
     # Generate merging-firm price data
-    _price_data = _gen_pr_data(
-        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec_here, _pr_rng_seed_seq
+    _price_data = _gen_price_data(
+        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec, _pr_rng_seed_seq
     )
 
     _price_array, _hsr_filing_test = (
@@ -132,16 +135,13 @@ def gen_market_sample(
 
     # Calculate diversion ratios
     _divr_array = gen_divr_array(
-        _mktshr_array[:, :2],
-        _mkt_sample_spec_here.recapture_rate or 0.8,
-        _recapture_spec,
-        _aggregate_purchase_prob,
+        _recapture_form, _recapture_rate, _mktshr_array[:, :2], _aggregate_purchase_prob
     )
 
     # Generate margin data
     _pcm_data = _gen_pcm_data(
         _mktshr_array[:, :2],
-        _mkt_sample_spec_here,
+        _mkt_sample_spec,
         _price_array,
         _aggregate_purchase_prob,
         _pcm_rng_seed_seq,
@@ -151,7 +151,7 @@ def gen_market_sample(
         getattr(_pcm_data, _f) for _f in ("pcm_array", "mnl_test_array")
     )
 
-    _s_size = _mkt_sample_spec.sample_size  # originally-specified sample size
+    _s_size = sample_size  # originally-specified sample size
     if _dist_firm2_pcm == FM2Constants.MNL:
         _mktshr_array = _mktshr_array[_mnl_test_rows][:_s_size]
         _pcm_array = _pcm_array[_mnl_test_rows][:_s_size]
@@ -185,18 +185,18 @@ def gen_market_sample(
 
 def parse_seed_seq_list(
     _sseq_list: list[SeedSequence] | None,
-    _dist_type_mktshr: SHRConstants,
-    _pr_sym_spec: PRIConstants,
+    _mktshr_dist_type: SHRConstants,
+    _price_spec: PRIConstants,
     /,
 ) -> tuple[SeedSequence, SeedSequence, SeedSequence | None, SeedSequence | None]:
     """Initialize RNG seed sequences to ensure independence of distinct random streams."""
     _fcount_rng_seed_seq: SeedSequence | None = None
     _pr_rng_seed_seq: SeedSequence | None = None
 
-    if _pr_sym_spec == PRIConstants.ZERO:
+    if _price_spec == PRIConstants.ZERO:
         _pr_rng_seed_seq = _sseq_list.pop() if _sseq_list else SeedSequence(pool_size=8)
 
-    if _dist_type_mktshr == SHRConstants.UNI:
+    if _mktshr_dist_type == SHRConstants.UNI:
         _fcount_rng_seed_seq = None
         _seed_count = 2
         _mktshr_rng_seed_seq, _pcm_rng_seed_seq = (
@@ -221,10 +221,10 @@ def parse_seed_seq_list(
 
 
 def gen_divr_array(
-    _frmshr_array: NDArray[np.floating[TF]],
-    _r_bar: float,
-    _recapture_spec: RECConstants = RECConstants.INOUT,
-    _aggregate_purchase_prob: NDArray[np.floating[TF]] = EMPTY_ARRAY_DEFAULT,
+    _recapture_form: RECConstants,
+    _recapture_rate: float | None,
+    _frmshr_array: NDArray[np.float64],
+    _aggregate_purchase_prob: NDArray[np.float64] = EMPTY_ARRAY_DEFAULT,
     /,
 ) -> NDArray[np.float64]:
     """
@@ -235,20 +235,20 @@ def gen_divr_array(
 
     Parameters
     ----------
-    _frmshr_array
-        Merging-firm shares.
+    _recapture_form
+        Enum specifying Fixed (proportional), Inside-out, or Outside-in
 
-    _r_bar
+    _recapture_rate
         If recapture is proportional or inside-out, the recapture rate
         for the firm with the smaller share.
 
+    _frmshr_array
+        Merging-firm shares.
+
     _aggregate_purchase_prob
         1 minus probability that the outside good is chosen; converts
         market shares to choice probabilities by multiplication.
 
-    _recapture_spec
-        Enum specifying Fixed (proportional), Inside-out, or Outside-in
-
     Returns
     -------
         Merging-firm diversion ratios for mergers in the sample.
@@ -256,8 +256,8 @@ def gen_divr_array(
     """
 
     _divr_array: NDArray[np.float64]
-    if _recapture_spec == RECConstants.FIXED:
-        _divr_array = _r_bar * _frmshr_array[:, ::-1] / (1 - _frmshr_array)
+    if _recapture_form == RECConstants.FIXED:
+        _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
 
     else:
         _purchprob_array = _aggregate_purchase_prob * _frmshr_array

mergeron/gen/investigations_stats.py

@@ -1,5 +1,5 @@
 """
-Routines to format and print summary data on merger enforcement patterns.
+Methods to format and print summary data on merger enforcement patterns.
 
 """
 

mergeron/gen/market_sample.py

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