# 🌾 Winnow

[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)
[![Maintainability](https://img.shields.io/badge/maintainability-A-brightgreen.svg)](https://github.com/)

**The Intelligent Feature Selection Library for Machine Learning**

Winnow is a high-performance, modular Python library designed to separate the signal from the noise in your data. It provides both classic statistical criteria and state-of-the-art selection techniques like BorutaSHAP and mRMR, all wrapped in a clean, developer-friendly API.

---

## 🎯 Why Winnow?

In data science, more data isn't always better. Irrelevant or redundant features can lead to overfitting, slow training times, and poor model interpretability. Winnow helps you "winnow the wheat from the chaff," leaving you with only the most impactful features.

### ✨ Key Features

*   **⚡ Base Selection**: Correlation-based pruning, variance thresholding, and target relevancy.
*   **🧠 Advanced Techniques**: 
    *   **mRMR**: Minimum Redundancy Maximum Relevance for diverse feature sets.
    *   **BorutaSHAP**: Rigorous statistical selection using shadow features and SHAP values.
    *   **PCA Contribution**: Filter features based on their influence on principal components.
*   **🛠️ Custom Logic**: Easily register your own selection criteria into the pipeline.
*   **📊 Transparency**: Comprehensive reporting of why each feature was kept or removed.

---

## 📦 Installation

```bash
pip install winnow-ml
```

---

## 🚀 Quick Start

### Basic Selection

```python
import pandas as pd
from winnow import BaseSelector

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

# Initialize and transform
selector = BaseSelector(correlation_threshold=0.85)
result = selector.fit_transform(df, target_column='target')

print(f"Selected features: {result.selected_features}")
```

### Advanced Selection (Boruta + mRMR)

```python
from winnow import AdvancedSelector

selector = AdvancedSelector(
    use_borutashap=True, 
    n_boruta_trials=20,
    use_mrmr=True,
    n_mrmr_features=10
)

result = selector.fit_transform(X, y)
```

---

## 📁 Project Structure

```
winnow/
├── winnow/               # Core source code
│   ├── base_selector.py  # Core selection logic
│   ├── advanced_selector.py # Boruta, mRMR, and PCA
│   └── logger.py         # Centralized logging
├── examples/             # Real-world usage examples
├── tests/                # Robust test suite
└── README.md
```

---

## 📄 License

Winnow is released under the **MIT License**.