mergeron 2025.739290.3__py3-none-any.whl → 2025.739290.5__py3-none-any.whl

mergeron/__init__.py

@@ -1,26 +1,21 @@
 from __future__ import annotations
 
 import enum
+from collections.abc import Mapping
 from multiprocessing import cpu_count
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 import numpy as np
-from numpy.random import SeedSequence
 from numpy.typing import NDArray
 from ruamel import yaml
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2025.739290.3"
+VERSION = "2025.739290.5"
 
 __version__ = VERSION
 
-this_yaml = yaml.YAML(typ="safe", pure=True)
-this_yaml.constructor.deep_construct = True
-this_yaml.indent(mapping=2, sequence=4, offset=2)
-
-
 DATA_DIR: Path = Path.home() / _PKG_NAME
 """
 Defines a subdirectory named for this package in the user's home path.
@@ -37,18 +32,24 @@ EMPTY_ARRAYINT = np.array([], int)
 
 NTHREADS = 2 * cpu_count()
 
+PKG_ATTRS_MAP: dict[str, object] = {}
+
 np.set_printoptions(precision=24, floatmode="fixed")
 
 type HMGPubYear = Literal[1982, 1984, 1992, 2010, 2023]
 
 type ArrayBoolean = NDArray[np.bool_]
-type ArrayFloat = NDArray[np.float16 | np.float32 | np.float64 | np.float128]
-type ArrayINT = NDArray[np.intp]
+type ArrayFloat = NDArray[np.floating]
+type ArrayINT = NDArray[np.unsignedinteger]
 
 type ArrayDouble = NDArray[np.float64]
-type ArrayBIGINT = NDArray[np.int64]
+type ArrayBIGINT = NDArray[np.uint64]
+
+
+this_yaml = yaml.YAML(typ="rt")
+this_yaml.indent(mapping=2, sequence=4, offset=2)
 
-## Add yaml representer, constructor for NoneType
+# Add yaml representer, constructor for NoneType
 (_, _) = (
     this_yaml.representer.add_representer(
         type(None), lambda _r, _d: _r.represent_scalar("!None", "none")
@@ -56,44 +57,116 @@ type ArrayBIGINT = NDArray[np.int64]
     this_yaml.constructor.add_constructor("!None", lambda _c, _n, /: None),
 )
 
-## Add yaml representer, constructor for ndarray
+
+# Add yaml representer, constructor for ndarray
 (_, _) = (
     this_yaml.representer.add_representer(
         np.ndarray,
         lambda _r, _d: _r.represent_sequence("!ndarray", (_d.tolist(), _d.dtype.str)),
     ),
     this_yaml.constructor.add_constructor(
-        "!ndarray", lambda _c, _n, /: np.array(*_c.construct_sequence(_n))
+        "!ndarray", lambda _c, _n, /: np.array(*_c.construct_sequence(_n, deep=True))
     ),
 )
 
-# Add yaml representer, constructor for SeedSequence
-this_yaml.representer.add_representer(
-    SeedSequence,
-    lambda _r, _d: _r.represent_mapping(
-        "!SeedSequence",
-        {
-            _a: getattr(_d, _a)
-            for _a in ("entropy", "spawn_key", "pool_size", "n_children_spawned")
-        },
-    ),
-)
-this_yaml.constructor.add_constructor(
-    "!SeedSequence", lambda _c, _n, /: SeedSequence(**_c.construct_mapping(_n))
-)
+
+def yaml_rt_mapper(
+    _c: yaml.constructor.RoundTripConstructor, _n: yaml.MappingNode
+) -> Mapping[str, Any]:
+    """
+    Constructs a mapping from a mapping node with the RoundTripConstructor
+
+    """
+    data_: Mapping[str, Any] = yaml.constructor.CommentedMap()
+    _c.construct_mapping(_n, maptyp=data_, deep=True)
+    return data_
+
+
+def yamelize_attrs(
+    _typ: object, /, *, attr_map: Mapping[str, object] = PKG_ATTRS_MAP
+) -> None:
+    """Add yaml representer, constructor for attrs-defined class.
+
+    Applying this function, attributes with property, `init=False` are
+    not serialized to YAML.
+    """
+
+    attr_map |= {_typ.__name__: _typ}
+
+    _ = this_yaml.representer.add_representer(
+        _typ,
+        lambda _r, _d: _r.represent_mapping(
+            f"!{_d.__class__.__name__}",
+            # construct mapping, rather than calling attrs.asdict(),
+            # to use yaml representers defined in this package for
+            # "upstream" objects
+            {_a.name: getattr(_d, _a.name) for _a in _d.__attrs_attrs__ if _a.init},
+        ),
+    )
+    _ = this_yaml.constructor.add_constructor(
+        f"!{_typ.__name__}",
+        lambda _c, _n: attr_map[_n.tag.lstrip("!")](**yaml_rt_mapper(_c, _n)),
+    )
 
 
+@this_yaml.register_class
+class Enameled(enum.Enum):
+    """Add YAML representer, constructor for enum.Enum"""
+
+    @classmethod
+    def to_yaml(
+        cls, _r: yaml.representer.RoundTripRepresenter, _d: object[enum.EnumType]
+    ) -> yaml.ScalarNode:
+        return _r.represent_scalar(
+            f"!{super().__getattribute__(cls, '__name__')}", f"{_d.name}"
+        )
+
+    @classmethod
+    def from_yaml(
+        cls, _c: yaml.constructor.RoundTripConstructor, _n: yaml.ScalarNode
+    ) -> object[enum.EnumType]:
+        return super().__getattribute__(cls, _n.value)
+
+
+@this_yaml.register_class
 @enum.unique
-class RECForm(enum.StrEnum):
+class RECForm(str, Enameled):
     """For derivation of recapture ratio from market shares."""
 
     INOUT = "inside-out"
+    R"""
+    Given, :math:`\overline{r}, s_i {\ } \forall {\ } i \in \set{1, 2, \ldots, m}`, with
+    :math:`s_{min} = \min(s_1, s_2)`,
+
+    .. math::
+
+        REC_i = \frac{(1 - s_i) \overline{r}}{(1 - s_{min}) - (s_i - s_{min}) \overline{r}}
+
+    """
+
     OUTIN = "outside-in"
+    R"""
+    Given, :math:`\pi_i {\ } \forall {\ } i \in N`,
+
+    .. math::
+
+        REC_i = \frac{\sum_{i \in M} \pi_i}{\sum_{j \in N} \pi_j}
+
+    """
+
     FIXED = "proportional"
+    R"""Given, :math:`\overline{r}`,
+
+    .. math::
+
+        REC_i = \overline{r} {\ } \forall {\ } i \in M
+
+    """
 
 
+@this_yaml.register_class
 @enum.unique
-class UPPAggrSelector(enum.StrEnum):
+class UPPAggrSelector(str, Enameled):
     """
     Aggregator for GUPPI and diversion ratio estimates.
 
@@ -110,21 +183,3 @@ class UPPAggrSelector(enum.StrEnum):
     OSA = "own-share weighted average"
     OSD = "own-share weighted distance"
     OSG = "own-share weighted geometric mean"
-
-
-for _typ in (RECForm, UPPAggrSelector):
-    #  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)
-            ),
-        ),
-    )

mergeron/core/__init__.py

@@ -1,8 +1,109 @@
-from mpmath import mp  # type: ignore
+from __future__ import annotations
 
-from .. import VERSION  # noqa: TID252
+from collections.abc import Mapping
+from decimal import Decimal
+from types import MappingProxyType
+from typing import Any
+
+import mpmath  # type: ignore
+import numpy as np
+from attrs import cmp_using, field, frozen
+
+from .. import VERSION, ArrayBIGINT, this_yaml, yaml_rt_mapper  # noqa: TID252
 
 __version__ = VERSION
 
-type MPFloat = mp.mpf  # type: ignore
-type MPMatrix = mp.matrix  # type: ignore
+type MPFloat = mpmath.ctx_mp_python.mpf
+type MPMatrix = mpmath.matrix  # type: ignore
+
+
+@frozen
+class INVTableData:
+    industry_group: str
+    additional_evidence: str
+    data_array: ArrayBIGINT = field(eq=cmp_using(eq=np.array_equal))
+
+
+type INVData = MappingProxyType[
+    str, MappingProxyType[str, MappingProxyType[str, INVTableData]]
+]
+type INVData_in = Mapping[str, Mapping[str, Mapping[str, INVTableData]]]
+
+
+(_, _) = (
+    this_yaml.representer.add_representer(
+        Decimal, lambda _r, _d: _r.represent_scalar("!Decimal", f"{_d}")
+    ),
+    this_yaml.constructor.add_constructor(
+        "!Decimal", lambda _c, _n, /: Decimal(_c.construct_scalar(_n))
+    ),
+)
+
+
+(_, _) = (
+    this_yaml.representer.add_representer(
+        mpmath.mpf, lambda _r, _d: _r.represent_scalar("!MPFloat", f"{_d}")
+    ),
+    this_yaml.constructor.add_constructor(
+        "!MPFloat", lambda _c, _n, /: mpmath.mpf(_c.construct_scalar(_n))
+    ),
+)
+
+(_, _) = (
+    this_yaml.representer.add_representer(
+        mpmath.matrix, lambda _r, _d: _r.represent_sequence("!MPMatrix", _d.tolist())
+    ),
+    this_yaml.constructor.add_constructor(
+        "!MPMatrix",
+        lambda _c, _n, /: mpmath.matrix(_c.construct_sequence(_n, deep=True)),
+    ),
+)
+
+
+def _dict_from_mapping(_p: Mapping[Any, Any], /) -> dict[Any, Any]:
+    retval = {}
+    for _k, _v in _p.items():  # for subit in it:
+        retval |= {_k: _dict_from_mapping(_v)} if isinstance(_v, Mapping) else {_k: _v}
+    return retval
+
+
+def _mappingproxy_from_mapping(_p: Mapping[Any, Any], /) -> MappingProxyType[Any, Any]:
+    retval = {}
+    for _k, _v in _p.items():  # for subit in it:
+        retval |= (
+            {_k: _mappingproxy_from_mapping(_v)}
+            if isinstance(_v, Mapping)
+            else {_k: _v}
+        )
+    return MappingProxyType(retval)
+
+
+_, _ = (
+    this_yaml.representer.add_representer(
+        MappingProxyType,
+        lambda _r, _d: _r.represent_mapping("!mappingproxy", dict(_d.items())),
+    ),
+    this_yaml.constructor.add_constructor(
+        "!mappingproxy", lambda _c, _n: MappingProxyType(yaml_rt_mapper(_c, _n))
+    ),
+)
+
+
+for _typ in (INVTableData,):
+    _, _ = (
+        this_yaml.representer.add_representer(
+            _typ,
+            lambda _r, _d: _r.represent_mapping(
+                f"!{_d.__class__.__name__}",
+                {
+                    _a.name: getattr(_d, _a.name)
+                    for _a in _d.__attrs_attrs__
+                    if _a.name not in {"coordinates", "area"}
+                },
+            ),
+        ),
+        this_yaml.constructor.add_constructor(
+            f"!{_typ.__name__}",
+            lambda _c, _n: globals()[_n.tag.lstrip("!")](**yaml_rt_mapper(_c, _n)),
+        ),
+    )

mergeron/core/empirical_margin_distribution.py

@@ -2,7 +2,7 @@
 Functions to parse margin data compiled by
 Prof. Aswath Damodaran, Stern School of Business, NYU.
 
-Provides :func:`mgn_data_resampler` for generating margin data
+Provides :func:`margin_data_resampler` for generating margin data
 from an estimated Gaussian KDE from the source (margin) data.
 
 Data are downloaded or reused from a local copy, on demand.
@@ -37,123 +37,139 @@ price-cost margins fall in the interval :math:`[0, 1]`.
 """
 
 import shutil
+import zipfile
 from collections.abc import Mapping
 from importlib import resources
 from pathlib import Path
 from types import MappingProxyType
 
-import msgpack  # type:ignore
 import numpy as np
 import urllib3
 from numpy.random import PCG64DXSM, Generator, SeedSequence
 from scipy import stats  # type: ignore
 from xlrd import open_workbook  # type: ignore
 
-from .. import _PKG_NAME, DATA_DIR, VERSION, ArrayDouble  # noqa: TID252
+from .. import _PKG_NAME, DATA_DIR, VERSION, ArrayDouble, this_yaml  # noqa: TID252
+from . import _mappingproxy_from_mapping
 
 __version__ = VERSION
 
-MGNDATA_ARCHIVE_PATH = DATA_DIR / "damodaran_margin_data_dict.msgpack"
+MGNDATA_ARCHIVE_PATH = DATA_DIR / "damodaran_margin_data_serialized.zip"
+
 
 u3pm = urllib3.PoolManager()
 
 
-def mgn_data_getter(  # noqa: PLR0912
+def margin_data_getter(  # noqa: PLR0912
     _table_name: str = "margin",
     *,
     data_archive_path: Path | None = None,
     data_download_flag: bool = False,
-) -> MappingProxyType[str, Mapping[str, float | int]]:
+) -> MappingProxyType[str, MappingProxyType[str, float | int]]:
     if _table_name != "margin":  # Not validated for other tables
         raise ValueError(
             "This code is designed for parsing Prof. Damodaran's margin tables."
         )
 
-    _data_archive_path = data_archive_path or MGNDATA_ARCHIVE_PATH
-
-    _mgn_urlstr = f"https://pages.stern.nyu.edu/~adamodar/pc/datasets/{_table_name}.xls"
-    _mgn_path = _data_archive_path.parent / f"damodaran_{_table_name}_data.xls"
-    if _data_archive_path.is_file() and not data_download_flag:
-        return MappingProxyType(msgpack.unpackb(_data_archive_path.read_bytes()))
-    elif _mgn_path.is_file():
-        _mgn_path.unlink()
-        if _data_archive_path.is_file():
-            _data_archive_path.unlink()
-
+    data_archive_path = data_archive_path or MGNDATA_ARCHIVE_PATH
+    workbook_path = data_archive_path.parent / f"damodaran_{_table_name}_data.xls"
+    if data_archive_path.is_file() and not data_download_flag:
+        # with data_archive_path_.open("r") as _yfh:
+        #     margin_data_dict: dict[str, dict[str, float | int]] = this_yaml.load(_yfh)
+        with (
+            zipfile.ZipFile(data_archive_path) as _yzip,
+            _yzip.open(f"{data_archive_path.stem}.yaml") as _yfh,
+        ):
+            margin_data_dict: dict[str, dict[str, float | int]] = this_yaml.load(_yfh)
+        return _mappingproxy_from_mapping(margin_data_dict)
+    elif workbook_path.is_file():
+        workbook_path.unlink()
+        if data_archive_path.is_file():
+            data_archive_path.unlink()
+
+    margin_urlstr = (
+        f"https://pages.stern.nyu.edu/~adamodar/pc/datasets/{_table_name}.xls"
+    )
     try:
-        _chunk_size = 1024 * 1024
+        chunk_size_ = 1024 * 1024
         with (
-            u3pm.request("GET", _mgn_urlstr, preload_content=False) as _urlopen_handle,
-            _mgn_path.open("wb") as _mgn_file,
+            u3pm.request(
+                "GET", margin_urlstr, preload_content=False
+            ) as _urlopen_handle,
+            workbook_path.open("wb") as margin_file,
         ):
             while True:
-                _data = _urlopen_handle.read(_chunk_size)
-                if not _data:
+                data_ = _urlopen_handle.read(chunk_size_)
+                if not data_:
                     break
-                _mgn_file.write(_data)
+                margin_file.write(data_)
 
-        print(f"Downloaded {_mgn_urlstr} to {_mgn_path}.")
+        print(f"Downloaded {margin_urlstr} to {workbook_path}.")
 
-    except urllib3.exceptions.MaxRetryError as _err:
-        if isinstance(_err.__cause__, urllib3.exceptions.SSLError):
+    except urllib3.exceptions.MaxRetryError as error_:
+        if isinstance(error_.__cause__, urllib3.exceptions.SSLError):
             # Works fine with other sites secured with certificates
             # from the Internet2 CA, such as,
             # https://snap.stanford.edu/data/web-Stanford.txt.gz
             print(
-                f"WARNING: Could not establish secure connection to, {_mgn_urlstr}."
+                f"WARNING: Could not establish secure connection to, {margin_urlstr}."
                 "Using bundled copy."
             )
-            if not _mgn_path.is_file():
+            if not workbook_path.is_file():
                 with resources.as_file(
                     resources.files(f"{_PKG_NAME}.data").joinpath(
                         "empirical_margin_distribution.xls"
                     )
-                ) as _mgn_data_archive_path:
-                    shutil.copy2(_mgn_data_archive_path, _mgn_path)
+                ) as margin_data_archive_path:
+                    shutil.copy2(margin_data_archive_path, workbook_path)
         else:
-            raise _err
-
-    _xl_book = open_workbook(_mgn_path, ragged_rows=True, on_demand=True)
-    _xl_sheet = _xl_book.sheet_by_name("Industry Averages")
-
-    _mgn_dict: dict[str, dict[str, float]] = {}
-    _mgn_row_keys: list[str] = []
-    _read_row_flag = False
-    for _ridx in range(_xl_sheet.nrows):
-        _xl_row = _xl_sheet.row_values(_ridx)
-        if _xl_row[0] == "Industry Name":
-            _read_row_flag = True
-            _mgn_row_keys = _xl_row
+            raise error_
+
+    xl_book = open_workbook(workbook_path, ragged_rows=True, on_demand=True)
+    xl_sheet = xl_book.sheet_by_name("Industry Averages")
+
+    margin_dict: dict[str, dict[str, float | int]] = {}
+    row_keys: list[str] = []
+    read_row_flag = False
+    for _ridx in range(xl_sheet.nrows):
+        xl_row = xl_sheet.row_values(_ridx)
+        if xl_row[0] == "Industry Name":
+            read_row_flag = True
+            row_keys = xl_row
             continue
 
-        if not _xl_row[0] or not _read_row_flag:
+        if not xl_row[0] or not read_row_flag:
             continue
 
-        _xl_row[1] = int(_xl_row[1])
-        _mgn_dict[_xl_row[0]] = dict(zip(_mgn_row_keys[1:], _xl_row[1:], strict=True))
+        xl_row[1] = int(xl_row[1])
+        margin_dict[xl_row[0]] = dict(zip(row_keys[1:], xl_row[1:], strict=True))
 
-    _ = _data_archive_path.write_bytes(msgpack.packb(_mgn_dict))
+    with (
+        zipfile.ZipFile(data_archive_path, "w") as _yzip,
+        _yzip.open(f"{data_archive_path.stem}.yaml", "w") as _yfh,
+    ):
+        this_yaml.dump(margin_dict, _yfh)
 
-    return MappingProxyType(_mgn_dict)
+    return _mappingproxy_from_mapping(margin_dict)
 
 
-def mgn_data_builder(
-    _mgn_tbl_dict: Mapping[str, Mapping[str, float | int]] | None = None, /
+def margin_data_builder(
+    _src_data_dict: Mapping[str, Mapping[str, float | int]] | None = None, /
 ) -> tuple[ArrayDouble, ArrayDouble, ArrayDouble]:
-    if _mgn_tbl_dict is None:
-        _mgn_tbl_dict = mgn_data_getter()
+    if _src_data_dict is None:
+        _src_data_dict = margin_data_getter()
 
-    _mgn_data_wts, _mgn_data_obs = (
+    margin_data_wts, margin_data_obs = (
         _f.flatten()
         for _f in np.hsplit(
             np.array([
                 tuple(
-                    _mgn_tbl_dict[_g][_h] for _h in ["Number of firms", "Gross Margin"]
+                    _src_data_dict[_g][_h] for _h in ["Number of firms", "Gross Margin"]
                 )
-                for _g in _mgn_tbl_dict
+                for _g in _src_data_dict
                 if not _g.startswith("Total Market")
                 and _g
-                not in (
+                not in {
                     "Bank (Money Center)",
                     "Banks (Regional)",
                     "Brokerage & Investment Banking",
@@ -165,29 +181,35 @@ def mgn_data_builder(
                     "R.E.I.T.",
                     "Retail (REITs)",
                     "Reinsurance",
-                )
+                }
             ]),
             2,
         )
     )
 
-    _mgn_wtd_avg = np.average(_mgn_data_obs, weights=_mgn_data_wts)
+    margin_wtd_avg = np.average(margin_data_obs, weights=margin_data_wts)
     # https://www.itl.nist.gov/div898/software/dataplot/refman2/ch2/weighvar.pdf
-    _mgn_wtd_stderr = np.sqrt(
-        np.average((_mgn_data_obs - _mgn_wtd_avg) ** 2, weights=_mgn_data_wts)
-        * (len(_mgn_data_wts) / (len(_mgn_data_wts) - 1))
+    margin_wtd_stderr = np.sqrt(
+        np.average((margin_data_obs - margin_wtd_avg) ** 2, weights=margin_data_wts)
+        * (len(margin_data_wts) / (len(margin_data_wts) - 1))
     )
 
     return (
-        _mgn_data_obs,
-        _mgn_data_wts,
+        margin_data_obs,
+        margin_data_wts,
         np.round(
-            (_mgn_wtd_avg, _mgn_wtd_stderr, _mgn_data_obs.min(), _mgn_data_obs.max()), 8
+            (
+                margin_wtd_avg,
+                margin_wtd_stderr,
+                margin_data_obs.min(),
+                margin_data_obs.max(),
+            ),
+            8,
         ),
     )
 
 
-def mgn_data_resampler(
+def margin_data_resampler(
     _sample_size: int | tuple[int, ...] = (10**6, 2),
     /,
     *,
@@ -216,26 +238,26 @@ def mgn_data_resampler(
 
     """
 
-    _seed_sequence = seed_sequence or SeedSequence(pool_size=8)
+    seed_sequence_ = seed_sequence or SeedSequence(pool_size=8)
 
-    _x, _w, _ = mgn_data_builder(mgn_data_getter())
+    _x, _w, _ = margin_data_builder(margin_data_getter())
 
-    _mgn_kde = stats.gaussian_kde(_x, weights=_w, bw_method="silverman")
-    _mgn_kde.set_bandwidth(bw_method=_mgn_kde.factor / 3.0)
+    margin_kde = stats.gaussian_kde(_x, weights=_w, bw_method="silverman")
+    margin_kde.set_bandwidth(bw_method=margin_kde.factor / 3.0)
 
     if isinstance(_sample_size, int):
         return np.array(
-            _mgn_kde.resample(_sample_size, seed=Generator(PCG64DXSM(_seed_sequence)))[
-                0
-            ]
+            margin_kde.resample(
+                _sample_size, seed=Generator(PCG64DXSM(seed_sequence_))
+            )[0]
         )
     elif isinstance(_sample_size, tuple) and len(_sample_size) == 2:
-        _ssz, _num_cols = _sample_size
-        _ret_array = np.empty(_sample_size, np.float64)
-        for _idx, _seed_seq in enumerate(_seed_sequence.spawn(_num_cols)):
-            _ret_array[:, _idx] = _mgn_kde.resample(
-                _ssz, seed=Generator(PCG64DXSM(_seed_seq))
+        ssz, num_cols = _sample_size
+        ret_array = np.empty(_sample_size, np.float64)
+        for idx, seed_seq in enumerate(seed_sequence_.spawn(num_cols)):
+            ret_array[:, idx] = margin_kde.resample(
+                ssz, seed=Generator(PCG64DXSM(seed_seq))
             )[0]
-        return _ret_array
+        return ret_array
     else:
         raise ValueError(f"Invalid sample size: {_sample_size!r}")