🚀 Migration Guide to v3.0.0

Welcome to RegressionMadeSimple v3.0.0! This guide will help you upgrade from v2.x to take advantage of the new features and improvements.

📋 What's New in v3.0.0

1. Model Registry Pattern NEW

Models are now accessible through a dedicated models module:

• rms.models.Linear - Linear regression
• rms.models.Quadratic - Quadratic regression
• rms.models.Cubic - Cubic regression
• rms.models.CustomCurve - Custom curve fitting

2. Enhanced Base Class NEW

All models now inherit from an enhanced BaseModel that provides:

• Model Serialization: save_model() and load_model() methods
• Additional Metrics: r2_score(), mae(), rmse()
• Shared Functionality: Common train/test split logic and plotting
• Type Hints: Better IDE support and code clarity

3. Class-Based Model Specification RECOMMENDED

The new recommended way to specify models uses class references instead of strings.

🔄 Migration Steps

Step 1: Update Model Instantiation

import regressionmadesimple as rms

# Direct instantiation
model = rms.Linear(data, 'x', 'y')

# Using wrapper with string
model = rms.LinearRegressionModel.fit(
    data, 'x', 'y', 
    model='linear'
)

import regressionmadesimple as rms

# Direct instantiation (still works!)
model = rms.Linear(data, 'x', 'y')

# Or use model registry (recommended)
model = rms.models.Linear(data, 'x', 'y')

# Using wrapper with class
model = rms.LinearRegressionModel.fit(
    data, 'x', 'y', 
    model=rms.models.Linear
)

Step 2: Update Model Selection in Wrapper

# String-based model selection
models = ['linear', 'quadratic', 'cubic']

for model_name in models:
    model = rms.LinearRegressionModel.fit(
        data, 'x', 'y',
        model=model_name
    )

# Class-based model selection
models = [
    rms.models.Linear,
    rms.models.Quadratic,
    rms.models.Cubic
]

for model_class in models:
    model = rms.LinearRegressionModel.fit(
        data, 'x', 'y',
        model=model_class
    )

Step 3: Take Advantage of New Features

Model Serialization NEW

import regressionmadesimple as rms

# Train and save model
model = rms.models.Linear(data, 'x', 'y')
model.save_model('my_model.pkl')

# Load model later
from regressionmadesimple.models import BaseModel
loaded_model = BaseModel.load_model('my_model.pkl')

# Use loaded model
predictions = loaded_model.predict(new_data)

Additional Metrics NEW

# Get comprehensive model evaluation
summary = model.summary()
print(f"R² Score: {summary['r2_score']:.4f}")
print(f"RMSE: {summary['rmse']:.4f}")
print(f"MAE: {summary['mae']:.4f}")

# Or access metrics directly
print(f"R² Score: {model.r2_score()}")
print(f"Mean Absolute Error: {model.mae()}")
print(f"Root Mean Squared Error: {model.rmse()}")

⚠️ Breaking Changes

No other breaking changes! All existing functionality from v2.x continues to work in v3.0.0.

📚 Complete Migration Example

Before (v2.x)

import regressionmadesimple as rms
import pandas as pd

# Load data
data = pd.read_csv('data.csv')

# Fit model using string
model = rms.LinearRegressionModel.fit(
    data, 'x', 'y',
    model='quadratic',
    testsize=0.2
)

# Make predictions
predictions = model.predict(new_data)

# Get basic metrics
summary = model.summary()
print(f"MSE: {summary['mse']}")

After (v3.0.0)

import regressionmadesimple as rms
import pandas as pd

# Load data
data = pd.read_csv('data.csv')

# Fit model using class (new recommended way)
model = rms.LinearRegressionModel.fit(
    data, 'x', 'y',
    model=rms.models.Quadratic,  # ✅ Class-based
    testsize=0.2
)

# Make predictions
predictions = model.predict(new_data)

# Get comprehensive metrics (new in v3.0.0!)
summary = model.summary()
print(f"MSE: {summary['mse']}")
print(f"R² Score: {summary['r2_score']:.4f}")  # ✨ NEW
print(f"RMSE: {summary['rmse']:.4f}")          # ✨ NEW
print(f"MAE: {summary['mae']:.4f}")            # ✨ NEW

# Save model for later use (new in v3.0.0!)
model.save_model('quadratic_model.pkl')  # ✨ NEW

✅ Migration Checklist

1. ✅ Update imports to use rms.models.* for new projects
2. ✅ Replace string-based model specification (model='linear') with class-based (model=rms.models.Linear)
3. ✅ Take advantage of new features:
   • save_model() and load_model() for model persistence
   • r2_score(), mae(), rmse() for better evaluation
4. ✅ Test your existing code (it should work with deprecation warnings)
5. ✅ Plan complete migration before v4.0.0 (when legacy API will be removed)

🆘 Need Help?

If you encounter any issues during migration:

• 📖 Check the GitHub README for detailed examples
• 🐛 Report bugs on GitHub Issues
• 💬 Ask questions in GitHub Discussions

← Back to Home | View Changelog | GitHub Repository