mergeron 2024.739099.0__py3-none-any.whl → 2024.739099.2__py3-none-any.whl

mergeron/__init__.py

@@ -2,12 +2,14 @@ from __future__ import annotations
 
 import enum
 from pathlib import Path
+from typing import TypeAlias, TypeVar
 
 import numpy as np
+from numpy.typing import NBitBase, NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739099.0"
+VERSION = "2024.739099.2"
 
 __version__ = VERSION
 
@@ -24,6 +26,18 @@ if not DATA_DIR.is_dir():
 np.set_printoptions(precision=18)
 
 
+TI = TypeVar("TI", bound=NBitBase)
+ArrayINT = NDArray[np.integer[TI]]
+TF = TypeVar("TF", bound=NBitBase)
+ArrayFloat = NDArray[np.floating[TF]]
+
+
+ArrayBoolean: TypeAlias = NDArray[np.bool_]
+
+ArrayDouble: TypeAlias = NDArray[np.float64]
+ArrayBIGINT: TypeAlias = NDArray[np.int64]
+
+
 @enum.unique
 class RECConstants(enum.StrEnum):
     """Recapture rate - derivation methods."""

mergeron/core/damodaran_margin_data.py

@@ -43,11 +43,10 @@ import msgpack  # type:ignore
 import numpy as np
 import urllib3
 from numpy.random import PCG64DXSM, Generator, SeedSequence
-from numpy.typing import NDArray
 from scipy import stats  # type: ignore
 from xlrd import open_workbook  # type: ignore
 
-from .. import _PKG_NAME, DATA_DIR, VERSION  # noqa: TID252
+from .. import _PKG_NAME, DATA_DIR, VERSION, ArrayDouble  # noqa: TID252
 
 __version__ = VERSION
 
@@ -137,7 +136,7 @@ def mgn_data_getter(  # noqa: PLR0912
 
 def mgn_data_builder(
     _mgn_tbl_dict: Mapping[str, Mapping[str, float | int]] | None = None, /
-) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+) -> tuple[ArrayDouble, ArrayDouble, ArrayDouble]:
     if _mgn_tbl_dict is None:
         _mgn_tbl_dict = mgn_data_getter()
 
@@ -190,7 +189,7 @@ def mgn_data_resampler(
     /,
     *,
     seed_sequence: SeedSequence | None = None,
-) -> NDArray[np.float64]:
+) -> ArrayDouble:
     """
     Generate draws from the empirical distribution bassed on Prof. Damodaran's margin data.
 

mergeron/core/ftc_merger_investigations_data.py

@@ -23,9 +23,8 @@ import re2 as re  # type: ignore
 import urllib3
 from bs4 import BeautifulSoup
 from numpy.testing import assert_array_equal
-from numpy.typing import NDArray
 
-from .. import _PKG_NAME, DATA_DIR, VERSION  # noqa: TID252
+from .. import _PKG_NAME, DATA_DIR, VERSION, ArrayBIGINT  # noqa: TID252
 
 __version__ = VERSION
 
@@ -93,7 +92,7 @@ CNT_FCOUNT_DICT = {
 class INVTableData(NamedTuple):
     industry_group: str
     additional_evidence: str
-    data_array: NDArray[np.int64]
+    data_array: ArrayBIGINT
 
 
 INVData: TypeAlias = Mapping[str, dict[str, dict[str, INVTableData]]]
@@ -585,12 +584,12 @@ def _identify_table_type(_tnstr: str = CONC_TABLE_ALL, /) -> tuple[str, int, str
 
 def _process_table_blks_conc_type(
     _table_blocks: Sequence[Sequence[str]], /
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     _conc_row_pat = re.compile(r"((?:0|\d,\d{3}) (?:- \d+,\d{3}|\+)|TOTAL)")
 
     _col_titles_array = tuple(CONC_DELTA_DICT.values())
-    _col_totals: NDArray[np.int64] = np.zeros(len(_col_titles_array), np.int64)
-    _invdata_array: NDArray[np.int64] = np.array(None)
+    _col_totals: ArrayBIGINT = np.zeros(len(_col_titles_array), np.int64)
+    _invdata_array: ArrayBIGINT = np.array(None)
 
     for _tbl_blk in _table_blocks:
         if _conc_row_pat.match(_blk_str := _tbl_blk[-3]):
@@ -642,13 +641,11 @@ def _process_table_blks_conc_type(
 
 def _process_table_blks_cnt_type(
     _table_blocks: Sequence[Sequence[str]], /
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     _cnt_row_pat = re.compile(r"(\d+ (?:to \d+|\+)|TOTAL)")
 
-    _invdata_array: NDArray[np.int64] = np.array(None)
-    _col_totals: NDArray[np.int64] = np.zeros(
-        3, np.int64
-    )  # "enforced", "closed", "total"
+    _invdata_array: ArrayBIGINT = np.array(None)
+    _col_totals: ArrayBIGINT = np.zeros(3, np.int64)  # "enforced", "closed", "total"
 
     for _tbl_blk in _table_blocks:
         if _cnt_row_pat.match(_blk_str := _tbl_blk[-3]):

mergeron/core/guidelines_boundaries.py

@@ -12,9 +12,8 @@ from typing import Literal, TypeAlias
 import numpy as np
 from attrs import Attribute, field, frozen, validators
 from mpmath import mp, mpf  # type: ignore
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import VERSION, ArrayDouble, RECConstants, UPPAggrSelector  # noqa: TID252
 from . import guidelines_boundary_functions as gbfn
 
 __version__ = VERSION
@@ -191,7 +190,7 @@ class ConcentrationBoundary:
         validator=(validators.instance_of(str), _concentration_measure_name_validator),
     )
 
-    coordinates: NDArray[np.float64] = field(init=False, kw_only=True)
+    coordinates: ArrayDouble = field(init=False, kw_only=True)
     """Market-share pairs as Cartesian coordinates of points on the concentration boundary."""
 
     area: float = field(init=False, kw_only=True)
@@ -321,7 +320,7 @@ class DiversionRatioBoundary:
 
     """
 
-    coordinates: NDArray[np.float64] = field(init=False, kw_only=True)
+    coordinates: ArrayDouble = field(init=False, kw_only=True)
     """Market-share pairs as Cartesian coordinates of points on the diversion ratio boundary."""
 
     area: float = field(init=False, kw_only=True)

mergeron/core/guidelines_boundary_functions.py

@@ -4,9 +4,8 @@ from typing import Any, Literal, TypedDict
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
-from numpy.typing import NDArray
 
-from .. import VERSION  # noqa: TID252
+from .. import VERSION, ArrayBIGINT, ArrayDouble  # noqa: TID252
 
 __version__ = VERSION
 
@@ -27,7 +26,7 @@ class ShareRatioBoundaryKeywords(TypedDict, total=False):
 class GuidelinesBoundary:
     """Output of a Guidelines boundary function."""
 
-    coordinates: NDArray[np.float64]
+    coordinates: ArrayDouble
     """Market-share pairs as Cartesian coordinates of points on the boundary."""
 
     area: float
@@ -668,7 +667,7 @@ def shrratio_boundary_max(
     """
 
     # _r_val is not needed for max boundary, but is specified for consistency
-    # of function call with other shrratio_mgnsym_boundary functions
+    # of function call with other share-ratio boundary functions
     del _r_val
     _delta_star = mpf(f"{_delta_star}")
     _s_intcpt = _delta_star
@@ -718,11 +717,11 @@ def _shrratio_boundary_intcpt(
 
 
 def lerp(
-    _x1: int | float | mpf | NDArray[np.float64 | np.int64] = 3,
-    _x2: int | float | mpf | NDArray[np.float64 | np.int64] = 1,
+    _x1: int | float | mpf | ArrayDouble | ArrayBIGINT = 3,
+    _x2: int | float | mpf | ArrayDouble | ArrayBIGINT = 1,
     _r: float | mpf = 0.25,
     /,
-) -> float | mpf | NDArray[np.float64]:
+) -> float | mpf | ArrayDouble:
     """
     From the function of the same name in the C++ standard [2]_
 
@@ -884,9 +883,9 @@ def boundary_plot(*, mktshares_plot_flag: bool = True) -> tuple[Any, ...]:
         mktshares_plot_flag: bool = False,
         mktshares_axlbls_flag: bool = False,
     ) -> mpa.Axes:
-        # Set the width of axis gridlines, and tick marks:
+        # Set the width of axis grid lines, and tick marks:
         # both axes, both major and minor ticks
-        # Frame, grid, and facecolor
+        # Frame, grid, and face color
         for _spos0 in "left", "bottom":
             _ax1.spines[_spos0].set_linewidth(0.5)
             _ax1.spines[_spos0].set_zorder(5)

mergeron/core/guidelines_boundary_functions_extra.py

@@ -13,11 +13,10 @@ from typing import Literal
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
-from numpy.typing import NDArray
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
 from sympy import lambdify, simplify, solve, symbols  # type: ignore
 
-from .. import VERSION  # noqa: TID252
+from .. import VERSION, ArrayDouble  # noqa: TID252
 from .guidelines_boundary_functions import (
     GuidelinesBoundary,
     _shrratio_boundary_intcpt,
@@ -33,7 +32,7 @@ mp.trap_complex = True
 
 @dataclass(slots=True, frozen=True)
 class GuidelinesBoundaryCallable:
-    boundary_function: Callable[[NDArray[np.float64]], NDArray[np.float64]]
+    boundary_function: Callable[[ArrayDouble], ArrayDouble]
     area: float
     s_naught: float = 0
 

mergeron/core/pseudorandom_numbers.py

@@ -13,9 +13,8 @@ from typing import Literal
 
 import numpy as np
 from numpy.random import PCG64DXSM, Generator, SeedSequence
-from numpy.typing import NDArray
 
-from .. import VERSION  # noqa: TID252
+from .. import VERSION, ArrayDouble  # noqa: TID252
 
 __version__ = VERSION
 
@@ -134,13 +133,13 @@ class MultithreadedRNG:
 
     def __init__(
         self,
-        _out_array: NDArray[np.float64],
+        _out_array: ArrayDouble,
         /,
         *,
         dist_type: Literal[
             "Beta", "Dirichlet", "Gaussian", "Normal", "Random", "Uniform"
         ] = "Uniform",
-        dist_parms: NDArray[np.float64] | None = DIST_PARMS_DEFAULT,
+        dist_parms: ArrayDouble | None = DIST_PARMS_DEFAULT,
         seed_sequence: SeedSequence | None = None,
         nthreads: int = NTHREADS,
     ):
@@ -206,8 +205,8 @@ class MultithreadedRNG:
         def _fill(
             _rng: np.random.Generator,
             _dist_type: str,
-            _dist_parms: NDArray[np.float64],
-            _out: NDArray[np.float64],
+            _dist_parms: ArrayDouble,
+            _out: ArrayDouble,
             _first: int,
             _last: int,
             /,

mergeron/gen/__init__.py

@@ -1,5 +1,5 @@
 """
-Defines constants and containers for industry data generation and testing
+Defines constants and containers for industry data generation and testing.
 
 """
 
@@ -11,9 +11,15 @@ from typing import ClassVar, Protocol
 
 import numpy as np
 from attrs import Attribute, cmp_using, define, field, frozen, validators
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import (  # noqa: TID252
+    VERSION,
+    ArrayBIGINT,
+    ArrayBoolean,
+    ArrayDouble,
+    RECConstants,
+    UPPAggrSelector,
+)
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
 
 __version__ = VERSION
@@ -128,7 +134,7 @@ class ShareSpec:
     dist_type: SHRConstants
     """See :class:`SHRConstants`"""
 
-    dist_parms: NDArray[np.float64] | None = field(
+    dist_parms: ArrayDouble | None = field(
         default=None, eq=cmp_using(eq=np.array_equal)
     )
     """Parameters for tailoring market-share distribution
@@ -139,9 +145,9 @@ class ShareSpec:
     type of Dirichlet-distribution specified.
 
     """
-    firm_counts_weights: NDArray[np.float64 | np.int64] | None = field(
-        default=None, eq=cmp_using(eq=np.array_equal)
-    )
+    firm_counts_weights: (
+        ArrayDouble | ArrayBIGINT | ArrayDouble | ArrayBIGINT | None
+    ) = field(default=None, eq=cmp_using(eq=np.array_equal))
     """Relative or absolute frequencies of firm counts
 
 
@@ -193,7 +199,7 @@ class PCMSpec:
     dist_type: PCMConstants
     """See :class:`PCMConstants`"""
 
-    dist_parms: NDArray[np.float64] | None
+    dist_parms: ArrayDouble | None
     """Parameter specification for tailoring PCM distribution
 
     For Uniform distribution, bounds of the distribution; defaults to `(0, 1)`;
@@ -356,39 +362,39 @@ class MarketSpec:
 class MarketDataSample:
     """Container for generated markets data sample."""
 
-    frmshr_array: NDArray[np.float64]
+    frmshr_array: ArrayDouble
     """Merging-firm shares (with two merging firms)"""
 
-    pcm_array: NDArray[np.float64]
+    pcm_array: ArrayDouble
     """Merging-firms' prices (normalized to 1, in default specification)"""
 
-    price_array: NDArray[np.float64]
+    price_array: ArrayDouble
     """Merging-firms' price-cost margins (PCM)"""
 
-    fcounts: NDArray[np.int64]
+    fcounts: ArrayBIGINT
     """Number of firms in market"""
 
-    aggregate_purchase_prob: NDArray[np.float64]
+    aggregate_purchase_prob: ArrayDouble
     """
     One (1) minus probability that the outside good is chosen
 
     Converts market shares to choice probabilities by multiplication.
     """
 
-    nth_firm_share: NDArray[np.float64]
+    nth_firm_share: ArrayDouble
     """Market-share of n-th firm
 
     Relevant for testing for draws the do or
     do not meet HSR filing thresholds.
     """
 
-    divr_array: NDArray[np.float64]
+    divr_array: ArrayDouble
     """Diversion ratio between the merging firms"""
 
-    hhi_post: NDArray[np.float64]
+    hhi_post: ArrayDouble
     """Post-merger change in Herfindahl-Hirschmann Index (HHI)"""
 
-    hhi_delta: NDArray[np.float64]
+    hhi_delta: ArrayDouble
     """Change in HHI from combination of merging firms"""
 
 
@@ -400,16 +406,16 @@ class ShareDataSample:
     and aggregate purchase probability.
     """
 
-    mktshr_array: NDArray[np.float64]
+    mktshr_array: ArrayDouble
     """All-firm shares (with two merging firms)"""
 
-    fcounts: NDArray[np.int64]
+    fcounts: ArrayBIGINT
     """All-firm-count for each draw"""
 
-    nth_firm_share: NDArray[np.float64]
+    nth_firm_share: ArrayDouble
     """Market-share of n-th firm"""
 
-    aggregate_purchase_prob: NDArray[np.float64]
+    aggregate_purchase_prob: ArrayDouble
     """Converts market shares to choice probabilities by multiplication."""
 
 
@@ -417,10 +423,10 @@ class ShareDataSample:
 class PriceDataSample:
     """Container for generated price array, and related."""
 
-    price_array: NDArray[np.float64]
+    price_array: ArrayDouble
     """Merging-firms' prices"""
 
-    hsr_filing_test: NDArray[np.bool_]
+    hsr_filing_test: ArrayBoolean
     """Flags draws as meeting HSR filing thresholds or not"""
 
 
@@ -428,10 +434,10 @@ class PriceDataSample:
 class MarginDataSample:
     """Container for generated margin array and related MNL test array."""
 
-    pcm_array: NDArray[np.float64]
+    pcm_array: ArrayDouble
     """Merging-firms' PCMs"""
 
-    mnl_test_array: NDArray[np.bool_]
+    mnl_test_array: ArrayBoolean
     """Flags infeasible observations as False and rest as True
 
     Applying restrictions from Bertrand-Nash oligopoly
@@ -476,18 +482,18 @@ class UPPTestsRaw:
     :func:`enforcement_stats.gen_upp_arrays`.
     """
 
-    guppi_test_simple: NDArray[np.bool_]
+    guppi_test_simple: ArrayBoolean
     """True if GUPPI estimate meets criterion"""
 
-    guppi_test_compound: NDArray[np.bool_]
+    guppi_test_compound: ArrayBoolean
     """True if both GUPPI estimate and diversion ratio estimate
     meet criterion
     """
 
-    cmcr_test: NDArray[np.bool_]
+    cmcr_test: ArrayBoolean
     """True if CMCR estimate meets criterion"""
 
-    ipr_test: NDArray[np.bool_]
+    ipr_test: ArrayBoolean
     """True if IPR (partial price-simulation) estimate meets criterion"""
 
 
@@ -498,9 +504,9 @@ class UPPTestsCounts:
     Resolution may be either :attr:`INVResolution.ENFT` or :attr:`INVResolution.CLRN`.
     """
 
-    by_firm_count: NDArray[np.int64]
-    by_delta: NDArray[np.int64]
-    by_conczone: NDArray[np.int64]
+    by_firm_count: ArrayBIGINT
+    by_delta: ArrayBIGINT
+    by_conczone: ArrayBIGINT
     """Zones are "unoncentrated", "moderately concentrated", and "highly concentrated"
     """
 

mergeron/gen/_data_generation_functions.py

@@ -9,9 +9,8 @@ from typing import Literal
 import numpy as np
 from attrs import evolve
 from numpy.random import SeedSequence
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants  # noqa: TID252
+from .. import VERSION, ArrayBIGINT, ArrayDouble, RECConstants  # noqa: TID252
 from ..core.damodaran_margin_data import mgn_data_resampler  # noqa: TID252
 from ..core.pseudorandom_numbers import (  # noqa: TID252
     DIST_PARMS_DEFAULT,
@@ -112,7 +111,7 @@ def _gen_share_data(
 
 def _gen_market_shares_uniform(
     _s_size: int = 10**6,
-    _dist_parms_mktshr: NDArray[np.float64] | None = DIST_PARMS_DEFAULT,
+    _dist_parms_mktshr: ArrayDouble | None = DIST_PARMS_DEFAULT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
     /,
@@ -137,7 +136,7 @@ def _gen_market_shares_uniform(
     """
 
     _frmshr_array = np.empty((_s_size, 2), dtype=np.float64)
-    _dist_parms_mktshr: NDArray[np.float64] = (
+    _dist_parms_mktshr: ArrayDouble = (
         DIST_PARMS_DEFAULT if _dist_parms_mktshr is None else _dist_parms_mktshr
     )
     _mrng = MultithreadedRNG(
@@ -149,7 +148,7 @@ def _gen_market_shares_uniform(
     )
     _mrng.fill()
     # Convert draws on U[0, 1] to Uniformly-distributed draws on simplex, s_1 + s_2 <= 1
-    _frmshr_array = np.sort(_frmshr_array, axis=1)
+    _frmshr_array.sort(axis=1)
     _frmshr_array = np.column_stack((
         _frmshr_array[:, 0],
         _frmshr_array[:, 1] - _frmshr_array[:, 0],
@@ -163,7 +162,7 @@ def _gen_market_shares_uniform(
         _frmshr_array, ((0, 0), (0, 1)), "constant", constant_values=np.nan
     )
 
-    _fcounts: NDArray[np.int64] = np.ones((_s_size, 1), np.int64) * np.nan  # type: ignore
+    _fcounts: ArrayBIGINT = np.ones((_s_size, 1), np.int64) * np.nan  # type: ignore
     _nth_firm_share, _aggregate_purchase_prob = (
         np.nan * np.ones((_s_size, 1), np.float64) for _ in range(2)
     )
@@ -177,8 +176,8 @@ def _gen_market_shares_dirichlet_multisample(
     _s_size: int = 10**6,
     _recapture_form: RECConstants = RECConstants.INOUT,
     _dist_type_dir: SHRConstants = SHRConstants.DIR_FLAT,
-    _dist_parms_dir: NDArray[np.float64] | None = None,
-    _firm_count_wts: NDArray[np.float64] | None = None,
+    _dist_parms_dir: ArrayDouble | None = None,
+    _firm_count_wts: ArrayDouble | None = None,
     _fcount_rng_seed_seq: SeedSequence | None = None,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
@@ -216,7 +215,7 @@ def _gen_market_shares_dirichlet_multisample(
 
     """
 
-    _firm_count_wts: NDArray[np.float64] = (
+    _firm_count_wts: ArrayDouble = (
         FCOUNT_WTS_DEFAULT if _firm_count_wts is None else _firm_count_wts
     )
 
@@ -243,7 +242,7 @@ def _gen_market_shares_dirichlet_multisample(
 
     if _dist_type_dir == SHRConstants.DIR_COND:
 
-        def _gen_dir_alphas(_fcv: int) -> NDArray[np.float64]:
+        def _gen_dir_alphas(_fcv: int) -> ArrayDouble:
             _dat = [2.5] * 2
             if _fcv > len(_dat):
                 _dat += [1.0 / (_fcv - 2)] * (_fcv - 2)
@@ -251,7 +250,7 @@ def _gen_market_shares_dirichlet_multisample(
 
     else:
 
-        def _gen_dir_alphas(_fcv: int) -> NDArray[np.float64]:
+        def _gen_dir_alphas(_fcv: int) -> ArrayDouble:
             return np.array(_dir_alphas_full[:_fcv], dtype=np.float64)  # type: ignore
 
     _fcounts = prng(_fcount_rng_seed_seq).choice(
@@ -312,7 +311,7 @@ def _gen_market_shares_dirichlet_multisample(
 
 
 def _gen_market_shares_dirichlet(
-    _dir_alphas: NDArray[np.float64],
+    _dir_alphas: ArrayDouble,
     _s_size: int = 10**6,
     _recapture_form: RECConstants = RECConstants.INOUT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
@@ -394,9 +393,9 @@ def _gen_market_shares_dirichlet(
 
 
 def _gen_margin_price_data(
-    _frmshr_array: NDArray[np.float64],
-    _nth_firm_share: NDArray[np.float64],
-    _aggregate_purchase_prob: NDArray[np.float64],
+    _frmshr_array: ArrayDouble,
+    _nth_firm_share: ArrayDouble,
+    _aggregate_purchase_prob: ArrayDouble,
     _pcm_spec: PCMSpec,
     _price_spec: PriceConstants,
     _hsr_filing_test_type: SSZConstants,
@@ -472,11 +471,6 @@ def _gen_margin_price_data(
                     1 + _m1_nr,
                 )
                 _mnl_test_array = (_pcm_array[:, [1]] >= 0) & (_pcm_array[:, [1]] <= 1)
-            else:
-                # Generate i.i.d. PCMs
-                # Construct price_array = 1/ (1 - pcm_array)
-                # Rgenerate MNL test
-                pass
 
             _margin_data = MarginDataSample(_pcm_array[:, :2], _mnl_test_array)
             del _price_array_here
@@ -543,8 +537,8 @@ def _gen_margin_price_data(
 
 # marked for deletion
 def _gen_price_data(
-    _frmshr_array: NDArray[np.float64],
-    _nth_firm_share: NDArray[np.float64],
+    _frmshr_array: ArrayDouble,
+    _nth_firm_share: ArrayDouble,
     _price_spec: PriceConstants,
     _hsr_filing_test_type: SSZConstants,
     _seed_seq: SeedSequence | None = None,
@@ -630,9 +624,9 @@ def _gen_price_data(
 
 
 def _gen_margin_data(
-    _frmshr_array: NDArray[np.float64],
-    _price_array: NDArray[np.float64],
-    _aggregate_purchase_prob: NDArray[np.float64],
+    _frmshr_array: ArrayDouble,
+    _price_array: ArrayDouble,
+    _aggregate_purchase_prob: ArrayDouble,
     _pcm_spec: PCMSpec,
     _pcm_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
@@ -719,8 +713,8 @@ def _gen_margin_data(
 
 
 def _beta_located(
-    _mu: float | NDArray[np.float64], _sigma: float | NDArray[np.float64], /
-) -> NDArray[np.float64]:
+    _mu: float | ArrayDouble, _sigma: float | ArrayDouble, /
+) -> ArrayDouble:
     """
     Given mean and stddev, return shape parameters for corresponding Beta distribution
 
@@ -743,7 +737,7 @@ def _beta_located(
     return np.array([_mu * _mul, (1 - _mu) * _mul], dtype=np.float64)
 
 
-def beta_located_bound(_dist_parms: NDArray[np.float64], /) -> NDArray[np.float64]:
+def beta_located_bound(_dist_parms: ArrayDouble, /) -> ArrayDouble:
     R"""
     Return shape parameters for a non-standard beta, given the mean, stddev, range
 

mergeron/gen/data_generation.py

@@ -10,9 +10,8 @@ from typing import NamedTuple
 
 import numpy as np
 from numpy.random import SeedSequence
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants  # noqa: TID252
+from .. import VERSION, ArrayDouble, RECConstants  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
     FM2Constants,
@@ -227,10 +226,10 @@ def parse_seed_seq_list(
 def gen_divr_array(
     _recapture_form: RECConstants,
     _recapture_rate: float | None,
-    _frmshr_array: NDArray[np.float64],
-    _aggregate_purchase_prob: NDArray[np.float64] = EMPTY_ARRAY_DEFAULT,
+    _frmshr_array: ArrayDouble,
+    _aggregate_purchase_prob: ArrayDouble = EMPTY_ARRAY_DEFAULT,
     /,
-) -> NDArray[np.float64]:
+) -> ArrayDouble:
     """
     Given merging-firm shares and related parameters, return diverion ratios.
 
@@ -259,7 +258,7 @@ def gen_divr_array(
 
     """
 
-    _divr_array: NDArray[np.float64]
+    _divr_array: ArrayDouble
     if _recapture_form == RECConstants.FIXED:
         _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
 

mergeron/gen/enforcement_stats.py

@@ -15,12 +15,19 @@ from typing import Literal
 import numpy as np
 import re2 as re  # type: ignore
 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, VERSION  # noqa: TID252
+from scipy.stats import beta, norm  # type: ignore
+
+from .. import (  # noqa: TID252
+    _PKG_NAME,
+    DATA_DIR,
+    TI,
+    VERSION,
+    ArrayBIGINT,
+    ArrayDouble,
+    ArrayINT,
+)
 from ..core import ftc_merger_investigations_data as fid  # noqa: TID252
-from ..core.proportions_tests import propn_ci  # noqa: TID252
 from . import INVResolution
 
 __version__ = VERSION
@@ -114,7 +121,7 @@ if not (_out_path := DATA_DIR.joinpath(f"{_PKG_NAME}.cls")).is_file():
 
 
 if not (_DOTTEX := DATA_DIR / Rf"{_PKG_NAME}_TikZTableSettings.tex").is_file():
-    # Write to dottex
+    # Write to LaTeX table settings file
     with resources.as_file(
         resources.files(f"{_PKG_NAME}.data.jinja2_LaTeX_templates").joinpath(
             "setup_tikz_tables.tex"
@@ -293,7 +300,7 @@ def enf_stats_listing_by_group(
     _stats_group: StatsGrpSelector,
     _enf_spec: INVResolution,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _stats_group == StatsGrpSelector.HD:
         raise ValueError(
             f"Clearance/enforcement statistics, '{_stats_group}' not valied here."
@@ -328,7 +335,7 @@ def enf_cnts_listing_byfirmcount(
     _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -364,7 +371,7 @@ def enf_cnts_listing_byhhianddelta(
     _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -419,7 +426,7 @@ def table_no_lku(
     return _tno
 
 
-def enf_cnts_byfirmcount(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_byfirmcount(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     _ndim_in = 1
     return np.vstack([
         np.concatenate([
@@ -430,7 +437,7 @@ def enf_cnts_byfirmcount(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]
     ])
 
 
-def enf_cnts_bydelta(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_bydelta(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     _ndim_in = 2
     return np.vstack([
         np.concatenate([
@@ -441,7 +448,7 @@ def enf_cnts_bydelta(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
     ])
 
 
-def enf_cnts_byconczone(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_byconczone(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     # 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)
@@ -513,7 +520,7 @@ def enf_cnts_byconczone(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
 
 
 def enf_stats_table_onedim(
-    _inparr: NDArray[np.float64 | np.int64],
+    _inparr: ArrayDouble | ArrayBIGINT | ArrayDouble | ArrayBIGINT,
     _totals_row: int | None = None,
     /,
     *,
@@ -568,7 +575,7 @@ def enf_stats_table_onedim(
 
 
 def enf_stats_table_byzone(
-    _inparr: NDArray[np.float64 | np.int64],
+    _inparr: ArrayDouble | ArrayBIGINT | ArrayDouble | ArrayBIGINT,
     _totals_row: int | None = None,
     /,
     *,
@@ -650,8 +657,8 @@ def enf_stats_table_byzone(
 
 
 def _stats_formatted_row(
-    _stats_row_cnt: NDArray[np.int64],
-    _stats_row_tot: NDArray[np.int64],
+    _stats_row_cnt: ArrayBIGINT,
+    _stats_row_tot: ArrayBIGINT,
     _return_type_sel: StatsReturnSelector,
     /,
 ) -> list[list[str]]:
@@ -715,6 +722,109 @@ def stats_print_rows(
     print()
 
 
+def propn_ci(
+    _npos: ArrayINT[TI] | int = 4,
+    _nobs: ArrayINT[TI] | int = 10,
+    /,
+    *,
+    alpha: float = 0.05,
+    method: Literal[
+        "Agresti-Coull", "Clopper-Pearson", "Exact", "Wilson", "Score"
+    ] = "Wilson",
+) -> tuple[
+    ArrayDouble | float, ArrayDouble | float, ArrayDouble | float, ArrayDouble | float
+]:
+    """Returns point estimates and confidence interval for a proportion
+
+    Methods "Clopper-Pearson" and "Exact" are synoymous [3]_.  Similarly,
+    "Wilson" and "Score" are synonyms here.
+
+    Parameters
+    ----------
+    _npos
+        Number of positives
+
+    _nobs
+        Number of observed values
+
+    alpha
+        Significance level
+
+    method
+        Method to use for estimating confidence interval
+
+    Returns
+    -------
+        Raw and estimated proportions, and bounds of the confidence interval
+
+
+    References
+    ----------
+
+    .. [3] Alan Agresti & Brent A. Coull (1998) Approximate is Better
+       than “Exact” for Interval Estimation of Binomial Proportions,
+       The American Statistician, 52:2, 119-126,
+       https://doi.org/10.1080/00031305.1998.10480550
+
+    """
+
+    for _f in _npos, _nobs:
+        if not isinstance(_f, int | np.integer):
+            raise ValueError(
+                f"Count, {_f!r} must have type that is a subtype of np.integer."
+            )
+
+    if not _nobs:
+        return (np.nan, np.nan, np.nan, np.nan)
+
+    _raw_phat: ArrayDouble | float = _npos / _nobs
+    _est_phat: ArrayDouble | float
+    _est_ci_l: ArrayDouble | float
+    _est_ci_u: ArrayDouble | float
+
+    match method:
+        case "Clopper-Pearson" | "Exact":
+            _est_ci_l, _est_ci_u = (
+                beta.ppf(*_f)
+                for _f in (
+                    (alpha / 2, _npos, _nobs - _npos + 1),
+                    (1 - alpha / 2, _npos + 1, _nobs - _npos),
+                )
+            )
+            _est_phat = 1 / 2 * (_est_ci_l + _est_ci_u)
+
+        case "Agresti-Coull":
+            _zsc = norm.ppf(1 - alpha / 2)
+            _zscsq = _zsc * _zsc
+            _adjmt = 4 if alpha == 0.05 else _zscsq
+            _est_phat = (_npos + _adjmt / 2) / (_nobs + _adjmt)
+            _est_ci_l, _est_ci_u = (
+                _est_phat + _g
+                for _g in [
+                    _f * _zsc * np.sqrt(_est_phat * (1 - _est_phat) / (_nobs + _adjmt))
+                    for _f in (-1, 1)
+                ]
+            )
+
+        case "Wilson" | "Score":
+            _zsc = norm.ppf(1 - alpha / 2)
+            _zscsq = _zsc * _zsc
+            _est_phat = (_npos + _zscsq / 2) / (_nobs + _zscsq)
+            _est_ci_l, _est_ci_u = (
+                _est_phat
+                + _f
+                * _zsc
+                * np.sqrt(_nobs * _raw_phat * (1 - _raw_phat) + _zscsq / 4)
+                / (_nobs + _zscsq)
+                for _f in (-1, 1)
+            )
+
+        case _:
+            raise ValueError(f"Method, {f'"{method}"'} not yet implemented.")
+
+    return _raw_phat, _est_phat, _est_ci_l, _est_ci_u
+
+
 def render_table_pdf(
     _table_dottex_pathlist: Sequence[str], _table_coll_path: str, /
 ) -> None:

mergeron/gen/upp_tests.py

@@ -13,9 +13,19 @@ import numpy as np
 import tables as ptb  # type: ignore
 from joblib import Parallel, cpu_count, delayed  # type: ignore
 from numpy.random import SeedSequence
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import (  # noqa: TID252
+    TF,
+    TI,
+    VERSION,
+    ArrayBIGINT,
+    ArrayBoolean,
+    ArrayDouble,
+    ArrayFloat,
+    ArrayINT,
+    RECConstants,
+    UPPAggrSelector,
+)
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
@@ -250,7 +260,7 @@ def enf_cnts(
         )
         _enf_cnts_sim_byfirmcount_array[0] = 2
 
-    # Clearance/enfrocement counts --- by delta
+    # Clearance/enforcement counts --- by delta
     _hhi_delta_ranged = esl.hhi_delta_ranger(_hhi_delta)
     _enf_cnts_sim_bydelta_array = -1 * np.ones(_stats_rowlen, np.int64)
     for _hhi_delta_lim in esl.HHI_DELTA_KNOTS[:-1]:
@@ -272,7 +282,7 @@ def enf_cnts(
 
     _enf_cnts_sim_bydelta_array = _enf_cnts_sim_bydelta_array[1:]
 
-    # Clearance/enfrocement counts --- by zone
+    # Clearance/enforcement counts --- by zone
     try:
         _hhi_zone_post_ranged = esl.hhi_zone_post_ranger(_hhi_post)
     except ValueError as _err:
@@ -357,23 +367,11 @@ def gen_upp_test_arrays(
         out=_guppi_array,
     )
 
-    _cmcr_array = np.empty_like(_market_data.divr_array)
-    np.divide(
-        np.einsum("ij,ij->ij", _market_data.pcm_array, _market_data.divr_array),
-        np.einsum("ij,ij->ij", 1 - _market_data.pcm_array, 1 - _market_data.divr_array),
-        out=_cmcr_array,
-    )
-
     _ipr_array = np.empty_like(_market_data.divr_array)
-    np.divide(
-        np.einsum("ij,ij->ij", _market_data.pcm_array, _market_data.divr_array),
-        1 - _market_data.divr_array,
-        out=_ipr_array,
-    )
+    np.divide(_guppi_array, (1 - _market_data.divr_array[:, ::-1]), out=_ipr_array)
 
-    # This one needs further testing:
-    # _ipr_array_alt = np.empty_like(_market_data.divr_array)
-    # np.divide(_guppi_array, (1 - _market_data.divr_array[:, ::-1]), out=_ipr_array_alt)
+    _cmcr_array = np.empty_like(_market_data.divr_array)
+    np.divide(_ipr_array, 1 - _market_data.pcm_array, out=_cmcr_array)
 
     _test_measure_seq = (_market_data.divr_array, _guppi_array, _cmcr_array, _ipr_array)
 
@@ -496,7 +494,11 @@ def save_data_to_hdf5(
 
 
 def save_array_to_hdf5(
-    _array_obj: NDArray[np.float64 | np.int64 | np.bool_],
+    _array_obj: ArrayFloat[TF]
+    | ArrayINT[TI]
+    | ArrayDouble
+    | ArrayBIGINT
+    | ArrayBoolean,
     _array_name: str,
     _h5_group: ptb.Group,
     _h5_file: ptb.File,

{mergeron-2024.739099.0.dist-info → mergeron-2024.739099.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.739099.0
+Version: 2024.739099.2
 Summary: Merger Policy Analysis using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI

{mergeron-2024.739099.0.dist-info → mergeron-2024.739099.2.dist-info}/RECORD

@@ -1,12 +1,12 @@
 mergeron/License.txt,sha256=7iX-y0EyjkbVJKJLS4ZKzuuE1wd0lryfsD_IytLG8lQ,1246
-mergeron/__init__.py,sha256=pMy7hhDJ3JsmUIppTioFhGC59pc6gLtFNHOvYNiZ1MA,1180
+mergeron/__init__.py,sha256=A0iVjdlUd_UZWbclyBnPrbCH-JYk_JaMxVv8Dp5y-yU,1541
 mergeron/core/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
-mergeron/core/damodaran_margin_data.py,sha256=PRbdNHqDRN4tG3MI9ZTsilx8SkJ5mZYQc7SgRxcT3YI,8606
-mergeron/core/ftc_merger_investigations_data.py,sha256=Akwc0spRhydXd17j2t37V6EijlJMBk54pcYCNDaykns,28205
-mergeron/core/guidelines_boundaries.py,sha256=__OHme8aGtwOgRXKp56WdX7k4vssAVQ8Ub54XwpS7mg,15621
-mergeron/core/guidelines_boundary_functions.py,sha256=l5fNs65ciEVH-K-QfR8clsfY89xqdf79UIyyZWlSGxU,29718
-mergeron/core/guidelines_boundary_functions_extra.py,sha256=LHeYOHAkhVuwmzOFzP1KqyXNE58BIWqW4pzRkceJx_Q,11316
-mergeron/core/pseudorandom_numbers.py,sha256=k3sDs_NJ2jXlkIWKQ6iiTB5n_QS0RoJ-sqzvFYkC7pY,9277
+mergeron/core/damodaran_margin_data.py,sha256=rMrgN1Qtw572a0ftY97OOj4otq8ldlLrcOi-bcE-org,8554
+mergeron/core/ftc_merger_investigations_data.py,sha256=oL_4yrNPpjuNIluBsDc51lYd2Z4NBBrd7-sHKd3FCbg,28129
+mergeron/core/guidelines_boundaries.py,sha256=Lv-7EE7b2SiudpRjW3gFY1uHu-K0UdesewwiqaqjcOw,15585
+mergeron/core/guidelines_boundary_functions.py,sha256=gohb7Uj1AjJQtD5ew7bVZZjGhJEYCjNNAPB1o6TsA9M,29683
+mergeron/core/guidelines_boundary_functions_extra.py,sha256=t84dMsaMKnYUNuvvGrMCP6vI8MDn88PJOgGZlNe1Zts,11280
+mergeron/core/pseudorandom_numbers.py,sha256=cJEWDTfy9CUTzR_di6Fm1Vl1Le6xWoU8wFHbYVMEuLI,9225
 mergeron/data/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/data/damodaran_margin_data.xls,sha256=Qggl1p5nkOMJI8YUXhkwXQRz-OhRSqBTzz57N0JQyYA,79360
 mergeron/data/damodaran_margin_data_dict.msgpack,sha256=sr6s4L69kposEpzGI7jpPb4ULz0UpY-bEYfeNi6UlRA,57621
@@ -20,13 +20,13 @@ mergeron/data/jinja2_LaTeX_templates/mergeron_table_collection_template.tex.jinj
 mergeron/data/jinja2_LaTeX_templates/setup_tikz_tables.tex,sha256=1hw3RINDtBrh9ZEToMIiNFIu9rozcPwRly69-5O_0UQ,3207
 mergeron/demo/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/demo/visualize_empirical_margin_distribution.py,sha256=v1xFJumBX2Ooye82kSSgly-_GpFVkYSDqBwM__rcmZY,2363
-mergeron/gen/__init__.py,sha256=Ky1p93L-epw42g8HDIcfiENGT1iiXdolnsv12ZUWGM4,17169
-mergeron/gen/_data_generation_functions.py,sha256=boNQkDtarx_BqYHWjlsIXSQHqOBvgBcI_R53UfT66qg,27763
-mergeron/gen/data_generation.py,sha256=n_rdi6Zk5-2Q0K_xXdWI14sj9XZyrF57hnyqvBf5v6Y,8531
-mergeron/gen/enforcement_stats.py,sha256=Hr-w3LZ9SJD4A1RZS1KMhXwuKyGzPC7eeNQullWZRNU,24410
+mergeron/gen/__init__.py,sha256=a60dpqC8G8J518Tb3qEJvTvFnVTYSmgZfhciVckokfw,17051
+mergeron/gen/_data_generation_functions.py,sha256=tBdzpo-6WjwnHTB3uy2B6TE0e0Ajx0rgi6fVtW9I1b4,27386
+mergeron/gen/data_generation.py,sha256=dj9otFi1OE3Eo7f32BD0ZXm9Xvlg0fCp4DDQ_XhDN_w,8479
+mergeron/gen/enforcement_stats.py,sha256=p-CgaOo2qh5G9QZjCxZdbVazXeb_AJ_ABDOc2Kdtt-Q,27438
 mergeron/gen/market_sample.py,sha256=HkzRFTKBXYIs2HbAyVDUiUHo9nCtAciSn5sohR-34cM,4282
-mergeron/gen/upp_tests.py,sha256=N-spIAYKPGJngtlckSjhQGcFBZv_sVZDvCHYzy0TxSc,17132
+mergeron/gen/upp_tests.py,sha256=ZnV_x2TQqhJuWnnG9aTLnw1OBisgHCwHYxy94OK8W9E,16846
 mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-mergeron-2024.739099.0.dist-info/METADATA,sha256=gZtttSjzUwqb-uuxIZ0zE_4VpCtC9txLJbXTO8nszr0,10922
-mergeron-2024.739099.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-mergeron-2024.739099.0.dist-info/RECORD,,
+mergeron-2024.739099.2.dist-info/METADATA,sha256=dyRrp-CAzkssNWLw44aQ-AbKKeuPFleWqEYaRPxaLG0,10922
+mergeron-2024.739099.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+mergeron-2024.739099.2.dist-info/RECORD,,