Metadata-Version: 2.4
Name: prolaboost
Version: 0.1.0
Summary: Hybrid time-series forecasting with Prophet, Lasso feature selection, and Gradient Boosting residual learning.
Author: Numan Yaqoob
License: MIT License
        
        Copyright (c) 2026 Numan Yaqoob
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Keywords: forecasting,time-series,prophet,lasso,gradient-boosting,machine-learning,hybrid-forecasting
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: matplotlib
Requires-Dist: prophet
Requires-Dist: scikit-learn
Dynamic: license-file

# ProLaBoost

**ProLaBoost** is a hybrid time-series forecasting Python package combining:

- Prophet for trend and seasonality modelling
- Polynomial interaction feature engineering
- Lasso for feature selection
- Gradient Boosting for Prophet residual learning

**ProLaBoost Forecast = Prophet Forecast + Predicted Residual Correction**

---

## Installation

    pip install prolaboost

---

## Quick Start

    from prolaboost import HybridForecaster

    model = HybridForecaster()

    model.fit(
        train_df,
        date_col="ds",
        target_col="y"
    )

    forecast = model.predict(test_df)

    print(forecast.head())

---

## Plot Forecast

    model.plot(
        forecast,
        actual_df=test_df,
        show_prophet=True,
        title="ProLaBoost Forecast"
    )

---

## Evaluate Performance

    results = model.evaluate(
        test_df,
        forecast
    )

    print(results)

Example synthetic-data results:

| Model | RMSE | MAE | R² |
|---|---:|---:|---:|
| Prophet | 3.8251 | 3.2029 | 0.3701 |
| ProLaBoost | 2.2423 | 1.7788 | 0.7835 |

In this demonstration, ProLaBoost reduced RMSE by approximately **41.38%** compared with Prophet.

> These results are illustrative and do not guarantee performance on other datasets.

---

## Input Data

ProLaBoost requires:

- A date/time column
- A target variable
- One or more predictor variables

Example:

| ds | y | x1 | x2 | x3 |
|---|---:|---:|---:|---:|
| 2025-01-01 | 25.4 | 1.2 | 4.1 | 2.7 |
| 2025-01-02 | 27.8 | 1.5 | 3.8 | 2.9 |

Default column names:

    ds = date/time
    y  = target

Custom column names are supported:

    model.fit(
        df,
        date_col="date",
        target_col="sales"
    )

---

## Methodology

    Input Data
        |
        v
    Prophet
        |
        v
    Prophet Residuals
        |
        v
    Polynomial Interaction Features
        |
        v
    Lasso Feature Selection
        |
        v
    Selected Features
        |
        v
    Gradient Boosting
        |
        v
    Residual Prediction
        |
        v
    Prophet Forecast + Residual Correction
        |
        v
    ProLaBoost Forecast

Prophet first captures the main temporal structure of the time series.

Residuals are calculated as:

    Residual = Actual - Prophet Forecast

Polynomial interaction features are generated from the predictor variables.

Lasso identifies useful predictors and interaction terms.

Gradient Boosting then learns remaining predictable structure in Prophet's residuals.

The final hybrid forecast is:

    ProLaBoost = Prophet + Boosting Residual Correction

---

## Main Parameters

    model = HybridForecaster(
        n_estimators=50,
        learning_rate=0.1,
        max_depth=3,
        lasso_cv=5,
        random_state=42,
        interval_width=0.95,
        weekly_seasonality=True,
        yearly_seasonality=False,
        daily_seasonality=False
    )

---

## Lasso Selected Features

    print(model.feature_summary())

You can also inspect the selected Lasso regularization parameter:

    print(model.selector_.alpha_)

---

## Forecast Output

The `predict()` method returns:

| Column | Description |
|---|---|
| `ds` | Date/time |
| `prophet` | Prophet baseline forecast |
| `residual_correction` | Gradient Boosting residual prediction |
| `yhat` | Final ProLaBoost forecast |
| `yhat_lower` | Approximate lower prediction interval |
| `yhat_upper` | Approximate upper prediction interval |

---

## Complete Example

    from prolaboost import HybridForecaster

    model = HybridForecaster()

    model.fit(
        train_df,
        date_col="ds",
        target_col="y"
    )

    forecast = model.predict(test_df)

    results = model.evaluate(
        test_df,
        forecast
    )

    print(results)

    model.plot(
        forecast,
        actual_df=test_df
    )

---

## Research Background

ProLaBoost is based on a hybrid forecasting approach combining Prophet decomposition, feature selection, and machine-learning-based residual correction.

The framework is designed to retain the interpretable temporal modelling capabilities of Prophet while using Lasso-selected predictors and Gradient Boosting to capture nonlinear structure remaining in Prophet residuals.

---

## Author

**Numan Yaqoob**

---

## License

MIT License
