mergeron 2024.738972.0__py3-none-any.whl → 2024.739079.9__py3-none-any.whl

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

@@ -1,26 +1,30 @@
 """
 Specialized methods for defining and analyzing boundaries for Guidelines standards.
 
-These methods 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 collections.abc import Callable
 from dataclasses import dataclass
-from importlib.metadata import version
 from typing import Literal
 
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
 from numpy.typing import NDArray
 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, _shrratio_boundary_intcpt, lerp
+from .. import VERSION  # noqa: TID252
+from .guidelines_boundary_functions import (
+    GuidelinesBoundary,
+    _shrratio_boundary_intcpt,
+    lerp,
+)
 
-__version__ = version(_PKG_NAME)
+__version__ = VERSION
 
 
 mp.prec = 80
@@ -34,7 +38,39 @@ class GuidelinesBoundaryCallable:
     s_naught: float = 0
 
 
-def delta_hhi_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
+def dh_area_quad(_dh_val: float = 0.01, /, *, prec: 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.
+    prec
+        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])
+        ),
+        prec,
+    )
+
+
+def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCallable:
     """
     Generate the list of share combination on the ΔHHI boundary.
 
@@ -70,7 +106,7 @@ def delta_hhi_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCalla
 
 def shrratio_boundary_qdtr_wtd_avg(
     _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+    _r_val: float = 0.85,
     /,
     *,
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
@@ -189,10 +225,10 @@ def shrratio_boundary_qdtr_wtd_avg(
 
 def shrratio_boundary_distance(
     _delta_star: float = 0.075,
-    _r_val: float = 0.80,
+    _r_val: float = 0.85,
     /,
     *,
-    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_form: Literal["inside-out", "proportional"] = "inside-out",
     prec: int = 5,
@@ -202,7 +238,7 @@ def shrratio_boundary_distance(
     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.
@@ -214,7 +250,7 @@ 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_form
@@ -272,7 +308,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
                     )
@@ -334,11 +370,12 @@ 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(
+    _gbdry_points = np.vstack((_gbdry_points, (mpf("0.0"), _s_intcpt))).astype(
         np.float64
     )
     # Points defining boundary to point-of-symmetry
     return GuidelinesBoundary(
-        np.row_stack((np.flip(_gbdry_points, 0), np.flip(_gbdry_points[1:], 1))),
+        np.vstack((np.flip(_gbdry_points, 0), np.flip(_gbdry_points[1:], 1))),
         round(float(_gbdry_area_total), prec),
     )
+

mergeron/core/proportions_tests.py

@@ -9,7 +9,6 @@ from __future__ import annotations
 
 from collections.abc import Sequence
 from dataclasses import dataclass
-from importlib.metadata import version
 from typing import Literal, TypeVar
 
 import numpy as np
@@ -17,10 +16,9 @@ from numpy.typing import NBitBase, NDArray
 from scipy.optimize import OptimizeResult, root  # type: ignore
 from scipy.stats import beta, chi2, norm  # type: ignore
 
-from .. import _PKG_NAME  # noqa: TID252
-
-__version__ = version(_PKG_NAME)
+from .. import VERSION  # noqa: TID252
 
+__version__ = VERSION
 
 TI = TypeVar("TI", bound=NBitBase)
 

mergeron/core/pseudorandom_numbers.py

@@ -8,21 +8,16 @@ 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 numpy.typing import NDArray
 
-from .. import _PKG_NAME  # noqa: TID252
+from .. import VERSION  # 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)
@@ -145,7 +140,7 @@ class MultithreadedRNG:
         dist_type: Literal[
             "Beta", "Dirichlet", "Gaussian", "Normal", "Random", "Uniform"
         ] = "Uniform",
-        dist_parms: NDArray[np.floating[TF]] | None = DIST_PARMS_DEFAULT,  # type: ignore
+        dist_parms: NDArray[np.float64] | None = DIST_PARMS_DEFAULT,
         seed_sequence: SeedSequence | None = None,
         nthreads: int = NTHREADS,
     ):
@@ -211,7 +206,7 @@ class MultithreadedRNG:
         def _fill(
             _rng: np.random.Generator,
             _dist_type: str,
-            _dist_parms: NDArray[np.floating[TF]],
+            _dist_parms: NDArray[np.float64],
             _out: NDArray[np.float64],
             _first: int,
             _last: int,

mergeron/data/__init__.py

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

mergeron/{jinja_LaTex_templates/setup_tikz_tables.tex.jinja2 → data/jinja2_LaTeX_templates/setup_tikz_tables.tex}

@@ -1,11 +1,7 @@
-((# We force some color defintions here. These could be set in package code. #))
-((* set obs_header_color = "0a6c97" *))
-((* set sim_header_color = "646464" *))
-((* set data_fill_color = "dfeadf" *))
 % Tables in tikz, but first we need to define some colors for nonwhite text backgrounds
-\definecolor{OBSHDRFill}{HTML}{\JINVAR{- obs_header_color -}}
-\definecolor{SIMHDRFill}{HTML}{\JINVAR{- sim_header_color -}}
-\definecolor{DataFill}{HTML}{\JINVAR{- data_fill_color -}}
+\definecolor{OBSHDRFill}{HTML}{0a6c97}
+\definecolor{SIMHDRFill}{HTML}{646464}
+\definecolor{DataFill}{HTML}{dfeadf}
 % The below are definition's from Paul Tol's website, https://personal.sron.nl/~pault/
 \definecolor{VibrBlue}{HTML}{0077bb}
 \definecolor{BrightGreen}{HTML}{228833}
@@ -24,61 +20,60 @@
 \tikzset{
     % If you only have numbers, text depth = 0ex; if text, text depth = 0.25ex, (may need tweaking for alignment across cells)
     anytext/.style = {
-        align = center, 
-        font = \sffamily\scriptsize, 
-        inner sep = 0pt, 
-        text depth = 0pt, 
-        },  % 
+            align = center,
+            font = \sffamily\scriptsize,
+            inner sep = 0pt,
+            text depth = 0pt,
+        },  %
     hdrtext/.style = {
-        anytext,
-        text = white, 
-        fill = OBSHDRFill,
-        }, % 
+            anytext,
+            text = white,
+            fill = OBSHDRFill,
+        }, %
     notetext/.style = {
-        anytext,
-        font = \sffamily\tiny, 
-        align = left,
+            anytext,
+            font = \sffamily\tiny,
+            align = left,
         },
     anytable/.style = {
-        matrix of nodes,
-        nodes in empty cells,
-        column sep = -1.0\pgflinewidth,
-        row sep = -1.0\pgflinewidth,
-        inner sep = -0.25\pgflinewidth, 
-        outer sep = -0.25\pgflinewidth,
-        nodes = {anchor = center, minimum height = 12.5pt,}
+            matrix of nodes,
+            nodes in empty cells,
+            column sep = -1.0\pgflinewidth,
+            row sep = -1.0\pgflinewidth,
+            inner sep = -0.25\pgflinewidth,
+            outer sep = -0.25\pgflinewidth,
+            nodes = {anchor = center, minimum height = 12.5pt,}
         },
     datatable/.style = {
-        anytable,
-        nodes = {
-            font = \sffamily\scriptsize\addfontfeatures{Numbers={Monospaced,Lining}},
-            align = right,
-            inner xsep = 3pt,
-            inner ysep = 0pt,
-            text depth = 0pt,
-            draw = none,
-            fill = none,
-            },
-        every even row/.style = {
-            nodes = {fill = DataFill}
-            },
+            anytable,
+            nodes = {
+                    font = \sffamily\scriptsize\addfontfeatures{Numbers={Monospaced,Lining}},
+                    align = right,
+                    inner xsep = 3pt,
+                    inner ysep = 0pt,
+                    text depth = 0pt,
+                    draw = none,
+                    fill = none,
+                },
+            every even row/.style = {
+                    nodes = {fill = DataFill}
+                },
         },
     hrow/.style = {
-        anytable,
-        nodes = {
-            hdrtext, 
-            draw = none, 
-            fill = OBSHDRFill, 
-            text width = 40pt,
-            },
+            anytable,
+            nodes = {
+                    hdrtext,
+                    draw = none,
+                    fill = OBSHDRFill,
+                    text width = 40pt,
+                },
         },
     hcol/.style = {
-        hrow, 
-        nodes = {text width = 60pt,},
+            hrow,
+            nodes = {text width = 60pt,},
         },
-    }
+}
 % Define layers for later reference
 % https://tex.stackexchange.com/questions/40840/put-a-node-behind-another-in-a-tikz-diagram
 \pgfdeclarelayer{background}
 \pgfsetlayers{background,main}
-    

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,88 @@
+"""
+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.damodaran_margin_data 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)
+
+mgn_xvec = np.linspace(0, BIN_COUNT, 10**5) / BIN_COUNT
+mgn_ax.plot(
+    mgn_xvec,
+    mgn_kde(mgn_xvec),
+    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")

mergeron/ext/__init__.py

@@ -1,5 +1,3 @@
-from importlib.metadata import version
+from .. import VERSION  # noqa: TID252
 
-from .. import _PKG_NAME  # noqa: TID252
-
-__version__ = version(_PKG_NAME)
+__version__ = VERSION

mergeron/ext/tol_colors.py

@@ -796,7 +796,7 @@ def main() -> None:
     schemes: Sequence[str] = tol_cset()
     fig, axes = plt.subplots(ncols=len(schemes), figsize=(9, 3))
     fig.subplots_adjust(top=0.9, bottom=0.02, left=0.02, right=0.92)
-    for ax, scheme in zip(axes, schemes):
+    for ax, scheme in zip(axes, schemes):  # type: ignore
         cset = tol_cset(scheme)
         names = cset._fields  # type: ignore
         colors = list(cset)
@@ -813,7 +813,7 @@ def main() -> None:
     gradient = np.vstack((gradient, gradient))
     fig, axes = plt.subplots(nrows=len(schemes))
     fig.subplots_adjust(top=0.98, bottom=0.02, left=0.2, right=0.99)
-    for ax, scheme in zip(axes, schemes):
+    for ax, scheme in zip(axes, schemes):  # type: ignore
         pos = list(ax.get_position().bounds)
         ax.set_axis_off()
         ax.imshow(gradient, aspect=4, cmap=tol_cmap(scheme))
@@ -832,7 +832,7 @@ def main() -> None:
     gradient = np.vstack((gradient, gradient))
     fig, axes = plt.subplots(nrows=23)
     fig.subplots_adjust(top=0.98, bottom=0.02, left=0.25, right=0.99)
-    for lut, ax in enumerate(axes, start=1):
+    for lut, ax in enumerate(axes, start=1):  # type: ignore
         pos = list(ax.get_position().bounds)
         ax.set_axis_off()
         ax.imshow(gradient, aspect=4, cmap=tol_cmap("rainbow_discrete", lut))