mergeron 2024.739097.4__py3-none-any.whl → 2024.739099.1__py3-none-any.whl

mergeron/gen/enforcement_stats.py

@@ -15,12 +15,19 @@ from typing import Literal
 import numpy as np
 import re2 as re  # type: ignore
 from jinja2 import Environment, FileSystemLoader, Template, select_autoescape
-from numpy.typing import NDArray
 from scipy.interpolate import interp1d  # type: ignore
-
-from .. import _PKG_NAME, DATA_DIR, VERSION  # noqa: TID252
+from scipy.stats import beta, norm  # type: ignore
+
+from .. import (  # noqa: TID252
+    _PKG_NAME,
+    DATA_DIR,
+    TI,
+    VERSION,
+    ArrayBIGINT,
+    ArrayDouble,
+    ArrayINT,
+)
 from ..core import ftc_merger_investigations_data as fid  # noqa: TID252
-from ..core.proportions_tests import propn_ci  # noqa: TID252
 from . import INVResolution
 
 __version__ = VERSION
@@ -293,7 +300,7 @@ def enf_stats_listing_by_group(
     _stats_group: StatsGrpSelector,
     _enf_spec: INVResolution,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _stats_group == StatsGrpSelector.HD:
         raise ValueError(
             f"Clearance/enforcement statistics, '{_stats_group}' not valied here."
@@ -328,7 +335,7 @@ def enf_cnts_listing_byfirmcount(
     _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -364,7 +371,7 @@ def enf_cnts_listing_byhhianddelta(
     _table_evid_cond: EVIDENConstants = EVIDENConstants.UR,
     _enf_spec: INVResolution = INVResolution.CLRN,
     /,
-) -> NDArray[np.int64]:
+) -> ArrayBIGINT:
     if _data_period not in _data_array_dict:
         raise ValueError(
             f"Invalid value of data period, {f'"{_data_period}"'}."
@@ -419,7 +426,7 @@ def table_no_lku(
     return _tno
 
 
-def enf_cnts_byfirmcount(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_byfirmcount(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     _ndim_in = 1
     return np.vstack([
         np.concatenate([
@@ -430,7 +437,7 @@ def enf_cnts_byfirmcount(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]
     ])
 
 
-def enf_cnts_bydelta(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_bydelta(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     _ndim_in = 2
     return np.vstack([
         np.concatenate([
@@ -441,7 +448,7 @@ def enf_cnts_bydelta(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
     ])
 
 
-def enf_cnts_byconczone(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
+def enf_cnts_byconczone(_cnts_array: ArrayBIGINT, /) -> ArrayBIGINT:
     # Prepare to tag clearance stats by presumption zone
     _hhi_zone_post_ranged = hhi_zone_post_ranger(_cnts_array[:, 0] / 1e4)
     _hhi_delta_ranged = hhi_delta_ranger(_cnts_array[:, 1] / 1e4)
@@ -513,7 +520,7 @@ def enf_cnts_byconczone(_cnts_array: NDArray[np.int64], /) -> NDArray[np.int64]:
 
 
 def enf_stats_table_onedim(
-    _inparr: NDArray[np.float64 | np.int64],
+    _inparr: ArrayDouble | ArrayBIGINT | ArrayDouble | ArrayBIGINT,
     _totals_row: int | None = None,
     /,
     *,
@@ -568,7 +575,7 @@ def enf_stats_table_onedim(
 
 
 def enf_stats_table_byzone(
-    _inparr: NDArray[np.float64 | np.int64],
+    _inparr: ArrayDouble | ArrayBIGINT | ArrayDouble | ArrayBIGINT,
     _totals_row: int | None = None,
     /,
     *,
@@ -650,8 +657,8 @@ def enf_stats_table_byzone(
 
 
 def _stats_formatted_row(
-    _stats_row_cnt: NDArray[np.int64],
-    _stats_row_tot: NDArray[np.int64],
+    _stats_row_cnt: ArrayBIGINT,
+    _stats_row_tot: ArrayBIGINT,
     _return_type_sel: StatsReturnSelector,
     /,
 ) -> list[list[str]]:
@@ -660,7 +667,7 @@ def _stats_formatted_row(
     match _return_type_sel:
         case StatsReturnSelector.RIN:
             _stats_row_ci = np.array([
-                propn_ci(*g, method="Wilson")
+                _propn_ci(*g, method="Wilson")
                 for g in zip(_stats_row_cnt[1:], _stats_row_tot[1:], strict=True)
             ])
             return [
@@ -715,6 +722,109 @@ def stats_print_rows(
     print()
 
 
+def _propn_ci(
+    _npos: ArrayINT[TI] | int = 4,
+    _nobs: ArrayINT[TI] | int = 10,
+    /,
+    *,
+    alpha: float = 0.05,
+    method: Literal[
+        "Agresti-Coull", "Clopper-Pearson", "Exact", "Wilson", "Score"
+    ] = "Wilson",
+) -> tuple[
+    ArrayDouble | float, ArrayDouble | float, ArrayDouble | float, ArrayDouble | float
+]:
+    """Returns point estimates and confidence interval for a proportion
+
+    Methods "Clopper-Pearson" and "Exact" are synoymous [3]_.  Similarly,
+    "Wilson" and "Score" are synonyms here.
+
+    Parameters
+    ----------
+    _npos
+        Number of positives
+
+    _nobs
+        Number of observed values
+
+    alpha
+        Significance level
+
+    method
+        Method to use for estimating confidence interval
+
+    Returns
+    -------
+        Raw and estimated proportions, and bounds of the confidence interval
+
+
+    References
+    ----------
+
+    .. [3] Alan Agresti & Brent A. Coull (1998) Approximate is Better
+       than “Exact” for Interval Estimation of Binomial Proportions,
+       The American Statistician, 52:2, 119-126,
+       https://doi.org/10.1080/00031305.1998.10480550
+
+    """
+
+    for _f in _npos, _nobs:
+        if not isinstance(_f, int | np.integer):
+            raise ValueError(
+                f"Count, {_f!r} must have type that is a subtype of np.integer."
+            )
+
+    if not _nobs:
+        return (np.nan, np.nan, np.nan, np.nan)
+
+    _raw_phat: ArrayDouble | float = _npos / _nobs
+    _est_phat: ArrayDouble | float
+    _est_ci_l: ArrayDouble | float
+    _est_ci_u: ArrayDouble | float
+
+    match method:
+        case "Clopper-Pearson" | "Exact":
+            _est_ci_l, _est_ci_u = (
+                beta.ppf(*_f)
+                for _f in (
+                    (alpha / 2, _npos, _nobs - _npos + 1),
+                    (1 - alpha / 2, _npos + 1, _nobs - _npos),
+                )
+            )
+            _est_phat = 1 / 2 * (_est_ci_l + _est_ci_u)
+
+        case "Agresti-Coull":
+            _zsc = norm.ppf(1 - alpha / 2)
+            _zscsq = _zsc * _zsc
+            _adjmt = 4 if alpha == 0.05 else _zscsq
+            _est_phat = (_npos + _adjmt / 2) / (_nobs + _adjmt)
+            _est_ci_l, _est_ci_u = (
+                _est_phat + _g
+                for _g in [
+                    _f * _zsc * np.sqrt(_est_phat * (1 - _est_phat) / (_nobs + _adjmt))
+                    for _f in (-1, 1)
+                ]
+            )
+
+        case "Wilson" | "Score":
+            _zsc = norm.ppf(1 - alpha / 2)
+            _zscsq = _zsc * _zsc
+            _est_phat = (_npos + _zscsq / 2) / (_nobs + _zscsq)
+            _est_ci_l, _est_ci_u = (
+                _est_phat
+                + _f
+                * _zsc
+                * np.sqrt(_nobs * _raw_phat * (1 - _raw_phat) + _zscsq / 4)
+                / (_nobs + _zscsq)
+                for _f in (-1, 1)
+            )
+
+        case _:
+            raise ValueError(f"Method, {f'"{method}"'} not yet implemented.")
+
+    return _raw_phat, _est_phat, _est_ci_l, _est_ci_u
+
+
 def render_table_pdf(
     _table_dottex_pathlist: Sequence[str], _table_coll_path: str, /
 ) -> None:

mergeron/gen/upp_tests.py

@@ -13,9 +13,19 @@ import numpy as np
 import tables as ptb  # type: ignore
 from joblib import Parallel, cpu_count, delayed  # type: ignore
 from numpy.random import SeedSequence
-from numpy.typing import NDArray
 
-from .. import VERSION, RECConstants, UPPAggrSelector  # noqa: TID252
+from .. import (  # noqa: TID252
+    TF,
+    TI,
+    VERSION,
+    ArrayBIGINT,
+    ArrayBoolean,
+    ArrayDouble,
+    ArrayFloat,
+    ArrayINT,
+    RECConstants,
+    UPPAggrSelector,
+)
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from . import (
     EMPTY_ARRAY_DEFAULT,
@@ -496,7 +506,11 @@ def save_data_to_hdf5(
 
 
 def save_array_to_hdf5(
-    _array_obj: NDArray[np.float64 | np.int64 | np.bool_],
+    _array_obj: ArrayFloat[TF]
+    | ArrayINT[TI]
+    | ArrayDouble
+    | ArrayBIGINT
+    | ArrayBoolean,
     _array_name: str,
     _h5_group: ptb.Group,
     _h5_file: ptb.File,

{mergeron-2024.739097.4.dist-info → mergeron-2024.739099.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.739097.4
+Version: 2024.739099.1
 Summary: Merger Policy Analysis using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
@@ -83,29 +83,6 @@ Documentation for this package is in the form of the API Reference. Documentatio
 
     help(market_sample.MarketSample)
 
-"Extras" Subpackage
----------------------
-
-The "Extras" sub-package includes a small number of modules potentially useful to users, but which do not implement the principal functions of the package, and are hence considered "extras"  or "external" modules. One of these modules is, in fact, repackaged here although published independently.
-
-On of the external modules provides methods for estimating confidence intervals for proportions and for contrasts (differences) in proportions. This module  improve is coded for conformance to the literature and to results from the corresponding modules in :code:`R`. Although written from scratch, the APIs implemented in the module included here are designed for consistency with the APIs in, :code:`statsmodels.stats.proportion` from the package, :code:`statsmodels` (https://pypi.org/project/statsmodels/). To access these directly:
-
-.. code-block:: python
-
-    import mergeron.ext.proportions_tests as prci
-
-Module :code:`mergeron.ext.xlsxw_helper` is useful for writing highly formatted output to spreadsheets with xlsx format. The class, :code:`mergeron.ext.xlsxw_helper.CFmt` and function, :code:`mergeron.ext.xlsxw_helper.array_to_sheet` are of particular interest, and can be accessed as :code:`xlh.CFmt` and :code:`xlh.array_to_sheet` with the following import:
-
-.. code-block:: python
-
-    import mergeron.ext.xlsxw_helper as xlsxw_helper
-
-A recent version of Paul Tol's python module, :code:`tol_colors.py`, which provides high-contrast color schemes for making displays with improved visibility for individuals with color-blindness, is redistributed within this package. Other than re-formatting and type annotation, the :code:`mergeron.ext.tol_colors` module is re-distributed as downloaded from, https://personal.sron.nl/~pault/data/tol_colors.py. The :code:`tol_colors.py` module is distributed under the Standard 3-clause BSD license. To access the :code:`mergeron.ext.tol_colors` module directly:
-
-.. code-block:: python
-
-    import mergeron.ext.tol_colors as ptc
-
 .. image:: https://img.shields.io/endpoint?url=https://python-poetry.org/badge/v0.json
    :alt: Poetry
    :target: https://python-poetry.org/

{mergeron-2024.739097.4.dist-info → mergeron-2024.739099.1.dist-info}/RECORD

@@ -1,12 +1,12 @@
 mergeron/License.txt,sha256=7iX-y0EyjkbVJKJLS4ZKzuuE1wd0lryfsD_IytLG8lQ,1246
-mergeron/__init__.py,sha256=p_4HhYPKBwm93IWuOVlQ_eINlxG6ozyvujs8iaDEYFM,1180
+mergeron/__init__.py,sha256=u08ycqko_RgETIhaYivtm7Tglj2dZFk83KUJIbPRuL4,1541
 mergeron/core/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
-mergeron/core/damodaran_margin_data.py,sha256=PRbdNHqDRN4tG3MI9ZTsilx8SkJ5mZYQc7SgRxcT3YI,8606
-mergeron/core/ftc_merger_investigations_data.py,sha256=Akwc0spRhydXd17j2t37V6EijlJMBk54pcYCNDaykns,28205
-mergeron/core/guidelines_boundaries.py,sha256=__OHme8aGtwOgRXKp56WdX7k4vssAVQ8Ub54XwpS7mg,15621
-mergeron/core/guidelines_boundary_functions.py,sha256=l5fNs65ciEVH-K-QfR8clsfY89xqdf79UIyyZWlSGxU,29718
-mergeron/core/guidelines_boundary_functions_extra.py,sha256=LHeYOHAkhVuwmzOFzP1KqyXNE58BIWqW4pzRkceJx_Q,11316
-mergeron/core/pseudorandom_numbers.py,sha256=k3sDs_NJ2jXlkIWKQ6iiTB5n_QS0RoJ-sqzvFYkC7pY,9277
+mergeron/core/damodaran_margin_data.py,sha256=rMrgN1Qtw572a0ftY97OOj4otq8ldlLrcOi-bcE-org,8554
+mergeron/core/ftc_merger_investigations_data.py,sha256=oL_4yrNPpjuNIluBsDc51lYd2Z4NBBrd7-sHKd3FCbg,28129
+mergeron/core/guidelines_boundaries.py,sha256=Lv-7EE7b2SiudpRjW3gFY1uHu-K0UdesewwiqaqjcOw,15585
+mergeron/core/guidelines_boundary_functions.py,sha256=HbuVOpQWlbIhvlWYvL2PXovase5az8DFU82woVl1VLo,29685
+mergeron/core/guidelines_boundary_functions_extra.py,sha256=t84dMsaMKnYUNuvvGrMCP6vI8MDn88PJOgGZlNe1Zts,11280
+mergeron/core/pseudorandom_numbers.py,sha256=cJEWDTfy9CUTzR_di6Fm1Vl1Le6xWoU8wFHbYVMEuLI,9225
 mergeron/data/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/data/damodaran_margin_data.xls,sha256=Qggl1p5nkOMJI8YUXhkwXQRz-OhRSqBTzz57N0JQyYA,79360
 mergeron/data/damodaran_margin_data_dict.msgpack,sha256=sr6s4L69kposEpzGI7jpPb4ULz0UpY-bEYfeNi6UlRA,57621
@@ -20,17 +20,13 @@ mergeron/data/jinja2_LaTeX_templates/mergeron_table_collection_template.tex.jinj
 mergeron/data/jinja2_LaTeX_templates/setup_tikz_tables.tex,sha256=1hw3RINDtBrh9ZEToMIiNFIu9rozcPwRly69-5O_0UQ,3207
 mergeron/demo/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
 mergeron/demo/visualize_empirical_margin_distribution.py,sha256=v1xFJumBX2Ooye82kSSgly-_GpFVkYSDqBwM__rcmZY,2363
-mergeron/ext/__init__.py,sha256=KtjBlZOl7jwBCAUhrTJB9PdrN39YLYytNiSUSM_gRmA,62
-mergeron/ext/proportions_tests.py,sha256=akq0Xhdgtst4RAT42_E5cBD_kATq_V4bQeBznmzRSLg,15267
-mergeron/ext/tol_colors.py,sha256=QBw8s-ZGpUpIIYOplHbLFZSXVoa6eDDJDtzSScP954E,22303
-mergeron/ext/xlsxw_helper.py,sha256=GqetJK5tLfg8JmXKrWIOHaCDHt_mspcopiAK3xxtqhM,18018
-mergeron/gen/__init__.py,sha256=Ky1p93L-epw42g8HDIcfiENGT1iiXdolnsv12ZUWGM4,17169
-mergeron/gen/_data_generation_functions.py,sha256=boNQkDtarx_BqYHWjlsIXSQHqOBvgBcI_R53UfT66qg,27763
-mergeron/gen/data_generation.py,sha256=n_rdi6Zk5-2Q0K_xXdWI14sj9XZyrF57hnyqvBf5v6Y,8531
-mergeron/gen/enforcement_stats.py,sha256=Hr-w3LZ9SJD4A1RZS1KMhXwuKyGzPC7eeNQullWZRNU,24410
+mergeron/gen/__init__.py,sha256=Tm_eDiZkOwoOrfKyRu_3jkmNpFqyBMxfMY-Lu9BYAnc,17050
+mergeron/gen/_data_generation_functions.py,sha256=I4J8cDTMR27683Kr18ST1nzdA8kCZVKz7cyk8y3rfMo,27582
+mergeron/gen/data_generation.py,sha256=dj9otFi1OE3Eo7f32BD0ZXm9Xvlg0fCp4DDQ_XhDN_w,8479
+mergeron/gen/enforcement_stats.py,sha256=6IekvV8qvGFid6xbvqOazKYytMZQEwLyApt5TzTFPWU,27421
 mergeron/gen/market_sample.py,sha256=HkzRFTKBXYIs2HbAyVDUiUHo9nCtAciSn5sohR-34cM,4282
-mergeron/gen/upp_tests.py,sha256=N-spIAYKPGJngtlckSjhQGcFBZv_sVZDvCHYzy0TxSc,17132
+mergeron/gen/upp_tests.py,sha256=xYhzWBgJJxYtz6VlGrrtx_cwwSZD3FdTDLD5zB1RDng,17261
 mergeron/py.typed,sha256=frcCV1k9oG9oKj3dpUqdJg1PxRT2RSN_XKdLCPjaYaY,2
-mergeron-2024.739097.4.dist-info/METADATA,sha256=GMyImdNjjsqCS54AHzAvUzVBozx2HhGUyqoIZ2MVZkY,12948
-mergeron-2024.739097.4.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
-mergeron-2024.739097.4.dist-info/RECORD,,
+mergeron-2024.739099.1.dist-info/METADATA,sha256=9AN4mWKYnvtQInNpO-ytzRthOUI3nB63FcnVVBNjD_s,10922
+mergeron-2024.739099.1.dist-info/WHEEL,sha256=sP946D7jFCHeNz5Iq4fL4Lu-PrWrFsgfLXbbkciIZwg,88
+mergeron-2024.739099.1.dist-info/RECORD,,

mergeron/ext/__init__.py

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