DOCSEARCHbyAlgolia
Submit Docs

pyMannKendall

repository·master·Indexed 42 days ago

https://github.com/mmhs013/pymannkendall

A pure Python implementation of the non-parametric Mann-Kendall family of trend tests for analyzing monotonic trends in time series data. It includes 11 test implementations—such as original_test, seasonal_test, and various modification tests for serial autocorrelation (Hamed and Rao, Yue and Wang, Pre-Whitening)—along with Sen's slope estimators (sens_slope and seasonal_sens_slope) to determine trend magnitude.

Tokens
2K
Snippets
5
Records
9
Agent score
54%

What's inside pyMannKendall

  1. Overview of pyMannKendall test functions

    master

    The pyMannKendall package provides a suite of non-parametric trend analysis tools implemented in pure Python using a vectorization approach for performance. It includes 11 different Mann-Kendall (MK) tests to handle various data characteristics like serial correlation, seasonality, and multivariate parameters, as well as 2 Sen's slope estimators for magnitude calculation.

    Mann-Kendall Trend Tests

    • original_test: The standard non-parametric test; does not account for serial correlation or seasonality.
    • hamed_rao_modification_test: Addresses serial autocorrelation via a variance correction approach. Users can specify the number of significant lags to consider.
    • yue_wang_modification_test: Another variance correction method for serial autocorrelation; allows setting a specific number of significant lags.
    • pre_whitening_modification_test: Applies the Pre-Whitening method to the time series before testing.
    • trend_free_pre_whitening_modification_test: Removes trend components and then applies Pre-Whitening before testing.
    • multivariate_test: Designed for multiple parameters (e.g., seasonal MK tests where each month is a parameter).
    • seasonal_test: Calculates trends specifically for seasonal time series data.
    • regional_test: Calculates the overall trend on a regional scale based on seasonal MK principles.
    • correlated_multivariate_test: A multivariate test used when parameters are correlated.
    • correlated_seasonal_test: Used when time series significantly correlate with preceding months or seasons.
    • partial_test: Used to remove bias from independent parameters that affect the response parameter.

  2. Install pyMannKendall

    master

    You can install pyMannKendall using pip or conda. The package requires numpy and scipy as dependencies.

    Using pip (Linux):

    sudo pip install pymannkendall

    Using pip (Windows):

    pip install pymannkendall

    Using conda:

    conda install -c conda-forge pymannkendall

    Installing from source:

    git clone https://github.com/mmhs013/pymannkendall
cd pymannkendall
python setup.py install
    pip install pymannkendall

  3. Use pyMannKendall for trend analysis

    master

    To perform a Mann-Kendall trend test, import the package and pass your data (as a list, numpy array, or pandas series) to one of the test functions. The results are returned as a named tuple, allowing you to access specific metrics by name or unpack them directly.

    import numpy as np
import pymannkendall as mk

# Generate sample data
data = np.random.rand(360, 1)

# Perform the original Mann-Kendall test
result = mk.original_test(data)

# Access results by name
print(f"Trend: {result.trend}")
print(f"Slope: {result.slope}")

# Or unpack the results directly
trend, h, p, z, Tau, s, var_s, slope, intercept = mk.original_test(data)
    import numpy as np
import pymannkendall as mk

data = np.random.rand(360,1)
result = mk.original_test(data)
print(result)
print(result.slope)

  4. Mann-Kendall test functions and parameters

    master

    The package provides 11 different Mann-Kendall test implementations to handle various data conditions like serial correlation, seasonality, and multivariate parameters.

    Common Input Parameters

    Most test functions accept the following arguments:

    • x: The input data (vector, list, numpy array, or pandas series).
    • alpha: Significance level (default is 0.05).
    • lag: Number of first significant lags (only for hamed_rao_modification_test and yue_wang_modification_test).
    • period: Seasonal cycle (e.g., 12 for monthly, 52 for weekly). Only available in seasonal tests.

    Available Tests

    1. original_test: Standard non-parametric test (no serial correlation or seasonal effects considered).
    2. hamed_rao_modification_test: Addresses serial autocorrelation via variance correction.
    3. yue_wang_modification_test: Variance correction for serial autocorrelation.
    4. pre_whitening_modification_test: Uses Pre-Whitening before the test.
    5. trend_free_pre_whitening_modification_test: Removes trend component before Pre-Whitening.
    6. multivariate_test: For multiple parameters (e.g., seasonal MK where each month is a parameter).
    7. seasonal_test: Calculates seasonal trends.
    8. regional_test: Calculates overall trends on a regional scale.
    9. correlated_multivariate_test: For correlated parameters.
    10. correlated_seasonal_test: For time series significantly correlated with preceding seasons.
    11. partial_test: Accounts for independent parameters affecting the response parameter.

    Slope Estimators

    • sens_slope: Estimates the magnitude of the monotonic trend.
    • seasonal_sens_slope: Estimates trend magnitude for seasonal data (default period=12).

  5. Estimate trend magnitude with Sen's slope estimators

    master

    To estimate the magnitude of a monotonic trend, pyMannKendall provides two Sen's slope estimator functions:

    1. sens_slope: The standard Theil-Sen's slope estimator for monotonic trends.
    2. seasonal_sens_slope: An estimator designed for data that exhibits seasonal effects.

  6. Reference: Mann-Kendall test output format

    master

    Mann-Kendall test functions return a namedtuple containing the following fields:

    • trend: The direction of the trend (increasing, decreasing, or no trend).
    • h: Boolean indicating if a trend is present (True) or absent (False).
    • p: The p-value of the significance test.
    • z: Normalized test statistics.
    • Tau: Kendall Tau.
    • s: Mann-Kendall's score.
    • var_s: Variance S.
    • slope: Theil-Sen estimator/slope.
    • intercept: Intercept of the Kendall-Theil Robust Line (for seasonal tests, the full period cycle is considered a unit time step).

  7. Perform Modified Mann-Kendall Tests for Autocorrelated Data

    master

    When your data shows autocorrelation (e.g., visible in an ACF plot), use a modified Mann-Kendall test to avoid false positives. The package provides several options:

    1. Hamed and Rao Modified MK Test: mk.hamed_rao_modification_test(data)
    2. Yue and Wang Modified MK Test: mk.yue_wang_modification_test(data)
    3. Trend Free Pre-Whitening (TFPW) Test: mk.trend_free_pre_whitening_modification_test(data)
    4. Pre-Whitening Test: mk.pre_whitening_modification_test(data)

    Example using Hamed and Rao to plot a trend line:

    import pymannkendall as mk
import matplotlib.pyplot as plt
import numpy as np

res = mk.hamed_rao_modification_test(data)
# Calculate trend line using slope and intercept from result
trend_line = np.arange(len(data)) * res.slope + res.intercept

fig, ax = plt.subplots(figsize=(12, 8))
ax.plot(data)
ax.plot(data.index, trend_line)
ax.legend(['data', 'trend line'])
plt.show()
    mk.hamed_rao_modification_test(data)

  8. Perform the Original Mann-Kendall Test

    master

    Use mk.original_test() to detect trends in time series data when you assume there is no autocorrelation present. You can specify the significance level using the alpha parameter.

    Example usage:

    import pymannkendall as mk
import pandas as pd

# Assuming Birth_data is a pandas Series or DataFrame
result = mk.original_test(Birth_data, alpha=0.05)
print(result)

    Interpreting results:

    • If h is True, a significant trend exists.
    • If p (p-value) is less than alpha, the trend is statistically significant.
    • The trend field indicates if the trend is 'increasing' or 'decreasing'.
    • The slope field provides the value of the trend.
    mk.original_test(Birth_data, alpha=0.05)

  9. Perform the Seasonal Mann-Kendall Test

    master

    For datasets with noticeable seasonality (e.g., monthly data), use mk.seasonal_test(). You must provide the period parameter to account for the seasonal cycle.

    Example usage (Monthly data):

    import pymannkendall as mk

# For monthly data, period=12
res = mk.seasonal_test(Passenger_data, period=12)

# To plot the trend line for seasonal data:
# Note: the slope is scaled by the period
trend_line = np.arange(len(Passenger_data)) / 12 * res.slope + res.intercept
    mk.seasonal_test(Passenger_data, period=12)