DOC: Add decprecated and versionadded admonitions

bashtage · bashtage · commit e12de82fabd8 · 2023-05-05T10:06:32.000+01:00
diff --git 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.0.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
@@ -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
@@ -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
@@ -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
@@ -400,13 +400,21 @@ 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
         two-step method.
         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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -35,6 +35,8 @@ class MSTL:
 
     Season-Trend decomposition using LOESS for multiple seasonalities.
 
+    .. versionadded:: 0.14.0
+
     Parameters
     ----------
     endog : array_like
