# AutoScore

**AutoScore** is a comprehensive, automated Python library for building Credit Risk Scorecards. It streamlines the entire modeling lifecycle—from Exploratory Data Analysis (EDA) and Feature Engineering to Model Training, Evaluation, and Scorecard Generation—making it easy to develop professional-grade credit scoring models with minimal code.

## 🚀 Key Features

*   **End-to-End Automation**: One-line `fit()` to go from raw data to a production-ready scorecard.
*   **Intelligent Binning**:
    *   **ChiMerge** algorithm with automatic trend detection.
    *   **Monotonicity Constraints**: Enforce strictly increasing/decreasing bad rates.
    *   **Visual Adjustment**: Interactive plots to manually fine-tune bins.
*   **Robust Feature Selection**:
    *   IV (Information Value) filtering.
    *   Stepwise Logistic Regression (optimized for convergence).
*   **Advanced Evaluation**:
    *   **PSI (Population Stability Index)** calculation for Train, Test, and OOT (Out-of-Time) datasets.
    *   AUC, KS statistics.
*   **Production Ready**:
    *   Standard Scorecard format export (Excel).
    *   Model persistence (save/load).
    *   OOT sample splitting support.

## 📦 Installation

```bash
pip install autoscore
```

## ⚡ Quick Start

### 1. Standard Pipeline

```python
import pandas as pd
from autoscore import AutoScore

# Load your dataset
df = pd.read_csv('german_credit_data.csv')

# Initialize AutoScore
score = AutoScore(random_state=42)

# Fit the model
score.fit(
    X=df.drop(columns=['target']),
    y=df['target'],
    test_size=0.3,
    selection_method='stepwise',
    iv_threshold=0.02,
    max_bins=5,
    pdo=20, base_score=600, base_odds=50
)

# Generate Excel Report
score.create_report('scorecard_report.xlsx')
```

### 2. Advanced Usage: OOT Split & Constraints

```python
# Define Monotonicity Constraints
# 1: Increasing Risk, -1: Decreasing Risk, 0: Auto
constraints = {
    'duration': 1,       
    'age': -1            
}

score.fit(
    X=df.drop(columns=['target']),
    y=df['target'],
    date_col='create_time',        # Column for time-based split
    oot_split_date='2023-10-01',   # Date to split OOT
    monotonicity_constraints=constraints
)
```

### 3. Visual Binning Adjustment

Visualize the binning results and adjust rules manually if needed.

```python
# Visualize 'duration' binning
score.visualize_binning('duration', filename='duration_plot.png')

# Manually adjust cutoffs
new_rules = {
    'duration': {'cutoffs': [12, 24, 36]}
}
score.adjust_rules(new_rules, X_train, y_train)
```

### 4. Standalone Components

You can use specific modules independently.

```python
from autoscore import BinningProcess

# Independent Binning
binning = BinningProcess(max_bins=5)
binning.fit(X, y)
X_woe = binning.transform(X)
```

## 📊 Report Output

The generated `scorecard_report.xlsx` includes:
*   **Summary**: Data shape, target distribution.
*   **IV Analysis**: Information Value for all features.
*   **Model Performance**: AUC, KS, PSI for Train/Test/OOT.
*   **Scorecard**: The final points table for implementation.
*   **Model Coefficients**: Logistic Regression weights.

## 🛠 Dependencies

*   pandas
*   numpy
*   scikit-learn
*   matplotlib
*   openpyxl
*   joblib

## 📄 License

MIT License
