pastas.stats.tests.stoffer_toloi
================================

.. py:function:: pastas.stats.tests.stoffer_toloi(series: pandas.Series, lags: int = 15, nparam: int = 0, freq: str = 'D', snap_to_equidistant_timestamps: bool = False) -> tuple[float, float]

   
   Adapted Ljung-Box test to deal with missing data [Rcb3cfb20bb89-stoffer_1992]_.

   :param series: Time series to compute the adapted Ljung-Box statistic for.
   :type series: pandas.Series
   :param lags: the number of lags to compute the statistic for. Only lags for which a
                correlation is computed are used.
   :type lags: int, optional
   :param nparam: Number of parameters of the noisemodel.
   :type nparam: int, optional
   :param freq: String with the frequency to resample the time series to.
   :type freq: str, optional
   :param snap_to_equidistant_timestamps: if False (default), a sample is taken from series with equidistant timesteps
                                          using pandas' reindex. Only values are kept that lie on those equidistant
                                          timestamps. If True, an equidistant time series is created taking as many
                                          values as possible from the original series which are then snapped to the
                                          nearest equidistant timestamp.
   :type snap_to_equidistant_timestamps: bool, optional

   :returns: * **qm** (*float*) -- Adapted Ljung-Box test statistic.
             * **pval** (*float*) -- p-value for the test statistic, based on a chi-squared distribution.

   .. rubric:: Notes

   Stoffer and Toloi [Rcb3cfb20bb89-stoffer_1992]_ extended the Ljung-Box test to also work with
   missing data. The test statistic is computed as follows:

   .. math ::

       Q_k = n^2 \sum_{k=1}^{h} \frac{\hat{\rho}_k^2}{n-k}

   where :math:`\hat{\rho}_k` is the autocorrelation for lag $k$. When the
   residual time series have non-equidistant time steps it is recommended to use
   this test over the original Ljung-Box test.

   The Stoffer-Toloi test is strictly an adapted version of the Ljung-Box test to
   deal with missing data in a time series and not a time series with
   non-equidistant time steps. This means that the time series is updated to an
   equidistant time series by filling nan-values.

   **Considerations for this test:**

   - Test is also applicable to irregular time series.
   - The time step has to be chosen (e.g., Days). This should not be smaller than
     the smallest time step or the test will most likely fail to reject $H_0$ anyway.

   .. rubric:: References

   .. [Rcb3cfb20bb89-stoffer_1992] Stoffer, D. S., & Toloi, C. M. (1992). A note on the
      Ljung—Box—Pierce stoffer_toloi statistic with missing data. Statistics &
      probability letters, 13(5), 391-396.

   .. rubric:: Examples

   >>> data= pd.Series(index=pd.date_range(start=0, periods=1000, freq="D"),
   >>>                 data=np.random.rand(1000))
   >>> stat, p = ps.stats.stoffer_toloi(noise, lags=15, freq="D")
   >>> if p > alpha:
   >>>    print("Failed to reject the Null-hypothesis, no significant"
   >>>          "autocorrelation. p =", p.round(2))
   >>> else:
   >>>    print("Reject the Null-hypothesis")

   .. seealso:: :py:obj:`pastas.timeseries_utils.get_equidistant_series_nearest`















   ..
       !! processed by numpydoc !!