Mann Kendall Automated (MKA)

Automated Trend Analysis for Environmental Engineering and Geology

🌐 Live Demo | 📖 Documentation | 🐛 Report Bug | ✨ Request Feature

Mann Kendall Automated (MKA) is a comprehensive Python tool for performing the Mann-Kendall statistical test on time series data. Designed specifically for environmental engineering and geology applications, it automates trend detection in datasets such as:

• 🏭 Groundwater monitoring data
• 🧪 Contaminant concentration trends
• 🌡️ Temperature and pH measurements
• 💧 Well water quality assessments
• 📊 Any time-series environmental data

✅ Save Time: Automate what used to take hours in spreadsheets ✅ Reliable: Implements standard Mann-Kendall methodology with Sen's slope ✅ Flexible: Web interface, CLI, or Python API ✅ Visual: Interactive plots with Plotly ✅ Robust: Handles missing data, detection limits, and data validation

• 🖥️ Web Interface: Beautiful Streamlit web application with drag-and-drop file upload
• ⌨️ CLI Tool: Command-line interface for batch processing and automation
• 📊 Export Results: Download results as Excel, CSV, or JSON
• 📈 Interactive Visualizations: Dynamic trend plots with Plotly
• ✅ Data Validation: Automatic detection and reporting of invalid data
• 🔬 Statistical Rigor: Proper Mann-Kendall implementation with seasonal variant support
• 🎯 Sen's Slope: Trend magnitude estimation included
• 🔄 Batch Processing: Analyze multiple wells and components simultaneously
• ⚡ Performance: Optimized with caching for repeated analyses

If this project helps you, please consider supporting it!

pip install mann-kendall-automated

git clone https://github.com/gabrielclimb/mann_kendall_automated.git
cd mann_kendall_automated
pip install -e .

Option 1: Using pip (recommended)

git clone https://github.com/gabrielclimb/mann_kendall_automated.git
cd mann_kendall_automated
pip install -e ".[dev]"
pre-commit install  # Set up git hooks

Option 2: Using uv (Recommended)

git clone https://github.com/gabrielclimb/mann_kendall_automated.git
cd mann_kendall_automated
# Install dependencies including dev
uv sync

To build the documentation:

pip install -e ".[docs]"
cd docs
sphinx-build -b html . _build/html
# Open docs/_build/html/index.html in your browser

Launch the interactive web interface:

streamlit run app.py

Or try the live demo hosted on Streamlit Cloud!

Features:

• Drag-and-drop file upload
• Real-time data validation
• Interactive trend plots
• Download results as Excel/CSV

Perfect for automation and batch processing:

# Analyze a file (outputs to <filename>_mann_kendall_results.xlsx)
mann-kendall data.xlsx

# Specify output file
mann-kendall data.xlsx -o results.xlsx

# Export as CSV
mann-kendall data.xlsx --format csv

# Verbose mode with summary
mann-kendall data.xlsx --verbose --summary

# Enable debug logging
mann-kendall data.xlsx --log-level DEBUG

# Save logs to file
mann-kendall data.xlsx --log-file analysis.log

# JSON export for further processing
mann-kendall data.xlsx --format json -o results.json

Use MKA programmatically in your scripts:

import mann_kendall as mka
import numpy as np

# Simple trend test
data = np.array([1.2, 1.4, 1.3, 1.7, 1.9, 2.1, 2.3])
result = mka.mk_test(data)

print(f"Trend: {result.trend}")
print(f"Statistic: {result.statistic}")
print(f"Confidence: {result.confidence_factor:.2%}")
print(f"Sen's Slope: {result.slope}")

# Load and process Excel file
df = mka.load_excel_data("monitoring_data.xlsx")
results, transposed_data = mka.generate_mann_kendall(df)

# Export results
results.to_excel("analysis_results.xlsx", index=False)

Your Excel file should follow this structure:

Format Requirements:

• First row: Well names (column headers)
• First column: Dates in any standard format (YYYY-MM-DD, MM/DD/YYYY, etc.)
• Subsequent rows: Component names and measurements
• Special values:
  • ND, N/D, NOT DETECTED → Treated as 0.5 (configurable)
  • <0.01 → Detection limit used (0.01)
  • Empty cells → Ignored in analysis

📁 Example Files: Check the examples/ directory for sample datasets you can use to test MKA.

MKA generates a comprehensive results table with:

Trend Classifications:

• increasing - Strong increasing trend (>95% confidence)
• decreasing - Strong decreasing trend (>95% confidence)
• probably increasing - Moderate increasing trend (90-95% confidence)
• probably decreasing - Moderate decreasing trend (90-95% confidence)
• no trend - No statistically significant trend (<90% confidence)

The project follows a modular architecture:

mann_kendall_automated/
├── app.py                  # Main entry point for Streamlit app
├── mann_kendall/           # Main package
│   ├── core/               # Core functionality
│   │   ├── mann_kendall.py # Statistical implementation
│   │   └── processor.py    # Data processing logic
│   ├── data/               # Data handling
│   │   ├── loader.py       # File loading functionality
│   │   └── cleaner.py      # Data cleaning
│   ├── ui/                 # UI components
│   │   ├── app.py          # Streamlit app
│   │   ├── visualizer.py   # Plotting functionality
│   │   └── download.py     # Export functionality
│   └── utils/              # Utilities
│       └── progress.py     # Progress bar
├── scripts/                # CLI scripts
│   └── mann_kendall_cli.py # Command line interface
├── tests/                  # Unit and integration tests
└── examples/               # Example data and notebooks

For developers:

1. Create a virtual environment: python -m venv venv
2. Activate it: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
3. Install with dev dependencies: pip install -e ".[dev]"
4. Run tests: pytest

Note: Now that the project includes [project.optional-dependencies], the pip install -e ".[dev]" command will work correctly to install all development dependencies.

MIT

• Core Mann-Kendall implementation adapted from code by Sat Kumar Tomer
• Original implementation based on the GSI Spreadsheet

Visit the MKA GitHub repository to learn more.