From e12de82fabd8e3fd71413aae384763c1442c4516 Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Fri, 5 May 2023 10:06:32 +0100 Subject: [PATCH 1/2] DOC: Add decprecated and versionadded admonitions --- docs/source/release/index.rst | 2 +- .../{version0.14.rst => version0.14.0.rst} | 6 +-- statsmodels/discrete/discrete_model.py | 54 +++++++++++++++++-- statsmodels/discrete/truncated_model.py | 10 ++++ statsmodels/stats/_diagnostic_other.py | 10 +++- statsmodels/stats/multitest.py | 8 +++ statsmodels/stats/rates.py | 32 +++++++++-- statsmodels/treatment/treatment_effects.py | 5 +- statsmodels/tsa/ar_model.py | 2 +- .../tsa/statespace/simulation_smoother.py | 11 ++++ statsmodels/tsa/stl/mstl.py | 2 + 11 files changed, 125 insertions(+), 17 deletions(-) rename docs/source/release/{version0.14.rst => version0.14.0.rst} (99%) diff --git a/docs/source/release/index.rst b/docs/source/release/index.rst index c2df071f3d5..952e03a3307 100644 --- a/docs/source/release/index.rst +++ b/docs/source/release/index.rst @@ -7,7 +7,7 @@ Release Notes .. toctree:: :maxdepth: 1 - version0.14 + version0.14.0 version0.13.4-5 version0.13.3 version0.13.2 diff --git a/docs/source/release/version0.14.rst b/docs/source/release/version0.14.0.rst similarity index 99% rename from docs/source/release/version0.14.rst rename to docs/source/release/version0.14.0.rst index 774147f154f..8833cecbeb5 100644 --- a/docs/source/release/version0.14.rst +++ b/docs/source/release/version0.14.0.rst @@ -44,14 +44,14 @@ selection or treatment model, outcome model and effect functions. Hurdle and Truncated Count Regression ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -:class:`statsmodels.discrete.truncated_model.HurdleModel` implements +:class:`statsmodels.discrete.truncated_model.HurdleCountModel` implements hurdle models for count data with either Poisson or NegativeBinomialP as submodels. Three left truncated models used for zero truncation are available, :class:`statsmodels.discrete.truncated_model.TruncatedLFPoisson`, :class:`statsmodels.discrete.truncated_model.TruncatedLFNegativeBinomialP` and -:class:`statsmodels.discrete.truncated_model.TruncatedLFGeneralized Poisson`. +:class:`statsmodels.discrete.truncated_model.TruncatedLFGeneralizedPoisson`. Models for right censoring at one are implemented but only as support for the hurdle models. @@ -108,7 +108,7 @@ Other Notable Enhancments ------------------------- - burg option in pacf :pr:`8113` -- new link for GLM: logc :pr:`8155` +- new link for GLM: Logc :pr:`8155` - rename class names for links for GLM, lower case names are deprecated :pr:`8569` - allow singular covariance in gaussian copula :pr:`8504` - GLM: Tweedie full loglikelihood :pr:`8560` diff --git a/statsmodels/discrete/discrete_model.py b/statsmodels/discrete/discrete_model.py index 134c223fa7d..368e378a74e 100644 --- a/statsmodels/discrete/discrete_model.py +++ b/statsmodels/discrete/discrete_model.py @@ -506,6 +506,11 @@ def predict(self, params, exog=None, which="mean", linear=None, - 'var' returns the estimated variance of endog implied by the model. + .. versionadded: 0.14 + + ``which`` replaces and extends the deprecated ``linear`` + argument. + linear : bool If True, returns the linear predicted values. If False or None, then the statistic specified by ``which`` will be returned. @@ -741,9 +746,28 @@ def predict(self, params, exog=None, which="mean", linear=None): it assumed to be 1 row of exogenous variables. If you only have one regressor and would like to do prediction, you must provide a 2d array with shape[1] == 1. - linear : bool, optional - If True, returns the linear predictor dot(exog,params). Else, - returns the value of the cdf at the linear predictor. + which : {'mean', 'linear', 'var', 'prob'}, optional + Statistic to predict. Default is 'mean'. + + - 'mean' returns the conditional expectation of endog E(y | x), + i.e. exp of linear predictor. + - 'linear' returns the linear predictor of the mean function. + - 'var' returns the estimated variance of endog implied by the + model. + + .. versionadded: 0.14 + + ``which`` replaces and extends the deprecated ``linear`` + argument. + + linear : bool + If True, returns the linear predicted values. If False or None, + then the statistic specified by ``which`` will be returned. + + .. deprecated: 0.14 + + The ``linear` keyword is deprecated and will be removed, + use ``which`` keyword instead. Notes ----- @@ -999,12 +1023,21 @@ def predict(self, params, exog=None, exposure=None, offset=None, - 'var' variance of endog implied by the likelihood model - 'prob' predicted probabilities for counts. + .. versionadded: 0.14 + + ``which`` replaces and extends the deprecated ``linear`` + argument. + linear : bool - The ``linear` keyword is deprecated and will be removed, - use ``which`` keyword instead. If True, returns the linear predicted values. If False or None, then the statistic specified by ``which`` will be returned. + .. deprecated: 0.14 + + The ``linear` keyword is deprecated and will be removed, + use ``which`` keyword instead. + + Notes ----- If exposure is specified, then it will be logged by the method. @@ -1621,11 +1654,22 @@ def predict(self, params, exog=None, exposure=None, offset=None, - 'prob' return probabilities for counts from 0 to max(endog) or for y_values if those are provided. + .. versionadded: 0.14 + + ``which`` replaces and extends the deprecated ``linear`` + argument. + linear : bool The ``linear` keyword is deprecated and will be removed, use ``which`` keyword instead. If True, returns the linear predicted values. If False or None, then the statistic specified by ``which`` will be returned. + + .. deprecated: 0.14 + + The ``linear` keyword is deprecated and will be removed, + use ``which`` keyword instead. + y_values : array_like Values of the random variable endog at which pmf is evaluated. Only used if ``which="prob"`` diff --git a/statsmodels/discrete/truncated_model.py b/statsmodels/discrete/truncated_model.py index a978f612ef2..215b3eae818 100644 --- a/statsmodels/discrete/truncated_model.py +++ b/statsmodels/discrete/truncated_model.py @@ -31,6 +31,8 @@ class TruncatedLFGeneric(CountModel): __doc__ = """ Generic Truncated model for count data + + .. versionadded:: 0.14.0 %(params)s %(extra_params)s @@ -433,6 +435,8 @@ class TruncatedLFPoisson(TruncatedLFGeneric): __doc__ = """ Truncated Poisson model for count data + .. versionadded:: 0.14.0 + %(params)s %(extra_params)s @@ -504,6 +508,8 @@ class TruncatedLFNegativeBinomialP(TruncatedLFGeneric): __doc__ = """ Truncated Generalized Negative Binomial model for count data + .. versionadded:: 0.14.0 + %(params)s %(extra_params)s @@ -588,6 +594,8 @@ class TruncatedLFGeneralizedPoisson(TruncatedLFGeneric): __doc__ = """ Truncated Generalized Poisson model for count data + .. versionadded:: 0.14.0 + %(params)s %(extra_params)s @@ -1037,6 +1045,8 @@ def _prob_nonzero(self, mu, params): class HurdleCountModel(CountModel): __doc__ = """ Hurdle model for count data + + .. versionadded:: 0.14.0 %(params)s %(extra_params)s diff --git a/statsmodels/stats/_diagnostic_other.py b/statsmodels/stats/_diagnostic_other.py index 773d3b8982f..9be330e3c5e 100644 --- a/statsmodels/stats/_diagnostic_other.py +++ b/statsmodels/stats/_diagnostic_other.py @@ -202,7 +202,10 @@ def dispersion_poisson(results): Each test has two strings a descriptive name and a string for the alternative hypothesis. """ - msg = 'dispersion_poisson here is deprecated, use ' + msg = ( + 'dispersion_poisson here is deprecated, use the version in ' + 'discrete._diagnostic_count' + ) warnings.warn(msg, FutureWarning) from statsmodels.discrete._diagnostics_count import test_poisson_dispersion @@ -225,7 +228,10 @@ def dispersion_poisson_generic(results, exog_new_test, exog_new_control=None, Warning: insufficiently tested, especially for options """ - msg = 'dispersion_poisson here is deprecated, use ' + msg = ( + 'dispersion_poisson_generic here is deprecated, use the version in ' + 'discrete._diagnostic_count' + ) warnings.warn(msg, FutureWarning) from statsmodels.discrete._diagnostics_count import ( diff --git a/statsmodels/stats/multitest.py b/statsmodels/stats/multitest.py index 4d3b1bb0fe7..2139a2ce915 100644 --- a/statsmodels/stats/multitest.py +++ b/statsmodels/stats/multitest.py @@ -400,6 +400,10 @@ def fdrcorrection_twostage(pvals, alpha=0.05, method='bky', maxiter=False is two-stage fdr (maxiter=1) maxiter=True is full iteration (maxiter=-1 or maxiter=len(pvals)) + .. versionadded:: 0.14 + + Replacement for ``iter`` with additional features. + iter : bool ``iter`` is deprecated use ``maxiter`` instead. If iter is True, then only one iteration step is used, this is the @@ -407,6 +411,10 @@ def fdrcorrection_twostage(pvals, alpha=0.05, method='bky', If iter is False, then iterations are stopped at convergence which occurs in a finite number of steps (at most len(pvals) steps). + .. deprecated:: 0.14 + + Use ``maxiter`` instead of ``iter``. + Returns ------- rejected : ndarray, bool diff --git a/statsmodels/stats/rates.py b/statsmodels/stats/rates.py index 9f028434055..479322a0188 100644 --- a/statsmodels/stats/rates.py +++ b/statsmodels/stats/rates.py @@ -638,9 +638,19 @@ def test_poisson_2indep(count1, exposure1, count2, exposure2, value=None, ratio_null: float Ratio of the two Poisson rates under the Null hypothesis. Default is 1. Deprecated, use ``value`` instead. + + .. deprecaated:: 0.14.0 + + Use ``value`` instead. + value : float Value of the ratio or difference of 2 independent rates under the null hypothesis. Default is equal rates, i.e. 1 for ratio and 0 for diff. + + .. versionadded:: 0.14.0 + + Replacement for ``ratio_null``. + method : string Method for the test statistic and the p-value. Defaults to `'score'`. see Notes. @@ -747,13 +757,13 @@ def test_poisson_2indep(count1, exposure1, count2, exposure2, value=None, # default method method = 'score' - if ratio_null is None and value is None: - # default value - value = ratio_null = 1 - elif ratio_null is not None: + if ratio_null is not None: warnings.warn("'ratio_null' is deprecated, use 'value' keyword", FutureWarning) value = ratio_null + if ratio_null is None and value is None: + # default value + value = ratio_null = 1 else: # for results holder instance, it still contains ratio_null ratio_null = value @@ -932,9 +942,19 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, ratio_null: float Ratio of the two Poisson rates under the Null hypothesis. Default is 1. Deprecated, use ``value`` instead. + + .. deprecaated:: 0.14.0 + + Use ``value`` instead. + value : float Value of the ratio or diff of 2 independent rates under the null hypothesis. Default is equal rates, i.e. 1 for ratio and 0 for diff. + + .. versionadded:: 0.14.0 + + Replacement for ``ratio_null``. + method : {"score", "wald"} Method for the test statistic that defines the rejection region. alternative : string @@ -953,6 +973,10 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, Same as y_grid. Deprecated. If both y_grid and ygrid are provided, ygrid will be ignored. + .. deprecaated:: 0.14.0 + + Use ``y_grid`` instead. + Returns ------- stat_sample : float diff --git a/statsmodels/treatment/treatment_effects.py b/statsmodels/treatment/treatment_effects.py index d7f7ee23b83..db96271fe5f 100644 --- a/statsmodels/treatment/treatment_effects.py +++ b/statsmodels/treatment/treatment_effects.py @@ -604,7 +604,10 @@ def __init__(self, teff, results_gmm, method, **kwds): class TreatmentEffect(object): - """Estimate average treatment effect under conditional independence + """ + Estimate average treatment effect under conditional independence + + .. versionadded:: 0.14.0 This class estimates treatment effect and potential outcome using 5 different methods, ipw, ra, aipw, aipw-wls, ipw-ra. diff --git a/statsmodels/tsa/ar_model.py b/statsmodels/tsa/ar_model.py index 5ff3f6ac692..7dfde38b2b7 100644 --- a/statsmodels/tsa/ar_model.py +++ b/statsmodels/tsa/ar_model.py @@ -148,7 +148,7 @@ class AutoReg(tsa_model.TimeSeriesModel): old_names : bool Flag indicating whether to use the v0.11 names or the v0.12+ names. - .. deprecated:: 0.13 + .. deprecated:: 0.13.0 old_names is deprecated and will be removed after 0.14 is released. You must update any code reliant on the old variable diff --git a/statsmodels/tsa/statespace/simulation_smoother.py b/statsmodels/tsa/statespace/simulation_smoother.py index ffe2ad5d6e9..27c8e585395 100644 --- a/statsmodels/tsa/statespace/simulation_smoother.py +++ b/statsmodels/tsa/statespace/simulation_smoother.py @@ -614,9 +614,20 @@ def simulate(self, simulation_output=-1, disturbance_variates : bool, optional Deprecated, please use pretransformed_measurement_shocks and pretransformed_state_shocks instead. + + .. deprecated:: 0.14.0 + + Use ``measurement_disturbance_variates`` and + ``state_disturbance_variates`` as replacements. + pretransformed : bool, optional Deprecated, please use pretransformed_measurement_shocks and pretransformed_state_shocks instead. + + .. deprecated:: 0.14.0 + + Use ``pretransformed_measurement_disturbance_variates`` and + ``pretransformed_state_disturbance_variates`` as replacements. """ # Handle deprecated argumennts if disturbance_variates is not None: diff --git a/statsmodels/tsa/stl/mstl.py b/statsmodels/tsa/stl/mstl.py index 119aec81918..0cbf774f175 100644 --- a/statsmodels/tsa/stl/mstl.py +++ b/statsmodels/tsa/stl/mstl.py @@ -35,6 +35,8 @@ class MSTL: Season-Trend decomposition using LOESS for multiple seasonalities. + .. versionadded:: 0.14.0 + Parameters ---------- endog : array_like From edcaf3a6a0b4be31aeb12fb6caef3caf5ad058b7 Mon Sep 17 00:00:00 2001 From: Kevin Sheppard Date: Fri, 5 May 2023 11:37:48 +0100 Subject: [PATCH 2/2] DOC/RLS: Final update for release 0.14 --- .../_static/stylesheets/deprecation.css | 14 +++++++++- docs/source/release/version0.14.0.rst | 28 +++++++++++++++---- statsmodels/discrete/truncated_model.py | 6 ++-- statsmodels/stats/rates.py | 25 +++++++++-------- 4 files changed, 51 insertions(+), 22 deletions(-) diff --git a/docs/source/_static/stylesheets/deprecation.css b/docs/source/_static/stylesheets/deprecation.css index cdea971d3c4..f8de657db63 100644 --- a/docs/source/_static/stylesheets/deprecation.css +++ b/docs/source/_static/stylesheets/deprecation.css @@ -23,7 +23,7 @@ div.deprecated, div.versionadded, div.versionchanged { position: relative; transition: color .25s,background-color .25s,border-color .25s; vertical-align: middle; - font-size: 0.64rem; + font-size: 0.72rem; } div.deprecated>p, div.versionadded>p, div.versionchanged>p { margin-bottom: .6rem; @@ -35,6 +35,11 @@ div.deprecated { background-color: rgba(255, 0, 0, 0.1); } +div.versionadded { + border-color: #459db9; + background-color: rgba(0, 191, 255, 0.1); +} + span.versionmodified { font-weight: 600; } @@ -47,7 +52,14 @@ div.deprecated p:before { background-color: #dc3545; } +div.versionadded p:before { + background-color: #459db9; +} + span.versionmodified.deprecated:before { color: #dc3545; } +span.versionmodified.added { + color: #459db9; +} diff --git a/docs/source/release/version0.14.0.rst b/docs/source/release/version0.14.0.rst index 8833cecbeb5..986ca6cd87b 100644 --- a/docs/source/release/version0.14.0.rst +++ b/docs/source/release/version0.14.0.rst @@ -21,11 +21,11 @@ was already in statsmodels main and how much usage it has already seen. If there are specific known problems or limitations, then they are mentioned in the docstrings. -Github Stats ------------- -**Issues Closed**: 248 +Stats +----- +**Issues Closed**: 255 -**Pull Requests Merged**: 335 +**Pull Requests Merged**: 345 The Highlights @@ -144,7 +144,7 @@ Submodules - Fix a typo in the documentation (:pr:`8275`) - Fix `histogram` (:pr:`8299`) - Add notebook for Poisson post-estimation overview (:pr:`8420`) - +- Add version (:pr:`8863`) @@ -186,6 +186,7 @@ Submodules - MNLogit if endog is series with no name (:pr:`8674`) - Get_distribution, return 1-d instead of column frozen distribution (:pr:`8780`) - Numpy compat, indexed assignment shape in NegativeBinomial (:pr:`8822`) +- Support offset in truncated count models (:pr:`8845`) @@ -245,6 +246,9 @@ Submodules - Update PRs in release note (:pr:`8805`) - Improve release notes highlights (:pr:`8806`) - Fix more deprecations and restore doc build (:pr:`8826`) +- Final changes for 0.14.0rc0 notes (:pr:`8839`) +- Fix internet address of dataset (:pr:`8861`) +- Small additional fixes (:pr:`8862`) @@ -616,7 +620,7 @@ Thanks to all of the contributors for the 0.14.0 release (based on git log): - Eva Maxfield Brown - Evgeny Zhurko - Ewout Ter Hoeven -- Geoffrey M. Oxberry +- Geoffrey Oxberry - Greg Mcmahan - Gregory Parkes - Guilherme Silveira @@ -629,6 +633,7 @@ Thanks to all of the contributors for the 0.14.0 release (based on git log): - Josef Perktold - João Tanaka - Kees Mulder +- Kerby Shedden - Kevin Sheppard - Kirill Milash - Kirill Ulanov @@ -1019,3 +1024,14 @@ The following Pull Requests were merged since the last release: - :pr:`8831`: BUG: Correct initial level, treand and seasonal - :pr:`8834`: MAINT: Switch DeprecationWarn to FutureWarn - :pr:`8835`: ENH: Add sharex for seasonal decompose plots +- :pr:`8839`: DOC: Final changes for 0.14.0rc0 notes +- :pr:`8845`: BUG/ENH: support offset in truncated count models +- :pr:`8847`: DOC: Use JSON for versioning +- :pr:`8851`: BUG: Fix added variable plots to work with OLS +- :pr:`8857`: DOC: Small fix for STLForecast example +- :pr:`8858`: DOC: Fix example notebooks +- :pr:`8861`: DOC: Fix internet address of dataset +- :pr:`8862`: DOC: Small additional fixes +- :pr:`8863`: DOC: Add version +- :pr:`8865`: MAINT: Move from Styler.applymap to map +- :pr:`8866`: DOC: Add admonitions for changes and deprecations \ No newline at end of file diff --git a/statsmodels/discrete/truncated_model.py b/statsmodels/discrete/truncated_model.py index 215b3eae818..24f97b9ef17 100644 --- a/statsmodels/discrete/truncated_model.py +++ b/statsmodels/discrete/truncated_model.py @@ -31,7 +31,7 @@ class TruncatedLFGeneric(CountModel): __doc__ = """ Generic Truncated model for count data - + .. versionadded:: 0.14.0 %(params)s @@ -509,7 +509,7 @@ class TruncatedLFNegativeBinomialP(TruncatedLFGeneric): Truncated Generalized Negative Binomial model for count data .. versionadded:: 0.14.0 - + %(params)s %(extra_params)s @@ -1045,7 +1045,7 @@ def _prob_nonzero(self, mu, params): class HurdleCountModel(CountModel): __doc__ = """ Hurdle model for count data - + .. versionadded:: 0.14.0 %(params)s diff --git a/statsmodels/stats/rates.py b/statsmodels/stats/rates.py index 479322a0188..cfb0e62c30c 100644 --- a/statsmodels/stats/rates.py +++ b/statsmodels/stats/rates.py @@ -1,4 +1,5 @@ -'''Test for ratio of Poisson intensities in two independent samples +''' +Test for ratio of Poisson intensities in two independent samples Author: Josef Perktold License: BSD-3 @@ -639,7 +640,7 @@ def test_poisson_2indep(count1, exposure1, count2, exposure2, value=None, Ratio of the two Poisson rates under the Null hypothesis. Default is 1. Deprecated, use ``value`` instead. - .. deprecaated:: 0.14.0 + .. deprecated:: 0.14.0 Use ``value`` instead. @@ -908,12 +909,12 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, value=None, method='score', compare="ratio", alternative='two-sided', ygrid=None, y_grid=None): - """E-test for ratio of two sample Poisson rates. - - Rates are defined as expected count divided by exposure. + """ + E-test for ratio of two sample Poisson rates. - The Null and alternative hypothesis for the rates, rate1 and rate2, of two - independent Poisson samples are + Rates are defined as expected count divided by exposure. The Null and + alternative hypothesis for the rates, rate1 and rate2, of two independent + Poisson samples are: for compare = 'diff' @@ -943,7 +944,7 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, Ratio of the two Poisson rates under the Null hypothesis. Default is 1. Deprecated, use ``value`` instead. - .. deprecaated:: 0.14.0 + .. deprecated:: 0.14.0 Use ``value`` instead. @@ -960,9 +961,9 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, alternative : string The alternative hypothesis, H1, has to be one of the following - 'two-sided': H1: ratio of rates is not equal to ratio_null (default) - 'larger' : H1: ratio of rates is larger than ratio_null - 'smaller' : H1: ratio of rates is smaller than ratio_null + - 'two-sided': H1: ratio of rates is not equal to ratio_null (default) + - 'larger' : H1: ratio of rates is larger than ratio_null + - 'smaller' : H1: ratio of rates is smaller than ratio_null y_grid : None or 1-D ndarray Grid values for counts of the Poisson distribution used for computing @@ -973,7 +974,7 @@ def etest_poisson_2indep(count1, exposure1, count2, exposure2, ratio_null=None, Same as y_grid. Deprecated. If both y_grid and ygrid are provided, ygrid will be ignored. - .. deprecaated:: 0.14.0 + .. deprecated:: 0.14.0 Use ``y_grid`` instead.