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

mergeron/gen/__init__.py

@@ -7,28 +7,26 @@ from __future__ import annotations
 
 import enum
 from dataclasses import dataclass
-from importlib.metadata import version
-from typing import ClassVar, Protocol, TypeVar
+from typing import ClassVar, Protocol
 
 import numpy as np
-from attrs import Attribute, define, field, frozen, validators
-from numpy.typing import NBitBase, NDArray
+from attrs import Attribute, cmp_using, define, field, frozen, validators
+from numpy.typing import NDArray
 
-from .. import _PKG_NAME, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
 from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
 EMPTY_ARRAY_DEFAULT = np.zeros(2)
-FCOUNT_WTS_DEFAULT = ((_nr := np.arange(1, 6)[::-1]) / _nr.sum()).astype(np.float64)
-
-TF = TypeVar("TF", bound=NBitBase)
-TI = TypeVar("TI", bound=NBitBase)
+FCOUNT_WTS_DEFAULT = np.divide(
+    (_nr := np.arange(1, 6)[::-1]), _nr.sum(), dtype=np.float64
+)
 
 
 @enum.unique
-class PRIConstants(tuple[bool, str | None], enum.ReprEnum):
+class PriceConstants(tuple[bool, str | None], enum.ReprEnum):
     """Price specification.
 
     Whether prices are symmetric and, if not, the direction of correlation, if any.
@@ -38,7 +36,7 @@ class PRIConstants(tuple[bool, str | None], enum.ReprEnum):
     ZERO = (False, None)
     NEG = (False, "negative share-correlation")
     POS = (False, "positive share-correlation")
-    CSY = (False, "market-wide cost-symmetry")
+    # TODO: CSY = (False, "market-wide cost-symmetry")
 
 
 @enum.unique
@@ -46,7 +44,7 @@ class SHRConstants(enum.StrEnum):
     """Market share distributions."""
 
     UNI = "Uniform"
-    """Uniform distribution over the 3-simplex"""
+    R"""Uniform distribution over :math:`s_1 + s_2 \leqslant 1`"""
 
     DIR_FLAT = "Flat Dirichlet"
     """Shape parameter for all merging-firm-shares is unity (1)"""
@@ -87,48 +85,56 @@ class ShareSpec:
     """
 
     recapture_form: RECConstants
-    """see RECConstants"""
+    """See :class:`mergeron.RECConstants`"""
 
     recapture_rate: float | None
-    """A value between 0 and 1.
+    """A value between 0 and 1, typically 0.8.
 
-    None if market share specification requires direct generation of
-    outside good choice probabilities (RECConstants.OUTIN).
+    :code:`None` if market share specification requires direct generation of
+    outside good choice probabilities (:attr:`mergeron.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:
+    HHI threshold for the presumtion of harm from unilateral competitive effects
+    in published merger guidelines. Accordingly, the recapture rate rounded to
+    the nearest 5% is:
+
+    * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1992, 2023
+    * 0.80, **6-to-5 merger to symmetry**; EU Guidelines for horizontal mergers, 2004
+    * 0.80, 5-to-4 merger from symmetry
+    * 0.80, **5-to-4 merger to symmetry**; US Guidelines, 2010
 
-    * 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 in the neighborhood of (the boundary of)
+    the Guidelines presumption of harm. (In the EU Guidelines, concentration measures serve as
+    screens for further investigation, rather than as the basis for presumptions of harm or
+    presumptions no harm.)
 
-    Highlighting indicates hypothetical mergers close to the boundary of the presumption.
     """
 
     dist_type: SHRConstants
-    """see SHRConstants"""
+    """See :class:`mergeron.gen.SHRConstants`"""
 
-    dist_parms: NDArray[np.float64] | None
+    dist_parms: NDArray[np.float64] | None = field(
+        default=None, eq=cmp_using(eq=np.array_equal)
+    )
     """Parameters for tailoring market-share distribution
 
     For Uniform distribution, bounds of the distribution; defaults to `(0, 1)`;
-    for Beta distribution, shape parameters, defaults to `(1, 1)`;
-    for Bounded-Beta distribution, vector of (min, max, mean, std. deviation), non-optional;
     for Dirichlet-type distributions, a vector of shape parameters of length
     no less than the length of firm-count weights below; defaults depend on
     type of Dirichlet-distribution specified.
 
     """
-    firm_counts_weights: NDArray[np.float64 | np.int64] | None
-    """relative or absolute frequencies of firm counts
+    firm_counts_weights: NDArray[np.float64 | np.int64] | None = field(
+        default=None, eq=cmp_using(eq=np.array_equal)
+    )
+    """Relative or absolute frequencies of firm counts
 
 
     Given frequencies are exogenous to generated market data sample;
-    defaults to FCOUNT_WTS_DEFAULT, which specifies firm-counts of 2 to 6
-    with weights in descending order from 5 to 1."""
+    for Dirichlet-type distributions, defaults to FCOUNT_WTS_DEFAULT, which specifies
+    firm-counts of 2 to 6 with weights in descending order from 5 to 1.
+
+    """
 
 
 @enum.unique
@@ -167,10 +173,10 @@ class PCMSpec:
     """
 
     firm2_pcm_constraint: FM2Constants
-    """See FM2Constants"""
+    """See :class:`mergeron.gen.FM2Constants`"""
 
     dist_type: PCMConstants
-    """See PCMConstants"""
+    """See :class:`mergeron.gen.PCMConstants`"""
 
     dist_parms: NDArray[np.float64] | None
     """Parameter specification for tailoring PCM distribution
@@ -179,6 +185,7 @@ class PCMSpec:
     for Beta distribution, shape parameters, defaults to `(1, 1)`;
     for Bounded-Beta distribution, vector of (min, max, mean, std. deviation), non-optional;
     for empirical distribution based on Damodaran margin data, optional, ignored
+
     """
 
 
@@ -223,15 +230,6 @@ class SSZConstants(float, enum.ReprEnum):
 
 
 # Validators for selected attributes of MarketSpec
-def _sample_size_validator(
-    _object: MarketSpec, _attribute: Attribute[int], _value: int, /
-) -> None:
-    if _value < 10**6:
-        raise ValueError(
-            f"Sample size must be no less than {10**6:,d}; got, {_value:,d}."
-        )
-
-
 def _share_spec_validator(
     _instance: MarketSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
 ) -> None:
@@ -312,31 +310,31 @@ class MarketSpec:
 
     share_spec: ShareSpec = field(
         kw_only=True,
-        default=ShareSpec(RECConstants.INOUT, 0.855, SHRConstants.UNI, None, None),
+        default=ShareSpec(RECConstants.INOUT, 0.85, SHRConstants.UNI, None, None),
         validator=[validators.instance_of(ShareSpec), _share_spec_validator],
     )
-    """Market-share specification, see definition of ShareSpec"""
+    """Market-share specification, see :class:`mergeron.gen.ShareSpec`"""
 
     pcm_spec: PCMSpec = field(
         kw_only=True,
         default=PCMSpec(FM2Constants.IID, PCMConstants.UNI, None),
         validator=[validators.instance_of(PCMSpec), _pcm_spec_validator],
     )
-    """Margin specification, see definition of PCMSpec"""
+    """Margin specification, see :class:`mergeron.gen.PCMSpec`"""
 
-    price_spec: PRIConstants = field(
+    price_spec: PriceConstants = field(
         kw_only=True,
-        default=PRIConstants.SYM,
-        validator=validators.instance_of(PRIConstants),
+        default=PriceConstants.SYM,
+        validator=validators.instance_of(PriceConstants),
     )
-    """Price specification, see PRIConstants"""
+    """Price specification, see :class:`mergeron.gen.PriceConstants`"""
 
     hsr_filing_test_type: SSZConstants = field(
         kw_only=True,
         default=SSZConstants.ONE,
         validator=validators.instance_of(SSZConstants),
     )
-    """Method for modeling HSR filing threholds, see SSZConstants"""
+    """Method for modeling HSR filing threholds, see :class:`mergeron.gen.SSZConstants`"""
 
 
 @enum.unique
@@ -465,8 +463,8 @@ class UPPTestsRaw:
 
     A test success is a draw ("market") that meeets the
     specified test criterion, and a test failure is
-    one that does not; test criteria are defined and
-    evaluated in:code:`guidelines_stats.gen_upp_arrays`.
+    one that does not; test criteria are evaluated in
+    :func:`enforcement_stats.gen_upp_arrays`.
     """
 
     guppi_test_simple: NDArray[np.bool_]
@@ -488,7 +486,7 @@ class UPPTestsRaw:
 class UPPTestsCounts:
     """Counts of markets resolved as specified
 
-    Resolution may be either "enforcement" or "clearance".
+    Resolution may be either :attr:`INVResolution.ENFT` or :attr:`INVResolution.CLRN`.
     """
 
     by_firm_count: NDArray[np.int64]

mergeron/gen/_data_generation_functions.py

@@ -4,36 +4,33 @@ Non-public functions called in data_generation.py
 
 from __future__ import annotations
 
-from importlib.metadata import version
 from typing import Literal
 
 import numpy as np
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
 
-from .. import _PKG_NAME, RECConstants  # noqa: TID252
-from ..core.damodaran_margin_data import resample_mgn_data  # noqa: TID252
+from .. import VERSION, RECConstants  # noqa: TID252
+from ..core.damodaran_margin_data import mgn_data_resampler  # noqa: TID252
 from ..core.pseudorandom_numbers import (  # noqa: TID252
     DIST_PARMS_DEFAULT,
     MultithreadedRNG,
     prng,
 )
 from . import (
-    EMPTY_ARRAY_DEFAULT,
     FCOUNT_WTS_DEFAULT,
-    TF,
     FM2Constants,
     MarginDataSample,
     MarketSpec,
     PCMConstants,
+    PriceConstants,
     PriceDataSample,
-    PRIConstants,
     ShareDataSample,
     SHRConstants,
     SSZConstants,
 )
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
 def _gen_share_data(
@@ -100,7 +97,7 @@ def _gen_share_data(
 
     # 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.855
+    _r_bar = _mkt_sample_spec.share_spec.recapture_rate or 0.85
     if _recapture_form == RECConstants.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
@@ -114,7 +111,7 @@ def _gen_share_data(
 
 def _gen_market_shares_uniform(
     _s_size: int = 10**6,
-    _dist_parms_mktshr: NDArray[np.floating[TF]] | None = DIST_PARMS_DEFAULT,  # type: ignore
+    _dist_parms_mktshr: NDArray[np.float64] | None = DIST_PARMS_DEFAULT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
     /,
@@ -139,8 +136,8 @@ def _gen_market_shares_uniform(
     """
 
     _frmshr_array = np.empty((_s_size, 2), dtype=np.float64)
-    _dist_parms_mktshr: NDArray[np.floating[TF]] = (
-        DIST_PARMS_DEFAULT if _dist_parms_mktshr is None else _dist_parms_mktshr  # type: ignore
+    _dist_parms_mktshr: NDArray[np.float64] = (
+        DIST_PARMS_DEFAULT if _dist_parms_mktshr is None else _dist_parms_mktshr
     )
     _mrng = MultithreadedRNG(
         _frmshr_array,
@@ -150,7 +147,7 @@ def _gen_market_shares_uniform(
         nthreads=_nthreads,
     )
     _mrng.fill()
-    # Convert draws on U[0, 1] to Uniformly-distributed draws on simplex, s_1 + s_2 < 1
+    # Convert draws on U[0, 1] to Uniformly-distributed draws on simplex, s_1 + s_2 <= 1
     _frmshr_array = np.sort(_frmshr_array, axis=1)
     _frmshr_array = np.column_stack((
         _frmshr_array[:, 0],
@@ -179,8 +176,8 @@ def _gen_market_shares_dirichlet_multisample(
     _s_size: int = 10**6,
     _recapture_form: RECConstants = RECConstants.INOUT,
     _dist_type_dir: SHRConstants = SHRConstants.DIR_FLAT,
-    _dist_parms_dir: NDArray[np.floating[TF]] | None = None,
-    _firm_count_wts: NDArray[np.floating[TF]] | None = None,
+    _dist_parms_dir: NDArray[np.float64] | None = None,
+    _firm_count_wts: NDArray[np.float64] | None = None,
     _fcount_rng_seed_seq: SeedSequence | None = None,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
     _nthreads: int = 16,
@@ -218,7 +215,7 @@ def _gen_market_shares_dirichlet_multisample(
 
     """
 
-    _firm_count_wts: NDArray[np.floating[TF]] = (
+    _firm_count_wts: NDArray[np.float64] = (
         FCOUNT_WTS_DEFAULT if _firm_count_wts is None else _firm_count_wts
     )
 
@@ -314,7 +311,7 @@ def _gen_market_shares_dirichlet_multisample(
 
 
 def _gen_market_shares_dirichlet(
-    _dir_alphas: NDArray[np.floating[TF]],
+    _dir_alphas: NDArray[np.float64],
     _s_size: int = 10**6,
     _recapture_form: RECConstants = RECConstants.INOUT,
     _mktshr_rng_seed_seq: SeedSequence | None = None,
@@ -412,18 +409,18 @@ def _gen_price_data(
 
     _pr_max_ratio = 5.0
     match _mkt_sample_spec.price_spec:
-        case PRIConstants.SYM:
+        case PriceConstants.SYM:
             _nth_firm_price = np.ones((len(_frmshr_array), 1))
-        case PRIConstants.POS:
+        case PriceConstants.POS:
             _price_array, _nth_firm_price = (
                 np.ceil(_p * _pr_max_ratio) for _p in (_frmshr_array, _nth_firm_share)
             )
-        case PRIConstants.NEG:
+        case PriceConstants.NEG:
             _price_array, _nth_firm_price = (
                 np.ceil((1 - _p) * _pr_max_ratio)
                 for _p in (_frmshr_array, _nth_firm_share)
             )
-        case PRIConstants.ZERO:
+        case PriceConstants.ZERO:
             _price_array_gen = prng(_seed_seq).choice(
                 1 + np.arange(_pr_max_ratio), size=(len(_frmshr_array), 3)
             )
@@ -458,10 +455,10 @@ def _gen_price_data(
             _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
-            # matches the smaller firm in the size test; then if the smaller merging firm
-            # matches 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.
+            # 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)
@@ -483,33 +480,31 @@ def _gen_price_data(
 
 
 def _gen_pcm_data(
-    _frmshr_array: NDArray[np.floating[TF]],
+    _frmshr_array: NDArray[np.float64],
+    _price_array: NDArray[np.float64],
+    _aggregate_purchase_prob: NDArray[np.float64],
     _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_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")
     )
-    _dist_type: Literal["Beta", "Uniform"] = (
-        "Uniform" if _dist_type_pcm == PCMConstants.UNI else "Beta"
-    )
 
+    _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)
 
     _beta_min, _beta_max = [None] * 2  # placeholder
     if _dist_type_pcm == PCMConstants.EMPR:
-        _pcm_array = resample_mgn_data(
+        _pcm_array = mgn_data_resampler(
             _pcm_array.shape,  # type: ignore
             seed_sequence=_pcm_rng_seed_seq,
         )
     else:
+        _dist_type = "Uniform" if _dist_type_pcm == PCMConstants.UNI else "Beta"
         if _dist_type_pcm == PCMConstants.BETA:
             if _dist_parms_pcm is None:
                 _dist_parms_pcm = np.ones(2, np.float64)
@@ -562,66 +557,6 @@ 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]:
@@ -647,7 +582,7 @@ def _beta_located(
     return np.array([_mu * _mul, (1 - _mu) * _mul], dtype=np.float64)
 
 
-def beta_located_bound(_dist_parms: NDArray[np.floating[TF]], /) -> NDArray[np.float64]:
+def beta_located_bound(_dist_parms: NDArray[np.float64], /) -> NDArray[np.float64]:
     R"""
     Return shape parameters for a non-standard beta, given the mean, stddev, range
 

mergeron/gen/data_generation.py

@@ -5,31 +5,32 @@ Methods to generate data for analyzing merger enforcement policy.
 
 from __future__ import annotations
 
-from importlib.metadata import version
+from typing import NamedTuple
 
 import numpy as np
 from numpy.random import SeedSequence
 from numpy.typing import NDArray
 
-from .. import _PKG_NAME, RECConstants  # noqa: TID252
+from .. import VERSION, RECConstants  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
     FM2Constants,
     MarketDataSample,
     MarketSpec,
-    PRIConstants,
+    PriceConstants,
     SHRConstants,
     SSZConstants,
 )
-from ._data_generation_functions import (
-    _gen_market_shares_dirichlet,  # noqa: F401 easter-egg for external modules
-    _gen_market_shares_uniform,  # noqa: F401 easter-egg for external modules
-    _gen_pcm_data,
-    _gen_price_data,
-    _gen_share_data,
-)
+from ._data_generation_functions import _gen_pcm_data, _gen_price_data, _gen_share_data
+
+__version__ = VERSION
+
 
-__version__ = version(_PKG_NAME)
+class SeedSequenceData(NamedTuple):
+    mktshr_rng_seed_seq: SeedSequence
+    pcm_rng_seed_seq: SeedSequence
+    fcount_rng_seed_seq: SeedSequence | None
+    pr_rng_seed_seq: SeedSequence | None
 
 
 def gen_market_sample(
@@ -53,7 +54,7 @@ def gen_market_sample(
     2.) price-cost margins
     3.) firm-counts, from :code:`[2, 2 + len(firm_counts_weights)]`,
     weighted by :code:`firm_counts_weights`, where relevant
-    4.) prices, if :code:`price_spec == PRIConstants.ZERO`.
+    4.) prices, if :code:`price_spec == PriceConstants.ZERO`.
 
     Parameters
     ----------
@@ -74,8 +75,6 @@ def gen_market_sample(
 
     """
 
-    _mkt_sample_spec = _mkt_sample_spec or MarketSpec()
-
     _recapture_form = _mkt_sample_spec.share_spec.recapture_form
     _recapture_rate = _mkt_sample_spec.share_spec.recapture_rate
     _dist_type_mktshr = _mkt_sample_spec.share_spec.dist_type
@@ -141,9 +140,9 @@ def gen_market_sample(
     # Generate margin data
     _pcm_data = _gen_pcm_data(
         _mktshr_array[:, :2],
-        _mkt_sample_spec,
         _price_array,
         _aggregate_purchase_prob,
+        _mkt_sample_spec,
         _pcm_rng_seed_seq,
         nthreads,
     )
@@ -186,14 +185,14 @@ def gen_market_sample(
 def parse_seed_seq_list(
     _sseq_list: list[SeedSequence] | None,
     _mktshr_dist_type: SHRConstants,
-    _price_spec: PRIConstants,
+    _price_spec: PriceConstants,
     /,
-) -> tuple[SeedSequence, SeedSequence, SeedSequence | None, SeedSequence | None]:
+) -> SeedSequenceData:
     """Initialize RNG seed sequences to ensure independence of distinct random streams."""
     _fcount_rng_seed_seq: SeedSequence | None = None
     _pr_rng_seed_seq: SeedSequence | None = None
 
-    if _price_spec == PRIConstants.ZERO:
+    if _price_spec == PriceConstants.ZERO:
         _pr_rng_seed_seq = _sseq_list.pop() if _sseq_list else SeedSequence(pool_size=8)
 
     if _mktshr_dist_type == SHRConstants.UNI:
@@ -212,11 +211,8 @@ def parse_seed_seq_list(
             else (SeedSequence(pool_size=8) for _ in range(_seed_count))
         )
 
-    return (
-        _mktshr_rng_seed_seq,
-        _pcm_rng_seed_seq,
-        _fcount_rng_seed_seq,
-        _pr_rng_seed_seq,
+    return SeedSequenceData(
+        _mktshr_rng_seed_seq, _pcm_rng_seed_seq, _fcount_rng_seed_seq, _pr_rng_seed_seq
     )
 
 
@@ -230,7 +226,7 @@ def gen_divr_array(
     """
     Given merging-firm shares and related parameters, return diverion ratios.
 
-    If recapture is specified as "Outside-in" (RECConstants.OUTIN), then the
+    If recapture is specified as :attr:`mergeron.RECConstants.OUTIN`, then the
     choice-probability for the outside good must be supplied.
 
     Parameters