Piecewise Regression

Common errors

• ModuleNotFoundError: No module named 'piecewise_regression'

  cause The piecewise-regression library is not installed or the Python environment where the script is run does not have it installed.
  fix Install the library using pip: `pip install piecewise-regression`. Ensure you are in the correct virtual environment if you are using one.

• ValueError: n_breakpoints must be a positive integer less than number_of_data_points - 2

  cause The specified `n_breakpoints` is either zero, negative, or too large relative to the number of data points, making it statistically impossible or ill-defined to fit segments.
  fix Ensure `n_breakpoints` is a positive integer and `n_breakpoints < len(x) - 2`. For example, with 5 data points, `n_breakpoints` can be at most 2. Start with `n_breakpoints=1` for basic breakpoint detection.

• NameError: name 'PiecewiseRegression' is not defined

  cause The `PiecewiseRegression` class was used without being correctly imported from the library.
  fix Add the import statement at the top of your script: `from piecewise_regression import PiecewiseRegression`.

Warnings

• gotcha The Davies test for the existence of breakpoints was modified in v1.5.0 to use the Wald test statistic. This change affects the underlying methodology and may result in different p-values and statistical conclusions for breakpoint detection compared to versions prior to 1.5.0.
  Fix: Be aware that statistical results related to breakpoint significance might differ. Refer to the v1.5.0 release notes and cited literature (Muggeo, 2008) for details on the new methodology.
• gotcha Choosing the correct number of breakpoints (`n_breakpoints`) is crucial. Incorrectly specifying this parameter can lead to overfitting (too many breakpoints) or underfitting (too few), resulting in a poor model fit and misleading conclusions.
  Fix: Start with a reasonable number based on domain knowledge or visual inspection of the data. Use statistical tests provided by the library (e.g., Davies test for 1 breakpoint) or information criteria (e.g., AIC, BIC) for model selection, though these are not directly implemented for breakpoint count in the library itself.
• gotcha The optimization process for finding breakpoints and regression coefficients can sometimes fail to converge, especially with noisy data, sparse data, or poorly chosen initial parameters. This might lead to warnings or incorrect results.
  Fix: Inspect any warnings during the `fit()` process. Consider pre-processing your data, checking for outliers, or experimenting with different `n_breakpoints` values. Ensure your data distribution is suitable for linear regression segments.

Install

• pip install piecewise-regression Install stable version

Imports

• PiecewiseRegression

  from piecewise_regression import PiecewiseRegression

Quickstart

This quickstart demonstrates how to generate synthetic data with a breakpoint, initialize the `PiecewiseRegression` model, fit it to the data, and then visualize the results. It highlights the core workflow from data preparation to model interpretation.

import numpy as np
from piecewise_regression import PiecewiseRegression
import matplotlib.pyplot as plt

# Generate some synthetic data with a known breakpoint
x = np.linspace(0, 100, 500)
y = np.concatenate([
    -0.1 * x[x <= 50] + 10,
    0.5 * x[x > 50] - 20
]) + np.random.normal(0, 1, 500)

# Initialize and fit the model with one breakpoint
pw_fit = PiecewiseRegression(x, y, n_breakpoints=1)
pw_fit.fit()

# Print a summary of the fit
pw_fit.summary()

# Plot the fit (requires matplotlib to show)
fig, ax = pw_fit.plot_fit(show=False)
ax.set_title('Piecewise Regression Fit')
plt.show()