Pipeline Helpers

High-level functions for end-to-end analysis workflows.

End-to-End Model Fitting

better_lbnl_os.fit_models_with_auto_weather(bills, floor_area, address=None, latitude=None, longitude=None, google_maps_api_key=None, openmeteo_api_key=None, min_r_squared=0.6, max_cv_rmse=0.5, use_typed=True)[source]

Convenience function that fetches weather and fits models in one call.

Parameters:

bills (list[UtilityBillData]) – List of utility bills
floor_area (float) – Building floor area in square meters (must be positive)
address (str | None) – Address string to geocode (if lat/lon not supplied)
latitude (float | None) – Latitude coordinate if known
longitude (float | None) – Longitude coordinate if known
google_maps_api_key (str | None) – Google Maps API key for geocoding (required)
openmeteo_api_key (str | None) – Optional OpenMeteo API key (paid archive)
min_r_squared (float) – Minimum R² threshold for model acceptance
max_cv_rmse (float) – Maximum CV-RMSE threshold for model acceptance
use_typed (bool) – If True, use typed CalendarizedData (recommended)

Returns:

Dictionary mapping energy type to fitted model results

Return type:

dict[str, ChangePointModelResult]

better_lbnl_os.fit_models_from_inputs(bills, floor_area, weather, min_r_squared=0.6, max_cv_rmse=0.5)[source]

Fit change-point models directly from raw utility bills and weather data.

Parameters:

bills (list[UtilityBillData]) – List of utility bills
floor_area (float) – Building floor area in square meters (must be positive)
weather (list[WeatherData] | None) – Optional list of weather data
min_r_squared (float) – Minimum R² threshold for model acceptance
max_cv_rmse (float) – Maximum CV-RMSE threshold for model acceptance
use_typed – If True, use typed CalendarizedData (recommended)

Returns:

Dictionary mapping energy type to fitted model results

Raises:

ValueError – If floor_area is not positive

Return type:

dict[str, ChangePointModelResult]

better_lbnl_os.fit_calendarized_models(calendarized, min_r_squared=0.6, max_cv_rmse=0.5, energy_types=('ELECTRICITY', 'FOSSIL_FUEL'))[source]

Fit change-point models for available energy types from calendarized data.

Parameters:

calendarized (dict | CalendarizedData) – Either a CalendarizedData object or legacy dict format
min_r_squared (float) – Minimum R² threshold for model acceptance
max_cv_rmse (float) – Maximum CV-RMSE threshold for model acceptance
energy_types (tuple[str, ...]) – Energy types to attempt fitting

Returns:

Dictionary mapping energy type to fitted model results

Return type:

dict[str, ChangePointModelResult]

Data Preparation

better_lbnl_os.prepare_model_data(calendarized, energy_types=('ELECTRICITY', 'FOSSIL_FUEL'), window=12)[source]

Extract, gate, and trim model-ready arrays per energy type.

Parameters:

calendarized (CalendarizedData | dict) – CalendarizedData model or legacy dict format
energy_types (tuple[str, ...]) – Energy types to process
window (int) – Minimum consecutive months required

Returns:

Dict keyed by energy type with ModelData (temperature, eui, months, days). Only includes energy types with sufficient consecutive data after trimming.

Return type:

dict[str, ModelData]

Note

Uses get_consecutive_months() which handles both CalendarizedData and dict.

better_lbnl_os.get_weather_for_bills(bills, address=None, latitude=None, longitude=None, google_maps_api_key=None, openmeteo_api_key=None)[source]

Fetch monthly weather for the full bill date range using OpenMeteo.

Parameters:

bills (list[UtilityBillData]) – Utility bills to derive the date range
address (str | None) – Address string to geocode (if lat/lon not supplied)
latitude (float | None) – Latitude coordinate if known
longitude (float | None) – Longitude coordinate if known
google_maps_api_key (str | None) – Google Maps API key for geocoding (required)
openmeteo_api_key (str | None) – Optional OpenMeteo API key (paid archive)

Returns: