mergeron 2024.739091.2__tar.gz → 2024.739097.2__tar.gz

mergeron-2024.739097.2/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.1
+Name: mergeron
+Version: 2024.739097.2
+Summary: Merger Policy Analysis using Python
+License: MIT
+Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
+Author: Murthy Kambhampaty
+Author-email: smk@capeconomics.com
+Requires-Python: >=3.12,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Dist: aenum (>=3.1.15,<4.0.0)
+Requires-Dist: attrs (>=23.2)
+Requires-Dist: bs4 (>=0.0.1)
+Requires-Dist: certifi (>=2023.11.17)
+Requires-Dist: google-re2 (>=1.1)
+Requires-Dist: jinja2 (>=3.1)
+Requires-Dist: joblib (>=1.3)
+Requires-Dist: lxml (>=5.0)
+Requires-Dist: matplotlib (>=3.8)
+Requires-Dist: mpmath (>=1.3)
+Requires-Dist: msgpack (>=1.0)
+Requires-Dist: msgpack-numpy (>=0.4)
+Requires-Dist: numpy (>=1.26,<2.0)
+Requires-Dist: openpyxl (>=3.1.2)
+Requires-Dist: poetry-plugin-export (>=1.8.0,<2.0.0)
+Requires-Dist: requests (>=2.31)
+Requires-Dist: requests-toolbelt (>=1.0.0)
+Requires-Dist: scipy (>=1.12)
+Requires-Dist: sympy (>=1.12)
+Requires-Dist: tables (>=3.8)
+Requires-Dist: types-beautifulsoup4 (>=4.11.2)
+Requires-Dist: types-requests (>=2.31.0)
+Requires-Dist: xlrd (>=2.0.1,<3.0.0)
+Requires-Dist: xlsxwriter (>=3.1)
+Description-Content-Type: text/x-rst
+
+mergeron: Merger Policy Analysis using Python
+=============================================
+
+Analyze the sets of mergers conforming to concentration and diversion ratio bounds. Analyze intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions impled by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+
+Intrinsic enforcement rates and intrinsice clearance rates are distinguished from *observed* clearance and enforcement rates in that the former are derived from analyzing theorectical predictions regarding firm conduct against enforcement thresholds, treating enforcement policy as exogenous to firm conduct. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement, and, ny definition, the observed clearance rate is 1 minus the observed enforement rate.
+
+Introduction
+------------
+
+Module :code:`mergeron.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`mergeron.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`mergeron.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area. This module also includes a function for generating plots of concentation and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+
+Module :code:`mergeron.gen.market_sample` includes the :code:`mergeron.gen.market_sample.MarketSample` with methods for, (i) generating sample data under a rich specification of shares, diversion ratios, margins, prices, and HSR filing requirements, and (ii) for estimating enforcement or clearance rates under specified enforcement regimes given a method of aggregating diversion ratio or GUPPI estimates for the firms in a merger. Notably. share are genarated not just for markets with a fixed number of firms, but for markets with multiple firm-count weights, which may be left unspecified or explicitly specified.
+
+Unless otherwise specified, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution, with specified shape parameters (see :code:`mergeron.gen.ShareContants`. When drawing shares from the Dirichlet distribution, the user passes, using :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights`, a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights` is not assigned a value when defining :code:`mergeron.gen.MarketSpec.ShareSpec` (which has type, :code:`mergeron.gen.ShareSpec`), the default values is used, with results in a sample of markets with 2 to 6 firms with equal relative frequency.
+
+Recapture rates can be specifed as, "proportional", "inside-out", "outside-in" (see :code:`mergeron.RECConstants`. The "inside-out" specification results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification yields diversion ratios from purchase probabilities drawn at random for :math:`N+1` goods, from which are derived market shares and recapture rates for the :math:`N` goods in the putative market (see, :code:`mergeron.gen.DiversionRatioSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`mergeron.gen.MarketSpec.ShareSpec.dist_type ==`:code:`mergeron.gen.ShareContants.UNI`.
+
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or an empirical distribution. The empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand (see, :code:`mergeron.gen.PCMSpec`).
+
+Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified (see, :code:`mergeron.gen.PriceSpec`).
+
+The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the HSR filing threshold for the smaller (acquired) firm. In the other, the :math:`n`-th firm's size matches the size requirement for the smaller merging firm (see, :code:`mergeron.gen.SSZConstants`). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
+
+The full specification of a market sample is given in a :code:`mergeron.gen.market_sample.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`mergeron.gen.market_sample.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`mergeron.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`mergeron.gen.market_sample.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`mergeron.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`estimate_enf_counts` on a :code:`mergeron.gen.market_sample.MarketSample` object without first invoking :code:`generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the perfomance penalty is slight, but can be considerable if saving to SATA storage).
+
+Enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.enforcement_stats`.
+
+Programs demonstrating the use of this package are included in the sub-package, :code:`mergeron.demo`.
+
+This package includes  a class, :code:`mergeron.core.pseudorandom_numbers.MulithreadedRNG` for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. This class is an adaptation from the documentation of the :code:`numpy` package, from the discussion on `multithreaded random-number generation <https://numpy.org/doc/stable/reference/random/multithreading.html>_`; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
+
+.. code-block:: python
+
+    import mergeron.core.market_sample as market_sample
+
+    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/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+
+

mergeron-2024.739097.2/README.rst

@@ -0,0 +1,83 @@
+mergeron: Merger Policy Analysis using Python
+=============================================
+
+Analyze the sets of mergers conforming to concentration and diversion ratio bounds. Analyze intrinsic enforcement rates, and intrinsic clearance rates, under concentration, diversion ratio, GUPPI, CMCR, and IPR bounds using generated data with specified distributions of market shares, price-cost margins, firm counts, and prices, optionally imposing restrictions impled by statutory filing thresholds and/or Bertrand-Nash oligopoly with MNL demand. Download and analyze merger investigations data published by the U.S. Federal Trade Commission in various reports on extended merger investigations (Second Requests) during 1996 to 2011.
+
+Intrinsic enforcement rates and intrinsice clearance rates are distinguished from *observed* clearance and enforcement rates in that the former are derived from analyzing theorectical predictions regarding firm conduct against enforcement thresholds, treating enforcement policy as exogenous to firm conduct. Depending on the merger enforcement regime, or merger control regime, intrinsic enforcement rates may also not be the complement of intrinsic clearance rates, i.e, it is not necessarily true that the intrinsic clearance rate estimate for a given enforcement regime is 1 minus the intrinsic enforcement rate. In contrast, observed enforcement rates reflect the deterrent effects of merger enforcement on firm conduct as well as the effects of merger screening on the level of enforcement, and, ny definition, the observed clearance rate is 1 minus the observed enforement rate.
+
+Introduction
+------------
+
+Module :code:`mergeron.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`mergeron.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`mergeron.core.guidelines_boundaries.DiversionRatioBoundary`), with automatic generation of boundary (as an array of share-pairs) and area. This module also includes a function for generating plots of concentation and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+
+Module :code:`mergeron.gen.market_sample` includes the :code:`mergeron.gen.market_sample.MarketSample` with methods for, (i) generating sample data under a rich specification of shares, diversion ratios, margins, prices, and HSR filing requirements, and (ii) for estimating enforcement or clearance rates under specified enforcement regimes given a method of aggregating diversion ratio or GUPPI estimates for the firms in a merger. Notably. share are genarated not just for markets with a fixed number of firms, but for markets with multiple firm-count weights, which may be left unspecified or explicitly specified.
+
+Unless otherwise specified, merging-firm shares are drawn with uniform distribution over the space :math:`s_1 + s_2 \leqslant 1` for an unspecified number of firms. Alternatively, shares may be drawn from the Dirichlet distribution, with specified shape parameters (see :code:`mergeron.gen.ShareContants`. When drawing shares from the Dirichlet distribution, the user passes, using :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights`, a vector of weights specifying the frequency distribution over sequential firm counts, e.g., :code:`[133, 184, 134, 52, 32, 10, 12, 4, 3]` to specify shares drawn from Dirichlet distributions with 2 to 10 pre-merger firms distributed as in data for FTC merger investigations during 1996--2003 (See, for example, Table 4.1 of `FTC, Horizontal Merger Investigations Data, Fiscal Years 1996--2003 (Revised: August 31, 2004) <https://www.ftc.gov/sites/default/files/documents/reports/horizontal-merger-investigation-data-fiscal-years-1996-2003/040831horizmergersdata96-03.pdf>`_). If :code:`mergeron.gen.MarketSpec.ShareSpec.firm_count_weights` is not assigned a value when defining :code:`mergeron.gen.MarketSpec.ShareSpec` (which has type, :code:`mergeron.gen.ShareSpec`), the default values is used, with results in a sample of markets with 2 to 6 firms with equal relative frequency.
+
+Recapture rates can be specifed as, "proportional", "inside-out", "outside-in" (see :code:`mergeron.RECConstants`. The "inside-out" specification results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification yields diversion ratios from purchase probabilities drawn at random for :math:`N+1` goods, from which are derived market shares and recapture rates for the :math:`N` goods in the putative market (see, :code:`mergeron.gen.DiversionRatioSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`mergeron.gen.MarketSpec.ShareSpec.dist_type ==`:code:`mergeron.gen.ShareContants.UNI`.
+
+Price-cost-margins may be specified as having uniform distribution, Beta distribution (including a bounded Beta distribution with specified mean and variance), or an empirical distribution. The empirical margin distribution is based on resampling margin data published by Prof. Damodaran of NYU Stern School of Business (see Notes), using an estimated Gaussian KDE. The second merging firm's margin may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-mazimization in) Bertrand-Nash oligopoly with MNL demand (see, :code:`mergeron.gen.PCMSpec`).
+
+Prices may be specified as symmetric or asymmetric, and in the latter case, the direction of correlation between merging firm prices, if any, can also be specified (see, :code:`mergeron.gen.PriceSpec`).
+
+The market sample may be restricted to mergers meeting the HSR filing requirement under two alternative approaches: in the one, the smaller of the two merging firms meets the HSR filing threshold for the smaller (acquired) firm. In the other, the :math:`n`-th firm's size matches the size requirement for the smaller merging firm (see, :code:`mergeron.gen.SSZConstants`). The second assumption avoids the unfortunate assumption in the first that, within the resulting sample, the larger merging firm be at least 10 times as large as the smaller merging firm, as a consequence of the full definition of the HSR filing requirement.
+
+The full specification of a market sample is given in a :code:`mergeron.gen.market_sample.MarketSample` object, including the above parameters. Data are drawn by invoking :code:`mergeron.gen.market_sample.MarketSample.generate_sample` which adds a :code:`data` property of class, :code:`mergeron.gen.MarketDataSample`. Enforcement or clearance counts are computed by invoking :code:`mergeron.gen.market_sample.MarketSample.estimate_enf_counts`, which adds an :code:`enf_counts` property of class :code:`mergeron.gen.UPPTestsCounts`. For fast, parallel generation of enforcement or clearance counts over large market data samples that ordinarily would exceed available limits on machine memory, the user can invoke the method :code:`estimate_enf_counts` on a :code:`mergeron.gen.market_sample.MarketSample` object without first invoking :code:`generate_sample`. Note, however, that this strategy does not retain the market sample in memory in the interests of conserving memory and maintaining high performance (the user can specify that the market sample and enforcement statistics be stored to permanent storage; when saving to current PCIe NVMe storage, the perfomance penalty is slight, but can be considerable if saving to SATA storage).
+
+Enforcement statistics based on FTC investigations data and test data are printed to screen or rendered to LaTex files (for processing into publication-quality tables) using methods provided in :code:`mergeron.gen.enforcement_stats`.
+
+Programs demonstrating the use of this package are included in the sub-package, :code:`mergeron.demo`.
+
+This package includes  a class, :code:`mergeron.core.pseudorandom_numbers.MulithreadedRNG` for generating random numbers with selected continuous distribution over specified parameters, and with CPU multithreading on machines with multiple virtual, logical, or physical CPU cores. This class is an adaptation from the documentation of the :code:`numpy` package, from the discussion on `multithreaded random-number generation <https://numpy.org/doc/stable/reference/random/multithreading.html>_`; the version included here permits selection of the distribution with pre-tests to catch and inform on common errors. To access these directly:
+
+.. code-block:: python
+
+    import mergeron.core.pseudorandom_numbers as prng
+
+Documentation for this package is in the form of the API Reference. Documentation for individual functions and classes is accessible within a python shell. For example:
+
+.. code-block:: python
+
+    import mergeron.core.market_sample as market_sample
+
+    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/
+
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+   :alt: Ruff
+   :target: https://github.com/astral-sh/ruff
+
+.. image:: https://www.mypy-lang.org/static/mypy_badge.svg
+   :alt: Checked with mypy
+   :target: https://mypy-lang.org/
+
+.. image:: https://img.shields.io/badge/License-MIT-yellow.svg
+   :alt: License: MIT
+   :target: https://opensource.org/licenses/MIT
+

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/pyproject.toml

@@ -13,7 +13,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2024.739091.2"
+version = "2024.739097.2"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [
@@ -37,7 +37,6 @@ aenum = "^3.1.15"
 attrs = ">=23.2"
 bs4 = ">=0.0.1"
 google-re2 = ">=1.1"
-icecream = ">=2.1.0"
 jinja2 = ">=3.1"
 joblib = ">=1.3"
 lxml = ">=5.0"
@@ -47,7 +46,6 @@ msgpack = ">=1.0"
 msgpack-numpy = ">=0.4"
 numpy = ">=1.26, <2.0"
 openpyxl = ">=3.1.2"
-pendulum = ">=3.0.0"
 python = "^3.12"
 requests = ">=2.31"
 scipy = ">=1.12"
@@ -63,10 +61,12 @@ poetry-plugin-export = "^1.8.0"
 
 
 [tool.poetry.group.dev.dependencies]
-semver = ">=3.0"
+icecream = ">=2.1.0"
 mypy = ">=1.8"
+pendulum = ">=3.0.0"
 ruff = ">=0.5"
 pytest = ">=8.0"
+semver = ">=3.0"
 sphinx = ">=7.2"
 sphinx-autodoc-typehints = ">=2.0.0"
 sphinx-autoapi = ">=3.0"

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/src/mergeron/__init__.py

@@ -2,16 +2,12 @@ from __future__ import annotations
 
 import enum
 from pathlib import Path
-from typing import Any
 
 import numpy as np
-import pendulum  # type: ignore
-from icecream import argumentToString, ic, install  # type: ignore
-from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739091.2"
+VERSION = "2024.739097.2"
 
 __version__ = VERSION
 
@@ -28,19 +24,6 @@ if not DATA_DIR.is_dir():
 np.set_printoptions(precision=18)
 
 
-def _timestamper() -> str:
-    return f"{pendulum.now().strftime("%F %T.%f")} |>  "
-
-
-@argumentToString.register(np.ndarray)  # type: ignore
-def _(_obj: NDArray[Any]) -> str:
-    return f"ndarray, shape={_obj.shape}, dtype={_obj.dtype}"
-
-
-ic.configureOutput(prefix=_timestamper, includeContext=True)
-install()
-
-
 @enum.unique
 class RECConstants(enum.StrEnum):
     """Recapture rate - derivation methods."""

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/src/mergeron/core/damodaran_margin_data.py

@@ -202,7 +202,7 @@ def mgn_data_resampler(
     Parameters
     ----------
     _sample_size
-        Number of draws
+        Number of draws; if tuple, (number of draws, number of columns)
 
     seed_sequence
         SeedSequence for seeding random-number generator when results

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/src/mergeron/core/ftc_merger_investigations_data.py

@@ -22,7 +22,6 @@ import numpy as np
 import re2 as re  # type: ignore
 import requests
 from bs4 import BeautifulSoup
-from icecream import ic  # type: ignore
 from numpy.testing import assert_array_equal
 from numpy.typing import NDArray
 
@@ -345,7 +344,7 @@ def _construct_new_period_data(
                 #   _invdata_array_bld_enfcls < 0, _invdata_array_bld_enfcls, 0
                 # )
                 # if np.einsum('ij->', invdata_array_bld_tbc):
-                #     ic(
+                #     print(
                 #       f"{_data_period}, {_table_no}, {_invdata_ind_group}:",
                 #       abs(np.einsum('ij->', invdata_array_bld_tbc))
                 #       )
@@ -551,7 +550,7 @@ def _parse_table_blocks(
         _invdata_evid_cond = "Unrestricted on additional evidence"
 
     else:
-        # ic(_table_blocks)
+        # print(_table_blocks)
         _invdata_evid_cond = (
             _table_blocks[1][-3].strip()
             if _table_ser == 9
@@ -570,8 +569,8 @@ def _parse_table_blocks(
 
     _table_array = process_table_func(_table_blocks)
     if not isinstance(_table_array, np.ndarray) or _table_array.dtype != np.int64:
-        ic(_table_num)
-        ic(_table_blocks)
+        print(_table_num)
+        print(_table_blocks)
         raise ValueError
 
     _table_data = INVTableData(_invdata_ind_group, _invdata_evid_cond, _table_array)

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/src/mergeron/ext/xlsxw_helper.py

@@ -11,6 +11,14 @@ This module is designed for producing formatted summary output. For
 writing bulk data to Excel, facilities provided in third-party packages
 such as `polars <https://pola.rs/>`_ likely provide better performance.
 
+License
+========
+
+Copyright 2017-2023 S. Murthy Kambhampaty
+Licese: MIT
+https://mit-license.org/
+
+
 """
 
 from __future__ import annotations

{mergeron-2024.739091.2 → mergeron-2024.739097.2}/src/mergeron/gen/__init__.py

@@ -21,7 +21,7 @@ __version__ = VERSION
 
 EMPTY_ARRAY_DEFAULT = np.zeros(2)
 FCOUNT_WTS_DEFAULT = np.divide(
-    (_nr := np.arange(1, 6)[::-1]), _nr.sum(), dtype=np.float64
+    (_nr := np.arange(1, 7)[::-1]), _nr.sum(), dtype=np.float64
 )
 
 
@@ -36,7 +36,7 @@ class PriceConstants(tuple[bool, str | None], enum.ReprEnum):
     ZERO = (False, None)
     NEG = (False, "negative share-correlation")
     POS = (False, "positive share-correlation")
-    # TODO: CSY = (False, "market-wide cost-symmetry")
+    CSY = (False, "market-wide cost-symmetry")
 
 
 @enum.unique
@@ -59,7 +59,11 @@ class SHRConstants(enum.StrEnum):
     DIR_ASYM = "Asymmetric Dirichlet"
     """Share distribution for merging-firm shares has a higher peak share
 
-    Shape parameter for merging-firm-share is 2.5, and 1.0 for all others.
+    By default, shape parameter for merging-firm-share is 2.5, and
+    1.0 for all others. Defining, :attr:`mergeron.ShareSpec.dist_parms`
+    as a vector of shape parameters with length matching
+    that of :attr:`mergeron.ShareSpec.dist_parms` allows flexible specification
+    of Dirichlet-distributed share-data generation.
     """
 
     DIR_COND = "Conditional Dirichlet"
@@ -74,13 +78,24 @@ class SHRConstants(enum.StrEnum):
 class ShareSpec:
     """Market share specification
 
+    A key 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.SHRConstants.UNI`, for Dirichlet-distributed market-shares,
+    the default specification is that firm-counts  vary between
+    2 and 7 firms with each value equally likely.
+
     Notes
     -----
-    If recapture is determined "outside-in", market shares cannot have
-    Uniform distribution.
+    If :attr:`mergeron.gen.ShareSpec.dist_type`:code:` == `:attr:`mergeron.gen.SHRConstants.UNI`,
+    then it is infeasible that
+    :attr:`mergeron.gen.ShareSpec.recapture_form`:code:` == `:attr:`mergeron.RECConstants.OUTIN`.
+    In other words, if firm-counts are unspecified, the recapture rate cannot be
+    estimated using outside good choice probabilities.
 
-    If sample with varying firm counts is required, market shares must
-    be specified as having a supported Dirichlet distribution.
+    For a sample with explicit firm counts, market shares must
+    be specified as having a supported Dirichlet distribution
+    (see :class:`mergeron.gen.SHRConstants`).
 
     """
 
@@ -446,7 +461,8 @@ class UPPTestRegime:
         default=UPPAggrSelector.MIN, validator=validators.instance_of(UPPAggrSelector)
     )
     divr_aggregator: UPPAggrSelector | None = field(
-        default=None, validator=validators.instance_of((UPPAggrSelector, type(None)))
+        default=UPPAggrSelector.MIN,
+        validator=validators.instance_of((UPPAggrSelector, type(None))),
     )