mergeron 2024.738963.0__py3-none-any.whl → 2025.739265.0__py3-none-any.whl

mergeron/gen/__init__.py

@@ -1,36 +1,50 @@
 """
-Defines constants and containers for industry data generation and testing
+Defines constants, specifications (classes with attributes defining varous parameters) 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 typing import ClassVar, Literal, Protocol, TypeVar, Union
+from typing import ClassVar, NamedTuple, Protocol
 
 import numpy as np
-from attrs import Attribute, define, field, validators
-from numpy.typing import NBitBase, NDArray
+from attrs import Attribute, cmp_using, field, frozen, validators
+from numpy.random import SeedSequence
 
-from ..core.pseudorandom_numbers import DIST_PARMS_DEFAULT  # noqa: TID252
+from .. import (  # noqa: TID252
+    DEFAULT_REC_RATIO,
+    VERSION,
+    ArrayBIGINT,
+    ArrayBoolean,
+    ArrayDouble,
+    ArrayFloat,
+    ArrayINT,
+    RECForm,
+    UPPAggrSelector,
+)
+from ..core.pseudorandom_numbers import DEFAULT_DIST_PARMS  # noqa: TID252
 
-EMPTY_ARRAY_DEFAULT = np.zeros(2)
-FCOUNT_WTS_DEFAULT = ((_nr := np.arange(1, 6)[::-1]) / _nr.sum()).astype(np.float64)
+__version__ = VERSION
 
-TF = TypeVar("TF", bound=NBitBase)
-TI = TypeVar("TI", bound=NBitBase)
+
+DEFAULT_EMPTY_ARRAY = np.zeros(2)
+DEFAULT_FCOUNT_WTS = np.divide(
+    (_nr := np.arange(1, 7)[::-1]), _nr.sum(), dtype=np.float64
+)
+
+
+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
 
 
 @enum.unique
-class PRIConstants(tuple[bool, str | None], enum.ReprEnum):
+class PriceSpec(tuple[bool, str | None], enum.ReprEnum):
     """Price specification.
 
     Whether prices are symmetric and, if not, the direction of correlation, if any.
@@ -44,11 +58,11 @@ class PRIConstants(tuple[bool, str | None], enum.ReprEnum):
 
 
 @enum.unique
-class SHRConstants(enum.StrEnum):
+class SHRDistribution(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)"""
@@ -63,7 +77,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,77 +92,143 @@ class SHRConstants(enum.StrEnum):
     """
 
 
-@define(slots=True, frozen=True)
+@frozen(kw_only=False)
 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.SHRDistribution.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` == :attr:`mergeron.gen.SHRDistribution.UNI`,
+    then it is infeasible that
+    :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.
 
-    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.SHRDistribution`).
 
     """
 
-    recapture_form: RECConstants
-    """see RECConstants"""
+    dist_type: SHRDistribution = field(default=SHRDistribution.DIR_FLAT)
+    """See :class:`SHRDistribution`"""
+
+    @dist_type.validator  # pyright: ignore
+    def __dtv(
+        _i: ShareSpec, _a: Attribute[SHRDistribution], _v: SHRDistribution
+    ) -> None:
+        if _v == SHRDistribution.UNI:
+            if _i.firm_counts_weights is not None:
+                raise ValueError(
+                    "The specified value is incompatible with "
+                    " :code:`distypte`=:attr`:`SHRDistribution.UNI`. "
+                    "Set value to None or Consider revising the "
+                    r"distribution type to :attr:`SHRDistribution.DIR_FLAT`, which gives "
+                    "uniformly distributed draws on the :math:`n+1` simplex "
+                    "for firm-count, :math:`n`. "
+                    ""
+                )
+            elif _i.recapture_form == RECForm.OUTIN:
+                raise ValueError(
+                    "Market share specification requires estimation of recapture ratio from "
+                    "generated data. Either delete recapture ratio specification or set it to None."
+                )
+
+    dist_parms: ArrayFloat | ArrayINT | None = field(
+        default=None, eq=cmp_using(eq=np.array_equal)
+    )
+    """Parameters for tailoring market-share distribution
 
-    recapture_rate: float | None
-    """A value between 0 and 1.
+    For Uniform distribution, bounds of the distribution; defaults to `(0, 1)`;
+    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.
 
-    None if market share specification requires direct generation of
-    outside good choice probabilities (RECConstants.OUTIN).
+    """
+
+    @dist_parms.validator  # pyright: ignore
+    def __dpv(
+        _i: ShareSpec,
+        _a: Attribute[ArrayFloat | ArrayINT | None],
+        _v: ArrayFloat | ArrayINT | None,
+    ) -> None:
+        if (
+            _i.firm_counts_weights is not None
+            and _v is not None
+            and len(_v) < 1 + len(_i.firm_counts_weights)
+        ):
+            raise ValueError(
+                "If specified, the number of distribution parameters must be at least "
+                "the maximum firm-count premerger, which is 1 plus the length of the "
+                "vector specifying firm-count weights."
+            )
 
-    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:
+    firm_counts_weights: ArrayFloat | ArrayINT | None = field(
+        default=DEFAULT_FCOUNT_WTS, eq=cmp_using(eq=np.array_equal)
+    )
+    """Relative or absolute frequencies of firm counts
 
-    * 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
+    Given frequencies are exogenous to generated market data sample;
+    for Dirichlet-type distributions, defaults to DEFAULT_FCOUNT_WTS, which specifies
+    firm-counts of 2 to 6 with weights in descending order from 5 to 1.
 
-    Highlighting indicates hypothetical mergers close to the boundary of the presumption.
     """
 
-    dist_type: SHRConstants
-    """see SHRConstants"""
+    recapture_form: RECForm = field(default=RECForm.INOUT)
+    """See :class:`mergeron.RECForm`"""
 
-    dist_parms: NDArray[np.float64] | None
-    """Parameters for tailoring market-share distribution
+    recapture_ratio: float | None = field(default=DEFAULT_REC_RATIO)
+    """A value between 0 and 1.
 
-    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.
+    :code:`None` if market share specification requires direct generation of
+    outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
 
-    """
-    firm_counts_weights: NDArray[np.float64 | np.int64] | None
-    """relative or absolute frequencies of firm counts
+    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 ratio rounded to
+    the nearest 5% is:
 
+    * 0.85, **7-to-6 merger from symmetry**; US Guidelines, 1982, 1984, 1992, 2023
+    * 0.80, 5-to-4 merger from symmetry
+    * 0.80, **5-to-4 merger to symmetry**; US Guidelines, 2010
 
-    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."""
+    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.)
+
+    """
+
+    @recapture_ratio.validator  # pyright: ignore
+    def __rrv(_i: ShareSpec, _a: Attribute[float], _v: float) -> None:
+        if _v and not (0 < _v <= 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 ratio in the "
+                "interval [0, 1)."
+            )
 
 
 @enum.unique
-class PCMConstants(enum.StrEnum):
+class PCMDistribution(enum.StrEnum):
     """Margin distributions."""
 
     UNI = "Uniform"
     BETA = "Beta"
     BETA_BND = "Bounded Beta"
-    EMPR = "Damodaran margin data"
+    EMPR = "Damodaran margin data, resampled"
 
 
 @enum.unique
-class FM2Constants(enum.StrEnum):
+class FM2Constraint(enum.StrEnum):
     """Firm 2 margins - derivation methods."""
 
     IID = "i.i.d"
@@ -152,7 +236,7 @@ class FM2Constants(enum.StrEnum):
     SYM = "symmetric"
 
 
-@define(slots=True, frozen=True)
+@frozen
 class PCMSpec:
     """Price-cost margin (PCM) specification
 
@@ -168,24 +252,56 @@ class PCMSpec:
 
     """
 
-    firm2_pcm_constraint: FM2Constants
-    """See FM2Constants"""
-
-    dist_type: PCMConstants
-    """See PCMConstants"""
+    dist_type: PCMDistribution = field(kw_only=False, default=PCMDistribution.UNI)
+    """See :class:`PCMDistribution`"""
 
-    dist_parms: NDArray[np.float64] | None
+    dist_parms: ArrayDouble | None = field(kw_only=False, default=None)
     """Parameter specification for tailoring PCM 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 empirical distribution based on Damodaran margin data, optional, ignored
+
     """
 
+    @dist_parms.validator  # pyright: ignore
+    def __dpv(
+        _i: PCMSpec, _a: Attribute[ArrayDouble | None], _v: ArrayDouble | None
+    ) -> None:
+        if _i.dist_type.name.startswith("BETA"):
+            if _v is None:
+                pass
+            elif np.array_equal(_v, DEFAULT_DIST_PARMS):
+                raise ValueError(
+                    f"The distribution parameters, {DEFAULT_DIST_PARMS!r} "
+                    "are not valid with margin distribution, {_dist_type_pcm!r}"
+                )
+            elif (
+                _i.dist_type == PCMDistribution.BETA and len(_v) != len(("a", "b"))
+            ) or (
+                _i.dist_type == PCMDistribution.BETA_BND
+                and len(_v) != len(("mu", "sigma", "max", "min"))
+            ):
+                raise ValueError(
+                    f"Given number, {len(_v)} of parameters "
+                    f'for PCM with distribution, "{_i.dist_type}" is incorrect.'
+                )
+
+        elif _i.dist_type == PCMDistribution.EMPR and _v is not None:
+            raise ValueError(
+                f"Empirical distribution does not require additional parameters; "
+                f'"given value, {_v!r} is ignored."'
+            )
+
+    firm2_pcm_constraint: FM2Constraint = field(
+        kw_only=False, default=FM2Constraint.IID
+    )
+    """See :class:`FM2Constraint`"""
+
 
 @enum.unique
-class SSZConstants(float, enum.ReprEnum):
+class SSZConstant(float, enum.ReprEnum):
     """
     Scale factors to offset sample size reduction.
 
@@ -224,193 +340,46 @@ class SSZConstants(float, enum.ReprEnum):
     """When initial set of draws is not restricted in any way."""
 
 
-# Validators for selected attributes of MarketSampleSpec
-def _sample_size_validator(
-    _object: MarketSampleSpec, _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: MarketSampleSpec, _attribute: Attribute[ShareSpec], _value: ShareSpec, /
-) -> None:
-    _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).")
-
-    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."
-        )
-
-    if _value.dist_type == SHRConstants.UNI:
-        if _value.recapture_form == RECConstants.OUTIN:
-            raise ValueError(
-                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."
-            )
-        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 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`."
-            )
-    elif _value.recapture_form != RECConstants.OUTIN and (
-        _r_bar is None or not isinstance(_r_bar, float)
-    ):
-        raise ValueError(
-            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, /
-) -> None:
-    if (
-        _instance.share_spec.recapture_form == RECConstants.FIXED
-        and _value.firm2_pcm_constraint == FM2Constants.MNL
-    ):
-        raise ValueError(
-            "{} {} {}".format(
-                f'Specification of "recapture_form", "{_instance.share_spec.recapture_form}"',
-                "requires Firm 2 margin must have property, ",
-                f'"{FM2Constants.IID}" or "{FM2Constants.SYM}".',
-            )
-        )
-    elif _value.dist_type.name.startswith("BETA"):
-        if _value.dist_parms is None:
-            pass
-        elif np.array_equal(_value.dist_parms, DIST_PARMS_DEFAULT):
-            raise ValueError(
-                f"The distribution parameters, {DIST_PARMS_DEFAULT!r} "
-                "are not valid with margin distribution, {_dist_type_pcm!r}"
-            )
-        elif (
-            _value.dist_type == PCMConstants.BETA
-            and len(_value.dist_parms) != len(("max", "min"))
-        ) or (
-            _value.dist_type == PCMConstants.BETA_BND
-            and len(_value.dist_parms) != len(("mu", "sigma", "max", "min"))
-        ):
-            raise ValueError(
-                f"Given number, {len(_value.dist_parms)} of parameters "
-                f'for PCM with distribution, "{_value.dist_type}" is incorrect.'
-            )
-
-
-@define(slots=True, frozen=True)
-class MarketSampleSpec:
-    """Parameter specification for market data generation."""
-
-    sample_size: int = field(
-        default=10**6, validator=(validators.instance_of(int), _sample_size_validator)
-    )
-    """sample size generated"""
-
-    share_spec: ShareSpec = field(
-        kw_only=True,
-        default=ShareSpec(RECConstants.INOUT, 0.855, SHRConstants.UNI, None, None),
-        validator=[validators.instance_of(ShareSpec), _share_spec_validator],
-    )
-    """Market-share specification, see definition of 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"""
-
-    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(
-        kw_only=True,
-        default=SSZConstants.ONE,
-        validator=validators.instance_of(SSZConstants),
-    )
-    """Method for modeling HSR filing threholds, see SSZConstants"""
-
-
-@enum.unique
-class INVResolution(enum.StrEnum):
-    CLRN = "clearance"
-    ENFT = "enforcement"
-    BOTH = "both"
-
-
-@define(slots=True, frozen=True)
-class UPPTestRegime:
-    resolution: INVResolution = field(
-        default=INVResolution.ENFT, validator=validators.instance_of(INVResolution)
-    )
-    guppi_aggregator: UPPAggrSelector = field(
-        default=UPPAggrSelector.MAX, validator=validators.instance_of(UPPAggrSelector)
-    )
-    divr_aggregator: UPPAggrSelector | None = field(
-        default=guppi_aggregator,
-        validator=validators.instance_of((UPPAggrSelector, type(None))),
-    )
-
-
-# https://stackoverflow.com/questions/54668000
-class DataclassInstance(Protocol):
-    """Generic dataclass-instance"""
-
-    __dataclass_fields__: ClassVar
+# Validators for selected attributes of MarketSpec
 
 
 @dataclass(slots=True, frozen=True)
 class MarketDataSample:
     """Container for generated markets data sample."""
 
-    frmshr_array: NDArray[np.float64]
+    frmshr_array: ArrayDouble
     """Merging-firm shares (with two merging firms)"""
 
-    pcm_array: NDArray[np.float64]
+    pcm_array: ArrayDouble
     """Merging-firms' prices (normalized to 1, in default specification)"""
 
-    price_array: NDArray[np.float64]
+    price_array: ArrayDouble
     """Merging-firms' price-cost margins (PCM)"""
 
-    fcounts: NDArray[np.int64]
+    fcounts: ArrayBIGINT
     """Number of firms in market"""
 
-    aggregate_purchase_prob: NDArray[np.float64]
+    aggregate_purchase_prob: ArrayDouble
     """
     One (1) minus probability that the outside good is chosen
 
     Converts market shares to choice probabilities by multiplication.
     """
 
-    nth_firm_share: NDArray[np.float64]
+    nth_firm_share: ArrayDouble
     """Market-share of n-th firm
 
     Relevant for testing for draws the do or
     do not meet HSR filing thresholds.
     """
 
-    divr_array: NDArray[np.float64]
+    divr_array: ArrayDouble
     """Diversion ratio between the merging firms"""
 
-    hhi_post: NDArray[np.float64]
+    hhi_post: ArrayDouble
     """Post-merger change in Herfindahl-Hirschmann Index (HHI)"""
 
-    hhi_delta: NDArray[np.float64]
+    hhi_delta: ArrayDouble
     """Change in HHI from combination of merging firms"""
 
 
@@ -422,16 +391,16 @@ class ShareDataSample:
     and aggregate purchase probability.
     """
 
-    mktshr_array: NDArray[np.float64]
+    mktshr_array: ArrayDouble
     """All-firm shares (with two merging firms)"""
 
-    fcounts: NDArray[np.int64]
+    fcounts: ArrayBIGINT
     """All-firm-count for each draw"""
 
-    nth_firm_share: NDArray[np.float64]
+    nth_firm_share: ArrayDouble
     """Market-share of n-th firm"""
 
-    aggregate_purchase_prob: NDArray[np.float64]
+    aggregate_purchase_prob: ArrayDouble
     """Converts market shares to choice probabilities by multiplication."""
 
 
@@ -439,10 +408,10 @@ class ShareDataSample:
 class PriceDataSample:
     """Container for generated price array, and related."""
 
-    price_array: NDArray[np.float64]
+    price_array: ArrayDouble
     """Merging-firms' prices"""
 
-    hsr_filing_test: NDArray[np.bool_]
+    hsr_filing_test: ArrayBoolean
     """Flags draws as meeting HSR filing thresholds or not"""
 
 
@@ -450,10 +419,10 @@ class PriceDataSample:
 class MarginDataSample:
     """Container for generated margin array and related MNL test array."""
 
-    pcm_array: NDArray[np.float64]
+    pcm_array: ArrayDouble
     """Merging-firms' PCMs"""
 
-    mnl_test_array: NDArray[np.bool_]
+    mnl_test_array: ArrayBoolean
     """Flags infeasible observations as False and rest as True
 
     Applying restrictions from Bertrand-Nash oligopoly
@@ -467,40 +436,83 @@ class MarginDataSample:
     """
 
 
+@enum.unique
+class INVResolution(enum.StrEnum):
+    CLRN = "clearance"
+    ENFT = "enforcement"
+    BOTH = "both"
+
+
+@frozen
+class UPPTestRegime:
+    """Configuration for UPP tests."""
+
+    resolution: INVResolution = field(
+        kw_only=False,
+        default=INVResolution.ENFT,
+        validator=validators.in_([INVResolution.CLRN, INVResolution.ENFT]),
+    )
+    """Whether to test clearance, enforcement, or both."""
+
+    guppi_aggregator: UPPAggrSelector = field(
+        kw_only=False, default=UPPAggrSelector.MIN
+    )
+    """Aggregator for GUPPI test."""
+
+    divr_aggregator: UPPAggrSelector = field(kw_only=False, default=UPPAggrSelector.MIN)
+    """Aggregator for diversion ratio test."""
+
+
 @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
-    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_]
+    guppi_test_simple: ArrayBoolean
     """True if GUPPI estimate meets criterion"""
 
-    guppi_test_compound: NDArray[np.bool_]
+    guppi_test_compound: ArrayBoolean
     """True if both GUPPI estimate and diversion ratio estimate
     meet criterion
     """
 
-    cmcr_test: NDArray[np.bool_]
+    cmcr_test: ArrayBoolean
     """True if CMCR estimate meets criterion"""
 
-    ipr_test: NDArray[np.bool_]
+    ipr_test: ArrayBoolean
     """True if IPR (partial price-simulation) estimate meets criterion"""
 
 
 @dataclass(slots=True, frozen=True)
 class UPPTestsCounts:
-    """counts of markets resolved as specified
+    """Counts of markets resolved as specified
+
+    Resolution may be either :attr:`INVResolution.ENFT`,
+    :attr:`INVResolution.CLRN`, or :attr:`INVResolution.BOTH`.
+    In the case of :attr:`INVResolution.BOTH`, two colums of counts
+    are returned: one for each resolution.
 
-    Resolution is specified in a UPPTestRegime object.
     """
 
-    by_firm_count: NDArray[np.int64]
-    by_delta: NDArray[np.int64]
-    by_conczone: NDArray[np.int64]
-    """Zones are "unoncentrated", "moderately concentrated", and "highly concentrated"
+    by_firm_count: ArrayBIGINT
+    by_delta: ArrayBIGINT
+    by_conczone: ArrayBIGINT
+    """Zones are "unoncentrated", "moderately concentrated", and "highly concentrated",
+    with futher detail by HHI and ΔHHI for mergers in the "unconcentrated" and
+    "moderately concentrated" zones. See
+    :attr:`mergeron.gen.enforcement_stats.HMG_PRESUMPTION_ZONE_MAP` and
+    :attr:`mergeron.gen.enforcement_stats.ZONE_VALS` for more detail.
+
     """
+
+
+# https://stackoverflow.com/questions/54668000
+class DataclassInstance(Protocol):
+    """Generic dataclass-instance"""
+
+    __dataclass_fields__: ClassVar