Change-Point Modeling

Functions for fitting change-point regression models to building energy data.

Model Fitting

better_lbnl_os.fit_changepoint_model(x, y, min_r_squared=0.6, max_cv_rmse=0.5)

Fit a change-point model to any x,y data relationship.

This is the main entry point for change-point model fitting. It automatically determines the best model type (1P, 3P, or 5P) based on statistical significance and model quality metrics.

Common usage examples: - Energy analysis: x=temperature, y=energy_use - Price analysis: x=price, y=demand - Time series: x=time, y=usage

Parameters:

• x (ndarray) – Array of independent variable values (e.g., temperature, price, time)

• y (ndarray) – Array of dependent variable values (e.g., energy_use, demand, usage)

• min_r_squared (float) – Minimum R² threshold for model acceptance

• max_cv_rmse (float) – Maximum CV-RMSE threshold for model acceptance

Returns:

ChangePointModelResult with fitted coefficients and quality metrics

Raises:

• ValueError – If input arrays are invalid or empty

• Exception – If model fitting fails

Return type:

ChangePointModelResult

Model Quality Metrics

better_lbnl_os.calculate_r_squared(y_actual, y_predicted)

Calculate R-squared (coefficient of determination).

Parameters:

• y_actual (ndarray) – Actual values

• y_predicted (ndarray | float) – Predicted values

Returns:

R-squared value between 0 and 1

Raises:

• ValueError – If inputs are invalid

• Exception – If there’s no variance in actual values

Return type:

float

better_lbnl_os.calculate_cvrmse(y_actual, y_predicted)

Calculate Coefficient of Variation of Root Mean Squared Error.

Parameters:

• y_actual (ndarray) – Actual values

• y_predicted (ndarray) – Predicted values

Returns:

CV-RMSE value

Return type:

float

Module Reference

Change-point model fitting algorithms for building energy analysis.

This module contains pure change-point modeling functions for statistical analysis of energy consumption patterns with respect to temperature.

better_lbnl_os.core.changepoint.piecewise_linear_5p(x, heating_slope, heating_changepoint, baseload, cooling_changepoint, cooling_slope)

Five-parameter piecewise linear function for change-point modeling.

This function implements the classic change-point model: - Heating slope (negative) below heating changepoint - Flat baseload between changepoints - Cooling slope (positive) above cooling changepoint

Visual representation:

k1 / k2

/

y0 __________/

cpL cpR

Where:

k1 = heating_slope (typically negative) k2 = cooling_slope (typically positive) y0 = baseload (constant energy use) cpL = heating_changepoint cpR = cooling_changepoint

Parameters:

• x (ndarray) – Temperature values

• heating_slope (float | None) – Slope for heating regime (typically negative)

• heating_changepoint (float | None) – Temperature where heating turns on

• baseload (float) – Constant energy use in neutral zone

• cooling_changepoint (float | None) – Temperature where cooling turns on

• cooling_slope (float | None) – Slope for cooling regime (typically positive)

Returns:

Predicted energy use values

Return type:

ndarray

better_lbnl_os.core.changepoint.plot_changepoint_model(x, y, model_result, x_label='X', y_label='Y', title=None, figsize=(12, 6), save_path=None)

Plot change-point model results with data points and fitted line.

Parameters:

• x (ndarray) – Independent variable data (e.g., temperature)

• y (ndarray) – Dependent variable data (e.g., energy use)

• model_result (ChangePointModelResult) – Fitted change-point model result

• x_label (str) – Label for x-axis

• y_label (str) – Label for y-axis

• title (str | None) – Plot title (auto-generated if None)

• figsize (tuple[int, int]) – Figure size tuple

• save_path (str | None) – Path to save figure (optional)

Returns:

Figure and axes objects

Return type:

tuple[matplotlib.pyplot.Figure, matplotlib.pyplot.Axes]

class better_lbnl_os.core.changepoint.ChangePointModelResult(*, heating_slope=None, heating_change_point=None, baseload, cooling_change_point=None, cooling_slope=None, r_squared, cvrmse, model_type, heating_pvalue=None, cooling_pvalue=None)

Bases: BaseModel

Result of change-point model fitting.

Contains all coefficients, goodness-of-fit metrics, and metadata from fitting a change-point model to energy usage data.

Parameters:

• heating_slope (float | None)

• heating_change_point (float | None)

• baseload (float)

• cooling_change_point (float | None)

• cooling_slope (float | None)

• r_squared (float)

• cvrmse (float)

• model_type (str)

• heating_pvalue (float | None)

• cooling_pvalue (float | None)

heating_slope: float | None

heating_change_point: float | None

baseload: float

cooling_change_point: float | None

cooling_slope: float | None

r_squared: float

cvrmse: float

model_type: str

heating_pvalue: float | None

cooling_pvalue: float | None

is_valid(min_r_squared=0.6, max_cvrmse=0.5)

Check if model meets quality thresholds.

Parameters:

• min_r_squared (float)

• max_cvrmse (float)

Return type:

bool

get_model_complexity()

Get number of parameters in the model.

Return type:

int

estimate_annual_consumption(annual_hdd, annual_cdd)

Estimate annual energy consumption using heating/cooling degree days.

Parameters:

• annual_hdd (float)

• annual_cdd (float)

Return type:

float

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].