mergeron 2024.739105.2__tar.gz → 2024.739105.4__tar.gz

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mergeron
-Version: 2024.739105.2
+Version: 2024.739105.4
 Summary: Merger Policy Analysis using Python
 License: MIT
 Keywords: merger policy analysis,merger guidelines,merger screening,policy presumptions,concentration standards,upward pricing pressure,GUPPI
@@ -49,16 +49,16 @@ Here, enforcement rates derived with merger enforcement as being exogenous to fi
 Introduction
 ------------
 
-Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`..core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`..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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`.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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
 
 Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) 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 (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
-and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
+and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.share_spec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
 
-By default, 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:`.gen.data_generation.MarketSample.ShareSpec`, and, specifically, :code:`.gen.SHRDistribution`). When drawing shares from the Dirichlet distribution, the user passes, using :code:`.gen.data_generation.MarketSample.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:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.ShareSpec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
+By default, 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 property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec`, of type, :code:`.gen.SHRDistribution`). When drawing shares from the Dirichlet distribution, the user specifies the `firm_count_weights` property of :code:`.gen.data_generation.MarketSample.share_spec`, as 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 the property `firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.share_spec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
 
-Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`.RECForm`. The "inside-out" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) 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:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`.gen.data_generation.MarketSample.ShareSpec.dist_type`:code:` ==`:code:`.gen.ShareDistributions.UNI`, thus raising a :code:`ValueError` exception. The "proportional" form (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" form. See, for example, Coate (2011).
+Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`.RECForm`). The "inside-out" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) 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:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when the property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec` is assigned :code:`.gen.ShareDistributions.UNI`, raising a :code:`ValueError` exception. The "proportional" form (`recapture_form` = :code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" calibration. See, for example, Coate (2011).
 
-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 (see, :code:`.gen.PCMSpec`). 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 (:code:`.gen.data_generation.MarketSample.PCMSpec.firm2_pcm_constraint`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
+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 (see, :code:`.gen.PCMSpec`). 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 (per the property `firm2_pcm_constraint` of :code:`.gen.data_generation.MarketSample.pcm_spec`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
 
 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:`.gen.PriceSpec`). Prices may also be defined by imposing cost symmetry on firms in the sample, with fixed unit marginal costs normalized to 1 unit, such that price equal :math:`1 / (1 - \pmb{m})`, where :math:`\pmb{m}` represents the array of margins for firms in the sample.
 

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/README.rst

@@ -8,16 +8,16 @@ Here, enforcement rates derived with merger enforcement as being exogenous to fi
 Introduction
 ------------
 
-Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`..core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`..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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
+Module :code:`.core.guidelines_boundaries` includes classes for specifying concentration bounds (:code:`.core.guidelines_boundaries.ConcentrationBoundary`) and diversion-ratio bounds (:code:`.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 concentration and diversion-ratio boundaries, and functions for mapping GUPPI standards to concentration (ΔHHI) standards, and vice-versa.
 
 Module :code:`.gen.data_generation` includes the :code:`.gen.data_generation.MarketSample` which provides for a rich specification of shares and diversion ratios (:code:`.gen.data_generation.MarketSample.share_spec`), margins (:code:`.gen.data_generation.MarketSample.pcm_spec`, prices (:code:`.gen.data_generation.MarketSample.price_spec`), and HSR filing requirements (:code:`.gen.data_generation.MarketSample.hsr_filing_test_type`), and with methods for, (i) generating sample data (:code:`.gen.data_generation.MarketSample.generate_sample`), and (ii) 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 (:code:`.gen.data_generation.MarketSample.estimate_enf_counts`). While the latter populate the properties, :code:`.gen.data_generation.MarketSample.data`
-and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
+and :code:`.gen.data_generation.MarketSample.enf_counts`, respectively, the underlying methods for generating standalone :code:`MarketDataSample` and :code:`UPPTestCounts` objects are included in the class definition, with helper functions defined in the modules, :code:`.gen.data_generation_functions` and :code:`.gen.upp_tests`. Notably, market shares are generated for a sample of markets with firm-count distributed as specified in :code:`.gen.data_generation.MarketSample.share_spec.firm_count_weights`, with defaults as discussed below (also see, :code:`.gen.ShareSpec.firm_count_weights`.
 
-By default, 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:`.gen.data_generation.MarketSample.ShareSpec`, and, specifically, :code:`.gen.SHRDistribution`). When drawing shares from the Dirichlet distribution, the user passes, using :code:`.gen.data_generation.MarketSample.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:`.gen.data_generation.MarketSample.ShareSpec.firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.ShareSpec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
+By default, 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 property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec`, of type, :code:`.gen.SHRDistribution`). When drawing shares from the Dirichlet distribution, the user specifies the `firm_count_weights` property of :code:`.gen.data_generation.MarketSample.share_spec`, as 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 the property `firm_count_weights` is not explicitly assigned a value when defining :code:`.gen.data_generation.MarketSample.share_spec`, the default values is used, which results in a sample of markets with 2 to 7 firms with relative frequency in inverse proportion to firm-count, with 2-firm markets being 6 times as likely to be drawn as 7-firm markets.
 
-Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`.RECForm`. The "inside-out" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.INOUT`) 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:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when :code:`.gen.data_generation.MarketSample.ShareSpec.dist_type`:code:` ==`:code:`.gen.ShareDistributions.UNI`, thus raising a :code:`ValueError` exception. The "proportional" form (:code:`.gen.data_generation.MarketSample.ShareSpec.recapture_form`:code:` = `:code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" form. See, for example, Coate (2011).
+Recapture rates can be specified as, "proportional", "inside-out", "outside-in" (see :code:`.RECForm`). The "inside-out" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) results in recapture ratios consistent with merging-firms' in-market shares and a default recapture rate. The "outside-in" specification (assigning :code:`.RECForm.INOUT` to the `recapture_form` property of :code:`.gen.data_generation.MarketSample.share_spec`) 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:`.gen.ShareSpec`). The "outside-in" specification is invalid when the distribution of markets over firm-count is unspecified, i.e., when the property `dist_type` of :code:`.gen.data_generation.MarketSample.share_spec` is assigned :code:`.gen.ShareDistributions.UNI`, raising a :code:`ValueError` exception. The "proportional" form (`recapture_form` = :code:`.RECForm.FIXED`) is often used in the literature, as an approximation to the "inside-out" calibration. See, for example, Coate (2011).
 
-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 (see, :code:`.gen.PCMSpec`). 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 (:code:`.gen.data_generation.MarketSample.PCMSpec.firm2_pcm_constraint`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
+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 (see, :code:`.gen.PCMSpec`). 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 (per the property `firm2_pcm_constraint` of :code:`.gen.data_generation.MarketSample.pcm_spec`) may be specified as symmetric, i.i.d., or subject to equilibrium conditions for (profit-maximization in) Bertrand-Nash oligopoly with MNL demand (:code:`.gen.FM2Constraint`).
 
 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:`.gen.PriceSpec`). Prices may also be defined by imposing cost symmetry on firms in the sample, with fixed unit marginal costs normalized to 1 unit, such that price equal :math:`1 / (1 - \pmb{m})`, where :math:`\pmb{m}` represents the array of margins for firms in the sample.
 

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/pyproject.toml

@@ -13,7 +13,7 @@ keywords = [
     "upward pricing pressure",
     "GUPPI",
 ]
-version = "2024.739105.2"
+version = "2024.739105.4"
 
 # Classifiers list: https://pypi.org/classifiers/
 classifiers = [
@@ -68,8 +68,8 @@ pendulum = ">=3.0.0"
 ruff = ">=0.5"
 poetry-plugin-export = "^1.8.0"
 pytest = ">=8.0"
+Sphinx = ">=7.2, <8.0"
 semver = ">=3.0"
-sphinx = ">=7.2"
 sphinx-autodoc-typehints = ">=2.0.0"
 sphinx-autoapi = ">=3.0"
 sphinx-immaterial = ">=0.11"

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/__init__.py

@@ -9,7 +9,7 @@ from numpy.typing import NDArray
 
 _PKG_NAME: str = Path(__file__).parent.stem
 
-VERSION = "2024.739105.2"
+VERSION = "2024.739105.4"
 
 __version__ = VERSION
 
@@ -34,6 +34,8 @@ ArrayBoolean: TypeAlias = NDArray[np.bool_]
 ArrayDouble: TypeAlias = NDArray[np.double]
 ArrayBIGINT: TypeAlias = NDArray[np.int64]
 
+DEFAULT_REC_RATE = 0.85
+
 
 @enum.unique
 class RECForm(enum.StrEnum):

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/core/guidelines_boundaries.py

@@ -13,7 +13,13 @@ import numpy as np
 from attrs import Attribute, field, frozen, validators
 from mpmath import mp, mpf  # type: ignore
 
-from .. import VERSION, ArrayDouble, RECForm, UPPAggrSelector  # noqa: TID252
+from .. import (  # noqa: TID252
+    DEFAULT_REC_RATE,
+    VERSION,
+    ArrayDouble,
+    RECForm,
+    UPPAggrSelector,
+)
 from . import guidelines_boundary_functions as gbfn
 
 __version__ = VERSION
@@ -86,7 +92,7 @@ class GuidelinesThresholds:
     """
 
     def __attrs_post_init__(self, /) -> None:
-        # In the 2023 Guidlines, the agencies do not define a
+        # In the 2023 Guidelines, the agencies do not define a
         # negative presumption, or safeharbor. Practically speaking,
         # given resource constraints and loss aversion, it is likely
         # that staff only investigates mergers that meet the presumption;
@@ -128,7 +134,7 @@ class GuidelinesThresholds:
         )
 
         # imputed_presumption is relevant for 2010 Guidelines
-        # merger to symmettry in numbers-equivalent of post-merger HHI
+        # merger to symmetry in numbers-equivalent of post-merger HHI
         object.__setattr__(
             self,
             "imputed_presumption",
@@ -262,16 +268,13 @@ class DiversionRatioBoundary:
     )
 
     recapture_rate: float = field(
-        kw_only=False, default=0.85, validator=validators.instance_of(float)
+        kw_only=False, default=DEFAULT_REC_RATE, validator=validators.instance_of(float)
     )
 
     recapture_form: RECForm | None = field(
         kw_only=True,
         default=RECForm.INOUT,
-        validator=(
-            validators.instance_of((type(None), RECForm)),
-            _rec_spec_validator,
-        ),
+        validator=(validators.instance_of((type(None), RECForm)), _rec_spec_validator),
     )
     """
     The form of the recapture rate.
@@ -373,7 +376,11 @@ class DiversionRatioBoundary:
 
 
 def guppi_from_delta(
-    _delta_bound: float = 0.01, /, *, m_star: float = 1.00, r_bar: float = 0.8
+    _delta_bound: float = 0.01,
+    /,
+    *,
+    m_star: float = 1.00,
+    r_bar: float = DEFAULT_REC_RATE,
 ) -> float:
     """
     Translate ∆HHI bound to GUPPI bound.
@@ -431,7 +438,11 @@ def critical_share_ratio(
 
 
 def share_from_guppi(
-    _guppi_bound: float = 0.065, /, *, m_star: float = 1.00, r_bar: float = 0.8
+    _guppi_bound: float = 0.065,
+    /,
+    *,
+    m_star: float = 1.00,
+    r_bar: float = DEFAULT_REC_RATE,
 ) -> float:
     """
     Symmetric-firm share for given GUPPI, margin, and recapture rate.

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/core/guidelines_boundary_functions.py

@@ -5,7 +5,7 @@ from typing import Any, Literal, TypedDict
 import numpy as np
 from mpmath import mp, mpf  # type: ignore
 
-from .. import VERSION, ArrayBIGINT, ArrayDouble  # noqa: TID252
+from .. import DEFAULT_REC_RATE, VERSION, ArrayBIGINT, ArrayDouble  # noqa: TID252
 
 __version__ = VERSION
 
@@ -211,7 +211,7 @@ def hhi_post_contrib_boundary(
 
 def shrratio_boundary_wtd_avg(
     _delta_star: float = 0.075,
-    _r_val: float = 0.85,
+    _r_val: float = DEFAULT_REC_RATE,
     /,
     *,
     agg_method: Literal[
@@ -420,7 +420,7 @@ def shrratio_boundary_wtd_avg(
 
 def shrratio_boundary_xact_avg(
     _delta_star: float = 0.075,
-    _r_val: float = 0.85,
+    _r_val: float = DEFAULT_REC_RATE,
     /,
     *,
     recapture_form: Literal["inside-out", "proportional"] = "inside-out",
@@ -579,7 +579,7 @@ def shrratio_boundary_xact_avg(
 
 def shrratio_boundary_min(
     _delta_star: float = 0.075,
-    _r_val: float = 0.85,
+    _r_val: float = DEFAULT_REC_RATE,
     /,
     *,
     recapture_form: str = "inside-out",
@@ -645,7 +645,7 @@ def shrratio_boundary_min(
 
 
 def shrratio_boundary_max(
-    _delta_star: float = 0.075, _r_val: float = 0.85, /, *, prec: int = 10
+    _delta_star: float = 0.075, _r_val: float = DEFAULT_REC_RATE, /, *, prec: int = 10
 ) -> GuidelinesBoundary:
     """
     Share combinations on the minimum GUPPI boundary with symmetric

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/core/guidelines_boundary_functions_extra.py

@@ -16,7 +16,7 @@ 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  # type: ignore
 
-from .. import VERSION, ArrayDouble  # noqa: TID252
+from .. import DEFAULT_REC_RATE, VERSION, ArrayDouble  # noqa: TID252
 from .guidelines_boundary_functions import (
     GuidelinesBoundary,
     _shrratio_boundary_intcpt,
@@ -105,7 +105,7 @@ def hhi_delta_boundary_qdtr(_dh_val: float = 0.01, /) -> GuidelinesBoundaryCalla
 
 def shrratio_boundary_qdtr_wtd_avg(
     _delta_star: float = 0.075,
-    _r_val: float = 0.85,
+    _r_val: float = DEFAULT_REC_RATE,
     /,
     *,
     weighting: Literal["own-share", "cross-product-share"] | None = "own-share",
@@ -224,7 +224,7 @@ def shrratio_boundary_qdtr_wtd_avg(
 
 def shrratio_boundary_distance(
     _delta_star: float = 0.075,
-    _r_val: float = 0.85,
+    _r_val: float = DEFAULT_REC_RATE,
     /,
     *,
     agg_method: Literal["arithmetic mean", "distance"] = "arithmetic mean",

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/gen/__init__.py

@@ -15,6 +15,7 @@ from attrs import Attribute, cmp_using, field, frozen, validators
 from numpy.random import SeedSequence
 
 from .. import (  # noqa: TID252
+    DEFAULT_REC_RATE,
     VERSION,
     ArrayBIGINT,
     ArrayBoolean,
@@ -164,8 +165,8 @@ class ShareSpec:
                 "generated data. Either delete recapture rate specification or set it to None."
             )
 
-    recapture_rate: float | None = field(default=0.8)
-    """A value between 0 and 1, typically 0.8.
+    recapture_rate: float | None = field(default=DEFAULT_REC_RATE)
+    """A value between 0 and 1.
 
     :code:`None` if market share specification requires direct generation of
     outside good choice probabilities (:attr:`mergeron.RECForm.OUTIN`).
@@ -276,7 +277,9 @@ class PCMSpec:
                 f'"given value, {_v!r} is ignored."'
             )
 
-    firm2_pcm_constraint: FM2Constraint = field(kw_only=False, default=FM2Constraint.IID)
+    firm2_pcm_constraint: FM2Constraint = field(
+        kw_only=False, default=FM2Constraint.IID
+    )
     """See :class:`FM2Constraint`"""
 
 

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/gen/data_generation.py

@@ -13,7 +13,7 @@ from attrs import Attribute, define, field, validators
 from joblib import Parallel, cpu_count, delayed  # type: ignore
 from numpy.random import SeedSequence
 
-from .. import VERSION, RECForm  # noqa: TID252  # noqa
+from .. import DEFAULT_REC_RATE, VERSION, RECForm  # noqa: TID252  # noqa
 from ..core import guidelines_boundaries as gbl  # noqa: TID252
 from ..core.guidelines_boundaries import HMGThresholds  # noqa: TID252
 from . import (
@@ -73,7 +73,9 @@ class MarketSample:
 
     share_spec: ShareSpec = field(
         kw_only=True,
-        default=ShareSpec(SHRDistribution.UNI, None, None, RECForm.INOUT, 0.8),
+        default=ShareSpec(
+            SHRDistribution.UNI, None, None, RECForm.INOUT, DEFAULT_REC_RATE
+        ),
         validator=validators.instance_of(ShareSpec),
     )
     """Market-share specification, see :class:`ShareSpec`"""

{mergeron-2024.739105.2 → mergeron-2024.739105.4}/src/mergeron/gen/data_generation_functions.py

@@ -11,7 +11,13 @@ import numpy as np
 from attrs import evolve
 from numpy.random import SeedSequence
 
-from .. import VERSION, ArrayBIGINT, ArrayDouble, RECForm  # noqa: TID252
+from .. import (  # noqa: TID252
+    DEFAULT_REC_RATE,
+    VERSION,
+    ArrayBIGINT,
+    ArrayDouble,
+    RECForm,
+)
 from ..core.damodaran_margin_data import mgn_data_resampler  # noqa: TID252
 from ..core.pseudorandom_numbers import (  # noqa: TID252
     DIST_PARMS_DEFAULT,
@@ -100,7 +106,7 @@ def gen_share_data(
 
     # If recapture_form == "inside-out", recalculate _aggregate_purchase_prob
     _frmshr_array = _mkt_share_sample.mktshr_array[:, :2]
-    _r_bar = _share_spec.recapture_rate or 0.8
+    _r_bar = _share_spec.recapture_rate or DEFAULT_REC_RATE
     if _recapture_form == RECForm.INOUT:
         _mkt_share_sample = ShareDataSample(
             _mkt_share_sample.mktshr_array,
@@ -226,9 +232,7 @@ def gen_market_shares_dirichlet_multimarket(
         FCOUNT_WTS_DEFAULT if _firm_count_wts is None else _firm_count_wts
     )
 
-    _min_choice_wt = (
-        0.03 if _dist_type_dir == SHRDistribution.DIR_FLAT_CONSTR else 0.00
-    )
+    _min_choice_wt = 0.03 if _dist_type_dir == SHRDistribution.DIR_FLAT_CONSTR else 0.00
     _fcount_keys, _choice_wts = zip(
         *(
             _f