mergeron 2025.739319.3__py3-none-any.whl → 2025.739341.9__py3-none-any.whl

mergeron/core/pseudorandom_numbers.py

@@ -1,8 +1,13 @@
 """
 Functions for generating synthetic data under specified distributions.
 
-Uses multiple CPUs when available, with PCG64DXSM as the PRNG
-https://github.com/numpy/numpy/issues/16313.
+Uses multiple CPUs when available, with PCG64DXSM as the PRNG. [#]_
+
+References
+----------
+
+.. [#] See,
+    https://numpy.org/doc/stable/reference/random/generated/numpy.random.PCG64DXSM.html
 
 """
 
@@ -14,7 +19,7 @@ from typing import Literal
 
 import numpy as np
 from attrs import Attribute, Converter, define, field
-from numpy.random import PCG64DXSM, Generator, SeedSequence
+from numpy.random import Generator, SeedSequence
 
 from .. import (  # noqa: TID252
     NTHREADS,
@@ -24,6 +29,7 @@ from .. import (  # noqa: TID252
     this_yaml,
     yaml_rt_mapper,
 )
+from . import DEFAULT_BITGENERATOR
 
 __version__ = VERSION
 
@@ -32,24 +38,24 @@ DEFAULT_BETA_DIST_PARMS: ArrayFloat = np.array([1.0, 1.0], float)
 
 
 def prng(_s: SeedSequence | None = None, /) -> np.random.Generator:
-    """Adopt the PCG64DXSM bit-generator, the future default in numpy.default_rng().
+    """Return a psure-random number generator.
 
     Parameters
     ----------
     _s
-        SeedSequence, for generating random numbers in repeatable fashion.
+        SeedSequence, for generating repeatable, non-overlapping random numbers.
 
     Returns
     -------
-        A numpy random BitGenerator.
+        A numpy random generator.
 
     """
-    return Generator(PCG64DXSM(_s))
+    return Generator(
+        DEFAULT_BITGENERATOR(SeedSequence(pool_size=8) if _s is None else _s)
+    )
 
 
 # Add yaml representer, constructor for SeedSequence
-
-
 (_, _) = (
     this_yaml.representer.add_representer(
         SeedSequence, lambda _r, _d: _r.represent_mapping("!SeedSequence", _d.state)
@@ -63,14 +69,14 @@ def prng(_s: SeedSequence | None = None, /) -> np.random.Generator:
 def gen_seed_seq_list_default(
     _len: int = 3, /, *, generated_entropy: Sequence[int] | None = None
 ) -> tuple[SeedSequence, ...]:
-    """
-    Return specified number of SeedSequences, for generating random variates
+    R"""
+    Return specified number of SeedSequences, for generating random variates.
 
     Initializes a specified number of SeedSequences based on a set of
     10 generated "seeds" in a hard-coded list. If the required number of
     random variates is larger than 10, the user must first generate
     a sufficient number of seeds to draw upon for initializing SeedSequences.
-    The generated seeds can be reused in subsequent calls to this function.
+    The generated entropy can be reused in subsequent calls to this function.
 
     Parameters
     ----------
@@ -85,20 +91,18 @@ def gen_seed_seq_list_default(
     Returns
     -------
         A list of numpy SeedSequence objects, which can be used to seed prng() or to spawn
-        seed sequences that can be used as seeds to generate non-overlapping streams in parallel.
+        seed sequences that can be used as seeds to generate non-overlapping streams in parallel. [#]_
 
     Raises
     ------
     ValueError
-        When, :math:`\\_sseq\\_list\\_len > max(10, len(generated\\_entropy))`.
+        When, :math:`\_sseq\_list\_len > max(10, len(generated\_entropy))`.
 
     References
     ----------
-    *See*, https://numpy.org/doc/stable/reference/random/parallel.html
-
+    .. [#] *See*, https://numpy.org/doc/stable/reference/random/parallel.html
 
     """
-
     generated_entropy = generated_entropy or [
         92156365243929466422624541055805800714117298857186959727264899187749727119124,
         45508962760932900824607908382088764294813063250106926349700153055300051503944,
@@ -214,7 +218,6 @@ class MultithreadedRNG:
 
     def fill(self) -> None:
         """Fill the provided output array with random number draws as specified."""
-
         if not len(self.dist_parms) or np.array_equal(
             self.dist_parms, DEFAULT_DIST_PARMS
         ):

mergeron/data/__init__.py

@@ -1,5 +1,5 @@
 """
-Data useful for empirical analysis of merger enforcement policy
+Data useful for empirical analysis of merger enforcement policy.
 
 These data are processed for further analysis within relevant
 submodules of the parent package. Thus, direct access is
@@ -14,39 +14,41 @@ __version__ = VERSION
 
 data_resources = resources.files(f"{_PKG_NAME}.data")
 
-DAMODARAN_MARGIN_WORKBOOK = data_resources / "damodaran_margin_data.xls"
+DAMODARAN_MARGIN_DATA = data_resources / "damodaran_margin_data_serialized.zip"
 """
-Python object pointing to included copy of Prof. Damodaran's margin data
+Included copy of Prof. Damodaran's margin data.
 
-Only used as a fallback, in case direct download from source fails.
+Use for replication/testing.
 
 NOTES
 -----
 Source data are from Prof. Aswath Damodaran, Stern School of Business, NYU; available online
-at https://pages.stern.nyu.edu/~adamodar/pc/datasets/margin.xls
+at https://pages.stern.nyu.edu/~adamodar/pc/datasets/margin.xls 
+and https://pages.stern.nyu.edu/~adamodar/pc/archives/margin*.xls.
 
+Gross margins are reported in 2017 data and later.
 
 Use as, for example:
 
 .. code-block:: python
 
-    from mergeron.data import DAMODARAN_MARGIN_WORKBOOK
+    import mergeron.data as mdat
 
-    shutil.copy2(DAMODARAN_MARGIN_WORKBOOK, Path.home() / f"{DAMODARAN_MARGIN_WORKBOOK.name}")
+    shutil.copy2(mdat.DAMODARAN_MARGIN_DATA, Path.home() / f"{DAMODARAN_MARGIN_DATA.name}")
 """
 
 FTC_MERGER_INVESTIGATIONS_DATA = data_resources / "ftc_merger_investigations_data.zip"
 """
-FTC merger investigtions data published in 2004, 2007, 2008, and 2013
+FTC merger investigations data published in 2004, 2007, 2008, and 2013
 
 NOTES
 -----
-Raw data tables published by the FTC are loaded into a nested distionary, organized by
+Raw data tables published by the FTC are loaded into a nested dictionary, organized by
 data period, table type, and table number. Each table is stored as a numerical array
-(:mod:`numpy` arrray), with additonal attrubutes for the industry group and additonal
+(:mod:`numpy` array), with additional attributes for the industry group and additional
 evidence noted in the source data.
 
-Data for additonal data periods (time spans) not reported in the  source data,
+Data for additional data periods (time spans) not reported in the  source data,
 e.g., 2004-2011, are constructed by subtracting counts in the base data from counts
 in the cumulative data, by table, for "enforced" mergers and "closed" mergers, when
 the cumulative data for the longer period are consistent with the base data for

mergeron/gen/__init__.py

@@ -1,8 +1,4 @@
-"""
-Defines constants, specifications (classes with attributes defining varous parameters) and
-containers for industry data generation and testing.
-
-"""
+"""Defines constants, specifications and containers for industry data generation and testing."""
 
 from __future__ import annotations
 
@@ -45,6 +41,8 @@ DEFAULT_BETA_BND_DIST_PARMS = np.array([0.5, 1.0, 0.0, 1.0], float)
 
 @frozen
 class SeedSequenceData:
+    """Seed sequence values for shares, margins, and, optionally, firm-counts and prices."""
+
     share: SeedSequence = field(eq=attrgetter("state"))
     pcm: SeedSequence = field(eq=attrgetter("state"))
     fcounts: SeedSequence | None = field(eq=lambda x: x if x is None else x.state)
@@ -78,7 +76,7 @@ class SHRDistribution(str, Enameled):
     """Shape parameter for all merging-firm-shares is unity (1)"""
 
     DIR_FLAT_CONSTR = "Flat Dirichlet - Constrained"
-    """Impose minimum probablility weight on each firm-count
+    """Impose minimum probability weight on each firm-count
 
     Only firm-counts with probability weight of 3% or more
     are included for data generation.
@@ -149,9 +147,9 @@ def _shr_dp_conv(_v: Sequence[float] | ArrayFloat | None, _i: ShareSpec) -> Arra
 
 @frozen
 class ShareSpec:
-    """Market share specification
+    """Market share specification.
 
-    A salientfeature of market-share specification in this package is that
+    A salient 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,
@@ -165,7 +163,6 @@ class ShareSpec:
     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(kw_only=False)
@@ -181,10 +178,9 @@ class ShareSpec:
     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
+    ALERT: Firm-count weights are irrelevant when the merging firms' 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
@@ -210,7 +206,6 @@ class ShareSpec:
     for Dirichlet-type distributions, a vector of shape parameters of length
     equal to 1 plus the length of firm-count weights below; defaults depend on
     type of Dirichlet-distribution specified.
-
     """
 
     @dist_parms.default
@@ -227,7 +222,7 @@ class ShareSpec:
             and 0 < len(_v) < (1 + len(_i.firm_counts_weights))
         ):
             raise ValueError(
-                "If specified, the number of distribution parameters must euqal or "
+                "If specified, the number of distribution parameters must equal or "
                 "exceed the maximum firm-count premerger, which is "
                 "1 plus the length of the vector specifying firm-count weights."
             )
@@ -252,7 +247,7 @@ class ShareSpec:
     outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
 
     The recapture ratio is usually calibrated to the numbers-equivalent of the
-    HHI threshold for the presumtion of harm from unilateral competitive effects
+    HHI threshold for the presumption of harm from unilateral competitive effects
     in published merger guidelines. Accordingly, the recapture ratio rounded to
     the nearest 5% is:
 
@@ -267,7 +262,6 @@ class ShareSpec:
 
     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.default
@@ -281,7 +275,7 @@ class ShareSpec:
         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 "
+                "the market sample specification includes a recapture ratio in the "
                 "interval [0, 1)."
             )
 
@@ -300,10 +294,10 @@ class PCMDistribution(str, Enameled):
 @this_yaml.register_class
 @enum.unique
 class PCMRestriction(str, Enameled):
-    """Firm 2 margins - derivation methods."""
+    """Restriction on generated Firm 2 margins."""
 
-    IID = "i.i.d"
-    MNL = "MNL-dep"
+    IID = "independent and identically distributed (IID)"
+    MNL = "Nash-Bertrand equilibrium with multinomial logit (MNL) demand"
     SYM = "symmetric"
 
 
@@ -320,7 +314,7 @@ def _pcm_dp_conv(_v: ArrayFloat | Sequence[float] | None, _i: PCMSpec) -> ArrayF
                 return DEFAULT_DIST_PARMS
     elif _i.dist_type == PCMDistribution.EMPR and not isinstance(_v, np.ndarray):
         raise ValueError(
-            "Invalid specification; use ..core.empriical_margin_distribution.margin_data_builider()[0]."
+            "Invalid specification; use ..core.empirical_margin_distribution.margin_data_builder()[0]."
         )
     elif isinstance(_v, Sequence | np.ndarray):
         return np.asarray(_v, float)
@@ -333,7 +327,7 @@ def _pcm_dp_conv(_v: ArrayFloat | Sequence[float] | None, _i: PCMSpec) -> ArrayF
 
 @frozen
 class PCMSpec:
-    """Price-cost margin (PCM) specification
+    """Price-cost margin (PCM) specification.
 
     If price-cost margins are specified as having Beta distribution,
     `dist_parms` is specified as a pair of positive, non-zero shape parameters of
@@ -343,8 +337,6 @@ class PCMSpec:
     Bounded-Beta distribution, `dist_parms` is specified as
     the tuple, (`mean`, `std deviation`, `min`, `max`), where `min` and `max`
     are lower- and upper-bounds respectively within the interval :math:`[0, 1]`.
-
-
     """
 
     dist_type: PCMDistribution = field()
@@ -365,7 +357,6 @@ 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
-
     """
 
     @dist_parms.default
@@ -399,7 +390,7 @@ class PCMSpec:
 
         elif _i.dist_type == PCMDistribution.EMPR and not isinstance(_v, np.ndarray):
             raise ValueError(
-                "Empirical distribution requires deserialzed margin data from Prof. Damodaran, NYU"
+                "Empirical distribution requires deserialized margin data from Prof. Damodaran, NYU"
             )
 
     pcm_restriction: PCMRestriction = field(kw_only=True, default=PCMRestriction.IID)
@@ -409,9 +400,9 @@ class PCMSpec:
     def __prv(_i: PCMSpec, _a: Attribute[PCMRestriction], _v: PCMRestriction) -> None:
         if _v == PCMRestriction.MNL and _i.dist_type == PCMDistribution.EMPR:
             print(
-                "NOTE: Estimated Firm 2 parameters will not be consistent with "
-                "the empirical distribution of margins in the source data. For "
-                "consistency, respecify pcm_spec.pcm_restriction = PCMRestriction.IID."
+                "NOTE: For consistency of generated Firm 2 margins with source data,",
+                "respecify pcm_spec.pcm_restriction = PCMRestriction.IID.",
+                sep="\n",
             )
 
 
@@ -458,7 +449,7 @@ class SSZConstant(float, Enameled):
 
 @frozen
 class MarketSampleData:
-    """Container for generated markets data sample."""
+    """Container for generated market sample dataset."""
 
     frmshr_array: ArrayDouble = field(eq=cmp_using(np.array_equal))
     """Merging-firm shares (with two merging firms)"""
@@ -509,7 +500,7 @@ class MarketSampleData:
         return retval
 
     hhi_post: ArrayDouble = field(eq=cmp_using(np.array_equal))
-    """Post-merger change in Herfindahl-Hirschmann Index (HHI)"""
+    """Post-merger contribution to Herfindahl-Hirschman Index (HHI)"""
 
     @hhi_post.default
     def __hpd(_i: MarketSampleData) -> ArrayDouble:
@@ -538,7 +529,7 @@ class MarketSampleData:
 
 
 @frozen
-class ShareDataSample:
+class ShareSampleData:
     """Container for generated market shares.
 
     Includes related measures of market structure
@@ -559,7 +550,7 @@ class ShareDataSample:
 
 
 @frozen
-class PriceDataSample:
+class PriceSampleData:
     """Container for generated price array, and related."""
 
     price_array: ArrayDouble
@@ -570,7 +561,7 @@ class PriceDataSample:
 
 
 @frozen
-class MarginDataSample:
+class MarginSampleData:
     """Container for generated margin array and related MNL test array."""
 
     pcm_array: ArrayDouble
@@ -581,7 +572,7 @@ class MarginDataSample:
 
     Applying restrictions from Bertrand-Nash oligopoly
     with MNL demand results in draws of Firm 2 PCM falling
-    outside the feabile interval,:math:`[0, 1]`, depending
+    outside the feasible interval,:math:`[0, 1]`, depending
     on the configuration of merging firm shares. Such draws
     are are flagged as infeasible (False)in :code:`mnl_test_array` while
     draws with PCM values within the feasible range are
@@ -593,9 +584,11 @@ class MarginDataSample:
 @this_yaml.register_class
 @enum.unique
 class INVResolution(str, Enameled):
+    """Report investigations resulting in clearance; enforcement; or both, respectively."""
+
     CLRN = "clearance"
     ENFT = "enforcement"
-    BOTH = "investigation"
+    BOTH = "clearance and enforcement, respectively"
 
 
 @frozen
@@ -639,24 +632,22 @@ class UPPTestRegime:
 
 @frozen
 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
+    In the case of :attr:`INVResolution.BOTH`, two columns of counts
     are returned: one for each resolution.
-
     """
 
     by_firm_count: ArrayBIGINT = field(eq=cmp_using(eq=np.array_equal))
     by_delta: ArrayBIGINT = field(eq=cmp_using(eq=np.array_equal))
     by_conczone: ArrayBIGINT = field(eq=cmp_using(eq=np.array_equal))
-    """Zones are "unoncentrated", "moderately concentrated", and "highly concentrated",
-    with futher detail by HHI and ΔHHI for mergers in the "unconcentrated" and
+    """Zones are "unconcentrated", "moderately concentrated", and "highly concentrated",
+    with further 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.
-
     """
 
 

mergeron/gen/data_generation.py

@@ -1,7 +1,4 @@
-"""
-Methods to generate data for analyzing merger enforcement policy.
-
-"""
+"""Methods to generate data for analyzing merger enforcement policy."""
 
 from __future__ import annotations
 
@@ -52,13 +49,13 @@ H5_CHUNK_SIZE = 10**6
 
 
 class SamplingFunctionKWArgs(TypedDict, total=False):
-    "Keyword arguments of sampling methods defined below"
+    """Keyword arguments of sampling methods defined below."""
 
     sample_size: int
     """number of draws to generate"""
 
     seed_data: SeedSequenceData | None
-    """seed data to ensure independedent and replicable draws"""
+    """seed data to ensure independent and replicable draws"""
 
     nthreads: int
     """number of parallel threads to use"""
@@ -116,7 +113,7 @@ class MarketSample:
     hsr_filing_test_type: SSZConstant = field(
         default=SSZConstant.ONE, validator=validators.instance_of(SSZConstant)
     )
-    """Method for modeling HSR filing threholds, see :class:`SSZConstant`"""
+    """Method for modeling HSR filing thresholds, see :class:`SSZConstant`"""
 
     sample_size: int = field(default=10**6, validator=validators.instance_of(int))
     """number of draws to simulate"""
@@ -166,7 +163,7 @@ class MarketSample:
         """
         Generate share, diversion ratio, price, and margin data for MarketSpec.
 
-        see :attr:`SamplingFunctionKWArgs` for description of keyord parameters
+        see :attr:`SamplingFunctionKWArgs` for description of keyword parameters
 
         Returns
         -------
@@ -174,7 +171,6 @@ class MarketSample:
             in the sample
 
         """
-
         # Scale up sample size to offset discards based on specified criteria
         shr_sample_size = sample_size * self.hsr_filing_test_type
         shr_sample_size *= (
@@ -253,14 +249,13 @@ class MarketSample:
         )
 
     def generate_sample(self, /) -> None:
-        """Populate :attr:`data` with generated data
+        """Populate :attr:`data` with generated data.
 
         Returns
         -------
         None
 
         """
-
         self.dataset = self._gen_market_sample(
             seed_data=self.seed_data,
             sample_size=self.sample_size,
@@ -277,11 +272,10 @@ class MarketSample:
         sample_size: int = 10**6,
         nthreads: int = NTHREADS,
     ) -> UPPTestsCounts:
-        """Generate market data and etstimate UPP test counts on same.
+        """Generate market data and compute UPP test counts on same.
 
         Parameters
         ----------
-
         _upp_test_parms
             Guidelines thresholds for testing UPP and related statistics
 
@@ -302,10 +296,9 @@ class MarketSample:
 
         Returns
         -------
-            UPPTestCounts ojbect with  of test counts by firm count, ΔHHI and concentration zone
+            UPPTestCounts object with  of test counts by firm count, ΔHHI and concentration zone
 
         """
-
         market_data_sample = self._gen_market_sample(
             sample_size=sample_size, seed_data=seed_data, nthreads=nthreads
         )
@@ -319,7 +312,7 @@ class MarketSample:
     def __sim_enf_cnts_ll(
         self, _enf_parm_vec: gbl.HMGThresholds, _sim_test_regime: UPPTestRegime, /
     ) -> UPPTestsCounts:
-        """A function to parallelize data-generation and testing
+        """Parallelize data-generation and testing.
 
         The parameters `_sim_enf_cnts_kwargs` are passed unaltered to
         the parent function, `sim_enf_cnts()`, except that, if provided,
@@ -331,7 +324,6 @@ class MarketSample:
 
         Parameters
         ----------
-
         _enf_parm_vec
             Guidelines thresholds to test against
 
@@ -346,7 +338,7 @@ class MarketSample:
         """
         sample_sz = self.sample_size
         subsample_sz = H5_CHUNK_SIZE
-        iter_count = (sample_sz / subsample_sz).__ceil__()  # noqa: PLC2801
+        iter_count = (sample_sz / subsample_sz).__ceil__()
         thread_count = self.nthreads or cpu_count()
 
         if (
@@ -382,7 +374,8 @@ class MarketSample:
             "nthreads": thread_count,
         })
 
-        res_list = Parallel(n_jobs=min(thread_count, iter_count), prefer="threads")(
+        _threads = min(thread_count, iter_count)
+        res_list = Parallel(n_jobs=_threads, prefer="threads")(
             delayed(self.__sim_enf_cnts)(
                 _enf_parm_vec,
                 _sim_test_regime,
@@ -434,7 +427,6 @@ class MarketSample:
         None
 
         """
-
         if self.dataset is None:
             self.enf_counts = self.__sim_enf_cnts_ll(_enf_parm_vec, _upp_test_regime)
         else:
@@ -445,6 +437,7 @@ class MarketSample:
     def to_archive(
         self, zip_: zipfile.ZipFile, _subdir: str = "", /, *, save_dataset: bool = False
     ) -> None:
+        """Serialize market sample to Zip archive."""
         zpath = zipfile.Path(zip_, at=_subdir)
         name_root = f"{_PKG_NAME}_market_sample"
 
@@ -455,7 +448,7 @@ class MarketSample:
             if all((_ndt := self.dataset is None, _net := self.enf_counts is None)):
                 raise ValueError(
                     "No dataset and/or enforcement counts available for saving. "
-                    "Generate some data or set save_dataset to False to poceed."
+                    "Generate some data or set save_dataset to False to proceed."
                 )
 
             if not _ndt:
@@ -469,6 +462,7 @@ class MarketSample:
     def from_archive(
         zip_: zipfile.ZipFile, _subdir: str = "", /, *, restore_dataset: bool = False
     ) -> MarketSample:
+        """Deserialize market sample from Zip archive."""
         zpath = zipfile.Path(zip_, at=_subdir)
         name_root = f"{_PKG_NAME}_market_sample"
 
@@ -486,11 +480,11 @@ class MarketSample:
 
             if _dt:
                 with _dp.open("rb") as _hfh:
-                    object.__setattr__(  # noqa: PLC2801
+                    object.__setattr__(
                         market_sample_, "dataset", MarketSampleData.from_h5f(_hfh)
                     )
             if _et:
-                object.__setattr__(  # noqa: PLC2801
+                object.__setattr__(
                     market_sample_, "enf_counts", this_yaml.load(_ep.read_text())
                 )
         return market_sample_
@@ -499,6 +493,7 @@ class MarketSample:
     def to_yaml(
         cls, _r: yaml.representer.RoundTripRepresenter, _d: MarketSample
     ) -> yaml.MappingNode:
+        """Serialize market sample to YAML representation."""
         retval: yaml.MappingNode = _r.represent_mapping(
             f"!{cls.__name__}",
             {
@@ -513,4 +508,5 @@ class MarketSample:
     def from_yaml(
         cls, _c: yaml.constructor.RoundTripConstructor, _n: yaml.MappingNode
     ) -> MarketSample:
+        """Deserialize market sample from YAML representation."""
         return cls(**yaml_rt_mapper(_c, _n))