Metadata-Version: 2.2
Name: teda-temporal
Version: 0.1.0
Summary: Temporal EDA for feature drift, PCA, breakpoints, and trends
Author: Tergel
Project-URL: Homepage, https://github.com/tergelitu/teda
Project-URL: Repository, https://github.com/tergelitu/teda
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.3.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: plotly>=5.0.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: xgboost>=1.5.0
Requires-Dist: ruptures>=1.1.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: ipywidgets>=7.6.0

# TEDA - Temporal Exploratory Data Analysis

A Python package for temporal feature analysis and drift detection.

## Features

### 1. **Feature Overview Table**
- Comprehensive statistics for all features
- Missing values, zero rates, unique percentages
- Volatility and PSI (Population Stability Index) tracking
- Correlation with target variable

### 2. **Monthly PSI Tracking**
- Track Population Stability Index over time
- Automatic threshold warnings

### 3. **3D PCA Visualization**
- Monthly mean projection in PCA space
- Travel distance bar chart showing monthly movement

### 4. **Structural Breakpoint Detection**
- Uses Ruptures library for changepoint detection
- Monthly aggregation with PELT/Binseg/Dynp algorithms
- Visual breakpoint markers on time series

### 5. **Feature Importance Evolution**
- Track feature importance over time
- Multiple models: RandomForest & XGBoost

### 6. **HP Filter Decomposition**
- Hodrick-Prescott filter for trend extraction
- Seasonal pattern detection
- Residual analysis

## Installation

```bash
pip install teda
```

Or install from source:
```bash
git clone https://github.com/tergelitu/teda.git
cd teda
pip install -e .
```

## Requirements

- Python 3.8+
- pandas >= 1.3.0
- numpy >= 1.21.0
- plotly >= 5.0.0
- scikit-learn >= 1.0.0
- xgboost >= 1.5.0
- ruptures >= 1.1.0
- statsmodels >= 0.13.0
- ipywidgets >= 7.6.0

## 📖 Quick Start

**See full example usage in [teda-demo.ipynb](teda-demo.ipynb)**

```python
import pandas as pd
import teda as te

# Load your data
df = pd.read_csv('your_data.csv')

# 1. Feature Overview
te.overview_table(df, date_col='date', target_col='target', exclude_cols=['id'])

# 2. PSI Tracking
te.plot_monthly_psi(df, date_col='date', feature_col='col')

# 3. 3D PCA Visualization
te.plot_monthly_pca(df, date_col='date', exclude_cols=['id', 'target'])

# 4. Structural Breakpoints
te.detect_change_points(df, date_col='date', feature_col='col', model='l2')

# 5. Feature Importance Evolution
te.plot_monthly_importance(df, date_col='date', target_col='target', feature_name='col')

# 6. HP Filter Decomposition
te.plot_hp_decomposition(df, date_col='date', feature_col='col')
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Author

**Tergel Munkhbaatar**
- GitHub: [@tergelitu](https://github.com/tergelitu)

## Use Cases

- **Model Monitoring**: Track feature drift in production ML systems
- **Data Quality**: Identify distribution shifts and anomalies
- **Feature Engineering**: Understand temporal patterns and breakpoints
- **Exploratory Analysis**: Quick overview of time-series feature behavior

---

**Star ⭐ this repo if you find it useful!**
