mergeron 2024.739091.2__py3-none-any.whl → 2024.739097.2__py3-none-any.whl

mergeron/__init__.py

@@ -2,16 +2,12 @@ from __future__ import annotations
 
 import enum
 from pathlib import Path
-from typing import Any
 
 import numpy as np
-import pendulum  # type: ignore
-from icecream import argumentToString, ic, install  # type: ignore
-from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739091.2"
+VERSION = "2024.739097.2"
 
 __version__ = VERSION
 
@@ -28,19 +24,6 @@ if not DATA_DIR.is_dir():
 np.set_printoptions(precision=18)
 
 
-def _timestamper() -> str:
-    return f"{pendulum.now().strftime("%F %T.%f")} |>  "
-
-
-@argumentToString.register(np.ndarray)  # type: ignore
-def _(_obj: NDArray[Any]) -> str:
-    return f"ndarray, shape={_obj.shape}, dtype={_obj.dtype}"
-
-
-ic.configureOutput(prefix=_timestamper, includeContext=True)
-install()
-
-
 @enum.unique
 class RECConstants(enum.StrEnum):
     """Recapture rate - derivation methods."""

mergeron/core/damodaran_margin_data.py

@@ -202,7 +202,7 @@ def mgn_data_resampler(
     Parameters
     ----------
     _sample_size
-        Number of draws
+        Number of draws; if tuple, (number of draws, number of columns)
 
     seed_sequence
         SeedSequence for seeding random-number generator when results

mergeron/core/ftc_merger_investigations_data.py

@@ -22,7 +22,6 @@ import numpy as np
 import re2 as re  # type: ignore
 import requests
 from bs4 import BeautifulSoup
-from icecream import ic  # type: ignore
 from numpy.testing import assert_array_equal
 from numpy.typing import NDArray
 
@@ -345,7 +344,7 @@ def _construct_new_period_data(
                 #   _invdata_array_bld_enfcls < 0, _invdata_array_bld_enfcls, 0
                 # )
                 # if np.einsum('ij->', invdata_array_bld_tbc):
-                #     ic(
+                #     print(
                 #       f"{_data_period}, {_table_no}, {_invdata_ind_group}:",
                 #       abs(np.einsum('ij->', invdata_array_bld_tbc))
                 #       )
@@ -551,7 +550,7 @@ def _parse_table_blocks(
         _invdata_evid_cond = "Unrestricted on additional evidence"
 
     else:
-        # ic(_table_blocks)
+        # print(_table_blocks)
         _invdata_evid_cond = (
             _table_blocks[1][-3].strip()
             if _table_ser == 9
@@ -570,8 +569,8 @@ def _parse_table_blocks(
 
     _table_array = process_table_func(_table_blocks)
     if not isinstance(_table_array, np.ndarray) or _table_array.dtype != np.int64:
-        ic(_table_num)
-        ic(_table_blocks)
+        print(_table_num)
+        print(_table_blocks)
         raise ValueError
 
     _table_data = INVTableData(_invdata_ind_group, _invdata_evid_cond, _table_array)

mergeron/ext/xlsxw_helper.py

@@ -11,6 +11,14 @@ This module is designed for producing formatted summary output. For
 writing bulk data to Excel, facilities provided in third-party packages
 such as `polars <https://pola.rs/>`_ likely provide better performance.
 
+License
+========
+
+Copyright 2017-2023 S. Murthy Kambhampaty
+Licese: MIT
+https://mit-license.org/
+
+
 """
 
 from __future__ import annotations

mergeron/gen/__init__.py

@@ -21,7 +21,7 @@ __version__ = VERSION
 
 EMPTY_ARRAY_DEFAULT = np.zeros(2)
 FCOUNT_WTS_DEFAULT = np.divide(
-    (_nr := np.arange(1, 6)[::-1]), _nr.sum(), dtype=np.float64
+    (_nr := np.arange(1, 7)[::-1]), _nr.sum(), dtype=np.float64
 )
 
 
@@ -36,7 +36,7 @@ class PriceConstants(tuple[bool, str | None], enum.ReprEnum):
     ZERO = (False, None)
     NEG = (False, "negative share-correlation")
     POS = (False, "positive share-correlation")
-    # TODO: CSY = (False, "market-wide cost-symmetry")
+    CSY = (False, "market-wide cost-symmetry")
 
 
 @enum.unique
@@ -59,7 +59,11 @@ class SHRConstants(enum.StrEnum):
     DIR_ASYM = "Asymmetric Dirichlet"
     """Share distribution for merging-firm shares has a higher peak share
 
-    Shape parameter for merging-firm-share is 2.5, and 1.0 for all others.
+    By default, shape parameter for merging-firm-share is 2.5, and
+    1.0 for all others. Defining, :attr:`mergeron.ShareSpec.dist_parms`
+    as a vector of shape parameters with length matching
+    that of :attr:`mergeron.ShareSpec.dist_parms` allows flexible specification
+    of Dirichlet-distributed share-data generation.
     """
 
     DIR_COND = "Conditional Dirichlet"
@@ -74,13 +78,24 @@ class SHRConstants(enum.StrEnum):
 class ShareSpec:
     """Market share specification
 
+    A key feature of market-share specification in this package is that
+    the draws represent markets with multiple different firm-counts.
+    Firm-counts are unspecified if the share distribution is
+    :attr:`mergeron.SHRConstants.UNI`, for Dirichlet-distributed market-shares,
+    the default specification is that firm-counts  vary between
+    2 and 7 firms with each value equally likely.
+
     Notes
     -----
-    If recapture is determined "outside-in", market shares cannot have
-    Uniform distribution.
+    If :attr:`mergeron.gen.ShareSpec.dist_type`:code:` == `:attr:`mergeron.gen.SHRConstants.UNI`,
+    then it is infeasible that
+    :attr:`mergeron.gen.ShareSpec.recapture_form`:code:` == `:attr:`mergeron.RECConstants.OUTIN`.
+    In other words, if firm-counts are unspecified, the recapture rate cannot be
+    estimated using outside good choice probabilities.
 
-    If sample with varying firm counts is required, market shares must
-    be specified as having a supported Dirichlet distribution.
+    For a sample with explicit firm counts, market shares must
+    be specified as having a supported Dirichlet distribution
+    (see :class:`mergeron.gen.SHRConstants`).
 
     """
 
@@ -446,7 +461,8 @@ class UPPTestRegime:
         default=UPPAggrSelector.MIN, validator=validators.instance_of(UPPAggrSelector)
     )
     divr_aggregator: UPPAggrSelector | None = field(
-        default=None, validator=validators.instance_of((UPPAggrSelector, type(None)))
+        default=UPPAggrSelector.MIN,
+        validator=validators.instance_of((UPPAggrSelector, type(None))),
     )
 
 

mergeron/gen/_data_generation_functions.py

@@ -7,6 +7,7 @@ from __future__ import annotations
 from typing import Literal
 
 import numpy as np
+from attrs import evolve
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
 
@@ -21,11 +22,12 @@ from . import (
     FCOUNT_WTS_DEFAULT,
     FM2Constants,
     MarginDataSample,
-    MarketSpec,
     PCMConstants,
+    PCMSpec,
     PriceConstants,
     PriceDataSample,
     ShareDataSample,
+    ShareSpec,
     SHRConstants,
     SSZConstants,
 )
@@ -35,7 +37,7 @@ __version__ = VERSION
 
 def _gen_share_data(
     _sample_size: int,
-    _mkt_sample_spec: MarketSpec,
+    _share_spec: ShareSpec,
     _fcount_rng_seed_seq: SeedSequence | None,
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
@@ -45,8 +47,8 @@ def _gen_share_data(
 
     Parameters
     ----------
-    _mkt_sample_spec
-        Class specifying parameters for share-, price-, and margin-data generation
+    _share_spec
+        Class specifying parameters for generating market share data
     _fcount_rng_seed_seq
         Seed sequence for assuring independent and, optionally, redundant streams
     _mktshr_rng_seed_seq
@@ -60,44 +62,43 @@ def _gen_share_data(
 
     """
 
-    _recapture_form, _dist_type_mktshr, _dist_parms_mktshr, _firm_count_prob_wts_raw = (
-        getattr(_mkt_sample_spec.share_spec, _f)
+    _recapture_form, _dist_type_mktshr, _dist_parms_mktshr, _firm_count_prob_wts = (
+        getattr(_share_spec, _f)
         for _f in ("recapture_form", "dist_type", "dist_parms", "firm_counts_weights")
     )
 
     _ssz = _sample_size
 
-    match _dist_type_mktshr:
-        case SHRConstants.UNI:
-            _mkt_share_sample = _gen_market_shares_uniform(
-                _ssz, _dist_parms_mktshr, _mktshr_rng_seed_seq, _nthreads
-            )
+    if _dist_type_mktshr == SHRConstants.UNI:
+        _mkt_share_sample = _gen_market_shares_uniform(
+            _ssz, _dist_parms_mktshr, _mktshr_rng_seed_seq, _nthreads
+        )
 
-        case _ if _dist_type_mktshr.name.startswith("DIR_"):
-            _firm_count_prob_wts = (
-                None
-                if _firm_count_prob_wts_raw is None
-                else np.array(_firm_count_prob_wts_raw, dtype=np.float64)
-            )
-            _mkt_share_sample = _gen_market_shares_dirichlet_multisample(
-                _ssz,
-                _recapture_form,
-                _dist_type_mktshr,
-                _dist_parms_mktshr,
-                _firm_count_prob_wts,
-                _fcount_rng_seed_seq,
-                _mktshr_rng_seed_seq,
-                _nthreads,
-            )
+    elif _dist_type_mktshr.name.startswith("DIR_"):
+        _firm_count_prob_wts = (
+            None
+            if _firm_count_prob_wts is None
+            else np.array(_firm_count_prob_wts, dtype=np.float64)
+        )
+        _mkt_share_sample = _gen_market_shares_dirichlet_multisample(
+            _ssz,
+            _recapture_form,
+            _dist_type_mktshr,
+            _dist_parms_mktshr,
+            _firm_count_prob_wts,
+            _fcount_rng_seed_seq,
+            _mktshr_rng_seed_seq,
+            _nthreads,
+        )
 
-        case _:
-            raise ValueError(
-                f'Unexpected type, "{_dist_type_mktshr}" for share distribution.'
-            )
+    else:
+        raise ValueError(
+            f'Unexpected type, "{_dist_type_mktshr}" for share distribution.'
+        )
 
     # If recapture_form == "inside-out", recalculate _aggregate_purchase_prob
     _frmshr_array = _mkt_share_sample.mktshr_array[:, :2]
-    _r_bar = _mkt_sample_spec.share_spec.recapture_rate or 0.85
+    _r_bar = _share_spec.recapture_rate or 0.85
     if _recapture_form == RECConstants.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
@@ -392,15 +393,163 @@ 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],
+    _pcm_spec: PCMSpec,
+    _price_spec: PriceConstants,
+    _hsr_filing_test_type: SSZConstants,
+    _pcm_rng_seed_seq: SeedSequence,
+    _pr_rng_seed_seq: SeedSequence | None = None,
+    _nthreads: int = 16,
+    /,
+) -> tuple[MarginDataSample, PriceDataSample]:
+    _price_array, _price_ratio_array = (
+        np.ones_like(_frmshr_array, np.float64),
+        np.empty_like(_frmshr_array, np.float64),
+    )
+
+    _pr_max_ratio = 5.0
+    match _price_spec:
+        case PriceConstants.SYM:
+            _nth_firm_price = np.ones((len(_frmshr_array), 1))
+        case PriceConstants.POS:
+            _price_array, _nth_firm_price = (
+                np.ceil(_p * _pr_max_ratio) for _p in (_frmshr_array, _nth_firm_share)
+            )
+        case PriceConstants.NEG:
+            _price_array, _nth_firm_price = (
+                np.ceil((1 - _p) * _pr_max_ratio)
+                for _p in (_frmshr_array, _nth_firm_share)
+            )
+        case PriceConstants.ZERO:
+            _price_array_gen = prng(_pr_rng_seed_seq).choice(
+                1 + np.arange(_pr_max_ratio), size=(len(_frmshr_array), 3)
+            )
+            _price_array = _price_array_gen[:, :2]
+            _nth_firm_price = _price_array_gen[:, [2]]
+            # del _price_array_gen
+        case PriceConstants.CSY:
+            # TODO:
+            # evolve FM2Constraint (save running MNL test twice); evolve copy of _mkt_sample_spec=1q
+            # generate the margin data
+            # generate price and margin data
+            _frmshr_array_plus = np.hstack((_frmshr_array, _nth_firm_share))
+            _pcm_spec_here = evolve(_pcm_spec, firm2_pcm_constraint=FM2Constants.IID)
+            _margin_data = _gen_margin_data(
+                _frmshr_array_plus,
+                np.ones_like(_frmshr_array_plus, np.float64),
+                _aggregate_purchase_prob,
+                _pcm_spec_here,
+                _pcm_rng_seed_seq,
+                _nthreads,
+            )
+
+            _pcm_array, _mnl_test_array = (
+                getattr(_margin_data, _f) for _f in ("pcm_array", "mnl_test_array")
+            )
+
+            _price_array_here = 1 / (1 - _pcm_array)
+            _price_array = _price_array_here[:, :2]
+            _nth_firm_price = _price_array_here[:, [-1]]
+            if _pcm_spec.firm2_pcm_constraint == FM2Constants.MNL:
+                # Generate i.i.d. PCMs then take PCM0 and construct PCM1
+                # Regenerate MNL test
+                _purchase_prob_array = _aggregate_purchase_prob * _frmshr_array
+                _pcm_array[:, 1] = np.divide(
+                    (
+                        _m1_nr := np.divide(
+                            np.einsum(
+                                "ij,ij,ij->ij",
+                                _price_array[:, [0]],
+                                _pcm_array[:, [0]],
+                                1 - _purchase_prob_array[:, [0]],
+                            ),
+                            1 - _purchase_prob_array[:, [1]],
+                        )
+                    ),
+                    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
+        case _:
+            raise ValueError(
+                f"Specitication of price distribution"
+                f' "{_price_spec.value}" is invalid.'
+            )
+    if _price_spec != PriceConstants.CSY:
+        _margin_data = _gen_margin_data(
+            _frmshr_array,
+            _price_array,
+            _aggregate_purchase_prob,
+            _pcm_spec,
+            _pcm_rng_seed_seq,
+            _nthreads,
+        )
+
+    _price_array = _price_array.astype(np.float64)
+    _rev_array = _price_array * _frmshr_array
+    _nth_firm_rev = _nth_firm_price * _nth_firm_share
+
+    # Although `_test_rev_ratio_inv` is not fixed at 10%,
+    # the ratio has not changed since inception of the HSR filing test,
+    # so we treat it as a constant of merger enforcement policy.
+    _test_rev_ratio, _test_rev_ratio_inv = 10, 1 / 10
+
+    match _hsr_filing_test_type:
+        case SSZConstants.HSR_TEN:
+            # See, https://www.ftc.gov/enforcement/premerger-notification-program/
+            #   -> Procedures For Submitting Post-Consummation Filings
+            #    -> Key Elements to Determine Whether a Post Consummation Filing is Required
+            #           under heading, "Historical Thresholds"
+            # Revenue ratio has been 10-to-1 since inception
+            # Thus, a simple form of the HSR filing test would impose a 10-to-1
+            # ratio restriction on the merging firms' revenues
+            _rev_ratio = (_rev_array.min(axis=1) / _rev_array.max(axis=1)).round(4)
+            _hsr_filing_test = _rev_ratio >= _test_rev_ratio_inv
+            # del _rev_array, _rev_ratio
+        case SSZConstants.HSR_NTH:
+            # To get around the 10-to-1 ratio restriction, specify that the nth firm test:
+            # if the smaller merging firm matches or exceeds the n-th firm in size, and
+            # the larger merging firm has at least 10 times the size of the nth firm,
+            # the size test is considered met.
+            # Alternatively, if the smaller merging firm has 10% or greater share,
+            # the value of transaction test is considered met.
+            _rev_ratio_to_nth = np.round(np.sort(_rev_array, axis=1) / _nth_firm_rev, 4)
+            _hsr_filing_test = (
+                np.einsum(
+                    "ij->i",
+                    1 * (_rev_ratio_to_nth > [1, _test_rev_ratio]),
+                    dtype=np.int64,
+                )
+                == _rev_ratio_to_nth.shape[1]
+            ) | (_frmshr_array.min(axis=1) >= _test_rev_ratio_inv)
+
+            # del _nth_firm_rev, _rev_ratio_to_nth
+        case _:
+            # Otherwise, all draws meet the filing test
+            _hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
+
+    return _margin_data, PriceDataSample(_price_array, _hsr_filing_test)
+
+
+# marked for deletion
 def _gen_price_data(
     _frmshr_array: NDArray[np.float64],
     _nth_firm_share: NDArray[np.float64],
-    _mkt_sample_spec: MarketSpec,
+    _price_spec: PriceConstants,
+    _hsr_filing_test_type: SSZConstants,
     _seed_seq: SeedSequence | None = None,
     /,
 ) -> PriceDataSample:
-    _hsr_filing_test_type = _mkt_sample_spec.hsr_filing_test_type
-
     _price_array, _price_ratio_array, _hsr_filing_test = (
         np.ones_like(_frmshr_array, np.float64),
         np.empty_like(_frmshr_array, np.float64),
@@ -408,7 +557,7 @@ def _gen_price_data(
     )
 
     _pr_max_ratio = 5.0
-    match _mkt_sample_spec.price_spec:
+    match _price_spec:
         case PriceConstants.SYM:
             _nth_firm_price = np.ones((len(_frmshr_array), 1))
         case PriceConstants.POS:
@@ -427,10 +576,12 @@ def _gen_price_data(
             _price_array = _price_array_gen[:, :2]
             _nth_firm_price = _price_array_gen[:, [2]]
             # del _price_array_gen
+        case PriceConstants.CSY:
+            raise ValueError("Market-wide cost-symmetry is not yet implemented.")
         case _:
             raise ValueError(
-                f"Condition regarding price symmetry"
-                f' "{_mkt_sample_spec.price_spec.value}" is invalid.'
+                f"Specitication of price distribution"
+                f' "{_price_spec.value}" is invalid.'
             )
 
     _price_array = _price_array.astype(np.float64)
@@ -471,7 +622,6 @@ def _gen_price_data(
                 == _rev_ratio_to_nth.shape[1]
             ) | (_frmshr_array.min(axis=1) >= _test_rev_ratio_inv)
 
-            # del _nth_firm_rev, _rev_ratio_to_nth
         case _:
             # Otherwise, all draws meet the filing test
             _hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
@@ -479,23 +629,26 @@ def _gen_price_data(
     return PriceDataSample(_price_array, _hsr_filing_test)
 
 
-def _gen_pcm_data(
+def _gen_margin_data(
     _frmshr_array: NDArray[np.float64],
     _price_array: NDArray[np.float64],
     _aggregate_purchase_prob: NDArray[np.float64],
-    _mkt_sample_spec: MarketSpec,
+    _pcm_spec: PCMSpec,
     _pcm_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
     /,
 ) -> MarginDataSample:
     _dist_type_pcm, _dist_firm2_pcm, _dist_parms_pcm = (
-        getattr(_mkt_sample_spec.pcm_spec, _f)
+        getattr(_pcm_spec, _f)
         for _f in ("dist_type", "firm2_pcm_constraint", "dist_parms")
     )
 
     _dist_type: Literal["Beta", "Uniform"]
-    _pcm_array = np.empty((len(_frmshr_array), 2), dtype=np.float64)
-    _mnl_test_array = np.empty((len(_frmshr_array), 2), dtype=int)
+    _pcm_array = (
+        np.empty((len(_frmshr_array), 1), dtype=np.float64)
+        if _pcm_spec.firm2_pcm_constraint == FM2Constants.SYM
+        else np.empty_like(_frmshr_array, dtype=np.float64)
+    )
 
     _beta_min, _beta_max = [None] * 2  # placeholder
     if _dist_type_pcm == PCMConstants.EMPR:
@@ -534,25 +687,33 @@ def _gen_pcm_data(
         _pcm_array = (_beta_max - _beta_min) * _pcm_array + _beta_min
         del _beta_min, _beta_max
 
+    if _dist_firm2_pcm == FM2Constants.SYM:
+        _pcm_array = np.column_stack((_pcm_array,) * _frmshr_array.shape[1])
     if _dist_firm2_pcm == FM2Constants.MNL:
         # Impose FOCs from profit-maximization with MNL demand
-        _purchprob_array = _aggregate_purchase_prob * _frmshr_array
+        if _dist_type_pcm == PCMConstants.EMPR:
+            print(
+                "NOTE: Estimated Firm 2 parameters will not be consistent with "
+                "the empirical distribution of margins in the source data. For "
+                "consistency, respecify pcm_spec.firm2_pcm_constraint = FM2Constants.IID."
+            )
+        _purchase_prob_array = _aggregate_purchase_prob * _frmshr_array
 
         _pcm_array[:, [1]] = np.divide(
             np.einsum(
                 "ij,ij,ij->ij",
                 _price_array[:, [0]],
                 _pcm_array[:, [0]],
-                1 - _purchprob_array[:, [0]],
+                1 - _purchase_prob_array[:, [0]],
+            ),
+            np.einsum(
+                "ij,ij->ij", _price_array[:, [1]], 1 - _purchase_prob_array[:, [1]]
             ),
-            np.einsum("ij,ij->ij", _price_array[:, [1]], 1 - _purchprob_array[:, [1]]),
         )
 
         _mnl_test_array = _pcm_array[:, 1].__ge__(0) & _pcm_array[:, 1].__le__(1)
     else:
         _mnl_test_array = np.ones(len(_pcm_array), dtype=bool)
-        if _dist_firm2_pcm == FM2Constants.SYM:
-            _pcm_array[:, [1]] = _pcm_array[:, [0]]
 
     return MarginDataSample(_pcm_array, _mnl_test_array)
 

mergeron/gen/data_generation.py

@@ -1,5 +1,6 @@
 """
-Methods to generate data for analyzing merger enforcement policy.
+Methods to generate market data, including shares price, marginsm, and diversion ratios
+for analyzing merger enforcement policy.
 
 """
 
@@ -21,7 +22,7 @@ from . import (
     SHRConstants,
     SSZConstants,
 )
-from ._data_generation_functions import _gen_pcm_data, _gen_price_data, _gen_share_data
+from ._data_generation_functions import _gen_margin_price_data, _gen_share_data
 
 __version__ = VERSION
 
@@ -42,24 +43,13 @@ def gen_market_sample(
     nthreads: int = 16,
 ) -> MarketDataSample:
     """
-    Generate share, diversion ratio, price, and margin data based on supplied parameters
+    Generate share, diversion ratio, price, and margin data for MarketSpec.
 
-    Diversion ratios generated assuming share-proportionality, unless
-    `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
-    for generating the relevant random variates:
-    1.) quantity shares
-    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 == PriceConstants.ZERO`.
 
     Parameters
     ----------
     _mkt_sample_spec
-        class specifying parameters for data generation
+        class specifying parameters for data generation, see :class:`mergeron.gen.MarketSpec`
     sample_size
         number of draws to generate
     seed_seq_list
@@ -100,7 +90,7 @@ def gen_market_sample(
     # Generate share data
     _mktshr_data = _gen_share_data(
         _shr_sample_size,
-        _mkt_sample_spec,
+        _mkt_sample_spec.share_spec,
         _fcount_rng_seed_seq,
         _mktshr_rng_seed_seq,
         nthreads,
@@ -116,40 +106,28 @@ def gen_market_sample(
         )
     )
 
-    # Generate merging-firm price data
-    _price_data = _gen_price_data(
-        _mktshr_array[:, :2], _nth_firm_share, _mkt_sample_spec, _pr_rng_seed_seq
+    # Generate merging-firm price and PCM data
+    _margin_data, _price_data = _gen_margin_price_data(
+        _mktshr_array[:, :2],
+        _nth_firm_share,
+        _aggregate_purchase_prob,
+        _mkt_sample_spec.pcm_spec,
+        _mkt_sample_spec.price_spec,
+        _mkt_sample_spec.hsr_filing_test_type,
+        _pcm_rng_seed_seq,
+        _pr_rng_seed_seq,
+        nthreads,
     )
 
     _price_array, _hsr_filing_test = (
         getattr(_price_data, _f) for _f in ("price_array", "hsr_filing_test")
     )
 
-    if _hsr_filing_test_type != SSZConstants.ONE:
-        _mktshr_array = _mktshr_array[_hsr_filing_test]
-        _fcounts = _fcounts[_hsr_filing_test]
-        _aggregate_purchase_prob = _aggregate_purchase_prob[_hsr_filing_test]
-        _nth_firm_share = _nth_firm_share[_hsr_filing_test]
-        _price_array = _price_array[_hsr_filing_test]
-
-    # Calculate diversion ratios
-    _divr_array = gen_divr_array(
-        _recapture_form, _recapture_rate, _mktshr_array[:, :2], _aggregate_purchase_prob
-    )
-
-    # Generate margin data
-    _pcm_data = _gen_pcm_data(
-        _mktshr_array[:, :2],
-        _price_array,
-        _aggregate_purchase_prob,
-        _mkt_sample_spec,
-        _pcm_rng_seed_seq,
-        nthreads,
-    )
     _pcm_array, _mnl_test_rows = (
-        getattr(_pcm_data, _f) for _f in ("pcm_array", "mnl_test_array")
+        getattr(_margin_data, _f) for _f in ("pcm_array", "mnl_test_array")
     )
 
+    _mnl_test_rows = _mnl_test_rows * _hsr_filing_test
     _s_size = sample_size  # originally-specified sample size
     if _dist_firm2_pcm == FM2Constants.MNL:
         _mktshr_array = _mktshr_array[_mnl_test_rows][:_s_size]
@@ -158,7 +136,11 @@ def gen_market_sample(
         _fcounts = _fcounts[_mnl_test_rows][:_s_size]
         _aggregate_purchase_prob = _aggregate_purchase_prob[_mnl_test_rows][:_s_size]
         _nth_firm_share = _nth_firm_share[_mnl_test_rows][:_s_size]
-        _divr_array = _divr_array[_mnl_test_rows][:_s_size]
+
+    # Calculate diversion ratios
+    _divr_array = gen_divr_array(
+        _recapture_form, _recapture_rate, _mktshr_array[:, :2], _aggregate_purchase_prob
+    )
 
     del _mnl_test_rows, _s_size
 
@@ -188,7 +170,33 @@ def parse_seed_seq_list(
     _price_spec: PriceConstants,
     /,
 ) -> SeedSequenceData:
-    """Initialize RNG seed sequences to ensure independence of distinct random streams."""
+    """Initialize RNG seed sequences to ensure independence of distinct random streams.
+
+    The tuple of SeedSequences, is parsed in the following order
+    for generating the relevant random variates:
+    1.) quantity shares
+    2.) price-cost margins
+    3.) firm-counts, if :code:`MarketSpec.share_spec.dist_type` is a Dirichlet distribution
+    4.) prices, if :code:`MarketSpec.price_spec ==`:attr:`mergeron.gen.PriceConstants.ZERO`.
+
+
+
+    Parameters
+    ----------
+    _sseq_list
+        List of RNG seed sequences
+
+    _mktshr_dist_type
+        Market share distribution type
+
+    _price_spec
+        Price specification
+
+    Returns
+    -------
+        Seed sequence data
+
+    """
     _fcount_rng_seed_seq: SeedSequence | None = None
     _pr_rng_seed_seq: SeedSequence | None = None
 

mergeron/gen/market_sample.py

@@ -23,22 +23,51 @@ class MarketSample(MarketSpec):
         self,
         /,
         *,
-        sample_size: int = 10**6,
+        sample_size: int,
         seed_seq_list: list[SeedSequence] | None,
         nthreads: int,
-        save_data_to_file: SaveData = False,
+        save_data_to_file: SaveData,
     ) -> None:
+        """Generate market data
+
+        Parameters
+        ----------
+        sample_size
+            Size of the market sample drawn
+
+        seed_seq_list
+            List of :code:`numpy.random.SeedSequence` objects
+
+        nthreads
+            Number of threads to use
+
+        save_data_to_file
+            Save data to given HDF5 file, at specified group node
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        See documentation for :class:`mergeron.gen.data_generation.gen_market_sample`
+        for more information, and :func:`mergeron.gen.data_generation.parse_seed_seq_list`
+        on the specification of :code:`seed_seq_list`.
+
+        """
         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,
@@ -57,19 +86,58 @@ class MarketSample(MarketSpec):
         nthreads: int,
         save_data_to_file: SaveData = False,
     ) -> None:
+        """Generate market data
+
+        Parameters
+        ----------
+        _enf_parm_vec
+            Threshold values for various Guidelines criteria
+
+        _upp_test_regime
+            Specifies whether to analyze enforcement, clearance, or both
+            and the GUPPI and diversion ratio aggregators employed, with
+            default being to analyze enforcement based on the maximum
+            merging-firm GUPPI and maximum diversion ratio between the
+            merging firms
+
+        sample_size
+            Size of the market sample drawn
+
+        seed_seq_list
+            List of :code:`numpy.random.SeedSequence` objects
+
+        nthreads
+            Number of threads to use
+
+        save_data_to_file
+            Save data to given HDF5 file, at specified group node
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        See documentation for :class:`mergeron.gen.MarketSpec` for details on specifying
+        how shares, margins, prices, and diversion ratios are generated, and whether to restrict
+        the sample to draws representing mergers that meet the HSR filing requirements. See
+        :class:`mergeron.gen.MarketDataSample` on the sample data generated; see,
+        :func:`mergeron.gen.data_generation.parse_seed_seq_list` on
+        the specification of :code:`seed_seq_list`.
+
+        """
+
         if getattr(self, "market_data_sample", None) is None:
             self.enf_counts = sim_enf_cnts_ll(
                 self,
                 _enf_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,
+                save_data_to_file=save_data_to_file,
             )
         else:
-            self.enf_counts = enf_cnts(
-                self.data, _enf_parm_vec, _upp_test_regime
-            )
-        if save_data_to_file:
-            save_data_to_hdf5(self.enf_counts, save_data_to_file=save_data_to_file)
+            self.enf_counts = enf_cnts(self.data, _enf_parm_vec, _upp_test_regime)
+            if save_data_to_file:
+                save_data_to_hdf5(self.enf_counts, save_data_to_file=save_data_to_file)

mergeron/gen/upp_tests.py

@@ -11,7 +11,6 @@ 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
@@ -195,9 +194,7 @@ def sim_enf_cnts(
         save_data_to_file=save_data_to_file,
     )
 
-    _upp_test_arrays = enf_cnts(
-        _market_data_sample, _upp_test_parms, _sim_test_regime
-    )
+    _upp_test_arrays = enf_cnts(_market_data_sample, _upp_test_parms, _sim_test_regime)
 
     save_data_to_hdf5(
         _upp_test_arrays,
@@ -279,7 +276,7 @@ def enf_cnts(
     try:
         _hhi_zone_post_ranged = esl.hhi_zone_post_ranger(_hhi_post)
     except ValueError as _err:
-        ic(_hhi_post)
+        print(_hhi_post)
         raise _err
 
     _stats_byconczone_sim = -1 * np.ones(_stats_rowlen + 1, np.int64)
@@ -310,9 +307,7 @@ def enf_cnts(
                 ]),
             ))
 
-    _enf_cnts_sim_byconczone_array = esl.enf_cnts_byconczone(
-        _stats_byconczone_sim[1:]
-    )
+    _enf_cnts_sim_byconczone_array = esl.enf_cnts_byconczone(_stats_byconczone_sim[1:])
     del _stats_byconczone_sim
     del _hhi_delta, _hhi_post, _fcounts
 

mergeron-2024.739097.2.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: mergeron
+Version: 2024.739097.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
+Author: Murthy Kambhampaty
+Author-email: smk@capeconomics.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: aenum (>=3.1.15,<4.0.0)
+Requires-Dist: attrs (>=23.2)
+Requires-Dist: bs4 (>=0.0.1)
+Requires-Dist: certifi (>=2023.11.17)
+Requires-Dist: google-re2 (>=1.1)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: joblib (>=1.3)
+Requires-Dist: lxml (>=5.0)
+Requires-Dist: matplotlib (>=3.8)
+Requires-Dist: mpmath (>=1.3)
+Requires-Dist: msgpack (>=1.0)
+Requires-Dist: msgpack-numpy (>=0.4)
+Requires-Dist: numpy (>=1.26,<2.0)
+Requires-Dist: openpyxl (>=3.1.2)
+Requires-Dist: poetry-plugin-export (>=1.8.0,<2.0.0)
+Requires-Dist: requests (>=2.31)
+Requires-Dist: requests-toolbelt (>=1.0.0)
+Requires-Dist: scipy (>=1.12)
+Requires-Dist: sympy (>=1.12)
+Requires-Dist: tables (>=3.8)
+Requires-Dist: types-beautifulsoup4 (>=4.11.2)
+Requires-Dist: types-requests (>=2.31.0)
+Requires-Dist: xlrd (>=2.0.1,<3.0.0)
+Requires-Dist: xlsxwriter (>=3.1)
+Description-Content-Type: text/x-rst
+
+mergeron: Merger Policy Analysis using Python
+=============================================
+
+Analyze the sets of mergers conforming to concentration and diversion ratio bounds. Analyze intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions impled by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+
+Intrinsic enforcement rates and intrinsice clearance rates are distinguished from *observed* clearance and enforcement rates in that the former are derived from analyzing theorectical predictions regarding firm conduct against enforcement thresholds, treating enforcement policy as exogenous to firm conduct. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement, and, ny definition, the observed clearance rate is 1 minus the observed enforement rate.
+
+Introduction
+------------
+
+Module :code:`mergeron.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`mergeron.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`mergeron.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area. This module also includes a function for generating plots of concentation and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+
+Module :code:`mergeron.gen.market_sample` includes the :code:`mergeron.gen.market_sample.MarketSample` with methods for, (i) generating sample data under a rich specification of shares, diversion ratios, margins, prices, and HSR filing requirements, and (ii) for estimating enforcement or clearance rates under specified enforcement regimes given a method of aggregating diversion ratio or GUPPI estimates for the firms in a merger. Notably. share are genarated not just for markets with a fixed number of firms, but for markets with multiple firm-count weights, which may be left unspecified or explicitly specified.
+
+Unless otherwise specified, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution, with specified shape parameters (see :code:`mergeron.gen.ShareContants`. When drawing shares from the Dirichlet distribution, the user passes, using :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights`, a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights` is not assigned a value when defining :code:`mergeron.gen.MarketSpec.ShareSpec` (which has type, :code:`mergeron.gen.ShareSpec`), the default values is used, with results in a sample of markets with 2 to 6 firms with equal relative frequency.
+
+Recapture rates can be specifed as, "proportional", "inside-out", "outside-in" (see :code:`mergeron.RECConstants`. The "inside-out" specification results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification yields diversion ratios from purchase probabilities drawn at random for :math:`N+1` goods, from which are derived market shares and recapture rates for the :math:`N` goods in the putative market (see, :code:`mergeron.gen.DiversionRatioSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`mergeron.gen.MarketSpec.ShareSpec.dist_type ==`:code:`mergeron.gen.ShareContants.UNI`.
+
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or an empirical distribution. The empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand (see, :code:`mergeron.gen.PCMSpec`).
+
+Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified (see, :code:`mergeron.gen.PriceSpec`).
+
+The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the HSR filing threshold for the smaller (acquired) firm. In the other, the :math:`n`-th firm's size matches the size requirement for the smaller merging firm (see, :code:`mergeron.gen.SSZConstants`). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
+
+The full specification of a market sample is given in a :code:`mergeron.gen.market_sample.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`mergeron.gen.market_sample.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`mergeron.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`mergeron.gen.market_sample.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`mergeron.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`estimate_enf_counts` on a :code:`mergeron.gen.market_sample.MarketSample` object without first invoking :code:`generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the perfomance penalty is slight, but can be considerable if saving to SATA storage).
+
+Enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.enforcement_stats`.
+
+Programs demonstrating the use of this package are included in the sub-package, :code:`mergeron.demo`.
+
+This package includes  a class, :code:`mergeron.core.pseudorandom_numbers.MulithreadedRNG` for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. This class is an adaptation from the documentation of the :code:`numpy` package, from the discussion on `multithreaded random-number generation <https://numpy.org/doc/stable/reference/random/multithreading.html>_`; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
+
+.. code-block:: python
+
+    import mergeron.core.market_sample as market_sample
+
+    help(market_sample.MarketSample)
+
+"Extras" Subpackage
+---------------------
+
+The "Extras" sub-package includes a small number of modules potentially useful to users, but which do not implement the principal functions of the package, and are hence considered "extras"  or "external" modules. One of these modules is, in fact, repackaged here although published independently.
+
+On of the external modules provides methods for estimating confidence intervals for proportions and for contrasts (differences) in proportions. This module  improve is coded for conformance to the literature and to results from the corresponding modules in :code:`R`. Although written from scratch, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/). To access these directly:
+
+.. code-block:: python
+
+    import mergeron.ext.proportions_tests as prci
+
+Module :code:`mergeron.ext.xlsxw_helper` is useful for writing highly formatted output to spreadsheets with xlsx format. The class, :code:`mergeron.ext.xlsxw_helper.CFmt` and function, :code:`mergeron.ext.xlsxw_helper.array_to_sheet` are of particular interest, and can be accessed as :code:`xlh.CFmt` and :code:`xlh.array_to_sheet` with the following import:
+
+.. code-block:: python
+
+    import mergeron.ext.xlsxw_helper as xlsxw_helper
+
+A recent version of Paul Tol's python module, :code:`tol_colors.py`, which provides high-contrast color schemes for making displays with improved visibility for individuals with color-blindness, is redistributed within this package. Other than re-formatting and type annotation, the :code:`mergeron.ext.tol_colors` module is re-distributed as downloaded from, https://personal.sron.nl/~pault/data/tol_colors.py. The :code:`tol_colors.py` module is distributed under the Standard 3-clause BSD license. To access the :code:`mergeron.ext.tol_colors` module directly:
+
+.. code-block:: python
+
+    import mergeron.ext.tol_colors as ptc
+
+.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
+   :alt: Poetry
+   :target: https://python-poetry.org/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+
+

{mergeron-2024.739091.2.dist-info → mergeron-2024.739097.2.dist-info}/RECORD

@@ -1,12 +1,11 @@
 mergeron/License.txt,sha256=7iX-y0EyjkbVJKJLS4ZKzuuE1wd0lryfsD_IytLG8lQ,1246
-mergeron/__init__.py,sha256=dQe1ZhZ4GP5p0TMy4E_chUcvo-6TpWhft70eWLQCZBY,1647
+mergeron/__init__.py,sha256=eXxEYw2DGgVE984IXzibIzZXEpfHfdwMtRIs8xqriOw,1180
 mergeron/core/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
-mergeron/core/damodaran_margin_data.py,sha256=pjI1rSK_O1-3Oel5b9KXH6ctnInjX1Vii7fypt00gV8,8541
-mergeron/core/ftc_merger_investigations_data.py,sha256=ZaV2DO7UZabV8eX0Ubq_ToIor7tIRzcvYC54ADliuTk,27931
+mergeron/core/damodaran_margin_data.py,sha256=mzCRsva47lnrLuTqzAXCKEIgqwvcUN6C3_qiqf_yDYI,8589
+mergeron/core/ftc_merger_investigations_data.py,sha256=9U0GPD6bl_xAsbFclt32Vnm9-rz9vnIWuiIi6jK1sc8,27903
 mergeron/core/guidelines_boundaries.py,sha256=__OHme8aGtwOgRXKp56WdX7k4vssAVQ8Ub54XwpS7mg,15621
 mergeron/core/guidelines_boundary_functions.py,sha256=rXjncqTn7NPgI2KY9Wuv3WNrsjmv74hpH9-mUI56NgQ,29714
 mergeron/core/guidelines_boundary_functions_extra.py,sha256=TYq3M5onfAIAY-35Q_SaSVF0Upa9hCSKIQkY-KCGzwM,11393
-mergeron/core/proportions_tests.py,sha256=akq0Xhdgtst4RAT42_E5cBD_kATq_V4bQeBznmzRSLg,15267
 mergeron/core/pseudorandom_numbers.py,sha256=k3sDs_NJ2jXlkIWKQ6iiTB5n_QS0RoJ-sqzvFYkC7pY,9277
 mergeron/data/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/data/damodaran_margin_data.xls,sha256=Qggl1p5nkOMJI8YUXhkwXQRz-OhRSqBTzz57N0JQyYA,79360
@@ -22,15 +21,16 @@ mergeron/data/jinja2_LaTeX_templates/setup_tikz_tables.tex,sha256=1hw3RINDtBrh9Z
 mergeron/demo/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/demo/visualize_empirical_margin_distribution.py,sha256=v1xFJumBX2Ooye82kSSgly-_GpFVkYSDqBwM__rcmZY,2363
 mergeron/ext/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
+mergeron/ext/proportions_tests.py,sha256=akq0Xhdgtst4RAT42_E5cBD_kATq_V4bQeBznmzRSLg,15267
 mergeron/ext/tol_colors.py,sha256=QBw8s-ZGpUpIIYOplHbLFZSXVoa6eDDJDtzSScP954E,22303
-mergeron/ext/xlsxw_helper.py,sha256=4wAhwQjWKSm65931sR_4yO6EuoU2RnWvtW5aCSQn5Iw,17951
-mergeron/gen/__init__.py,sha256=pAEirl5FAO9r_6f7BdvqU0LCH9lXMe1YR0SnrGMpCWI,16200
-mergeron/gen/_data_generation_functions.py,sha256=7fP4mSVaN36FBhPKSf1y_TbxfRUe-I7fgqdBt74oaCA,21029
-mergeron/gen/data_generation.py,sha256=gDvCZYJwGpQnokcygM7IRzHBpE5rYI2J5I8uu0_wQyE,8727
+mergeron/ext/xlsxw_helper.py,sha256=Kqlt89kcnoiE2aCtP3xbM4fypy_JNIg9ebjjURmyJ38,18050
+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/market_sample.py,sha256=ekMA9db2AWvrA-GDbIieu270fovFX0JyynCo5FRAGzk,2270
-mergeron/gen/upp_tests.py,sha256=GQZcXU4vQPJRxdI2DVsY7yX6TPqhntlTH-DOAufWFmM,17197
+mergeron/gen/market_sample.py,sha256=HkzRFTKBXYIs2HbAyVDUiUHo9nCtAciSn5sohR-34cM,4282
+mergeron/gen/upp_tests.py,sha256=N-spIAYKPGJngtlckSjhQGcFBZv_sVZDvCHYzy0TxSc,17132
 mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-mergeron-2024.739091.2.dist-info/METADATA,sha256=wK0ioIu_QUYP5PLYeJgBKqM8A1wfIWJOG22beUjM8AI,8899
-mergeron-2024.739091.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-mergeron-2024.739091.2.dist-info/RECORD,,
+mergeron-2024.739097.2.dist-info/METADATA,sha256=A3gMoFOyFeDY1eS80qv33K_O68hfNo1HGwS-cGEP7V0,13268
+mergeron-2024.739097.2.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+mergeron-2024.739097.2.dist-info/RECORD,,

mergeron-2024.739091.2.dist-info/METADATA

@@ -1,110 +0,0 @@
-Metadata-Version: 2.1
-Name: mergeron
-Version: 2024.739091.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
-Author: Murthy Kambhampaty
-Author-email: smk@capeconomics.com
-Requires-Python: >=3.12,<4.0
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: End Users/Desktop
-Classifier: Intended Audience :: Science/Research
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Classifier: Programming Language :: Python
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: Implementation :: CPython
-Requires-Dist: aenum (>=3.1.15,<4.0.0)
-Requires-Dist: attrs (>=23.2)
-Requires-Dist: bs4 (>=0.0.1)
-Requires-Dist: certifi (>=2023.11.17)
-Requires-Dist: google-re2 (>=1.1)
-Requires-Dist: icecream (>=2.1.0)
-Requires-Dist: jinja2 (>=3.1)
-Requires-Dist: joblib (>=1.3)
-Requires-Dist: lxml (>=5.0)
-Requires-Dist: matplotlib (>=3.8)
-Requires-Dist: mpmath (>=1.3)
-Requires-Dist: msgpack (>=1.0)
-Requires-Dist: msgpack-numpy (>=0.4)
-Requires-Dist: numpy (>=1.26,<2.0)
-Requires-Dist: openpyxl (>=3.1.2)
-Requires-Dist: pendulum (>=3.0.0)
-Requires-Dist: poetry-plugin-export (>=1.8.0,<2.0.0)
-Requires-Dist: requests (>=2.31)
-Requires-Dist: requests-toolbelt (>=1.0.0)
-Requires-Dist: scipy (>=1.12)
-Requires-Dist: sympy (>=1.12)
-Requires-Dist: tables (>=3.8)
-Requires-Dist: types-beautifulsoup4 (>=4.11.2)
-Requires-Dist: types-requests (>=2.31.0)
-Requires-Dist: xlrd (>=2.0.1,<3.0.0)
-Requires-Dist: xlsxwriter (>=3.1)
-Description-Content-Type: text/x-rst
-
-mergeron: Merger Policy Analysis using Python
-=============================================
-
-Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations during 1996 to 2011. Model the sets of mergers conforming to various U.S. Horizontal Merger Guidelines standards. Analyze intrinsic clearance rates and intrinsic enforcement rates under Guidelines standards using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions impled by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand.
-
-Intrinsic clearance and enforcement rates are distinguished from *observed* clearance and enforcement rates in that the former do not reflect the effects of screening and deterrence as do the latter.
-
-
-Introduction
-------------
-
-Classes for specifying concentration standards (:code:`mergeron.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio standards (:code:`mergeron.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area, are provided in :code:`mergeron.core.guidelines_boundaries`. This module also includes a function for generating plots of concentation and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
-
-Methods for generating industry data under various distributions of shares, margins, and prices are included in, :code:`mergeron.gen.data_generation`. Shares are drawn with uniform distribution with :math:`s_1 + s_2 \leqslant 1` and an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution. When drawing shares from the Dirichlet distribution, the user can specify a fixed number for firms or provide a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <"https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). The user can specify recapture rates as, "proportional", "inside-out" --- i.e., consistent with merging-firms' in-market shares and a default recapture rate) --- or "outside-in" --- i.e., purchase probabilities are drawn at random for :math:`N+1` goods, from which are derived market shares and recapture rates for the :math:`N` goods in the putative market. Documentation on specifying the sampling strategy for market shares is at :code:`mergeron.gen.ShareSpec`. Price-cost-margins may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand (see, :code:`mergeron.gen.PCMSpec`). Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified (see, :code:`mergeron.gen.PriceSpec`). Two alternative approaches for modeling statutory filing requirements (HSR filing thresholds) are implemented (see, :code:`mergeron.gen.SSZConstants`). The full specification of a market sample is given in a :code:`mergeron.gen.market_sample.MarketSample` object. Data are drawn by invoking :code:`mergeron.gen.market_sample.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`mergeron.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`mergeron.gen.market_sample.MarketSample.estimate_invres_counts`, which adds an :code:`invres_counts` property of class :code:`mergeron.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`estimate_invres_counts` on a :code:`mergeron.gen.market_sample.MarketSample` object without first invoking :code:`generate_sample`. Note, however, that this strategy discards the market sample in the interests of conserving memory and maintaining high performance.
-
-Methods for printing enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.enforcement_stats`.
-
-Programs demonstrating the analysis and reporting facilites provided by the sub-package, :code:`mergeron.demo`.
-
-This package exposes methods employed for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. To access these directly:
-
-.. code-block:: python
-
-    import mergeron.core.pseudorandom_numbers as prng
-
-Also included are methods for estimating confidence intervals for proportions and for contrasts (differences) in proportions. (Although coded from scratch using the source literature, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/).) To access these directly:
-
-.. code-block:: python
-
-    import mergeron.core.proportions_tests as prci
-
-A recent version of Paul Tol's python module, :code:`tol_colors.py` is redistributed within this package. Other than re-formatting and type annotation, the :code:`mergeron.ext.tol_colors` module is re-distributed as downloaded from, https://personal.sron.nl/~pault/data/tol_colors.py. The :code:`tol_colors.py` module is distributed under the Standard 3-clause BSD license. To access the :code:`mergeron.ext.tol_colors` module directly:
-
-.. code-block:: python
-
-    import mergeron.ext.tol_colors as ptc
-
-Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
-
-.. code-block:: python
-
-    import mergeron.core.market_sample as market_sample
-
-    help(market_sample.MarketSample)
-
-
-.. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
-   :alt: Poetry
-   :target: https://python-poetry.org/
-
-.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
-   :alt: Ruff
-   :target: https://github.com/astral-sh/ruff
-
-.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
-   :alt: Checked with mypy
-   :target: https://mypy-lang.org/
-
-.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
-   :alt: License: MIT
-   :target: https://opensource.org/licenses/MIT
-