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

mergeron/core/{guidelines_boundaries_specialized_functions.py → guidelines_boundary_functions_extra.py}

@@ -1,35 +1,71 @@
 """
-Specialized routines for defining and analyzing boundaries for Guidelines standards.
+Specialized methods for defining and analyzing boundaries for Guidelines standards.
 
-These routines provide improved precision or demonstrate additional methods, but tend
-to have poor performance
+These methods (functions) provide rely on scipy of sympy for core computations,
+and may provide improved precision than core functions, but tend to have
+poor performance
 
 """
 
-from importlib.metadata import version
+from collections.abc import Callable
+from dataclasses import dataclass
 from typing import Literal
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
 from scipy.spatial.distance import minkowski as distance_function  # type: ignore
-from sympy import lambdify, simplify, solve, symbols
+from sympy import lambdify, simplify, solve, symbols  # type: ignore
 
-from .. import _PKG_NAME  # noqa: TID252
-from .guidelines_boundaries import (
-    GuidelinesBoundary,
-    GuidelinesBoundaryCallable,
-    _shrratio_boundary_intcpt,
-    lerp,
-)
+from .. import DEFAULT_REC_RATIO, VERSION, ArrayDouble  # noqa: TID252
+from . import guidelines_boundary_functions as gbfn
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
-mp.prec = 80
+mp.dps = 32
 mp.trap_complex = True
 
 
-def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable:
+@dataclass(slots=True, frozen=True)
+class GuidelinesBoundaryCallable:
+    boundary_function: Callable[[ArrayDouble], ArrayDouble]
+    area: float
+    s_naught: float = 0
+
+
+def dh_area_quad(_dh_val: float = 0.01, /, *, dps: int = 9) -> float:
+    """
+    Area under the ΔHHI boundary.
+
+    When the given ΔHHI bound matches a Guidelines safeharbor,
+    the area under the boundary is half the intrinsic clearance rate
+    for the ΔHHI safeharbor.
+
+    Parameters
+    ----------
+    _dh_val
+        Merging-firms' ΔHHI bound.
+    dps
+        Specified precision in decimal places.
+
+    Returns
+    -------
+        Area under ΔHHI boundary.
+
+    """
+
+    _dh_val = mpf(f"{_dh_val}")
+    _s_naught = (1 - mp.sqrt(1 - 2 * _dh_val)) / 2
+
+    return round(
+        float(
+            _s_naught + mp.quad(lambda x: _dh_val / (2 * x), [_s_naught, 1 - _s_naught])
+        ),
+        dps,
+    )
+
+
+def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
     """
     Generate the list of share combination on the ΔHHI boundary.
 
@@ -37,8 +73,6 @@ def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable
     ----------
     _dh_val:
         Merging-firms' ΔHHI bound.
-    prec
-        Number of decimal places for rounding reported shares.
 
     Returns
     -------
@@ -52,12 +86,12 @@ def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable
 
     _hhi_eqn = _s_2 - 0.01 / (2 * _s_1)
 
-    _hhi_bdry = solve(_hhi_eqn, _s_2)[0]  # type: ignore
-    _s_nought = float(solve(_hhi_eqn.subs({_s_2: 1 - _s_1}), _s_1)[0])  # type: ignore
+    _hhi_bdry = solve(_hhi_eqn, _s_2)[0]
+    _s_nought = float(solve(_hhi_eqn.subs({_s_2: 1 - _s_1}), _s_1)[0])
 
     _hhi_bdry_area = 2 * (
         _s_nought
-        + mp.quad(lambdify(_s_1, _hhi_bdry, "mpmath"), (_s_nought, 1 - _s_nought))
+        + mp.quad(lambdify(_s_1, _hhi_bdry, "mpmath"), (_s_nought, 1 - _s_nought))  # pyright: ignore
     )
 
     return GuidelinesBoundaryCallable(
@@ -67,11 +101,11 @@ def delta_hhi_boundary_qdtr(_dh_val: float = 0.01) -> GuidelinesBoundaryCallable
 
 def shrratio_boundary_qdtr_wtd_avg(
     _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+    _r_val: float = DEFAULT_REC_RATIO,
     /,
     *,
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
 ) -> GuidelinesBoundaryCallable:
     """
     Share combinations for the share-weighted average GUPPI boundary with symmetric
@@ -85,7 +119,7 @@ def shrratio_boundary_qdtr_wtd_avg(
         recapture ratio
     weighting
         Whether "own-share" or "cross-product-share" (or None for simple, unweighted average)
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
 
@@ -109,23 +143,23 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - (_s_1 + _s_2) * _delta_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[0]  # type: ignore
+            _bdry_func = solve(_bdry_eqn, _s_2)[0]
             _s_naught = (
                 float(solve(simplify(_bdry_eqn.subs({_s_2: 1 - _s_1})), _s_1)[0])  # type: ignore
-                if recapture_spec == "inside-out"
+                if recapture_form == "inside-out"
                 else 0
             )
             _bdry_area = float(
                 2
                 * (
                     _s_naught
-                    + mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (_s_naught, _s_mid))
+                    + mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (_s_naught, _s_mid))  # pyright: ignore
                 )
                 - (_s_mid**2 + _s_naught**2)
             )
@@ -139,13 +173,13 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - (_s_1 + _s_2) * _d_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[1]  # type: ignore
+            _bdry_func = solve(_bdry_eqn, _s_2)[1]
             _bdry_area = float(
                 2
                 * (
@@ -155,7 +189,7 @@ def shrratio_boundary_qdtr_wtd_avg(
                         ),
                         (0, _s_mid),
                     )
-                ).real
+                ).real  # pyright: ignore
                 - _s_mid**2
             )
 
@@ -167,15 +201,15 @@ def shrratio_boundary_qdtr_wtd_avg(
                 * _s_1
                 / (
                     (1 - (_r_val * _s_2 + (1 - _r_val) * _s_1))
-                    if recapture_spec == "inside-out"
+                    if recapture_form == "inside-out"
                     else (1 - _s_2)
                 )
                 - _delta_star
             )
 
-            _bdry_func = solve(_bdry_eqn, _s_2)[0]  # type: ignore
+            _bdry_func = solve(_bdry_eqn, _s_2)[0]
             _bdry_area = float(
-                2 * (mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (0, _s_mid)))
+                2 * (mp.quad(lambdify(_s_1, _bdry_func, "mpmath"), (0, _s_mid)))  # pyright: ignore
                 - _s_mid**2
             )
 
@@ -186,20 +220,20 @@ def shrratio_boundary_qdtr_wtd_avg(
 
 def shrratio_boundary_distance(
     _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+    _r_val: float = DEFAULT_REC_RATIO,
     /,
     *,
-    agg_method: Literal["arithmetic", "distance"] = "arithmetic",
+    agg_method: Literal["arithmetic mean", "distance"] = "arithmetic mean",
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
-    recapture_spec: Literal["inside-out", "proportional"] = "inside-out",
-    prec: int = 5,
-) -> GuidelinesBoundary:
+    recapture_form: Literal["inside-out", "proportional"] = "inside-out",
+    dps: int = 5,
+) -> gbfn.GuidelinesBoundary:
     """
     Share combinations for the GUPPI boundaries using various aggregators with
     symmetric merging-firm margins.
 
     Reimplements the arithmetic-averages and distance estimations from function,
-    `shrratio_boundary_wtd_avg`but uses the Minkowski-distance function,
+    `shrratio_boundary_wtd_avg` but uses the Minkowski-distance function,
     `scipy.spatial.distance.minkowski` for all aggregators. This reimplementation
     is useful for testing the output of `shrratio_boundary_wtd_avg`
     but runs considerably slower.
@@ -211,13 +245,13 @@ def shrratio_boundary_distance(
     _r_val
         recapture ratio
     agg_method
-        Whether "arithmetic", "geometric", or "distance".
+        Whether "arithmetic mean" or "distance".
     weighting
         Whether "own-share" or "cross-product-share".
-    recapture_spec
+    recapture_form
         Whether recapture-ratio is MNL-consistent ("inside-out") or has fixed
         value for both merging firms ("proportional").
-    prec
+    dps
         Number of decimal places for rounding returned shares and area.
 
     Returns
@@ -232,11 +266,11 @@ def shrratio_boundary_distance(
     # initial conditions
     _gbdry_points = [(_s_mid, _s_mid)]
     _s_1_pre, _s_2_pre = _s_mid, _s_mid
-    _s_2_oddval, _s_2_oddsum, _s_2_evnsum = True, 0, 0
+    _s_2_oddval, _s_2_oddsum, _s_2_evnsum = True, 0.0, 0.0
 
     # parameters for iteration
     _weights_base = (mpf("0.5"),) * 2
-    _gbd_step_sz = mp.power(10, -prec)
+    _gbd_step_sz = mp.power(10, -dps)
     _theta = _gbd_step_sz * (10 if weighting == "cross-product-share" else 1)
     for _s_1 in mp.arange(_s_mid - _gbd_step_sz, 0, -_gbd_step_sz):
         # The wtd. avg. GUPPI is not always convex to the origin, so we
@@ -251,8 +285,8 @@ def shrratio_boundary_distance(
         while True:
             _de_1 = _s_2 / (1 - _s_1)
             _de_2 = (
-                _s_1 / (1 - lerp(_s_1, _s_2, _r_val))
-                if recapture_spec == "inside-out"
+                _s_1 / (1 - gbfn.lerp(_s_1, _s_2, _r_val))
+                if recapture_form == "inside-out"
                 else _s_1 / (1 - _s_2)
             )
 
@@ -269,7 +303,7 @@ def shrratio_boundary_distance(
             )
 
             match agg_method:
-                case "arithmetic":
+                case "arithmetic mean":
                     _delta_test = distance_function(
                         (_de_1, _de_2), (0.0, 0.0), p=1, w=_weights_i
                     )
@@ -306,11 +340,11 @@ def shrratio_boundary_distance(
     else:
         _s_2_oddsum -= _s_1_pre
 
-    _s_intcpt = _shrratio_boundary_intcpt(
+    _s_intcpt = gbfn._shrratio_boundary_intcpt(
         _s_1_pre,
         _delta_star,
         _r_val,
-        recapture_spec=recapture_spec,
+        recapture_form=recapture_form,
         agg_method=agg_method,
         weighting=weighting,
     )
@@ -331,11 +365,9 @@ def shrratio_boundary_distance(
         # Area under boundary
         _gbdry_area_total = 2 * _gbd_prtlarea - mp.power(_s_mid, "2")
 
-    _gbdry_points = np.row_stack((_gbdry_points, (mpf("0.0"), _s_intcpt))).astype(
-        np.float64
-    )
+    _gbdry_points.append((mpf("0.0"), _s_intcpt))
     # Points defining boundary to point-of-symmetry
-    return GuidelinesBoundary(
-        np.row_stack((np.flip(_gbdry_points, 0), np.flip(_gbdry_points[1:], 1))),
-        round(float(_gbdry_area_total), prec),
+    return gbfn.GuidelinesBoundary(
+        np.vstack((_gbdry_points[::-1], np.flip(_gbdry_points[1:], 1))),
+        round(float(_gbdry_area_total), dps),
     )

mergeron/core/pseudorandom_numbers.py

@@ -8,24 +8,18 @@ https://github.com/numpy/numpy/issues/16313.
 
 import concurrent.futures
 from collections.abc import Sequence
-from importlib.metadata import version
 from multiprocessing import cpu_count
-from typing import Literal, TypeVar
+from typing import Literal
 
 import numpy as np
 from numpy.random import PCG64DXSM, Generator, SeedSequence
-from numpy.typing import NBitBase, NDArray
 
-from .. import _PKG_NAME  # noqa: TID252
+from .. import VERSION, ArrayDouble  # noqa: TID252
 
-__version__ = version(_PKG_NAME)
-
-
-TF = TypeVar("TF", bound=NBitBase)
-TI = TypeVar("TI", bound=NBitBase)
+__version__ = VERSION
 
 NTHREADS = 2 * cpu_count()
-DIST_PARMS_DEFAULT = np.array([0.0, 1.0], np.float64)
+DEFAULT_DIST_PARMS = np.array([0.0, 1.0], np.float64)
 
 
 def prng(_s: SeedSequence | None = None, /) -> np.random.Generator:
@@ -123,7 +117,7 @@ class MultithreadedRNG:
 
     Parameters
     ----------
-    _out_array
+    __out_array
         The output array to which generated data are written.
         Its dimensions define the size of the sample.
     dist_type
@@ -139,24 +133,24 @@ class MultithreadedRNG:
 
     def __init__(
         self,
-        _out_array: NDArray[np.float64],
+        __out_array: ArrayDouble,
         /,
         *,
         dist_type: Literal[
             "Beta", "Dirichlet", "Gaussian", "Normal", "Random", "Uniform"
         ] = "Uniform",
-        dist_parms: NDArray[np.floating[TF]] | None = DIST_PARMS_DEFAULT,  # type: ignore
+        dist_parms: ArrayDouble | None = DEFAULT_DIST_PARMS,
         seed_sequence: SeedSequence | None = None,
         nthreads: int = NTHREADS,
     ):
         self.thread_count = nthreads
 
-        _seed_sequence = seed_sequence or SeedSequence(pool_size=8)
+        __seed_sequence = seed_sequence or SeedSequence(pool_size=8)
         self._random_generators = [
-            prng(_t) for _t in _seed_sequence.spawn(self.thread_count)
+            prng(_t) for _t in __seed_sequence.spawn(self.thread_count)
         ]
 
-        self.sample_sz = len(_out_array)
+        self.sample_sz = len(__out_array)
 
         if dist_type not in (_rdts := ("Beta", "Dirichlet", "Normal", "Uniform")):
             raise ValueError("Specified distribution must be one of {_rdts}")
@@ -172,7 +166,7 @@ class MultithreadedRNG:
 
         self.dist_type = dist_type
 
-        if dist_parms is None or np.array_equal(dist_parms, DIST_PARMS_DEFAULT):
+        if dist_parms is None or np.array_equal(dist_parms, DEFAULT_DIST_PARMS):
             match dist_type:
                 case "Uniform":
                     self.dist_type = "Random"
@@ -189,10 +183,10 @@ class MultithreadedRNG:
                     )
 
         elif dist_type == "Dirichlet":
-            if len(dist_parms) != _out_array.shape[1]:
+            if len(dist_parms) != __out_array.shape[1]:
                 raise ValueError(
                     f"Insufficient shape parameters for requested Dirichlet sample "
-                    f"of size, {_out_array.shape}"
+                    f"of size, {__out_array.shape}"
                 )
 
         elif (_lrdp := len(dist_parms)) != 2:
@@ -200,7 +194,7 @@ class MultithreadedRNG:
 
         self.dist_parms = dist_parms
 
-        self.values = _out_array
+        self.values = __out_array
         self.executor = concurrent.futures.ThreadPoolExecutor(self.thread_count)
 
         self.step_size = (len(self.values) / self.thread_count).__ceil__()
@@ -211,8 +205,8 @@ class MultithreadedRNG:
         def _fill(
             _rng: np.random.Generator,
             _dist_type: str,
-            _dist_parms: NDArray[np.floating[TF]],
-            _out: NDArray[np.float64],
+            _dist_parms: ArrayDouble,
+            _out: ArrayDouble,
             _first: int,
             _last: int,
             /,

mergeron/data/__init__.py

@@ -0,0 +1,3 @@
+from .. import VERSION  # noqa: TID252
+
+__version__ = VERSION

mergeron/demo/__init__.py

@@ -0,0 +1,3 @@
+from .. import VERSION  # noqa: TID252
+
+__version__ = VERSION

mergeron/demo/visualize_empirical_margin_distribution.py

@@ -0,0 +1,86 @@
+"""
+Plot the empirical distribution derived using the Gaussian KDE with
+margin data downloaded from Prof. Damodaran's website at NYU.
+
+"""
+
+import warnings
+from pathlib import Path
+
+import numpy as np
+from matplotlib.ticker import StrMethodFormatter
+from numpy.random import PCG64DXSM, Generator, SeedSequence
+from scipy import stats  # type: ignore
+
+import mergeron.core.empirical_margin_distribution as dmgn
+from mergeron import DATA_DIR
+from mergeron.core.guidelines_boundary_functions import boundary_plot
+
+SAMPLE_SIZE = 10**6
+BIN_COUNT = 25
+mgn_data_obs, mgn_data_wts, mgn_data_stats = dmgn.mgn_data_builder()
+print(repr(mgn_data_obs))
+print(repr(mgn_data_stats))
+
+plt, mgn_fig, mgn_ax, set_axis_def = boundary_plot(mktshares_plot_flag=False)
+mgn_fig.set_figheight(6.5)
+mgn_fig.set_figwidth(9.0)
+
+_, mgn_bins, _ = mgn_ax.hist(
+    x=mgn_data_obs,
+    weights=mgn_data_wts,
+    bins=BIN_COUNT,
+    alpha=0.4,
+    density=True,
+    label="Downloaded data",
+    color="#004488",  # Paul Tol's High Contrast Blue
+)
+
+with warnings.catch_warnings():
+    warnings.filterwarnings("ignore", category=UserWarning)
+    # Don't warn regarding the below; ticklabels have been fixed before this point
+    mgn_ax.set_yticklabels([
+        f"{float(_g.get_text()) * np.diff(mgn_bins)[-1]:.0%}"
+        for _g in mgn_ax.get_yticklabels()
+    ])
+
+mgn_kde = stats.gaussian_kde(mgn_data_obs, weights=mgn_data_wts, bw_method="silverman")
+mgn_kde.set_bandwidth(bw_method=mgn_kde.factor / 3.0)  # pyright: ignore
+
+mgn_ax.plot(
+    (_xv := np.linspace(0, BIN_COUNT, 10**5) / BIN_COUNT),
+    mgn_kde(_xv),
+    color="#004488",
+    rasterized=True,
+    label="Estimated Density",
+)
+
+mgn_ax.hist(
+    x=mgn_kde.resample(
+        SAMPLE_SIZE, seed=Generator(PCG64DXSM(SeedSequence(pool_size=8)))
+    )[0],
+    color="#DDAA33",  # Paul Tol's High Contrast Yellow
+    alpha=0.6,
+    bins=BIN_COUNT,
+    density=True,
+    label="Generated data",
+)
+
+mgn_ax.legend(
+    loc="best",
+    fancybox=False,
+    shadow=False,
+    frameon=True,
+    facecolor="white",
+    edgecolor="white",
+    framealpha=1,
+    fontsize="small",
+)
+
+mgn_ax.set_xlim(0.0, 1.0)
+mgn_ax.xaxis.set_major_formatter(StrMethodFormatter("{x:>3.0%}"))
+mgn_ax.set_xlabel("Price Cost Margin", fontsize=10)
+mgn_ax.set_ylabel("Relative Frequency", fontsize=10)
+
+mgn_fig.tight_layout()
+plt.savefig(DATA_DIR / f"{Path(__file__).stem}.pdf")