mergeron 2024.739127.0__py3-none-any.whl → 2024.739139.0__py3-none-any.whl

mergeron/__init__.py

@@ -2,14 +2,13 @@ from __future__ import annotations
 
 import enum
 from pathlib import Path
-from typing import TypeAlias
 
 import numpy as np
 from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739127.0"
+VERSION = "2024.739139.0"
 
 __version__ = VERSION
 
@@ -25,21 +24,21 @@ if not DATA_DIR.is_dir():
 np.set_printoptions(precision=18)
 
 
-ArrayINT = NDArray[np.intp]
-ArrayFloat = NDArray[np.half | np.single | np.double]
+type ArrayINT = NDArray[np.intp]
+type ArrayFloat = NDArray[np.half | np.single | np.double]
 
 
-ArrayBoolean: TypeAlias = NDArray[np.bool_]
+type ArrayBoolean = NDArray[np.bool_]
 
-ArrayDouble: TypeAlias = NDArray[np.double]
-ArrayBIGINT: TypeAlias = NDArray[np.int64]
+type ArrayDouble = NDArray[np.double]
+type ArrayBIGINT = NDArray[np.int64]
 
 DEFAULT_REC_RATE = 0.85
 
 
 @enum.unique
 class RECForm(enum.StrEnum):
-    """Recapture rate - derivation methods."""
+    """For derivation of recapture ratio from market shares."""
 
     INOUT = "inside-out"
     OUTIN = "outside-in"
@@ -49,7 +48,7 @@ class RECForm(enum.StrEnum):
 @enum.unique
 class UPPAggrSelector(enum.StrEnum):
     """
-    Aggregator selection for GUPPI and diversion ratio
+    Aggregator for GUPPI and diversion ratio estimates.
 
     """
 

mergeron/core/ftc_merger_investigations_data.py

@@ -14,7 +14,7 @@ from importlib import resources
 from operator import itemgetter
 from pathlib import Path
 from types import MappingProxyType
-from typing import Any, NamedTuple, TypeAlias
+from typing import Any, NamedTuple
 
 import msgpack  # type: ignore
 import msgpack_numpy as m  # type: ignore
@@ -95,7 +95,7 @@ class INVTableData(NamedTuple):
     data_array: ArrayBIGINT
 
 
-INVData: TypeAlias = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
+type INVData = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
 
 
 def construct_data(

mergeron/core/guidelines_boundaries.py

@@ -7,7 +7,7 @@ with a canvas on which to draw boundaries for Guidelines standards.
 from __future__ import annotations
 
 from dataclasses import dataclass
-from typing import Literal, TypeAlias
+from typing import Literal
 
 import numpy as np
 from attrs import Attribute, field, frozen, validators
@@ -28,7 +28,7 @@ __version__ = VERSION
 mp.prec = 80
 mp.trap_complex = True
 
-HMGPubYear: TypeAlias = Literal[1992, 2004, 2010, 2023]
+type HMGPubYear = Literal[1992, 2004, 2010, 2023]
 
 
 @dataclass(frozen=True)
@@ -47,7 +47,7 @@ class GuidelinesThresholds:
     """
     Guidelines threholds by Guidelines publication year
 
-    ΔHHI, Recapture Rate, GUPPI, Diversion ratio, CMCR, and IPR thresholds
+    ΔHHI, Recapture Ratio, GUPPI, Diversion ratio, CMCR, and IPR thresholds
     constructed from concentration standards in Guidelines published in
     1992, 2004, 2010, and 2023.
 
@@ -70,7 +70,7 @@ class GuidelinesThresholds:
     """
     Negative presumption quantified on various measures
 
-    ΔHHI safeharbor bound, default recapture rate, GUPPI bound,
+    ΔHHI safeharbor bound, default recapture ratio, GUPPI bound,
     diversion ratio limit, CMCR, and IPR
     """
 
@@ -78,7 +78,7 @@ class GuidelinesThresholds:
     """
     Presumption of harm defined in HMG
 
-    ΔHHI bound and corresponding default recapture rate, GUPPI bound,
+    ΔHHI bound and corresponding default recapture ratio, GUPPI bound,
     diversion ratio limit, CMCR, and IPR
     """
 
@@ -87,7 +87,7 @@ class GuidelinesThresholds:
     Presumption of harm imputed from guidelines
 
     ΔHHI bound inferred from strict numbers-equivalent
-    of (post-merger) HHI presumption, and corresponding default recapture rate,
+    of (post-merger) HHI presumption, and corresponding default recapture ratio,
     GUPPI bound, diversion ratio limit, CMCR, and IPR
     """
 
@@ -233,11 +233,11 @@ def _rec_spec_validator(
     _value: RECForm,
     /,
 ) -> None:
-    if _value == RECForm.OUTIN and _instance.recapture_rate:
+    if _value == RECForm.OUTIN and _instance.recapture_ratio:
         raise ValueError(
             f"Invalid recapture specification, {_value!r}. "
             "You may consider specifying `mergeron.RECForm.INOUT` here, and "
-            'assigning the default recapture rate as attribute, "recapture_rate" of '
+            'assigning the default recapture ratio as attribute, "recapture_ratio" of '
             "this `DiversionRatioBoundarySpec` object."
         )
     if _value is None and _instance.agg_method != UPPAggrSelector.MAX:
@@ -251,7 +251,7 @@ class DiversionRatioBoundary:
     """
     Diversion ratio specification, boundary coordinates, and area under boundary.
 
-    Along with the default diversion ratio and recapture rate,
+    Along with the default diversion ratio and recapture ratio,
     a diversion ratio boundary specification includes the recapture form --
     whether fixed for both merging firms' products ("proportional") or
     consistent with share-proportionality, i.e., "inside-out";
@@ -267,7 +267,7 @@ class DiversionRatioBoundary:
         validator=(validators.instance_of(float), _divr_value_validator),
     )
 
-    recapture_rate: float = field(
+    recapture_ratio: float = field(
         kw_only=False, default=DEFAULT_REC_RATE, validator=validators.instance_of(float)
     )
 
@@ -277,13 +277,13 @@ class DiversionRatioBoundary:
         validator=(validators.instance_of((type(None), RECForm)), _rec_spec_validator),
     )
     """
-    The form of the recapture rate.
+    The form of the recapture ratio.
 
-    When :attr:`mergeron.RECForm.INOUT`, the recapture rate for
+    When :attr:`mergeron.RECForm.INOUT`, the recapture ratio for
     he product having the smaller market-share is assumed to equal the default,
-    and the recapture rate for the product with the larger market-share is
-    computed assuming MNL demand. Fixed recapture rates are specified as
-    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture rates be
+    and the recapture ratio for the product with the larger market-share is
+    computed assuming MNL demand. Fixed recapture ratios are specified as
+    :attr:`mergeron.RECForm.FIXED`. (To specify that recapture ratios be
     constructed from the generated purchase-probabilities for products in
     the market and for the outside good, specify :attr:`mergeron.RECForm.OUTIN`.)
 
@@ -331,7 +331,7 @@ class DiversionRatioBoundary:
 
     def __attrs_post_init__(self, /) -> None:
         _share_ratio = critical_share_ratio(
-            self.diversion_ratio, r_bar=self.recapture_rate
+            self.diversion_ratio, r_bar=self.recapture_ratio
         )
         _upp_agg_kwargs: gbfn.ShareRatioBoundaryKeywords = {
             "recapture_form": getattr(self.recapture_form, "value", "inside-out"),
@@ -370,7 +370,7 @@ class DiversionRatioBoundary:
 
                 _upp_agg_kwargs |= {"agg_method": _aggregator, "weighting": _wgt_type}
 
-        _boundary = _upp_agg_fn(_share_ratio, self.recapture_rate, **_upp_agg_kwargs)
+        _boundary = _upp_agg_fn(_share_ratio, self.recapture_ratio, **_upp_agg_kwargs)
         object.__setattr__(self, "coordinates", _boundary.coordinates)
         object.__setattr__(self, "area", _boundary.area)
 
@@ -392,11 +392,11 @@ def guppi_from_delta(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
-        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture rate.
+        GUPPI bound corresponding to ∆HHI bound, at given margin and recapture ratio.
 
     """
     return gbfn.round_cust(
@@ -424,12 +424,12 @@ def critical_share_ratio(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
         Critical share ratio (share ratio bound) corresponding to the GUPPI bound
-        for given margin and recapture rate.
+        for given margin and recapture ratio.
 
     """
     return gbfn.round_cust(
@@ -445,7 +445,7 @@ def share_from_guppi(
     r_bar: float = DEFAULT_REC_RATE,
 ) -> float:
     """
-    Symmetric-firm share for given GUPPI, margin, and recapture rate.
+    Symmetric-firm share for given GUPPI, margin, and recapture ratio.
 
     Parameters
     ----------
@@ -454,13 +454,13 @@ def share_from_guppi(
     m_star
         Parametric price-cost margin.
     r_bar
-        Default recapture rate.
+        Default recapture ratio.
 
     Returns
     -------
     float
         Symmetric firm market share on GUPPI boundary, for given margin and
-        recapture rate.
+        recapture ratio.
 
     """
 

mergeron/demo/visualize_empirical_margin_distribution.py

@@ -48,10 +48,9 @@ with warnings.catch_warnings():
 mgn_kde = stats.gaussian_kde(mgn_data_obs, weights=mgn_data_wts, bw_method="silverman")
 mgn_kde.set_bandwidth(bw_method=mgn_kde.factor / 3.0)
 
-mgn_xvec = np.linspace(0, BIN_COUNT, 10**5) / BIN_COUNT
 mgn_ax.plot(
-    mgn_xvec,
-    mgn_kde(mgn_xvec),
+    (_xv := np.linspace(0, BIN_COUNT, 10**5) / BIN_COUNT),
+    mgn_kde(_xv),
     color="#004488",
     rasterized=True,
     label="Estimated Density",

mergeron/gen/__init__.py

@@ -105,15 +105,14 @@ class ShareSpec:
 
     Notes
     -----
-    If :attr:`mergeron.gen.ShareSpec.dist_type`:code:` == `:attr:`mergeron.gen.SHRDistribution.UNI`,
+    If :attr:`mergeron.gen.ShareSpec.dist_type` == :attr:`mergeron.gen.SHRDistribution.UNI`,
     then it is infeasible that
-    :attr:`mergeron.gen.ShareSpec.recapture_form`:code:` == `:attr:`mergeron.RECForm.OUTIN`.
-    In other words, if firm-counts are unspecified, the recapture rate cannot be
-    estimated using outside good choice probabilities.
+    :attr:`mergeron.gen.ShareSpec.recapture_form` == :attr:`mergeron.RECForm.OUTIN`.
+    In other words, if the distribution of markets over firm-counts is unspecified,
+    recapture ratios cannot be estimated using outside-good choice probabilities.
 
-    For a sample with explicit firm counts, market shares must
-    be specified as having a supported Dirichlet distribution
-    (see :class:`mergeron.gen.SHRDistribution`).
+    For a sample with explicit firm counts, market shares must be specified as
+    having a supported Dirichlet distribution (see :class:`mergeron.gen.SHRDistribution`).
 
     """
 
@@ -161,19 +160,19 @@ class ShareSpec:
     def _check_rf(_i: ShareSpec, _a: Attribute[RECForm], _v: RECForm) -> None:
         if _v == RECForm.OUTIN and _i.dist_type == SHRDistribution.UNI:
             raise ValueError(
-                "Market share specification requires estimation of recapture rate from "
-                "generated data. Either delete recapture rate specification or set it to None."
+                "Market share specification requires estimation of recapture ratio from "
+                "generated data. Either delete recapture ratio specification or set it to None."
             )
 
-    recapture_rate: float | None = field(default=DEFAULT_REC_RATE)
+    recapture_ratio: float | None = field(default=DEFAULT_REC_RATE)
     """A value between 0 and 1.
 
     :code:`None` if market share specification requires direct generation of
     outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
 
-    The recapture rate is usually calibrated to the numbers-equivalent of the
+    The recapture ratio is usually calibrated to the numbers-equivalent of the
     HHI threshold for the presumtion of harm from unilateral competitive effects
-    in published merger guidelines. Accordingly, the recapture rate rounded to
+    in published merger guidelines. Accordingly, the recapture ratio rounded to
     the nearest 5% is:
 
     * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1992, 2023
@@ -188,14 +187,14 @@ class ShareSpec:
 
     """
 
-    @recapture_rate.validator
+    @recapture_ratio.validator
     def _check_rr(_i: ShareSpec, _a: Attribute[float], _v: float) -> None:
         if _v and not (0 < _v <= 1):
-            raise ValueError("Recapture rate must lie in the interval, [0, 1).")
+            raise ValueError("Recapture ratio must lie in the interval, [0, 1).")
         elif _v is None and _i.recapture_form != RECForm.OUTIN:
             raise ValueError(
                 f"Recapture specification, {_i.recapture_form!r} requires that "
-                "the market sample specification inclues a recapture rate in the "
+                "the market sample specification inclues a recapture ratio in the "
                 "interval [0, 1)."
             )
 

mergeron/gen/data_generation.py

@@ -134,7 +134,7 @@ class MarketSample:
         """
 
         _recapture_form = self.share_spec.recapture_form
-        _recapture_rate = self.share_spec.recapture_rate
+        _recapture_ratio = self.share_spec.recapture_ratio
         _dist_type_mktshr = self.share_spec.dist_type
         _dist_firm2_pcm = self.pcm_spec.firm2_pcm_constraint
         _hsr_filing_test_type = self.hsr_filing_test_type
@@ -208,7 +208,7 @@ class MarketSample:
         # Calculate diversion ratios
         _divr_array = gen_divr_array(
             _recapture_form,
-            _recapture_rate,
+            _recapture_ratio,
             _mktshr_array[:, :2],
             _aggregate_purchase_prob,
         )
@@ -410,11 +410,11 @@ class MarketSample:
 
         if (
             self.share_spec.recapture_form != RECForm.OUTIN
-            and self.share_spec.recapture_rate != _enf_parm_vec.rec
+            and self.share_spec.recapture_ratio != _enf_parm_vec.rec
         ):
             raise ValueError(
                 "{} {} {}".format(
-                    f"Recapture rate from market sample spec, {self.share_spec.recapture_rate}",
+                    f"Recapture ratio from market sample spec, {self.share_spec.recapture_ratio}",
                     f"must match the value, {_enf_parm_vec.rec}",
                     "the guidelines thresholds vector.",
                 )

mergeron/gen/data_generation_functions.py

@@ -106,7 +106,7 @@ def gen_share_data(
 
     # If recapture_form == "inside-out", recalculate _aggregate_purchase_prob
     _frmshr_array = _mkt_share_sample.mktshr_array[:, :2]
-    _r_bar = _share_spec.recapture_rate or DEFAULT_REC_RATE
+    _r_bar = _share_spec.recapture_ratio or DEFAULT_REC_RATE
     if _recapture_form == RECForm.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
@@ -409,7 +409,7 @@ def gen_market_shares_dirichlet(
 
 def gen_divr_array(
     _recapture_form: RECForm,
-    _recapture_rate: float | None,
+    _recapture_ratio: float | None,
     _frmshr_array: ArrayDouble,
     _aggregate_purchase_prob: ArrayDouble = EMPTY_ARRAY_DEFAULT,
     /,
@@ -425,8 +425,8 @@ def gen_divr_array(
     _recapture_form
         Enum specifying Fixed (proportional), Inside-out, or Outside-in
 
-    _recapture_rate
-        If recapture is proportional or inside-out, the recapture rate
+    _recapture_ratio
+        If recapture is proportional or inside-out, the recapture ratio
         for the firm with the smaller share.
 
     _frmshr_array
@@ -450,7 +450,7 @@ def gen_divr_array(
 
     _divr_array: ArrayDouble
     if _recapture_form == RECForm.FIXED:
-        _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
+        _divr_array = _recapture_ratio * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
 
     else:
         _purchprob_array = _aggregate_purchase_prob * _frmshr_array

mergeron/gen/upp_tests.py

@@ -7,11 +7,12 @@ from generated market data.
 from collections.abc import Sequence
 from contextlib import suppress
 from pathlib import Path
-from typing import Literal, TypeAlias, TypedDict
+from typing import Any, Literal, TypedDict
 
 import numpy as np
 import tables as ptb  # type: ignore
 from numpy.random import SeedSequence
+from numpy.typing import NDArray
 
 from .. import (  # noqa
     VERSION,
@@ -40,7 +41,7 @@ __version__ = VERSION
 ptb.parameters.MAX_NUMEXPR_THREADS = 8
 ptb.parameters.MAX_BLOSC_THREADS = 4
 
-SaveData: TypeAlias = Literal[False] | tuple[Literal[True], ptb.File, ptb.Group]
+type SaveData = Literal[False] | tuple[Literal[True], ptb.File, ptb.Group]
 
 
 class INVRESCntsArgs(TypedDict, total=False):
@@ -213,7 +214,8 @@ def compute_upp_test_arrays(
 
     """
     _g_bar, _divr_bar, _cmcr_bar, _ipr_bar = (
-        getattr(_upp_test_parms, _f) for _f in ("guppi", "divr", "cmcr", "ipr"))
+        getattr(_upp_test_parms, _f) for _f in ("guppi", "divr", "cmcr", "ipr")
+    )
 
     _guppi_array, _ipr_array, _cmcr_array = (
         np.empty_like(_market_data.price_array) for _ in range(3)
@@ -366,7 +368,7 @@ def save_data_to_hdf5(
 
 
 def save_array_to_hdf5(
-    _array_obj: ArrayFloat | ArrayINT | ArrayDouble | ArrayBIGINT | ArrayBoolean,
+    _array_obj: NDArray[Any],
     _array_name: str,
     _h5_group: ptb.Group,
     _h5_file: ptb.File,

{mergeron-2024.739127.0.dist-info → mergeron-2024.739139.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.739127.0
+Version: 2024.739139.0
 Summary: Merger Policy Analysis using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
@@ -41,23 +41,23 @@ 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 implied 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.
+Visualize the sets of mergers conforming to concentration and diversion-ratio standards. Estimate 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 implied 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.
 
 Here, enforcement rates derived with merger enforcement as being exogenous to firm conduct are defined as intrinsic enforcement rates, and similarly intrinsic clearance rates. 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, by definition, the observed clearance rate is 1 minus the observed enforcement rate.
 
 Introduction
 ------------
 
-Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`.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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`.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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
 
-Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) 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 (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
+Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) computing the intrinsic enforcement rate and intrinsic clearance rate for the generated sample, given a method (:code:`.UPPAggrSelector`) of aggregating diversion ratio or GUPPI estimates for the firms in a merger (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
 and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.share_spec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
 
 By default, 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 (see property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec`, of type, :code:`.gen.SHRDistribution`), with specified shape parameters (property `dist_parms` of :code:`.gen.data_generation.MarketSample.share_spec`. When drawing shares from the Dirichlet distribution, the user specifies the `firm_count_weights` property of :code:`.gen.data_generation.MarketSample.share_spec`, as 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 the property `firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.share_spec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
 
-Recapture rates can be specified as, "proportional", "inside-out", or "outside-in" (see :code:`.RECForm`). The "inside-out" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) 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:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when the property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec` is assigned :code:`.gen.ShareDistributions.UNI`, raising a :code:`ValueError` exception. The "proportional" form (`recapture_form` = :code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" calibration. See, for example, Coate (2011).
+Recapture ratios can be specified as, "proportional", "inside-out", or "outside-in" (see :code:`.RECForm`). The "inside-out" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) results in recapture ratios consistent with MNL demand, given merging-firms' in-market shares and a default recapture ratio. The "outside-in" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) yields diversion ratios from purchase probabilities drawn at random for :math:`N+1` goods, with market shares and recapture ratios for the :math:`N` goods in the putative market (see, :code:`.gen.ShareSpec`) computed from the simulated choice probabilities. The "outside-in" specification requires specification of the distribution of markets over firm counts (the default being uniform distirbution over markets with 2 to 7 firms pre-merger), and Dirichlet-distributed shares, with optional parameters (the default being a "flat" Dirichlet distribution, i.e., one with all parameters being 1). The parameters of the Dirichlet distribution can, for example, be specified to increase (decrease) the probability of drawing mergers to monopoly relative to that probability associated with the Flat Dirichlet specification, by setting the first 2 specified parameters at higher (lower) values relative to the others. Lastly, the "proportional" form of recapture ratio (`recapture_form` = :code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" calibration. See, for example, Coate (2011).
 
-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 (see, :code:`.gen.PCMSpec`). 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 (per the property `firm2_pcm_constraint` of :code:`.gen.data_generation.MarketSample.pcm_spec`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or a built-in empirical distribution (see, :code:`.gen.PCMSpec`). The in-built 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 (per the property `firm2_pcm_constraint` of :code:`.gen.data_generation.MarketSample.pcm_spec`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
 
 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:`.gen.PriceSpec`). Prices may also be defined by imposing cost symmetry on firms in the sample, with fixed unit marginal costs normalized to 1 unit, such that prices equal :math:`1 / (1 - \pmb{m})`, where :math:`\pmb{m}` represents the array of margins for firms in the sample.
 
@@ -65,11 +65,11 @@ The market sample may be restricted to mergers meeting the HSR filing requiremen
 
 The full specification of a market sample is given in a :code:`.gen.data_generation.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`.gen.data_generation.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`.gen.data_generation.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`.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:`.gen.data_generation.MarketSample.estimate_enf_counts` on a :code:`.gen.data_generation.MarketSample` object without first invoking :code:`.gen.data_generation.MarketSample.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 performance 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:`.gen.enforcement_stats`.
+Enforcement statistics based on FTC investigations data and test data are tabulated using methods provided in :code:`.gen.enforcement_stats`.
 
 Programs demonstrating the use of this package are included in the sub-package, :code:`.demo`.
 
-This package includes  a class, :code:`.core.pseudorandom_numbers.MultithreadedRNG` 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:
+This package includes  a class, :code:`.core.pseudorandom_numbers.MultithreadedRNG` for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple CPU cores, be they virtual, logical, or physical cores. This class is an adaptation from the documentation for the external :code:`numpy.random` subpackage, from the discussion on, "`Multithreaded 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
 

{mergeron-2024.739127.0.dist-info → mergeron-2024.739139.0.dist-info}/RECORD

@@ -1,9 +1,9 @@
 mergeron/License.txt,sha256=7iX-y0EyjkbVJKJLS4ZKzuuE1wd0lryfsD_IytLG8lQ,1246
-mergeron/__init__.py,sha256=bTcTGdrdd0aHh_uD3Pl84q1uw-13oAwbGOXHqpK6vI8,1479
+mergeron/__init__.py,sha256=hiOhxFInENJRReecosK422vBUnZGrOEutNkWfEs7JOs,1460
 mergeron/core/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/core/damodaran_margin_data.py,sha256=rMrgN1Qtw572a0ftY97OOj4otq8ldlLrcOi-bcE-org,8554
-mergeron/core/ftc_merger_investigations_data.py,sha256=Q8d2N4brY2cwJClibwxOVfLE3WV0XZABssblGN6nOdA,28639
-mergeron/core/guidelines_boundaries.py,sha256=sEvIIaOvWl6tMDYeZCIr8EsBioXOn9RSXKyKlmxnH-k,15610
+mergeron/core/ftc_merger_investigations_data.py,sha256=eldNU4hX9oKE4Rb08YE9_1LgolvNKZnhOXW6KyWSwnM,28622
+mergeron/core/guidelines_boundaries.py,sha256=7C5hMa8vijDZbLdrSxO3XHpsXF5e7PZFpI-abDKqt90,15616
 mergeron/core/guidelines_boundary_functions.py,sha256=GGn5mwBWmxkqcat4Ya0D-J6-7ujosgCCK3eJ9RFWASI,29749
 mergeron/core/guidelines_boundary_functions_extra.py,sha256=HDwwKZDWlrj3Tw-I0gHm0TCSDcIyb9jDfwbuDvK55B8,11322
 mergeron/core/pseudorandom_numbers.py,sha256=cJEWDTfy9CUTzR_di6Fm1Vl1Le6xWoU8wFHbYVMEuLI,9225
@@ -12,13 +12,13 @@ mergeron/data/damodaran_margin_data.xls,sha256=Qggl1p5nkOMJI8YUXhkwXQRz-OhRSqBTz
 mergeron/data/damodaran_margin_data_dict.msgpack,sha256=sr6s4L69kposEpzGI7jpPb4ULz0UpY-bEYfeNi6UlRA,57621
 mergeron/data/ftc_invdata.msgpack,sha256=WBFHgi7Ld4R-h2zL2Zc3TOIlKqVrbVFMH1LoI4-T-M0,264664
 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=0rfcWpKDhYE_jNsw6xKTGFJqgNtfJ-5JFxHS89CIEuI,16575
-mergeron/gen/data_generation.py,sha256=jSpwB2BHBDPVTsT1-NZhTSCcUV6816qn5oZBe6S0Hio,16797
-mergeron/gen/data_generation_functions.py,sha256=bP3E0IPXINRc8s0dUxS_Wqo1byVzheZLX811A17WNbU,28571
+mergeron/demo/visualize_empirical_margin_distribution.py,sha256=R-sGC87kVovWBqcM5U6GiNC9oLsbNaMTJgljv8ts8w0,2347
+mergeron/gen/__init__.py,sha256=DU6uFbRwe6ng-2sKCmpymD90CDNmyelWvUnmtNu8iHM,16593
+mergeron/gen/data_generation.py,sha256=czTZcVZnT5kWViSFdSdbo0kupq1tUKGrKH5RThXbDwk,16803
+mergeron/gen/data_generation_functions.py,sha256=Ag6u1yZ93ikGuKhj7PWbJ2lCZHxNGTemDfhK8p5xFq0,28576
 mergeron/gen/enforcement_stats.py,sha256=ZjrV_VkFMF0D1myc-fj-W99M1EhJMA9-nCfyE5g9e54,10890
-mergeron/gen/upp_tests.py,sha256=PtPOcu1zPDoHJUi06ytDUPNk21rzMwnfeGqUhvYXZs0,12607
+mergeron/gen/upp_tests.py,sha256=uRF4RrBo3amwQQSu661Xa50xKGMUxtnM3zRtYy3nyB0,12581
 mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-mergeron-2024.739127.0.dist-info/METADATA,sha256=rvQUQmlBT2ECLY4t9Dy4fnUN1-A_sn_5f09z_IYNPE4,13976
-mergeron-2024.739127.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-mergeron-2024.739127.0.dist-info/RECORD,,
+mergeron-2024.739139.0.dist-info/METADATA,sha256=NrSRBKtvNhW9KFKRB4gW_YK39BmhFKiA8DNtz-nZQ7g,14430
+mergeron-2024.739139.0.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+mergeron-2024.739139.0.dist-info/RECORD,,