mergeron 2024.738940.0__py3-none-any.whl → 2024.738949.0__py3-none-any.whl

mergeron/examples/visualize_guidelines_tests.py

@@ -11,45 +11,53 @@ with the larger GUPPI estimate.
 from __future__ import annotations
 
 import gc
-from contextlib import suppress
 from dataclasses import fields
 from pathlib import Path
 from typing import Final
 
 import numpy as np
-import tables as ptb  # type: ignore
 from matplotlib import cm, colors
 from matplotlib.ticker import StrMethodFormatter
 from numpy.typing import NDArray
 
-import mergeron.core.guidelines_standards as gsl
+import mergeron.core.guidelines_boundaries as gbl
 import mergeron.gen.data_generation as dgl
-import mergeron.gen.guidelines_tests as gtl
-import mergeron.gen.investigations_stats as isl
+import mergeron.gen.upp_tests as utl
 from mergeron import DATA_DIR
 from mergeron.core.pseudorandom_numbers import DIST_PARMS_DEFAULT
-from mergeron.gen import ShareSpec
+from mergeron.gen import (
+    INVResolution,
+    MarketDataSample,
+    MarketSampleSpec,
+    RECConstants,
+    ShareSpec,
+    SHRConstants,
+    UPPAggrSelector,
+    UPPTestRegime,
+)
 
 PROG_PATH = Path(__file__)
 
 
-blosc_filters = ptb.Filters(
-    complevel=3, complib="blosc:lz4", bitshuffle=True, fletcher32=True
-)
-
-
 def gen_plot_data(
-    _market_data: dgl.MarketDataSample,
-    _std_vec: gsl.GuidelinesSTD,
+    _market_data: MarketDataSample,
+    _std_vec: gbl.HMGThresholds,
     _pcm_firm2_star: float,
-    _test_regime: gtl.UPPTestRegime,
+    _test_regime: UPPTestRegime,
     /,
     *,
-    h5handle: ptb.File | None = None,
+    save_data_to_file: utl.SaveData = False,
 ) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
-    _h5hier = "/plotData_mstar{}PCT".format(
-        f"{_pcm_firm2_star * 100:03.1f}".replace(".", "dot")
-    )
+    if save_data_to_file:
+        _, _h5_file, _h5_hier = save_data_to_file
+        _h5_hier = _h5_file.create_group(
+            _h5_hier,
+            "plotData_mstar{}PCT".format(
+                f"{_pcm_firm2_star * 100:03.1f}".replace(".", "dot")
+            ),
+            title=f"Firm 2 margin = {_pcm_firm2_star * 100:03.1f}%",
+        )
+        save_data_to_file = (True, _h5_file, _h5_hier)
 
     _pcm_array = np.column_stack((
         _m1 := _market_data.pcm_array[:, [0]],
@@ -57,12 +65,10 @@ def gen_plot_data(
     ))
     del _m1
 
-    _upp_test_raw = gtl.gen_upp_arrays(
+    _upp_test_raw = utl.gen_upp_arrays(
         _std_vec,
-        dgl.MarketDataSample(*[
-            _pcm_array.astype(_f.type)
-            if _f.name == "pcm_array"
-            else getattr(_market_data, _f.name)
+        MarketDataSample(*[  # type: ignore
+            _pcm_array if _f.name == "pcm_array" else getattr(_market_data, _f.name)
             for _f in fields(_market_data)
         ]),
         _test_regime,
@@ -83,7 +89,7 @@ def gen_plot_data(
 
     _pcm_plotter = _pcm_firm1_inv
 
-    if h5handle:
+    if save_data_to_file:
         print("Save data to tables")
         for _array_name in (
             "qtyshr_firm1_inv",
@@ -91,18 +97,14 @@ def gen_plot_data(
             "pcm_firm1_inv",
             "pcm_firm2_inv",
         ):
-            with suppress(ptb.NoSuchNodeError):
-                h5handle.remove_node(_h5hier, name=_array_name)
-            _array_h5 = h5handle.create_carray(
-                _h5hier,
-                _array_name,
-                obj=locals().get(f"_{_array_name}"),
-                createparents=True,
-                title=f"{_array_name}",
-            )
+            _array_obj: NDArray[any] = locals().get(f"_{_array_name}")  # type: ignore
+            if np.any(_array_obj):
+                utl.save_array_to_hdf5(
+                    _array_obj, _array_name, save_data_to_file[-1], save_data_to_file[1]
+                )
 
     _pcm_sorter = np.argsort(_pcm_plotter, axis=0)
-    if test_regime.resolution != isl.PolicySelector.CLRN:
+    if test_regime.resolution != INVResolution.CLRN:
         _pcm_sorter = _pcm_sorter[::-1, :]
     _qtyshr_firm1_plotter = _qtyshr_firm1_inv[_pcm_sorter]
     _qtyshr_firm2_plotter = _qtyshr_firm2_inv[_pcm_sorter]
@@ -121,19 +123,19 @@ def gen_plot_data(
 
 # Generate market data
 def _main(
-    _hmg_pub_year: gsl.HMGPubYear,
-    _market_sample_spec: dgl.MarketSampleSpec,
-    _test_regime: gtl.UPPTestRegime,
-    _save_data_to_file: gtl.SaveData,
+    _hmg_pub_year: gbl.HMGPubYear,
+    _market_sample_spec: MarketSampleSpec,
+    _test_regime: UPPTestRegime,
+    save_data_to_file: utl.SaveData,
 ) -> None:
     guidelins_std_vec = getattr(
-        gsl.GuidelinesStandards(_hmg_pub_year),
-        "safeharbor"
-        if test_regime.resolution == isl.PolicySelector.ENFT
-        else "presumption",
+        gbl.GuidelinesThresholds(_hmg_pub_year),
+        "safeharbor" if test_regime.resolution == INVResolution.ENFT else "presumption",
     )
 
-    _, _r_bar, _g_bar, _divr_bar, *_ = guidelins_std_vec
+    _r_bar, _g_bar, _divr_bar = (
+        getattr(guidelins_std_vec, _f) for _f in ("rec", "guppi", "divr")
+    )
 
     market_data = dgl.gen_market_sample(_market_sample_spec, seed_seq_list=None)
 
@@ -145,7 +147,7 @@ def _main(
     )
     _fig_norm = colors.Normalize(0.0, 1.0)
     _cmap_kwargs = {"cmap": "cividis", "norm": _fig_norm}
-    _plt, _, _, _set_axis_def = gsl.boundary_plot()
+    _plt, _, _, _set_axis_def = gbl.boundary_plot()
 
     _fig_2dsg = _plt.figure(figsize=(8.5, 9.5), dpi=600)
 
@@ -204,7 +206,7 @@ def _main(
             guidelins_std_vec,
             _pcm_firm2_star,
             _test_regime,
-            h5handle=_save_data_to_file[1] if _save_data_to_file else None,
+            save_data_to_file=save_data_to_file,
         )
 
         _ax_now.scatter(
@@ -255,44 +257,44 @@ def _main(
 if __name__ == "__main__":
     # Get Guidelines parameter values
     hmg_pub_year: Final = 2023
-    test_regime: gtl.UPPTestRegime = gtl.UPPTestRegime(
-        isl.PolicySelector.ENFT, gtl.UPPAggrSelector.MIN, gtl.UPPAggrSelector.MIN
+
+    test_regime: UPPTestRegime = UPPTestRegime(
+        INVResolution.ENFT, UPPAggrSelector.MIN, UPPAggrSelector.MIN
     )
+
     r_bar = getattr(
-        gsl.GuidelinesStandards(hmg_pub_year),
-        "presumption"
-        if test_regime.resolution == isl.PolicySelector.ENFT
-        else "safeharbor",
+        gbl.GuidelinesThresholds(hmg_pub_year),
+        "presumption" if test_regime.resolution == INVResolution.ENFT else "safeharbor",
     ).rec
 
     sample_sz = 10**7
 
-    market_sample_spec = dgl.MarketSampleSpec(
+    market_sample_spec = MarketSampleSpec(
         sample_sz,
         r_bar,
         share_spec=ShareSpec(
-            dgl.RECConstants.INOUT, dgl.SHRConstants.UNI, DIST_PARMS_DEFAULT, None
+            RECConstants.INOUT, SHRConstants.UNI, DIST_PARMS_DEFAULT, None
         ),
     )
 
-    save_data_to_file_flag = False
+    save_data_to_file_flag = True
     if save_data_to_file_flag:
-        h5path = DATA_DIR / PROG_PATH.with_suffix(".h5").name
-        h5datafile = ptb.open_file(
-            h5path,
-            mode="w",
-            title="Datasets, Sound GUPPI Safeharbor, Envelopes of GUPPI Boundaries",
-            filters=blosc_filters,
-        )
-        save_data_to_file: gtl.SaveData = (
-            True,
-            h5datafile,
-            "Intrinsic clearance stats",
+        h5_path = DATA_DIR / PROG_PATH.with_suffix(".h5").name
+        (_, h5_file, h5_group), h5_subgroup_name = utl.initialize_hd5(
+            h5_path, hmg_pub_year, test_regime
+        )  # type: ignore
+
+        h5_subgroup = h5_file.create_group(
+            h5_group,
+            h5_subgroup_name,
+            title=f"Market sample specifications: {market_sample_spec}",
         )
+        save_data_to_file: utl.SaveData = (True, h5_file, h5_subgroup)
     else:
         save_data_to_file = False
 
     _main(hmg_pub_year, market_sample_spec, test_regime, save_data_to_file)
 
     if save_data_to_file_flag:
+        save_data_to_file[1].flush()  # type: ignore
         save_data_to_file[1].close()  # type: ignore

mergeron/gen/__init__.py

@@ -16,8 +16,8 @@ import enum
 from dataclasses import dataclass
 from typing import ClassVar, Protocol, TypeVar
 
-import attrs
 import numpy as np
+from attrs import Attribute, define, field, validators
 from numpy.typing import NBitBase, NDArray
 
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
@@ -29,14 +29,6 @@ TF = TypeVar("TF", bound=NBitBase)
 TI = TypeVar("TI", bound=NBitBase)
 
 
-# https://stackoverflow.com/questions/54668000
-class DataclassInstance(Protocol):
-    """For type-hinting dataclass objects"""
-
-    __dataclass_asdict__: ClassVar
-    __dataclass_fields__: ClassVar
-
-
 @enum.unique
 class PRIConstants(tuple[bool, str | None], enum.ReprEnum):
     """Price specification.
@@ -91,7 +83,7 @@ class RECConstants(enum.StrEnum):
     FIXED = "proportional"
 
 
-@attrs.define(slots=True, frozen=True)
+@define(slots=True, frozen=True)
 class ShareSpec:
     """Market share specification
 
@@ -150,7 +142,7 @@ class FM2Constants(enum.StrEnum):
     SYM = "symmetric"
 
 
-@attrs.define(slots=True, frozen=True)
+@define(slots=True, frozen=True)
 class PCMSpec:
     """Price-cost margin (PCM) specification
 
@@ -224,18 +216,17 @@ class SSZConstants(float, enum.ReprEnum):
 
 # Validators for selected attributes of MarketSampleSpec
 def _sample_size_validator(
-    _object: MarketSampleSpec, _attribute: attrs.Attribute, _value: int, /
+    _object: MarketSampleSpec, _attribute: Attribute, _value: int, /
 ) -> None:
-    if _value < 10**6 or (_value % 10**5 != 0):
+    if _value < 10**6:
         raise ValueError(
-            f"Sample size must be a multiple of {10** 4:,d} and not less than {10** 6:,d}."
+            f"Sample size must be not less than {10**6:,d}. Got, {_value:,d}."
         )
 
 
 def _recapture_rate_validator(
-    _object: MarketSampleSpec, _attribute: attrs.Attribute, _value: float | None, /
+    _object: MarketSampleSpec, _attribute: Attribute, _value: float | None, /
 ) -> None:
-    # if _value < 10**6 or (np.log10(_value) % 1 != 0):
     if _value and not (0 < _value <= 1):
         raise ValueError("Recapture rate must lie in the interval, [0, 1).")
 
@@ -247,7 +238,7 @@ def _recapture_rate_validator(
 
 
 def _share_spec_validator(
-    _instance: MarketSampleSpec, _attribute: attrs.Attribute, _value: ShareSpec, /
+    _instance: MarketSampleSpec, _attribute: Attribute, _value: ShareSpec, /
 ) -> None:
     _r_bar = _instance.recapture_rate
     if _value.dist_type == SHRConstants.UNI:
@@ -278,7 +269,7 @@ def _share_spec_validator(
 
 
 def _pcm_spec_validator(
-    _instance: MarketSampleSpec, _attribute: attrs.Attribute, _value: PCMSpec, /
+    _instance: MarketSampleSpec, _attribute: Attribute, _value: PCMSpec, /
 ) -> None:
     if (
         _instance.share_spec.recapture_spec == RECConstants.FIXED
@@ -312,18 +303,18 @@ def _pcm_spec_validator(
             )
 
 
-@attrs.define(slots=True, frozen=True)
+@define(slots=True, frozen=True)
 class MarketSampleSpec:
     """Parameter specification for market data generation."""
 
-    sample_size: int = attrs.field(
-        default=10**6,
-        validator=(attrs.validators.instance_of(int), _sample_size_validator),
+    sample_size: int = field(
+        default=10**6, validator=(validators.instance_of(int), _sample_size_validator)
     )
     """sample size generated"""
 
-    recapture_rate: float | None = attrs.field(
-        default=None, validator=attrs.validators.instance_of(float | None)
+    recapture_rate: float | None = field(
+        default=None,
+        validator=(validators.instance_of(float | None), _recapture_rate_validator),
     )
     """market recapture rate
 
@@ -331,72 +322,119 @@ class MarketSampleSpec:
     outside good choice probabilities (RECConstants.OUTIN).
     """
 
-    pr_sym_spec: PRIConstants = attrs.field(  # type: ignore
+    pr_sym_spec: PRIConstants = field(  # type: ignore
         kw_only=True,
         default=PRIConstants.SYM,
-        validator=attrs.validators.instance_of(PRIConstants),  # type: ignore
+        validator=validators.instance_of(PRIConstants),  # type: ignore
     )
     """Price specification, see PRIConstants"""
 
-    share_spec: ShareSpec = attrs.field(
+    share_spec: ShareSpec = field(
         kw_only=True,
         default=ShareSpec(RECConstants.INOUT, SHRConstants.UNI, None, None),
-        validator=[attrs.validators.instance_of(ShareSpec), _share_spec_validator],
+        validator=[validators.instance_of(ShareSpec), _share_spec_validator],
     )
     """See definition of ShareSpec"""
 
-    pcm_spec: PCMSpec = attrs.field(
+    pcm_spec: PCMSpec = field(
         kw_only=True,
         default=PCMSpec(PCMConstants.UNI, FM2Constants.IID, None),
-        validator=[attrs.validators.instance_of(PCMSpec), _pcm_spec_validator],
+        validator=[validators.instance_of(PCMSpec), _pcm_spec_validator],
     )
     """See definition of PCMSpec"""
 
-    hsr_filing_test_type: SSZConstants = attrs.field(  # type: ignore
+    hsr_filing_test_type: SSZConstants = field(  # type: ignore
         kw_only=True,
         default=SSZConstants.ONE,
-        validator=attrs.validators.instance_of(SSZConstants),  # type: ignore
+        validator=validators.instance_of(SSZConstants),  # type: ignore
     )
     """Method for modeling HSR filing threholds, see SSZConstants"""
 
 
+@enum.unique
+class INVResolution(enum.StrEnum):
+    CLRN = "clearance"
+    ENFT = "enforcement"
+    BOTH = "both"
+
+
+@enum.unique
+class UPPAggrSelector(enum.StrEnum):
+    """
+    Aggregator selection for GUPPI and diversion ratio
+
+    """
+
+    AVG = "average"
+    CPA = "cross-product-share-weighted average"
+    CPD = "cross-product-share-weighted distance"
+    DIS = "symmetrically-weighted distance"
+    MAX = "max"
+    MIN = "min"
+    OSA = "own-share-weighted average"
+    OSD = "own-share-weighted distance"
+
+
+@define(slots=True, frozen=True)
+class UPPTestRegime:
+    resolution: INVResolution = field(  # type: ignore
+        default=INVResolution.ENFT,
+        validator=validators.instance_of(INVResolution),  # type: ignore
+    )
+    guppi_aggregator: UPPAggrSelector = field(  # type: ignore
+        default=UPPAggrSelector.MAX,
+        validator=validators.instance_of(UPPAggrSelector),  # type: ignore
+    )
+    divr_aggregator: UPPAggrSelector | None = field(  # type: ignore
+        default=guppi_aggregator,
+        validator=validators.instance_of(UPPAggrSelector | None),  # type: ignore
+    )
+
+
+# https://stackoverflow.com/questions/54668000
+class DataclassInstance(Protocol):
+    """Generic dataclass-instance"""
+
+    __dataclass_fields__: ClassVar
+
+
 @dataclass(slots=True, frozen=True)
 class MarketDataSample:
     """Container for generated markets data sample."""
 
-    frmshr_array: NDArray[np.floating]
+    frmshr_array: NDArray[np.float64]
     """Merging-firm shares (with two merging firms)"""
 
-    pcm_array: NDArray[np.floating]
+    pcm_array: NDArray[np.float64]
     """Merging-firms' prices (normalized to 1, in default specification)"""
 
-    price_array: NDArray[np.floating]
+    price_array: NDArray[np.float64]
     """Merging-firms' price-cost margins (PCM)"""
 
-    fcounts: NDArray[np.integer]
+    fcounts: NDArray[np.int64]
     """Number of firms in market"""
 
-    ratio_choice_prob_to_mktshr: NDArray[np.floating]
+    aggregate_purchase_prob: NDArray[np.float64]
     """
     One (1) minus probability that the outside good is chosen
 
     Converts market shares to choice probabilities by multiplication.
     """
 
-    nth_firm_share: NDArray[np.floating]
+    nth_firm_share: NDArray[np.float64]
     """Market-share of n-th firm
 
     Relevant for testing for draws the do or
     do not meet HSR filing thresholds.
     """
 
-    divr_array: NDArray[np.floating]
+    divr_array: NDArray[np.float64]
     """Diversion ratio between the merging firms"""
 
-    hhi_post: NDArray[np.floating]
+    hhi_post: NDArray[np.float64]
     """Post-merger change in Herfindahl-Hirschmann Index (HHI)"""
 
-    hhi_delta: NDArray[np.floating]
+    hhi_delta: NDArray[np.float64]
     """Change in HHI from combination of merging firms"""
 
 
@@ -425,7 +463,7 @@ class ShareDataSample:
 class PriceDataSample:
     """Container for generated price array, and related."""
 
-    price_array: NDArray[np.floating]
+    price_array: NDArray[np.float64]
     """Merging-firms' prices"""
 
     hsr_filing_test: NDArray[np.bool_]
@@ -455,14 +493,38 @@ class MarginDataSample:
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsRaw:
+    """arrays marking test failures and successes
+
+    A test success is a draw ("market") that meeets the
+    specified test criterion, and a test failure is
+    one that does not; test criteria are defined and
+    evaluated in:code:`guidelines_stats.gen_upp_arrays`.
+    """
+
     guppi_test_simple: NDArray[np.bool_]
+    """True if GUPPI estimate meets criterion"""
+
     guppi_test_compound: NDArray[np.bool_]
+    """True if both GUPPI estimate and diversion ratio estimate
+    meet criterion
+    """
+
     cmcr_test: NDArray[np.bool_]
+    """True if CMCR estimate meets criterion"""
+
     ipr_test: NDArray[np.bool_]
+    """True if IPR (partial price-simulation) estimate meets criterion"""
 
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsCounts:
+    """counts of markets resolved as specified
+
+    Resolution is specified in a UPPTestRegime object.
+    """
+
     by_firm_count: NDArray[np.int64]
     by_delta: NDArray[np.int64]
     by_conczone: NDArray[np.int64]
+    """Zones are "unoncentrated", "moderately concentrated", and "highly concentrated"
+    """

mergeron/gen/_data_generation_functions_nonpublic.py

@@ -116,7 +116,7 @@ def _gen_share_data(
 
 def _gen_market_shares_uniform(
     _s_size: int = 10**6,
-    _dist_parms_mktshr: NDArray[np.floating[TF]] | None = DIST_PARMS_DEFAULT,
+    _dist_parms_mktshr: NDArray[np.floating[TF]] | None = DIST_PARMS_DEFAULT,  # type: ignore
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
     /,
@@ -141,8 +141,8 @@ def _gen_market_shares_uniform(
     """
 
     _frmshr_array = np.empty((_s_size, 2), dtype=np.float64)
-    _dist_parms_mktshr = (
-        DIST_PARMS_DEFAULT if _dist_parms_mktshr is None else _dist_parms_mktshr  # type: ignore
+    _dist_parms_mktshr: NDArray[np.floating] = (
+        DIST_PARMS_DEFAULT if _dist_parms_mktshr is None else _dist_parms_mktshr
     )
     _mrng = MultithreadedRNG(
         _frmshr_array,
@@ -220,9 +220,9 @@ def _gen_market_shares_dirichlet_multisample(
 
     """
 
-    _firm_count_wts: np.float64 = (
+    _firm_count_wts: NDArray[np.floating] = (
         FCOUNT_WTS_DEFAULT if _firm_count_wts is None else _firm_count_wts
-    )  # type: ignore
+    )
 
     _min_choice_wt = 0.03 if _dist_type_dir == SHRConstants.DIR_FLAT_CONSTR else 0.00
     _fcount_keys, _choice_wts = zip(
@@ -441,7 +441,7 @@ def _gen_pr_data(
             )
     # del _pr_max_ratio
 
-    _price_ratio_array = _price_array / _price_array[:, ::-1]
+    _price_array = _price_array.astype(np.float64)
     _rev_array = _price_array * _frmshr_array
     _nth_firm_rev = _nth_firm_price * _nth_firm_share
 

mergeron/gen/data_generation.py

@@ -118,10 +118,7 @@ def gen_market_sample(
 
     # Generate merging-firm price data
     _price_data = _gen_pr_data(
-        _mktshr_data.mktshr_array[:, :2],
-        _mktshr_data.nth_firm_share,
-        _mkt_sample_spec_here,
-        _pr_rng_seed_seq,
+        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec_here, _pr_rng_seed_seq
     )
 
     _price_array, _hsr_filing_test = (