Metadata-Version: 2.4
Name: ngocbienml
Version: 2.1.2
Summary: An ecosystem for machine learning project with regression and classification support
Home-page: https://github.com/ngocbien/ngocbienml
Author: Nguyen Ngoc Bien
Author-email: ngocbien.nguyen.vn@gmail.com
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.6
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: scikit-learn>=0.24.0
Requires-Dist: scipy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: seaborn
Requires-Dist: lightgbm
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ngocbienml - Machine Learning Ecosystem

![Version](https://img.shields.io/badge/version-2.1.2-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Python](https://img.shields.io/badge/python-3.6%2B-blue)

A comprehensive Python library for machine learning projects with support for classification and regression tasks. Provides easy-to-use pipelines, multiple model implementations, and comprehensive evaluation metrics.

## Features

### New in Version 2.1.2
- **Regression Models**: Linear, Ridge, Lasso, ElasticNet, SVR, Random Forest, Gradient Boosting, LightGBM
- **Regression Metrics**: MSE, RMSE, MAE, MAPE, RÂ², Adjusted RÂ²
- **Improved Architecture**: Clean base classes with proper design patterns
- **Comprehensive Tests**: Full test suite with pytest
- **Better Error Handling**: Proper validation and error messages
- **Type Hints**: Full type annotations for better IDE support
- **Backward Compatible**: All original features still work

### Core Features
- **Multiple Regression Models**: Choose from 8+ regression algorithms
- **Classification Pipelines**: Binary and multiclass classification support
- **Data Preprocessing**: Fill missing values, encode labels, scale features, select features
- **Model Evaluation**: Comprehensive metrics for both classification and regression
- **Visualization**: Plot feature importance, AUC curves, and metrics
- **Pipeline Support**: Build complex preprocessing and model pipelines easily
- **K-Fold Cross Validation**: Built-in cross-validation support

## Installation

### Option 1: Install from PyPI

```bash
pip install ngocbienml
```

### Option 2: Install from source with `requirements.txt`

```bash
git clone https://github.com/ngocbien/ngocbienml.git
cd ngocbienml
pip install -r requirements.txt
pip install -e .
```

### Option 3: Create a Conda environment

```bash
conda create -n ngocbienml python=3.10
conda activate ngocbienml
pip install -r requirements.txt
pip install -e .
```

### Development setup

```bash
pip install -e ".[dev]"
```

## Quick Start

### Regression Models

#### Basic Linear Regression
```python
from ngocbienml import LinearRegressionModel
import pandas as pd
from sklearn.datasets import load_diabetes

# Load data
diabetes = load_diabetes()
X = pd.DataFrame(diabetes.data, columns=diabetes.feature_names)
y = diabetes.target

# Create and train model
model = LinearRegressionModel(verbose=True)
model.fit(X, y)

# Make predictions
predictions = model.predict(X)

# Evaluate (automatic with verbose=True during fit)
metrics = model.score(X, y)
```

#### Using Model Factory
```python
from ngocbienml import create_regression_model

# Easy model creation with factory function
model = create_regression_model('ridge', alpha=1.0)
model.fit(X_train, y_train)

# Supported models:
# 'linear', 'ridge', 'lasso', 'elasticnet', 'svr', 'rf', 'gb', 'lgbm'
```

#### Available Regression Models

1. **Linear Regression**
```python
from ngocbienml import LinearRegressionModel
model = LinearRegressionModel()
```

2. **Ridge Regression** (L2 regularization)
```python
from ngocbienml import RidgeRegressionModel
model = RidgeRegressionModel(alpha=1.0)
```

3. **Lasso Regression** (L1 regularization)
```python
from ngocbienml import LassoRegressionModel
model = LassoRegressionModel(alpha=0.1)
```

4. **ElasticNet** (L1 + L2 regularization)
```python
from ngocbienml import ElasticNetModel
model = ElasticNetModel(alpha=1.0, l1_ratio=0.5)
```

5. **Support Vector Regression**
```python
from ngocbienml import SVRModel
model = SVRModel(kernel='rbf', C=1.0)
```

6. **Random Forest Regression**
```python
from ngocbienml import RandomForestRegressionModel
model = RandomForestRegressionModel(n_estimators=100)
```

7. **Gradient Boosting Regression**
```python
from ngocbienml import GradientBoostingRegressionModel
model = GradientBoostingRegressionModel(n_estimators=100)
```

8. **LightGBM Regression**
```python
from ngocbienml import LGBMRegressionModel
model = LGBMRegressionModel()
```

### Regression Metrics

Get comprehensive regression metrics:

```python
from ngocbienml import regression_score, RegressionMetrics
import numpy as np

# Automatic evaluation with train/test split
metrics = regression_score(model, X_train, y_train, X_test, y_test)
# Returns: {'train': {...}, 'test': {...}}

# Or calculate individual metrics
y_pred = model.predict(X)
mse = RegressionMetrics.mean_squared_error(y, y_pred)
rmse = RegressionMetrics.root_mean_squared_error(y, y_pred)
mae = RegressionMetrics.mean_absolute_error(y, y_pred)
r2 = RegressionMetrics.r2_score_metric(y, y_pred)

# All metrics at once
all_metrics = RegressionMetrics.calculate_all_metrics(y, y_pred, n_features=10)
# Keys: MSE, RMSE, MAE, MAPE, RÂ², Adjusted RÂ²
```

### Classification Models

```python
from ngocbienml import MyPipeline
import pandas as pd

# Create pipeline with preprocessing and model
pipeline = MyPipeline(objective="binary", model_name='lgb')
pipeline.fit(X_train, y_train)

# Evaluate
pipeline.score(X_test, y_test)

# Make predictions
predictions = pipeline.predict(X_test)
probabilities = pipeline.predict_proba(X_test)
```

### Data Preprocessing

Use individual preprocessing components:

```python
from ngocbienml import Fillna, LabelEncoder, MinMaxScale, FeatureSelection
from sklearn.pipeline import Pipeline

# Create custom pipeline
steps = [
    ('fillna', Fillna(method='mean')),
    ('label_encoder', LabelEncoder()),
    ('scale', MinMaxScale()),
    ('feature_selection', FeatureSelection(threshold=0.01))
]

pipeline = Pipeline(steps=steps)
X_transformed = pipeline.fit_transform(X_train)
X_test_transformed = pipeline.transform(X_test)
```

### K-Fold Cross Validation

```python
from ngocbienml import PipelineKfold

# Create pipeline with K-Fold CV
pipeline = PipelineKfold(objective='binary', name='lgb')
pipeline.fit(X, y)
pipeline.score(X_test, y_test)
```

## Model Comparison

Easily compare multiple regression models:

```python
from ngocbienml import (
    LinearRegressionModel,
    RidgeRegressionModel,
    RandomForestRegressionModel,
    GradientBoostingRegressionModel
)
from sklearn.metrics import mean_squared_error

models = [
    ('Linear', LinearRegressionModel()),
    ('Ridge', RidgeRegressionModel()),
    ('RF', RandomForestRegressionModel()),
    ('GB', GradientBoostingRegressionModel()),
]

for name, model in models:
    model.verbose = False
    model.fit(X_train, y_train)
    predictions = model.predict(X_test)
    rmse = np.sqrt(mean_squared_error(y_test, predictions))
    print(f'{name:.<20} RMSE: {rmse:.4f}')
```

## Advanced Usage

### Custom Preprocessing Pipeline with Regression

```python
from ngocbienml import Fillna, MinMaxScale, LinearRegressionModel
from sklearn.pipeline import Pipeline

steps = [
    ('fillna', Fillna()),
    ('scale', MinMaxScale()),
    ('model', LinearRegressionModel())
]

pipeline = Pipeline(steps=steps)
pipeline.fit(X_train, y_train)
pipeline.score(X_test, y_test)
```

### Save and Load Models

```python
from joblib import dump, load

# Save
dump(model, 'my_model.pkl')

# Load
model = load('my_model.pkl')
predictions = model.predict(X_test)
```

## Regression Metrics Explained

| Metric | Formula | Interpretation |
|--------|---------|-----------------|
| **MSE** | Mean((y - Å·)Â²) | Lower is better |
| **RMSE** | âˆšMSE | In same units as y |
| **MAE** | Mean(\|y - Å·\|) | Average error magnitude |
| **MAPE** | Mean(\|y - Å·\|/y) | Percentage error |
| **RÂ²** | 1 - SS_res/SS_tot | 0-1, higher is better |
| **Adj RÂ²** | Adjusted for features | Better for comparison |

## Testing

Run the comprehensive test suite:

```bash
# Install test dependencies
pip install -e ".[dev]"

# Run tests
pytest test/

# Run tests with coverage
pytest --cov=ngocbienml test/
```

## Architecture Improvements

### Version 2.1.0 Improvements
1. **Clean Architecture**: Separated concerns with base classes
2. **Factory Pattern**: Easy model creation with `create_regression_model()`
3. **Type Hints**: Full type annotations for IDE support
4. **Error Handling**: Proper validation with clear error messages
5. **Logging**: Replace print statements with proper logging
6. **Documentation**: Comprehensive docstrings and examples
7. **Testing**: Full test coverage with pytest
8. **Backward Compatibility**: All original features still work

### Base Classes
```python
from ngocbienml import BaseModel, RegressionModel, ClassificationModel

# All models inherit from these base classes
# Provides common interface and validation
```

## Examples

### Example 1: House Price Prediction
```python
from ngocbienml import create_regression_model
import pandas as pd

# Load data
data = pd.read_csv('house_prices.csv')
X = data.drop('price', axis=1)
y = data['price']

# Train multiple models and compare
for model_type in ['linear', 'ridge', 'rf', 'gb']:
    model = create_regression_model(model_type)
    model.fit(X, y)
    score = model.score(X, y)
```

### Example 2: Classification with Pipeline
```python
from ngocbienml import MyPipeline
import pandas as pd

data = pd.read_csv('classification_data.csv')
X = data.drop('target', axis=1)
y = data['target']

# Train with automatic preprocessing
pipeline = MyPipeline(objective='binary', model_name='lgb')
pipeline.fit(X, y)
predictions = pipeline.predict(X_test)
```

### Example 3: Custom Preprocessing
```python
from ngocbienml import (
    Fillna, LabelEncoder, MinMaxScale, FeatureSelection,
    LinearRegressionModel
)
from sklearn.pipeline import Pipeline

# Build custom pipeline
steps = [
    ('fillna', Fillna(method='median')),
    ('label_encode', LabelEncoder()),
    ('scale', MinMaxScale()),
    ('feature_select', FeatureSelection(threshold=0.05)),
    ('model', LinearRegressionModel(verbose=True))
]

custom_pipeline = Pipeline(steps)
custom_pipeline.fit(X_train, y_train)
predictions = custom_pipeline.predict(X_test)
```

## API Reference

### Regression Models
- `LinearRegressionModel`
- `RidgeRegressionModel(alpha)`
- `LassoRegressionModel(alpha)`
- `ElasticNetModel(alpha, l1_ratio)`
- `SVRModel(kernel, C, gamma)`
- `RandomForestRegressionModel(n_estimators, max_depth)`
- `GradientBoostingRegressionModel(n_estimators, learning_rate)`
- `LGBMRegressionModel(params)`
- `create_regression_model(model_type, **kwargs)`

### Metrics
- `RegressionMetrics.mean_squared_error(y_true, y_pred)`
- `RegressionMetrics.root_mean_squared_error(y_true, y_pred)`
- `RegressionMetrics.mean_absolute_error(y_true, y_pred)`
- `RegressionMetrics.r2_score_metric(y_true, y_pred)`
- `regression_score(model, X_train, y_train, X_test, y_test)`

### Preprocessing
- `Fillna(method='mean')`
- `LabelEncoder()`
- `MinMaxScale()`
- `FeatureSelection(threshold=0.01)`
- `FillnaAndDropCatFeat()`
- `AssertGoodHeader()`

### Classification
- `MyPipeline(objective, model_name)`
- `PipelineKfold(objective, name, params)`
- `ModelWithPipeline(objective, model_name, params)`

## Performance Tips

1. **Scale your data**: Use MinMaxScale or StandardScaler for better results
2. **Handle missing values**: Use Fillna with appropriate method
3. **Feature selection**: Remove low-variance and highly-correlated features
4. **Choose the right model**: Start with simple models, then try complex ones
5. **Regularization**: Use Ridge/Lasso for high-dimensional data
6. **Hyperparameter tuning**: Use GridSearchCV or RandomizedSearchCV

## Troubleshooting

### Model not fitting
- Ensure X and y have same length
- Check data types (should be numeric)
- Verify no infinite or NaN values

### Poor model performance
- Try different models
- Adjust hyperparameters
- Increase training data
- Better feature engineering

### Memory issues with large datasets
- Use LGBMRegressor (memory efficient)
- Reduce number of features
- Use sample_weight or class_weight

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

## License

MIT License - see LICENSE file for details

## Citation

If you use ngocbienml in your research, please cite:

```bibtex
@software{ngocbienml2024,
  author = {Nguyen Ngoc Bien},
  title = {ngocbienml: Machine Learning Ecosystem},
  year = {2024},
  url = {https://github.com/ngocbien/ngocbienml}
}
```

## Contact

Author: Nguyen Ngoc Bien  
Email: ngocbien.nguyen.vn@gmail.com  
GitHub: https://github.com/ngocbien/ngocbienml
