mergeron 2024.738973.0__py3-none-any.whl → 2024.739079.10__py3-none-any.whl

mergeron/gen/data_generation.py

@@ -5,31 +5,32 @@ Methods to generate data for analyzing merger enforcement policy.
 
 from __future__ import annotations
 
-from importlib.metadata import version
+from typing import NamedTuple
 
 import numpy as np
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
 
-from .. import _PKG_NAME, RECConstants  # noqa: TID252
+from .. import VERSION, RECConstants  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
     FM2Constants,
     MarketDataSample,
     MarketSpec,
-    PRIConstants,
+    PriceConstants,
     SHRConstants,
     SSZConstants,
 )
-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_price_data,
-    _gen_share_data,
-)
+from ._data_generation_functions import _gen_pcm_data, _gen_price_data, _gen_share_data
+
+__version__ = VERSION
+
 
-__version__ = version(_PKG_NAME)
+class SeedSequenceData(NamedTuple):
+    mktshr_rng_seed_seq: SeedSequence
+    pcm_rng_seed_seq: SeedSequence
+    fcount_rng_seed_seq: SeedSequence | None
+    pr_rng_seed_seq: SeedSequence | None
 
 
 def gen_market_sample(
@@ -53,7 +54,7 @@ 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:`price_spec == PRIConstants.ZERO`.
+    4.) prices, if :code:`price_spec == PriceConstants.ZERO`.
 
     Parameters
     ----------
@@ -74,8 +75,6 @@ def gen_market_sample(
 
     """
 
-    _mkt_sample_spec = _mkt_sample_spec or MarketSpec()
-
     _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
@@ -141,9 +140,9 @@ def gen_market_sample(
     # Generate margin data
     _pcm_data = _gen_pcm_data(
         _mktshr_array[:, :2],
-        _mkt_sample_spec,
         _price_array,
         _aggregate_purchase_prob,
+        _mkt_sample_spec,
         _pcm_rng_seed_seq,
         nthreads,
     )
@@ -186,14 +185,14 @@ def gen_market_sample(
 def parse_seed_seq_list(
     _sseq_list: list[SeedSequence] | None,
     _mktshr_dist_type: SHRConstants,
-    _price_spec: PRIConstants,
+    _price_spec: PriceConstants,
     /,
-) -> tuple[SeedSequence, SeedSequence, SeedSequence | None, SeedSequence | None]:
+) -> SeedSequenceData:
     """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 _price_spec == PRIConstants.ZERO:
+    if _price_spec == PriceConstants.ZERO:
         _pr_rng_seed_seq = _sseq_list.pop() if _sseq_list else SeedSequence(pool_size=8)
 
     if _mktshr_dist_type == SHRConstants.UNI:
@@ -212,11 +211,8 @@ def parse_seed_seq_list(
             else (SeedSequence(pool_size=8) for _ in range(_seed_count))
         )
 
-    return (
-        _mktshr_rng_seed_seq,
-        _pcm_rng_seed_seq,
-        _fcount_rng_seed_seq,
-        _pr_rng_seed_seq,
+    return SeedSequenceData(
+        _mktshr_rng_seed_seq, _pcm_rng_seed_seq, _fcount_rng_seed_seq, _pr_rng_seed_seq
     )
 
 
@@ -230,7 +226,7 @@ def gen_divr_array(
     """
     Given merging-firm shares and related parameters, return diverion ratios.
 
-    If recapture is specified as "Outside-in" (RECConstants.OUTIN), then the
+    If recapture is specified as :attr:`mergeron.RECConstants.OUTIN`, then the
     choice-probability for the outside good must be supplied.
 
     Parameters

mergeron/gen/{investigations_stats.py → enforcement_stats.py}

@@ -1,5 +1,5 @@
 """
-Methods to format and print summary data on merger enforcement patterns.
+Methods to format and print summary statistics on merger enforcement patterns.
 
 """
 
@@ -7,7 +7,7 @@ import enum
 import shutil
 import subprocess
 from collections.abc import Mapping, Sequence
-from importlib.metadata import version
+from importlib import resources
 from pathlib import Path
 from types import SimpleNamespace
 
@@ -17,12 +17,12 @@ from jinja2 import Environment, FileSystemLoader, Template, select_autoescape
 from numpy.typing import NDArray
 from scipy.interpolate import interp1d  # type: ignore
 
-from .. import _PKG_NAME, DATA_DIR  # noqa: TID252
+from .. import _PKG_NAME, DATA_DIR, VERSION  # noqa: TID252
 from ..core import ftc_merger_investigations_data as fid  # noqa: TID252
 from ..core.proportions_tests import propn_ci  # noqa: TID252
-from . import TF, TI, INVResolution
+from . import INVResolution
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
 @enum.unique
@@ -108,38 +108,42 @@ class StatsContainer(SimpleNamespace):
 
 # Define the latex jinja environment
 # http://eosrei.net/articles/2015/11/latex-templates-python-and-jinja2-generate-pdfs
-latex_jinja_env = Environment(
-    block_start_string=R"((*",
-    block_end_string="*))",
-    variable_start_string=R"\JINVAR{",
-    variable_end_string="}",
-    comment_start_string=R"((#",  # r'#{',
-    comment_end_string=R"#))",  # '}',
-    line_statement_prefix="##",
-    line_comment_prefix="%#",
-    trim_blocks=True,
-    lstrip_blocks=True,
-    autoescape=select_autoescape(disabled_extensions=("tex.jinja2",)),
-    loader=FileSystemLoader(Path(__file__).parents[1] / "jinja_LaTex_templates"),
-)
+with resources.as_file(
+    resources.files(f"{_PKG_NAME}.data.jinja2_LaTeX_templates")
+) as _tmpl_folder:
+    latex_jinja_env = Environment(
+        block_start_string=R"((*",
+        block_end_string="*))",
+        variable_start_string=R"\JINVAR{",
+        variable_end_string="}",
+        comment_start_string=R"((#",  # r'#{',
+        comment_end_string=R"#))",  # '}',
+        line_statement_prefix="##",
+        line_comment_prefix="%#",
+        trim_blocks=True,
+        lstrip_blocks=True,
+        autoescape=select_autoescape(disabled_extensions=("tex.jinja2",)),
+        loader=FileSystemLoader(_tmpl_folder),
+    )
 
 # Place files related to rendering latex in output data directory
 if not (_out_path := DATA_DIR.joinpath(f"{_PKG_NAME}.cls")).is_file():
-    shutil.copyfile(
-        Path(__file__).parents[1].joinpath("jinja_LaTex_templates", "mergeron.cls"),
-        _out_path,
-    )
+    with resources.as_file(
+        resources.files(f"{_PKG_NAME}.data.jinja2_LaTeX_templates").joinpath(
+            "{_PKG_NAME}.cls"
+        )
+    ) as _in_path:
+        shutil.copy2(_in_path, _out_path)
 
 
 if not (_DOTTEX := DATA_DIR / Rf"{_PKG_NAME}_TikZTableSettings.tex").is_file():
     # Write to dottex
-    with _DOTTEX.open("w", encoding="UTF-8") as _table_helper_dottex:
-        _table_helper_dottex.write(
-            latex_jinja_env.get_template("setup_tikz_tables.tex.jinja2").render(
-                tmpl_data=StatsContainer()
-            )
+    with resources.as_file(
+        resources.files(f"{_PKG_NAME}.data.jinja2_LaTeX_templates").joinpath(
+            "setup_tikz_tables.tex"
         )
-        print("\n", file=_table_helper_dottex)
+    ) as _tex_path:
+        shutil.copy2(_tex_path, _DOTTEX)
 
 
 # Parameters and functions to interpolate selected HHI and ΔHHI values
@@ -172,7 +176,7 @@ HMG_PRESUMPTION_ZONE_DICT = {
 }
 
 ZONE_VALS = np.unique(
-    np.row_stack([
+    np.vstack([
         tuple(HMG_PRESUMPTION_ZONE_DICT[_k].values())
         for _k in HMG_PRESUMPTION_ZONE_DICT
     ]),
@@ -375,7 +379,7 @@ def table_no_lku(
     /,
 ) -> str:
     if _table_ind_group not in (
-        _igl := [_data_array_dict_sub[_v].ind_grp for _v in _data_array_dict_sub]
+        _igl := [_data_array_dict_sub[_v].industry_group for _v in _data_array_dict_sub]
     ):
         raise ValueError(
             f"Invalid value for industry group, {f'"{_table_ind_group}"'}."
@@ -386,19 +390,17 @@ def table_no_lku(
         _t
         for _t in _data_array_dict_sub
         if all((
-            _data_array_dict_sub[_t].ind_grp == _table_ind_group,
-            _data_array_dict_sub[_t].evid_cond == _table_evid_cond,
+            _data_array_dict_sub[_t].industry_group == _table_ind_group,
+            _data_array_dict_sub[_t].additional_evidence == _table_evid_cond,
         ))
     )
 
     return _tno
 
 
-def invres_cnts_byfirmcount(
-    _cnts_array: NDArray[np.integer[TI]], /
-) -> NDArray[np.int64]:
+def invres_cnts_byfirmcount(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
     _ndim_in = 1
-    return np.row_stack([
+    return np.vstack([
         np.concatenate([
             (f,),
             np.einsum("ij->j", _cnts_array[_cnts_array[:, 0] == f][:, _ndim_in:]),
@@ -407,9 +409,9 @@ def invres_cnts_byfirmcount(
     ])
 
 
-def invres_cnts_bydelta(_cnts_array: NDArray[np.integer[TI]], /) -> NDArray[np.int64]:
+def invres_cnts_bydelta(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
     _ndim_in = 2
-    return np.row_stack([
+    return np.vstack([
         np.concatenate([
             (f,),
             np.einsum("ij->j", _cnts_array[_cnts_array[:, 1] == f][:, _ndim_in:]),
@@ -418,9 +420,7 @@ def invres_cnts_bydelta(_cnts_array: NDArray[np.integer[TI]], /) -> NDArray[np.i
     ])
 
 
-def invres_cnts_byconczone(
-    _cnts_array: NDArray[np.integer[TI]], /
-) -> NDArray[np.int64]:
+def invres_cnts_byconczone(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
     # Prepare to tag clearance stats by presumption zone
     _hhi_zone_post_ranged = hhi_zone_post_ranger(_cnts_array[:, 0] / 1e4)
     _hhi_delta_ranged = hhi_delta_ranger(_cnts_array[:, 1] / 1e4)
@@ -453,7 +453,7 @@ def invres_cnts_byconczone(
 
             _conc_test = _level_test & _delta_test
 
-            _cnts_byhhipostanddelta = np.row_stack((
+            _cnts_byhhipostanddelta = np.vstack((
                 _cnts_byhhipostanddelta,
                 np.array(
                     (
@@ -475,7 +475,7 @@ def invres_cnts_byconczone(
             ])
         ).prod(axis=1) == 1
 
-        _cnts_byconczone = np.row_stack((
+        _cnts_byconczone = np.vstack((
             _cnts_byconczone,
             np.concatenate(
                 (
@@ -492,7 +492,7 @@ def invres_cnts_byconczone(
 
 
 def latex_tbl_invres_stats_1dim(
-    _inparr: NDArray[np.floating[TF] | np.integer[TI]],
+    _inparr: NDArray[np.float64 | np.int64],
     _totals_row: int | None = None,
     /,
     *,
@@ -527,7 +527,7 @@ def latex_tbl_invres_stats_1dim(
     if sort_order == SortSelector.REV:
         _inparr = _inparr[::-1]
 
-    _inparr = np.row_stack((_inparr, _in_totals_row))
+    _inparr = np.vstack((_inparr, _in_totals_row))
 
     _stats_hdr_list, _stats_dat_list = [], []
     for _stats_row in _inparr:
@@ -544,7 +544,7 @@ def latex_tbl_invres_stats_1dim(
 
 
 def latex_tbl_invres_stats_byzone(
-    _inparr: NDArray[np.floating[TF] | np.integer[TI]],
+    _inparr: NDArray[np.float64 | np.int64],
     _totals_row: int | None = None,
     /,
     *,
@@ -559,7 +559,7 @@ def latex_tbl_invres_stats_byzone(
         _zone_str_keys = _zone_str_keys[:-1][::-1] + [_zone_str_keys[-1]]
 
     if _totals_row is None:
-        _inparr = np.row_stack((
+        _inparr = np.vstack((
             _inparr,
             np.concatenate((
                 [fid.TTL_KEY, -1, -1],
@@ -611,8 +611,8 @@ def latex_tbl_invres_stats_byzone(
 
 
 def _stats_formatted_row(
-    _stats_row_cnt: NDArray[np.integer[TI]],
-    _stats_row_tot: NDArray[np.integer[TI]],
+    _stats_row_cnt: NDArray[np.int64],
+    _stats_row_tot: NDArray[np.int64],
     _return_type_sel: StatsReturnSelector,
     /,
 ) -> list[list[str]]:
@@ -691,19 +691,21 @@ def render_table_pdf(
         )
         print("\n", file=_table_coll_file)
 
-    _run_rc = subprocess.run(
-        f"latexmk -f -quiet -synctex=0 -interaction=nonstopmode -file-line-error -pdflua {_table_coll_path}".split(),  # noqa: S603
+    _run_rc = subprocess.run(  # noqa: S603
+        f"latexmk -f -quiet -synctex=0 -interaction=nonstopmode -file-line-error -pdflua {_table_coll_path}".split(),
         check=True,
         cwd=DATA_DIR,
     )
     if _run_rc:
-        subprocess.run(
-            "latexmk -quiet -c".split(),  # noqa: S603
-            check=True,
-            cwd=DATA_DIR,
-        )
+        subprocess.run("latexmk -quiet -c".split(), check=True, cwd=DATA_DIR)  # noqa: S603
     del _run_rc
 
     print(
         f"Tables rendered to path, {f"{Path(DATA_DIR / _table_coll_path).with_suffix(".pdf")}"}"
     )
+
+
+if __name__ == "__main__":
+    print(
+        "This module provides methods to format and print summary statistics on merger enforcement patterns.."
+    )

mergeron/gen/market_sample.py

@@ -5,18 +5,16 @@ 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 VERSION  # noqa: TID252
+from ..core.guidelines_boundaries import HMGThresholds  # 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)
+__version__ = VERSION
 
 
 @define(slots=False)
@@ -50,7 +48,7 @@ class MarketSample(MarketSpec):
 
     def estimate_invres_counts(
         self,
-        _invres_parm_vec: gbl.HMGThresholds,
+        _invres_parm_vec: HMGThresholds,
         _upp_test_regime: UPPTestRegime,
         /,
         *,
@@ -73,7 +71,5 @@ class MarketSample(MarketSpec):
             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
-                )
+        if save_data_to_file:
+            save_data_to_hdf5(self.invres_counts, save_data_to_file=save_data_to_file)

mergeron/gen/upp_tests.py

@@ -1,24 +1,22 @@
 """
-Methods to estimate intrinsic clearnace rates and intrinsic enforcement rates
+Methods to compute intrinsic clearance rates and intrinsic enforcement rates
 from generated market data.
 
 """
 
 from collections.abc import Sequence
 from contextlib import suppress
-from importlib.metadata import version
 from pathlib import Path
 from typing import Literal, TypeAlias, TypedDict
 
 import numpy as np
 import tables as ptb  # type: ignore
+from icecream import ic  # type: ignore
 from joblib import Parallel, cpu_count, delayed  # type: ignore
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
 
-from mergeron.core.pseudorandom_numbers import TF, TI
-
-from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
@@ -31,10 +29,9 @@ from . import (
     UPPTestsRaw,
 )
 from . import data_generation as dgl
-from . import investigations_stats as isl
-
-__version__ = version(_PKG_NAME)
+from . import enforcement_stats as esl
 
+__version__ = VERSION
 
 ptb.parameters.MAX_NUMEXPR_THREADS = 8
 ptb.parameters.MAX_BLOSC_THREADS = 4
@@ -45,11 +42,11 @@ SaveData: TypeAlias = Literal[False] | tuple[Literal[True], ptb.File, ptb.Group]
 class INVRESCntsArgs(TypedDict, total=False):
     "Keyword arguments of function, :code:`sim_invres_cnts`"
 
-    saved_array_name_suffix: str
-    save_data_to_file: SaveData
     sample_size: int
     seed_seq_list: list[SeedSequence] | None
     nthreads: int
+    save_data_to_file: SaveData
+    saved_array_name_suffix: str
 
 
 def sim_invres_cnts_ll(
@@ -58,11 +55,11 @@ def sim_invres_cnts_ll(
     _sim_test_regime: UPPTestRegime,
     /,
     *,
-    saved_array_name_suffix: str = "",
-    save_data_to_file: SaveData = False,
     sample_size: int = 10**6,
     seed_seq_list: list[SeedSequence] | None = None,
     nthreads: int = 16,
+    save_data_to_file: SaveData = False,
+    saved_array_name_suffix: str = "",
 ) -> UPPTestsCounts:
     """A function to parallelize data-generation and testing
 
@@ -171,11 +168,11 @@ def sim_invres_cnts(
     _sim_test_regime: UPPTestRegime,
     /,
     *,
-    saved_array_name_suffix: str = "",
-    save_data_to_file: SaveData = False,
     sample_size: int = 10**6,
     seed_seq_list: list[SeedSequence] | None = None,
     nthreads: int = 16,
+    save_data_to_file: SaveData = False,
+    saved_array_name_suffix: str = "",
 ) -> UPPTestsCounts:
     # Generate market data
     _market_data_sample = dgl.gen_market_sample(
@@ -235,7 +232,7 @@ def invres_cnts(
         for _firm_cnt in 2 + np.arange(_max_firm_count):
             _firm_count_test = _fcounts == _firm_cnt
 
-            _invres_cnts_sim_byfirmcount_array = np.row_stack((
+            _invres_cnts_sim_byfirmcount_array = np.vstack((
                 _invres_cnts_sim_byfirmcount_array,
                 np.array([
                     _firm_cnt,
@@ -257,12 +254,12 @@ def invres_cnts(
         _invres_cnts_sim_byfirmcount_array[0] = 2
 
     # Clearance/enfrocement counts --- by delta
-    _hhi_delta_ranged = isl.hhi_delta_ranger(_hhi_delta)
+    _hhi_delta_ranged = esl.hhi_delta_ranger(_hhi_delta)
     _invres_cnts_sim_bydelta_array = -1 * np.ones(_stats_rowlen, np.int64)
-    for _hhi_delta_lim in isl.HHI_DELTA_KNOTS[:-1]:
+    for _hhi_delta_lim in esl.HHI_DELTA_KNOTS[:-1]:
         _hhi_delta_test = _hhi_delta_ranged == _hhi_delta_lim
 
-        _invres_cnts_sim_bydelta_array = np.row_stack((
+        _invres_cnts_sim_bydelta_array = np.vstack((
             _invres_cnts_sim_bydelta_array,
             np.array([
                 _hhi_delta_lim,
@@ -280,13 +277,13 @@ def invres_cnts(
 
     # Clearance/enfrocement counts --- by zone
     try:
-        _hhi_zone_post_ranged = isl.hhi_zone_post_ranger(_hhi_post)
+        _hhi_zone_post_ranged = esl.hhi_zone_post_ranger(_hhi_post)
     except ValueError as _err:
-        print(_hhi_post)
+        ic(_hhi_post)
         raise _err
 
     _stats_byconczone_sim = -1 * np.ones(_stats_rowlen + 1, np.int64)
-    for _hhi_zone_post_knot in isl.HHI_POST_ZONE_KNOTS[:-1]:
+    for _hhi_zone_post_knot in esl.HHI_POST_ZONE_KNOTS[:-1]:
         _level_test = _hhi_zone_post_ranged == _hhi_zone_post_knot
 
         for _hhi_zone_delta_knot in [0, 100, 200]:
@@ -298,7 +295,7 @@ def invres_cnts(
 
             _conc_test = _level_test & _delta_test
 
-            _stats_byconczone_sim = np.row_stack((
+            _stats_byconczone_sim = np.vstack((
                 _stats_byconczone_sim,
                 np.array([
                     _hhi_zone_post_knot,
@@ -313,7 +310,7 @@ def invres_cnts(
                 ]),
             ))
 
-    _invres_cnts_sim_byconczone_array = isl.invres_cnts_byconczone(
+    _invres_cnts_sim_byconczone_array = esl.invres_cnts_byconczone(
         _stats_byconczone_sim[1:]
     )
     del _stats_byconczone_sim
@@ -472,11 +469,11 @@ def initialize_hd5(
         _h5_path.unlink()
     _h5_file = ptb.open_file(_h5_path, mode="w", title=_h5_title)
     _save_data_to_file: tuple[Literal[True], ptb.File, str] = (True, _h5_file, "/")
-    _next_subgroup_name = "invres_{}_{}_{}_{}".format(
+    _next_subgroup_name_root = "invres_{}_{}_{}_{}".format(
         _hmg_pub_year,
         *(getattr(_test_regime, _f.name).name for _f in _test_regime.__attrs_attrs__),
     )
-    return _save_data_to_file, _next_subgroup_name
+    return _save_data_to_file, _next_subgroup_name_root
 
 
 def save_data_to_hdf5(
@@ -504,7 +501,7 @@ def save_data_to_hdf5(
 
 
 def save_array_to_hdf5(
-    _array_obj: NDArray[np.floating[TF] | np.integer[TI] | np.bool_],
+    _array_obj: NDArray[np.float64 | np.int64 | np.bool_],
     _array_name: str,
     _h5_group: ptb.Group,
     _h5_file: ptb.File,
@@ -525,3 +522,9 @@ def save_array_to_hdf5(
         filters=ptb.Filters(complevel=3, complib="blosc:lz4hc", fletcher32=True),
     )
     _h5_array[:] = _array_obj
+
+
+if __name__ == "__main__":
+    print(
+        "This module defines classes with methods for generating UPP test arrays and UPP test-counts arrays on given data."
+    )