mergeron 2024.738953.1__py3-none-any.whl → 2024.738972.0__py3-none-any.whl

mergeron/gen/__init__.py

@@ -5,23 +5,21 @@ Defines constants and containers for industry data generation and testing
 
 from __future__ import annotations
 
-from importlib.metadata import version
-
-from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
-
-__version__ = version(_PKG_NAME)
-
-
 import enum
 from dataclasses import dataclass
+from importlib.metadata import version
 from typing import ClassVar, Protocol, TypeVar
 
 import numpy as np
-from attrs import Attribute, define, field, validators
+from attrs import Attribute, define, field, frozen, validators
 from numpy.typing import NBitBase, NDArray
 
+from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
 
+__version__ = version(_PKG_NAME)
+
+
 EMPTY_ARRAY_DEFAULT = np.zeros(2)
 FCOUNT_WTS_DEFAULT = ((_nr := np.arange(1, 6)[::-1]) / _nr.sum()).astype(np.float64)
 
@@ -74,7 +72,7 @@ class SHRConstants(enum.StrEnum):
     """
 
 
-@define(slots=True, frozen=True)
+@frozen
 class ShareSpec:
     """Market share specification
 
@@ -88,9 +86,28 @@ class ShareSpec:
 
     """
 
-    recapture_spec: RECConstants
+    recapture_form: RECConstants
     """see RECConstants"""
 
+    recapture_rate: float | None
+    """A value between 0 and 1.
+
+    None if market share specification requires direct generation of
+    outside good choice probabilities (RECConstants.OUTIN).
+
+    The recapture rate is usually calibrated to the numbers-equivalent of the
+    HHI threshold for the presumtion of harm from unilateral compoetitive effects
+    in published merger guidelines. Accordingly, values for the recapture rate may be:
+
+    * 0.855, **6-to-5 merger from symmetry**; US Guidelines, 1992, 2023
+    * 0.855, 6-to-5 merger from symmetry; EU Guidelines for horizontal mergers, 2004
+    * 0.82, **6-to-5 merger to symmetry**; EU Guidelines for horizontal mergers, 2004
+    * 0.80, 5-to-4 merger from symmetry; US Guidelines, 2010
+    * 0.78, **5-to-4 merger to symmetry**; US Guidelines, 2010
+
+    Highlighting indicates hypothetical mergers close to the boundary of the presumption.
+    """
+
     dist_type: SHRConstants
     """see SHRConstants"""
 
@@ -133,7 +150,7 @@ class FM2Constants(enum.StrEnum):
     SYM = "symmetric"
 
 
-@define(slots=True, frozen=True)
+@frozen
 class PCMSpec:
     """Price-cost margin (PCM) specification
 
@@ -149,12 +166,12 @@ class PCMSpec:
 
     """
 
-    dist_type: PCMConstants
-    """See PCMConstants"""
-
     firm2_pcm_constraint: FM2Constants
     """See FM2Constants"""
 
+    dist_type: PCMConstants
+    """See PCMConstants"""
+
     dist_parms: NDArray[np.float64] | None
     """Parameter specification for tailoring PCM distribution
 
@@ -205,40 +222,33 @@ class SSZConstants(float, enum.ReprEnum):
     """When initial set of draws is not restricted in any way."""
 
 
-# Validators for selected attributes of MarketSampleSpec
+# Validators for selected attributes of MarketSpec
 def _sample_size_validator(
-    _object: MarketSampleSpec, _attribute: Attribute[int], _value: int, /
+    _object: MarketSpec, _attribute: Attribute[int], _value: int, /
 ) -> None:
     if _value < 10**6:
         raise ValueError(
-            f"Sample size must be not less than {10**6:,d}. Got, {_value:,d}."
+            f"Sample size must be no less than {10**6:,d}; got, {_value:,d}."
         )
 
 
-def _recapture_rate_validator(
-    _object: MarketSampleSpec,
-    _attribute: Attribute[float | None],
-    _value: float | None,
-    /,
+def _share_spec_validator(
+    _instance: MarketSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
 ) -> None:
-    if _value and not (0 < _value <= 1):
+    _r_bar = _value.recapture_rate
+    if _r_bar and not (0 < _r_bar <= 1):
         raise ValueError("Recapture rate must lie in the interval, [0, 1).")
 
-    if _value and _object.share_spec.recapture_spec == RECConstants.OUTIN:
+    elif _r_bar and _value.recapture_form == RECConstants.OUTIN:
         raise ValueError(
             "Market share specification requires estimation of recapture rate from "
             "generated data. Either delete recapture rate specification or set it to None."
         )
 
-
-def _share_spec_validator(
-    _instance: MarketSampleSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
-) -> None:
-    _r_bar = _instance.recapture_rate
     if _value.dist_type == SHRConstants.UNI:
-        if _value.recapture_spec == RECConstants.OUTIN:
+        if _value.recapture_form == RECConstants.OUTIN:
             raise ValueError(
-                f"Invalid recapture specification, {_value.recapture_spec!r} "
+                f"Invalid recapture specification, {_value.recapture_form!r} "
                 "for market share specification with Uniform distribution. "
                 "Redefine the market-sample specification, modifying the ."
                 "market-share specification or the recapture specification."
@@ -246,32 +256,31 @@ def _share_spec_validator(
         elif _value.firm_counts_weights is not None:
             raise ValueError(
                 "Generated data for markets with specified firm-counts or "
-                "varying firm counts are not feasible with market shares "
+                "varying firm counts are not feasible for market shares "
                 "with Uniform distribution. Consider revising the "
                 r"distribution type to {SHRConstants.DIR_FLAT}, which gives "
                 "uniformly distributed draws on the :math:`n+1` simplex "
                 "for firm-count, :math:`n`."
             )
-        #   Outside-in calibration only valid for Dir-distributed shares
-    elif _value.recapture_spec != RECConstants.OUTIN and (
+    elif _value.recapture_form != RECConstants.OUTIN and (
         _r_bar is None or not isinstance(_r_bar, float)
     ):
         raise ValueError(
-            f"Recapture specification, {_value.recapture_spec!r} requires that "
+            f"Recapture specification, {_value.recapture_form!r} requires that "
             "the market sample specification inclues a recapture rate."
         )
 
 
 def _pcm_spec_validator(
-    _instance: MarketSampleSpec, _attribute: Attribute[PCMSpec], _value: PCMSpec, /
+    _instance: MarketSpec, _attribute: Attribute[PCMSpec], _value: PCMSpec, /
 ) -> None:
     if (
-        _instance.share_spec.recapture_spec == RECConstants.FIXED
+        _instance.share_spec.recapture_form == RECConstants.FIXED
         and _value.firm2_pcm_constraint == FM2Constants.MNL
     ):
         raise ValueError(
             "{} {} {}".format(
-                f'Specification of "recapture_spec", "{_instance.share_spec.recapture_spec}"',
+                f'Specification of "recapture_form", "{_instance.share_spec.recapture_form}"',
                 "requires Firm 2 margin must have property, ",
                 f'"{FM2Constants.IID}" or "{FM2Constants.SYM}".',
             )
@@ -297,49 +306,35 @@ def _pcm_spec_validator(
             )
 
 
-@define(slots=True, frozen=True)
-class MarketSampleSpec:
+@define(slots=False)
+class MarketSpec:
     """Parameter specification for market data generation."""
 
-    sample_size: int = field(
-        default=10**6, validator=(validators.instance_of(int), _sample_size_validator)
-    )
-    """sample size generated"""
-
-    recapture_rate: float | None = field(
-        default=None, validator=_recapture_rate_validator
-    )
-    """market recapture rate
-
-    Is None if market share specification requires generation of
-    outside good choice probabilities (RECConstants.OUTIN).
-    """
-
-    pr_sym_spec: PRIConstants = field(  # type: ignore
-        kw_only=True,
-        default=PRIConstants.SYM,
-        validator=validators.instance_of(PRIConstants),  # type: ignore
-    )
-    """Price specification, see PRIConstants"""
-
     share_spec: ShareSpec = field(
         kw_only=True,
-        default=ShareSpec(RECConstants.INOUT, SHRConstants.UNI, None, None),
+        default=ShareSpec(RECConstants.INOUT, 0.855, SHRConstants.UNI, None, None),
         validator=[validators.instance_of(ShareSpec), _share_spec_validator],
     )
-    """See definition of ShareSpec"""
+    """Market-share specification, see definition of ShareSpec"""
 
     pcm_spec: PCMSpec = field(
         kw_only=True,
-        default=PCMSpec(PCMConstants.UNI, FM2Constants.IID, None),
+        default=PCMSpec(FM2Constants.IID, PCMConstants.UNI, None),
         validator=[validators.instance_of(PCMSpec), _pcm_spec_validator],
     )
-    """See definition of PCMSpec"""
+    """Margin specification, see definition of PCMSpec"""
+
+    price_spec: PRIConstants = field(
+        kw_only=True,
+        default=PRIConstants.SYM,
+        validator=validators.instance_of(PRIConstants),
+    )
+    """Price specification, see PRIConstants"""
 
-    hsr_filing_test_type: SSZConstants = field(  # type: ignore
+    hsr_filing_test_type: SSZConstants = field(
         kw_only=True,
         default=SSZConstants.ONE,
-        validator=validators.instance_of(SSZConstants),  # type: ignore
+        validator=validators.instance_of(SSZConstants),
     )
     """Method for modeling HSR filing threholds, see SSZConstants"""
 
@@ -351,19 +346,16 @@ class INVResolution(enum.StrEnum):
     BOTH = "both"
 
 
-@define(slots=True, frozen=True)
+@frozen
 class UPPTestRegime:
-    resolution: INVResolution = field(  # type: ignore
-        default=INVResolution.ENFT,
-        validator=validators.instance_of(INVResolution),  # type: ignore
+    resolution: INVResolution = field(
+        default=INVResolution.ENFT, validator=validators.instance_of(INVResolution)
     )
-    guppi_aggregator: UPPAggrSelector = field(  # type: ignore
-        default=UPPAggrSelector.MAX,
-        validator=validators.instance_of(UPPAggrSelector),  # type: ignore
+    guppi_aggregator: UPPAggrSelector = field(
+        default=UPPAggrSelector.MIN, validator=validators.instance_of(UPPAggrSelector)
     )
-    divr_aggregator: UPPAggrSelector | None = field(  # type: ignore
-        default=guppi_aggregator,
-        validator=validators.instance_of(UPPAggrSelector | None),  # type: ignore
+    divr_aggregator: UPPAggrSelector | None = field(
+        default=None, validator=validators.instance_of((UPPAggrSelector, type(None)))
     )
 
 
@@ -469,7 +461,7 @@ class MarginDataSample:
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsRaw:
-    """arrays marking test failures and successes
+    """Container for arrays marking test failures and successes
 
     A test success is a draw ("market") that meeets the
     specified test criterion, and a test failure is
@@ -494,9 +486,9 @@ class UPPTestsRaw:
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsCounts:
-    """counts of markets resolved as specified
+    """Counts of markets resolved as specified
 
-    Resolution is specified in a UPPTestRegime object.
+    Resolution may be either "enforcement" or "clearance".
     """
 
     by_firm_count: NDArray[np.int64]

mergeron/gen/{_data_generation_functions_nonpublic.py → _data_generation_functions.py}

@@ -19,11 +19,12 @@ from ..core.pseudorandom_numbers import (  # noqa: TID252
     prng,
 )
 from . import (
+    EMPTY_ARRAY_DEFAULT,
     FCOUNT_WTS_DEFAULT,
     TF,
     FM2Constants,
     MarginDataSample,
-    MarketSampleSpec,
+    MarketSpec,
     PCMConstants,
     PriceDataSample,
     PRIConstants,
@@ -36,7 +37,8 @@ __version__ = version(_PKG_NAME)
 
 
 def _gen_share_data(
-    _mkt_sample_spec: MarketSampleSpec,
+    _sample_size: int,
+    _mkt_sample_spec: MarketSpec,
     _fcount_rng_seed_seq: SeedSequence | None,
     _mktshr_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
@@ -61,14 +63,12 @@ def _gen_share_data(
 
     """
 
-    _recapture_spec, _dist_type_mktshr, _dist_parms_mktshr, _firm_count_prob_wts_raw = (
+    _recapture_form, _dist_type_mktshr, _dist_parms_mktshr, _firm_count_prob_wts_raw = (
         getattr(_mkt_sample_spec.share_spec, _f)
-        for _f in ("recapture_spec", "dist_type", "dist_parms", "firm_counts_weights")
+        for _f in ("recapture_form", "dist_type", "dist_parms", "firm_counts_weights")
     )
 
-    _ssz = _mkt_sample_spec.sample_size
-
-    _r_bar = _mkt_sample_spec.recapture_rate or 0.80
+    _ssz = _sample_size
 
     match _dist_type_mktshr:
         case SHRConstants.UNI:
@@ -84,7 +84,7 @@ def _gen_share_data(
             )
             _mkt_share_sample = _gen_market_shares_dirichlet_multisample(
                 _ssz,
-                _recapture_spec,
+                _recapture_form,
                 _dist_type_mktshr,
                 _dist_parms_mktshr,
                 _firm_count_prob_wts,
@@ -98,9 +98,10 @@ def _gen_share_data(
                 f'Unexpected type, "{_dist_type_mktshr}" for share distribution.'
             )
 
-    # If recapture_spec == "inside-out", recalculate _aggregate_purchase_prob
+    # If recapture_form == "inside-out", recalculate _aggregate_purchase_prob
     _frmshr_array = _mkt_share_sample.mktshr_array[:, :2]
-    if _recapture_spec == RECConstants.INOUT:
+    _r_bar = _mkt_sample_spec.share_spec.recapture_rate or 0.855
+    if _recapture_form == RECConstants.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
             _mkt_share_sample.fcounts,
@@ -176,10 +177,10 @@ def _gen_market_shares_uniform(
 
 def _gen_market_shares_dirichlet_multisample(
     _s_size: int = 10**6,
-    _recapture_spec: RECConstants = RECConstants.INOUT,
+    _recapture_form: RECConstants = RECConstants.INOUT,
     _dist_type_dir: SHRConstants = SHRConstants.DIR_FLAT,
     _dist_parms_dir: NDArray[np.floating[TF]] | None = None,
-    _firm_count_wts: NDArray[np.floating[TF]] | None = None,  # type: ignore
+    _firm_count_wts: NDArray[np.floating[TF]] | None = None,
     _fcount_rng_seed_seq: SeedSequence | None = None,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
@@ -202,7 +203,7 @@ def _gen_market_shares_dirichlet_multisample(
         firm count weights array for sample to be drawn
     _dist_type_dir
         Whether Dirichlet is Flat or Asymmetric
-    _recapture_spec
+    _recapture_form
         r_1 = r_2 if "proportional", otherwise MNL-consistent
     _fcount_rng_seed_seq
         seed firm count rng, for replicable results
@@ -226,7 +227,7 @@ def _gen_market_shares_dirichlet_multisample(
         *(
             _f
             for _f in zip(
-                2 + np.arange(len(_firm_count_wts)),  # type: ignore
+                2 + np.arange(len(_firm_count_wts)),
                 _firm_count_wts / _firm_count_wts.sum(),
                 strict=True,
             )
@@ -277,7 +278,7 @@ def _gen_market_shares_dirichlet_multisample(
             _mktshr_sample_f = _gen_market_shares_dirichlet(
                 _dir_alphas_test,
                 len(_fcounts_match_rows),
-                _recapture_spec,
+                _recapture_form,
                 _f_sseq,
                 _nthreads,
             )
@@ -315,7 +316,7 @@ def _gen_market_shares_dirichlet_multisample(
 def _gen_market_shares_dirichlet(
     _dir_alphas: NDArray[np.floating[TF]],
     _s_size: int = 10**6,
-    _recapture_spec: RECConstants = RECConstants.INOUT,
+    _recapture_form: RECConstants = RECConstants.INOUT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
     /,
@@ -330,7 +331,7 @@ def _gen_market_shares_dirichlet(
         sample size to be drawn
     _r_bar
         market recapture rate
-    _recapture_spec
+    _recapture_form
         r_1 = r_2 if RECConstants.FIXED, otherwise MNL-consistent. If
         RECConstants.OUTIN; the number of columns in the output share array
         is len(_dir_alphas) - 1.
@@ -348,7 +349,7 @@ def _gen_market_shares_dirichlet(
     if not isinstance(_dir_alphas, np.ndarray):
         _dir_alphas = np.array(_dir_alphas)
 
-    if _recapture_spec == RECConstants.OUTIN:
+    if _recapture_form == RECConstants.OUTIN:
         _dir_alphas = np.concatenate((_dir_alphas, _dir_alphas[-1:]))
 
     _mktshr_seed_seq_ch = (
@@ -380,9 +381,9 @@ def _gen_market_shares_dirichlet(
             )
         )
 
-    # If recapture_spec == 'inside_out', further calculations downstream
+    # If recapture_form == 'inside_out', further calculations downstream
     _aggregate_purchase_prob = np.nan * np.empty((_s_size, 1))
-    if _recapture_spec == RECConstants.OUTIN:
+    if _recapture_form == RECConstants.OUTIN:
         _aggregate_purchase_prob = 1 - _mktshr_array[:, [-1]]
         _mktshr_array = _mktshr_array[:, :-1] / _aggregate_purchase_prob
 
@@ -394,27 +395,25 @@ def _gen_market_shares_dirichlet(
     )
 
 
-def _gen_pr_data(
-    _frmshr_array: NDArray[np.floating[TF]],
-    _nth_firm_share: NDArray[np.floating[TF]],
-    _mkt_sample_spec: MarketSampleSpec,
+def _gen_price_data(
+    _frmshr_array: NDArray[np.float64],
+    _nth_firm_share: NDArray[np.float64],
+    _mkt_sample_spec: MarketSpec,
     _seed_seq: SeedSequence | None = None,
     /,
 ) -> PriceDataSample:
-    _ssz = len(_frmshr_array)
-
     _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.empty_like(_frmshr_array),
-        np.empty(_ssz, dtype=bool),
+        np.ones_like(_frmshr_array, np.float64),
+        np.empty_like(_frmshr_array, np.float64),
+        np.empty(len(_frmshr_array), bool),
     )
 
     _pr_max_ratio = 5.0
-    match _mkt_sample_spec.pr_sym_spec:
+    match _mkt_sample_spec.price_spec:
         case PRIConstants.SYM:
-            _nth_firm_price = np.ones((_ssz, 1))
+            _nth_firm_price = np.ones((len(_frmshr_array), 1))
         case PRIConstants.POS:
             _price_array, _nth_firm_price = (
                 np.ceil(_p * _pr_max_ratio) for _p in (_frmshr_array, _nth_firm_share)
@@ -434,9 +433,8 @@ def _gen_pr_data(
         case _:
             raise ValueError(
                 f"Condition regarding price symmetry"
-                f' "{_mkt_sample_spec.pr_sym_spec.value}" is invalid.'
+                f' "{_mkt_sample_spec.price_spec.value}" is invalid.'
             )
-    # del _pr_max_ratio
 
     _price_array = _price_array.astype(np.float64)
     _rev_array = _price_array * _frmshr_array
@@ -444,7 +442,7 @@ def _gen_pr_data(
 
     # 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 policy.
+    # 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:
@@ -479,21 +477,21 @@ def _gen_pr_data(
             # del _nth_firm_rev, _rev_ratio_to_nth
         case _:
             # Otherwise, all draws meet the filing test
-            _hsr_filing_test = np.ones(_ssz, dtype=bool)
+            _hsr_filing_test = np.ones(len(_frmshr_array), dtype=bool)
 
     return PriceDataSample(_price_array, _hsr_filing_test)
 
 
 def _gen_pcm_data(
     _frmshr_array: NDArray[np.floating[TF]],
-    _mkt_sample_spec: MarketSampleSpec,
+    _mkt_sample_spec: MarketSpec,
     _price_array: NDArray[np.floating[TF]],
     _aggregate_purchase_prob: NDArray[np.floating[TF]],
     _pcm_rng_seed_seq: SeedSequence,
     _nthreads: int = 16,
     /,
 ) -> MarginDataSample:
-    _recapture_spec = _mkt_sample_spec.share_spec.recapture_spec
+    _recapture_form = _mkt_sample_spec.share_spec.recapture_form
     _dist_type_pcm, _dist_firm2_pcm, _dist_parms_pcm = (
         getattr(_mkt_sample_spec.pcm_spec, _f)
         for _f in ("dist_type", "firm2_pcm_constraint", "dist_parms")
@@ -506,27 +504,25 @@ def _gen_pcm_data(
     _mnl_test_array = np.empty((len(_frmshr_array), 2), dtype=int)
 
     _beta_min, _beta_max = [None] * 2  # placeholder
-    _dist_parms = np.ones(2, np.float64)
     if _dist_type_pcm == PCMConstants.EMPR:
         _pcm_array = resample_mgn_data(
             _pcm_array.shape,  # type: ignore
             seed_sequence=_pcm_rng_seed_seq,
         )
     else:
-        if _dist_type_pcm == PCMConstants.UNI:
-            _dist_parms = (
-                DIST_PARMS_DEFAULT if _dist_parms_pcm is None else _dist_parms_pcm
-            )
-        elif _dist_type_pcm == PCMConstants.BETA:
-            # Error-checking (could move to validators in definition of MarketSampleSpec)
-
+        if _dist_type_pcm == PCMConstants.BETA:
             if _dist_parms_pcm is None:
-                _dist_parms_pcm = _dist_parms
+                _dist_parms_pcm = np.ones(2, np.float64)
 
         elif _dist_type_pcm == PCMConstants.BETA_BND:  # Bounded beta
             if _dist_parms_pcm is None:
                 _dist_parms_pcm = np.array([0, 1, 0, 1], np.float64)
                 _dist_parms = beta_located_bound(_dist_parms_pcm)
+        else:
+            #  _dist_type_pcm == PCMConstants.UNI
+            _dist_parms = (
+                DIST_PARMS_DEFAULT if _dist_parms_pcm is None else _dist_parms_pcm
+            )
 
         _pcm_rng = MultithreadedRNG(
             _pcm_array,
@@ -539,7 +535,7 @@ def _gen_pcm_data(
         del _pcm_rng
 
     if _dist_type_pcm == PCMConstants.BETA_BND:
-        _beta_min, _beta_max = _dist_parms_pcm[2:]  # type: ignore
+        _beta_min, _beta_max = _dist_parms_pcm[2:]
         _pcm_array = (_beta_max - _beta_min) * _pcm_array + _beta_min
         del _beta_min, _beta_max
 
@@ -566,6 +562,66 @@ def _gen_pcm_data(
     return MarginDataSample(_pcm_array, _mnl_test_array)
 
 
+def _gen_divr_array(
+    _recapture_form: RECConstants,
+    _recapture_rate: float | None,
+    _frmshr_array: NDArray[np.float64],
+    _aggregate_purchase_prob: NDArray[np.float64] = EMPTY_ARRAY_DEFAULT,
+    /,
+) -> NDArray[np.float64]:
+    """
+    Given merging-firm shares and related parameters, return diverion ratios.
+
+    If recapture is specified as "Outside-in" (RECConstants.OUTIN), then the
+    choice-probability for the outside good must be supplied.
+
+    Parameters
+    ----------
+    _recapture_form
+        Enum specifying Fixed (proportional), Inside-out, or Outside-in
+
+    _recapture_rate
+        If recapture is proportional or inside-out, the recapture rate
+        for the firm with the smaller share.
+
+    _frmshr_array
+        Merging-firm shares.
+
+    _aggregate_purchase_prob
+        1 minus probability that the outside good is chosen; converts
+        market shares to choice probabilities by multiplication.
+
+    Returns
+    -------
+        Merging-firm diversion ratios for mergers in the sample.
+
+    """
+
+    _divr_array: NDArray[np.float64]
+    if _recapture_form == RECConstants.FIXED:
+        _divr_array = _recapture_rate * _frmshr_array[:, ::-1] / (1 - _frmshr_array)  # type: ignore
+
+    else:
+        _purchprob_array = _aggregate_purchase_prob * _frmshr_array
+        _divr_array = _purchprob_array[:, ::-1] / (1 - _purchprob_array)
+
+    _divr_assert_test = (
+        (np.round(np.einsum("ij->i", _frmshr_array), 15) == 1)
+        | (np.argmin(_frmshr_array, axis=1) == np.argmax(_divr_array, axis=1))
+    )[:, None]
+    if not all(_divr_assert_test):
+        raise ValueError(
+            "{} {} {} {}".format(
+                "Data construction fails tests:",
+                "the index of min(s_1, s_2) must equal",
+                "the index of max(d_12, d_21), for all draws.",
+                "unless frmshr_array sums to 1.00.",
+            )
+        )
+
+    return _divr_array
+
+
 def _beta_located(
     _mu: float | NDArray[np.float64], _sigma: float | NDArray[np.float64], /
 ) -> NDArray[np.float64]: