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

mergeron/gen/__init__.py

@@ -7,12 +7,15 @@ containers for industry data generation and testing.
 from __future__ import annotations
 
 import enum
+from collections.abc import Sequence
 from dataclasses import dataclass
-from typing import ClassVar, NamedTuple, Protocol
+from typing import ClassVar, Protocol
 
 import numpy as np
-from attrs import Attribute, cmp_using, field, frozen, validators
+from attrs import Attribute, Converter, cmp_using, field, validators
+from attrs import frozen as frozen_attrs
 from numpy.random import SeedSequence
+from ruamel import yaml
 
 from .. import (  # noqa: TID252
     DEFAULT_REC_RATIO,
@@ -24,25 +27,28 @@ from .. import (  # noqa: TID252
     ArrayINT,
     RECForm,
     UPPAggrSelector,
+    this_yaml,
+)
+from ..core.pseudorandom_numbers import (  # noqa: TID252
+    DEFAULT_BETA_DIST_PARMS,
+    DEFAULT_DIST_PARMS,
 )
-from ..core.pseudorandom_numbers import DEFAULT_DIST_PARMS  # noqa: TID252
 
 __version__ = VERSION
 
 
-DEFAULT_EMPTY_ARRAY = np.zeros(2)
-DEFAULT_FCOUNT_WTS = np.divide(
-    (_nr := np.arange(1, 7)[::-1]), _nr.sum(), dtype=np.float64
-)
+DEFAULT_FCOUNT_WTS = np.asarray((_nr := np.arange(6, 0, -1)) / _nr.sum(), float)
 
 
-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
+@dataclass
+class SeedSequenceData:
+    share: SeedSequence
+    pcm: SeedSequence
+    fcounts: SeedSequence | None
+    price: SeedSequence | None
 
 
+@this_yaml.register_class
 @enum.unique
 class PriceSpec(tuple[bool, str | None], enum.ReprEnum):
     """Price specification.
@@ -57,6 +63,7 @@ class PriceSpec(tuple[bool, str | None], enum.ReprEnum):
     CSY = (False, "market-wide cost-symmetry")
 
 
+@this_yaml.register_class
 @enum.unique
 class SHRDistribution(enum.StrEnum):
     """Market share distributions."""
@@ -70,7 +77,7 @@ class SHRDistribution(enum.StrEnum):
     DIR_FLAT_CONSTR = "Flat Dirichlet - Constrained"
     """Impose minimum probablility weight on each firm-count
 
-    Only firm-counts with probability weight of no less than 3%
+    Only firm-counts with probability weight of 3% or more
     are included for data generation.
     """
 
@@ -92,11 +99,59 @@ class SHRDistribution(enum.StrEnum):
     """
 
 
-@frozen(kw_only=False)
+def _fc_wts_conv(
+    _v: Sequence[float | int] | ArrayDouble | ArrayINT | None, _i: ShareSpec
+) -> ArrayFloat | None:
+    if _i.dist_type == SHRDistribution.UNI:
+        return None
+    elif _v is None or np.array_equal(_v, DEFAULT_FCOUNT_WTS):
+        return DEFAULT_FCOUNT_WTS
+    else:
+        return _tv if (_tv := np.asarray(_v, float)).sum() == 1 else _tv / _tv.sum()
+
+
+def _shr_dp_conv(_v: Sequence[float] | ArrayFloat | None, _i: ShareSpec) -> ArrayFloat:
+    match _v:
+        case None if _i.dist_type == SHRDistribution.UNI:
+            return DEFAULT_DIST_PARMS
+        case None:
+            _fc_max = 1 + (
+                len(DEFAULT_FCOUNT_WTS)
+                if not hasattr(_i, "firm_counts_weights")
+                or _i.firm_counts_weights is None
+                or len(_i.firm_counts_weights) == 0
+                else len(_i.firm_counts_weights)
+            )
+
+            match _i.dist_type:
+                case SHRDistribution.DIR_FLAT | SHRDistribution.DIR_FLAT_CONSTR:
+                    return np.ones(_fc_max, float)
+                case SHRDistribution.DIR_ASYM:
+                    return np.array([2.0] * 6 + [1.5] * 5 + [1.25] * _fc_max, float)
+                case SHRDistribution.DIR_COND:
+                    return np.array([], float)
+                case _ if isinstance(_i.dist_type, SHRDistribution):
+                    raise ValueError(
+                        f"No default defined for market share distribution, {_i.dist_type!r}"
+                    )
+                case _:
+                    raise ValueError(
+                        f"Unsupported distribution for market share generation, {_i.dist_type!r}"
+                    )
+        case _ if isinstance(_v, Sequence | np.ndarray):
+            return np.asarray(_v, float)
+        case _:
+            raise ValueError(
+                f"Input, {_v!r} has invalid type. Must be None, Sequence of floats, or Numpy ndarray."
+            )
+
+
+@this_yaml.register_class
+@frozen_attrs
 class ShareSpec:
     """Market share specification
 
-    A key feature of market-share specification in this package is that
+    A salientfeature 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,
@@ -105,85 +160,92 @@ class ShareSpec:
 
     Notes
     -----
-    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.
-
-    For a sample with explicit firm counts, market shares must be specified as
-    having a supported Dirichlet distribution (see :class:`mergeron.gen.SHRDistribution`).
+    If :attr:`.dist_type` == :attr:`.SHRDistribution.UNI`, it is then infeasible that
+    :attr:`.recapture_form` == :attr:`mergeron.RECForm.OUTIN`.
+    In other words, recapture ratios cannot be estimated using
+    outside-good choice probabilities if the distribution of markets over firm-counts
+    is unspecified.
 
     """
 
-    dist_type: SHRDistribution = field(default=SHRDistribution.DIR_FLAT)
+    dist_type: SHRDistribution = field(kw_only=False)
     """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."
-                )
+    firm_counts_weights: ArrayFloat | None = field(
+        kw_only=True,
+        eq=cmp_using(eq=np.array_equal),
+        converter=Converter(_fc_wts_conv, takes_self=True),  # type: ignore
+    )
+    """Relative or absolute frequencies of pre-merger firm counts
+
+    Defaults to :attr:`DEFAULT_FCOUNT_WTS`, which specifies pre-merger
+    firm-counts of 2 to 7 with weights in descending order from 6 to 1.
+
+    ALERT: Firm-count weights are irrelevant when the mergering firmss shares are specified
+    to have uniform distribution; therefore this attribute is forced to None if
+    :attr:`.dist_type` == :attr:`.SHRDistribution.UNI`.
+
+    """
+
+    @firm_counts_weights.default
+    def _fcwd(_i: ShareSpec) -> ArrayFloat | None:
+        return _fc_wts_conv(None, _i)
+
+    @firm_counts_weights.validator
+    def _fcv(_i: ShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
+        if _i.dist_type != SHRDistribution.UNI and not len(_v):
+            raise ValueError(
+                f"Attribute, {'"firm_counts_weights"'} must be populated if the share distribution is "
+                "other than uniform distribution."
+            )
 
-    dist_parms: ArrayFloat | ArrayINT | None = field(
-        default=None, eq=cmp_using(eq=np.array_equal)
+    dist_parms: ArrayFloat = field(
+        kw_only=True,
+        converter=Converter(_shr_dp_conv, takes_self=True),  # type: ignore
+        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 Dirichlet-type distributions, a vector of shape parameters of length
-    no less than the length of firm-count weights below; defaults depend on
+    equal to 1 plus the length of firm-count weights below; defaults depend on
     type of Dirichlet-distribution specified.
 
     """
 
-    @dist_parms.validator  # pyright: ignore
-    def __dpv(
-        _i: ShareSpec,
-        _a: Attribute[ArrayFloat | ArrayINT | None],
-        _v: ArrayFloat | ArrayINT | None,
-    ) -> None:
+    @dist_parms.default
+    def _dpd(_i: ShareSpec) -> ArrayFloat:
+        # converters run after defaults, and we
+        # avoid redundancy and confusion here
+        return _shr_dp_conv(None, _i)
+
+    @dist_parms.validator
+    def _dpv(_i: ShareSpec, _a: Attribute[ArrayFloat], _v: ArrayFloat) -> None:
         if (
             _i.firm_counts_weights is not None
             and _v is not None
-            and len(_v) < 1 + len(_i.firm_counts_weights)
+            and 0 < 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."
+                "If specified, the number of distribution parameters must euqal or "
+                "exceed the maximum firm-count premerger, which is "
+                "1 plus the length of the vector specifying firm-count weights."
             )
 
-    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
-
-    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.
-
-    """
-
     recapture_form: RECForm = field(default=RECForm.INOUT)
     """See :class:`mergeron.RECForm`"""
 
-    recapture_ratio: float | None = field(default=DEFAULT_REC_RATIO)
+    @recapture_form.validator
+    def _rfv(_i: ShareSpec, _a: Attribute[RECForm], _v: RECForm) -> None:
+        if _i.dist_type == SHRDistribution.UNI and _v == RECForm.OUTIN:
+            raise ValueError(
+                "Outside-good choice probabilities cannot be generated if the "
+                "merging firms' market shares have uniform distribution over the "
+                "3-dimensional simplex with the distribution of markets over "
+                "firm-counts unspecified."
+            )
+
+    recapture_ratio: float | None = field(kw_only=True)
     """A value between 0 and 1.
 
     :code:`None` if market share specification requires direct generation of
@@ -203,10 +265,17 @@ class ShareSpec:
     screens for further investigation, rather than as the basis for presumptions of harm or
     presumptions no harm.)
 
+    ALERT: If diversion ratios are estimated by specifying a choice probability for the
+    outside good, the recapture ratio is set to None, overriding any user-specified value.
+
     """
 
-    @recapture_ratio.validator  # pyright: ignore
-    def __rrv(_i: ShareSpec, _a: Attribute[float], _v: float) -> None:
+    @recapture_ratio.default
+    def _rrd(_i: ShareSpec) -> float | None:
+        return None if _i.recapture_form == RECForm.OUTIN else DEFAULT_REC_RATIO
+
+    @recapture_ratio.validator
+    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:
@@ -216,6 +285,22 @@ class ShareSpec:
                 "interval [0, 1)."
             )
 
+    @classmethod
+    def to_yaml(
+        cls, _r: yaml.representer.SafeRepresenter, _d: ShareSpec
+    ) -> yaml.MappingNode:
+        _ret: yaml.MappingNode = _r.represent_mapping(
+            f"!{cls.__name__}",
+            {_a.name: getattr(_d, _a.name) for _a in _d.__attrs_attrs__},
+        )
+        return _ret
+
+    @classmethod
+    def from_yaml(
+        cls, _c: yaml.constructor.SafeConstructor, _n: yaml.MappingNode
+    ) -> ShareSpec:
+        return cls(**_c.construct_mapping(_n))
+
 
 @enum.unique
 class PCMDistribution(enum.StrEnum):
@@ -236,7 +321,8 @@ class FM2Constraint(enum.StrEnum):
     SYM = "symmetric"
 
 
-@frozen
+@this_yaml.register_class
+@frozen_attrs
 class PCMSpec:
     """Price-cost margin (PCM) specification
 
@@ -252,10 +338,14 @@ class PCMSpec:
 
     """
 
-    dist_type: PCMDistribution = field(kw_only=False, default=PCMDistribution.UNI)
+    dist_type: PCMDistribution = field()
     """See :class:`PCMDistribution`"""
 
-    dist_parms: ArrayDouble | None = field(kw_only=False, default=None)
+    @dist_type.default
+    def _dtd(_i: PCMSpec) -> PCMDistribution:
+        return PCMDistribution.UNI
+
+    dist_parms: ArrayFloat | None = field(kw_only=True, eq=np.array_repr)
     """Parameter specification for tailoring PCM distribution
 
     For Uniform distribution, bounds of the distribution; defaults to `(0, 1)`;
@@ -265,12 +355,24 @@ class PCMSpec:
 
     """
 
-    @dist_parms.validator  # pyright: ignore
-    def __dpv(
-        _i: PCMSpec, _a: Attribute[ArrayDouble | None], _v: ArrayDouble | None
+    @dist_parms.default
+    def _dpwd(_i: PCMSpec) -> ArrayFloat | None:
+        match _i.dist_type:
+            case PCMDistribution.EMPR:
+                return None
+            case PCMDistribution.BETA:
+                return DEFAULT_BETA_DIST_PARMS
+            case PCMDistribution.BETA_BND:
+                return np.array([0.5, 1.0, 0.0, 0.1], float)
+            case _:
+                return DEFAULT_DIST_PARMS
+
+    @dist_parms.validator
+    def _dpv(
+        _i: PCMSpec, _a: Attribute[ArrayFloat | None], _v: ArrayFloat | None
     ) -> None:
         if _i.dist_type.name.startswith("BETA"):
-            if _v is None:
+            if _v is None or not any(_v.shape):
                 pass
             elif np.array_equal(_v, DEFAULT_DIST_PARMS):
                 raise ValueError(
@@ -288,17 +390,31 @@ class PCMSpec:
                     f'for PCM with distribution, "{_i.dist_type}" is incorrect.'
                 )
 
-        elif _i.dist_type == PCMDistribution.EMPR and _v is not None:
+        elif _v is not None and _i.dist_type == PCMDistribution.EMPR:
             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
-    )
+    firm2_pcm_constraint: FM2Constraint = field(kw_only=True, default=FM2Constraint.IID)
     """See :class:`FM2Constraint`"""
 
+    @classmethod
+    def to_yaml(
+        cls, _r: yaml.representer.SafeRepresenter, _d: PCMSpec
+    ) -> yaml.MappingNode:
+        _ret: yaml.MappingNode = _r.represent_mapping(
+            f"!{cls.__name__}",
+            {_a.name: getattr(_d, _a.name) for _a in _d.__attrs_attrs__},
+        )
+        return _ret
+
+    @classmethod
+    def from_yaml(
+        cls, _c: yaml.constructor.SafeConstructor, _n: yaml.MappingNode
+    ) -> PCMSpec:
+        return cls(**_c.construct_mapping(_n))
+
 
 @enum.unique
 class SSZConstant(float, enum.ReprEnum):
@@ -340,11 +456,8 @@ class SSZConstant(float, enum.ReprEnum):
     """When initial set of draws is not restricted in any way."""
 
 
-# Validators for selected attributes of MarketSpec
-
-
 @dataclass(slots=True, frozen=True)
-class MarketDataSample:
+class MarketSampleData:
     """Container for generated markets data sample."""
 
     frmshr_array: ArrayDouble
@@ -440,10 +553,10 @@ class MarginDataSample:
 class INVResolution(enum.StrEnum):
     CLRN = "clearance"
     ENFT = "enforcement"
-    BOTH = "both"
+    BOTH = "investigation"
 
 
-@frozen
+@frozen_attrs
 class UPPTestRegime:
     """Configuration for UPP tests."""
 
@@ -516,3 +629,28 @@ class DataclassInstance(Protocol):
     """Generic dataclass-instance"""
 
     __dataclass_fields__: ClassVar
+
+
+for _typ in (
+    PriceSpec,
+    SHRDistribution,
+    PCMDistribution,
+    FM2Constraint,
+    SSZConstant,
+    INVResolution,
+):
+    #  NOTE: If additional enums are defined in this module,
+    #  add themn to the list above
+
+    _, _ = (
+        this_yaml.representer.add_representer(
+            _typ,
+            lambda _r, _d: _r.represent_scalar(f"!{_d.__class__.__name__}", _d.name),
+        ),
+        this_yaml.constructor.add_constructor(
+            f"!{_typ.__name__}",
+            lambda _c, _n, /: getattr(
+                globals().get(_n.tag.lstrip("!")), _c.construct_scalar(_n)
+            ),
+        ),
+    )