ngocbienml - Machine Learning Ecosystem

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.3

• Regression Models: Linear, Ridge, Lasso, ElasticNet, SVR, Random Forest, Gradient Boosting, LightGBM
• Regression Metrics: MSE, RMSE, MAE, MAPE, R-squared, Adjusted R-squared
• 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

pip install ngocbienml

Option 2: Install from source with requirements.txt

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

Option 3: Create a Conda environment

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

Development setup

pip install -e ".[dev]"

Quick Start

Regression Models

Basic Linear Regression

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

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

from ngocbienml import LinearRegressionModel
model = LinearRegressionModel()

2. Ridge Regression (L2 regularization)

from ngocbienml import RidgeRegressionModel
model = RidgeRegressionModel(alpha=1.0)

3. Lasso Regression (L1 regularization)

from ngocbienml import LassoRegressionModel
model = LassoRegressionModel(alpha=0.1)

4. ElasticNet (L1 + L2 regularization)

from ngocbienml import ElasticNetModel
model = ElasticNetModel(alpha=1.0, l1_ratio=0.5)

5. Support Vector Regression

from ngocbienml import SVRModel
model = SVRModel(kernel='rbf', C=1.0)

6. Random Forest Regression

from ngocbienml import RandomForestRegressionModel
model = RandomForestRegressionModel(n_estimators=100)

7. Gradient Boosting Regression

from ngocbienml import GradientBoostingRegressionModel
model = GradientBoostingRegressionModel(n_estimators=100)

8. LightGBM Regression

from ngocbienml import LGBMRegressionModel
model = LGBMRegressionModel()

Regression Metrics

Get comprehensive regression metrics:

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-squared, Adjusted R-squared

Classification Models

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:

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

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:

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

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

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	Description	Interpretation
MSE	Mean of squared errors	Lower is better
RMSE	Square root of MSE	In same units as y
MAE	Mean of absolute errors	Average error magnitude
MAPE	Mean absolute percentage error	Percentage error
R-squared	Coefficient of determination (0 to 1)	Higher is better
Adj R-squared	R-squared adjusted for features	Better for comparison

Testing

Run the comprehensive test suite:

# 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

from ngocbienml import BaseModel, RegressionModel, ClassificationModel

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

Examples

Example 1: House Price Prediction (Regression)

from ngocbienml import create_regression_model
import pandas as pd
from sklearn.datasets import fetch_california_housing

# Load data
housing = fetch_california_housing()
X = pd.DataFrame(housing.data, columns=housing.feature_names)
y = housing.target

# 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

from ngocbienml import MyPipeline
import pandas as pd
from sklearn.datasets import load_breast_cancer
from sklearn.model_selection import train_test_split

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

X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2, random_state=42)

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

Example 3: Custom Preprocessing

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:

@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