Data Models

This module contains the core data models used throughout the library.

Building and Location

class better_lbnl_os.BuildingData(*, name, floor_area, space_type, location, country_code='US', climate_zone=None)[source]

Bases: BaseModel

Domain model for building information with business logic methods.

Parameters:

  • name (str)

  • floor_area (float)

  • space_type (str)

  • location (str)

  • country_code (str)

  • climate_zone (str | None)

name: str
floor_area: float
space_type: str
location: str
country_code: str
climate_zone: str | None
classmethod validate_space_type(v)[source]

Normalize and validate the space type against known choices.

Parameters:

v (str)

Return type:

str

validate_bills(bills)[source]

Validate utility bills for this building.

Returns: list of validation error messages

Parameters:

bills (list[UtilityBillData])

Return type:

list[str]

get_benchmark_category()[source]

Determine benchmark category based on space type.

Return type:

str

get_space_type_code()[source]

Return the enum code (name) for the current space type (e.g., “Office” -> “OFFICE”).

Return type:

str

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.models.LocationInfo(*, geo_lat, geo_lng, zipcode=None, state=None, country_code='US', noaa_station_id=None, noaa_station_name=None, egrid_sub_region=None)[source]

Bases: BaseModel

Domain model for geocoded location information.

Parameters:

  • geo_lat (float)

  • geo_lng (float)

  • zipcode (str | None)

  • state (str | None)

  • country_code (str)

  • noaa_station_id (str | None)

  • noaa_station_name (str | None)

  • egrid_sub_region (str | None)

geo_lat: float
geo_lng: float
zipcode: str | None
state: str | None
country_code: str
noaa_station_id: str | None
noaa_station_name: str | None
egrid_sub_region: str | None
is_valid_coordinates()[source]

Check if coordinates are within valid latitude/longitude ranges.

Returns:

True if coordinates are valid, False otherwise

Return type:

bool

calculate_distance_to(other)[source]

Calculate distance to another location.

Parameters:

other (LocationInfo) – Another LocationInfo object

Returns:

Distance in kilometers

Return type:

float

model_config: ClassVar[ConfigDict] = {}

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

Utility Data

class better_lbnl_os.UtilityBillData(*, fuel_type, start_date, end_date, consumption, units, cost=None)[source]

Bases: BaseModel

Domain model for utility bills with conversion methods.

Parameters:
fuel_type: str
start_date: date
end_date: date
consumption: float
units: str
cost: float | None
validate_dates()[source]

Validate that end date is after start date.

get_days()[source]

Calculate number of days in billing period.

Return type:

int

to_kwh()[source]

Convert consumption to kWh using standard conversion factors.

Returns:

Energy consumption in kWh

Return type:

float

calculate_daily_average()[source]

Calculate average daily consumption.

Returns:

Average daily consumption in original units

Return type:

float

calculate_cost_per_unit()[source]

Calculate cost per unit of consumption.

Returns:

Cost per unit, or None if cost is not available

Return type:

float | None

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.CalendarizedData(*, weather=<factory>, aggregated=<factory>, detailed=<factory>)[source]

Bases: BaseModel

Calendarized energy data with weather and aggregations.

Parameters:
weather: WeatherSeries
aggregated: EnergyAggregation
detailed: FuelAggregation
to_legacy_dict()[source]

Convert to legacy dictionary format for backward compatibility.

Returns:

Dictionary in legacy format

Return type:

dict

classmethod from_legacy_dict(data)[source]

Create instance from legacy dictionary format.

Parameters:

data (dict) – Dictionary in legacy format

Returns:

CalendarizedData instance

Return type:

CalendarizedData

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.EnergyAggregation(*, months=<factory>, days_in_period=<factory>, energy_kwh=<factory>, cost=<factory>, ghg_kg=<factory>, daily_eui_kwh_per_m2=<factory>, unit_price_per_kwh=<factory>, unit_emission_kg_per_kwh=<factory>)[source]

Bases: TimeSeriesAggregation

Time series aggregation for total energy consumption.

Parameters:
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.FuelAggregation(*, months=<factory>, days_in_period=<factory>, energy_kwh=<factory>, cost=<factory>, ghg_kg=<factory>, daily_eui_kwh_per_m2=<factory>, unit_price_per_kwh=<factory>, unit_emission_kg_per_kwh=<factory>)[source]

Bases: TimeSeriesAggregation

Time series aggregation broken down by fuel type.

Parameters:
model_config: ClassVar[ConfigDict] = {}

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

Weather Data

class better_lbnl_os.WeatherData(*, station_id=None, latitude, longitude, year, month, avg_temp_c, min_temp_c=None, max_temp_c=None, data_source='OpenMeteo')[source]

Bases: BaseModel

Domain model for weather data with calculation methods.

Parameters:
station_id: str | None
latitude: float
longitude: float
year: int
month: int
avg_temp_c: float
min_temp_c: float | None
max_temp_c: float | None
data_source: str
property avg_temp_f: float

Get average temperature in Fahrenheit.

property min_temp_f: float | None

Get minimum temperature in Fahrenheit.

property max_temp_f: float | None

Get maximum temperature in Fahrenheit.

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.WeatherSeries(*, months=<factory>, degC=<factory>, degF=<factory>)[source]

Bases: BaseModel

Monthly weather time series aligned to calendar months.

Parameters:
months: list[date]
degC: list[float]
degF: list[float]
model_config: ClassVar[ConfigDict] = {}

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

Analysis Results

class better_lbnl_os.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)[source]

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
is_valid(min_r_squared=0.6, max_cvrmse=0.5)[source]

Check if model meets quality thresholds.

Parameters:
Return type:

bool

get_model_complexity()[source]

Get number of parameters in the model.

Return type:

int

estimate_annual_consumption(annual_hdd, annual_cdd)[source]

Estimate annual energy consumption using heating/cooling degree days.

Parameters:
Return type:

float

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.BenchmarkResult(*, building_id=None, floor_area=None, savings_target=None, ELECTRICITY=None, FOSSIL_FUEL=None)[source]

Bases: BaseModel

Complete benchmark results for a building.

This represents the comparison of a single building’s change-point model coefficients against reference statistics for all energy types.

Parameters:

  • building_id (str | None)

  • floor_area (float | None)

  • savings_target (str | None)

  • ELECTRICITY (EnergyTypeBenchmarkResult | None)

  • FOSSIL_FUEL (EnergyTypeBenchmarkResult | None)

building_id: str | None
floor_area: float | None
savings_target: str | None
ELECTRICITY: EnergyTypeBenchmarkResult | None
FOSSIL_FUEL: EnergyTypeBenchmarkResult | None
get_overall_rating(energy_type='ELECTRICITY')[source]

Get overall performance rating for an energy type.

Parameters:

energy_type (str) – Energy type to get rating for (“ELECTRICITY” or “FOSSIL_FUEL”)

Returns:

Overall rating string or None if no valid rating found

Return type:

str | None

get_average_percentile(energy_type='ELECTRICITY')[source]

Get average percentile across all coefficients for an energy type.

Parameters:

energy_type (str) – Energy type to analyze (“ELECTRICITY” or “FOSSIL_FUEL”)

Returns:

Average percentile or None if no valid percentiles found

Return type:

float | None

model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.BenchmarkStatistics(*, ELECTRICITY=None, FOSSIL_FUEL=None)[source]

Bases: BaseModel

Complete benchmark statistics for all energy types.

This represents the statistical data derived from a reference dataset of buildings, used to benchmark individual buildings against.

Parameters:

  • ELECTRICITY (EnergyTypeBenchmarkStatistics | None)

  • FOSSIL_FUEL (EnergyTypeBenchmarkStatistics | None)

ELECTRICITY: EnergyTypeBenchmarkStatistics | None
FOSSIL_FUEL: EnergyTypeBenchmarkStatistics | None
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.CoefficientBenchmarkResult(*, coefficient_value=None, coefficient_value_with_area=None, rating=None, percentile=None, sample_median=None, sample_standard_deviation=None, conservative_level=None, nominal_level=None, aggressive_level=None, target_value=None)[source]

Bases: BaseModel

Benchmarking result for a single coefficient.

Contains the comparison of a building’s coefficient value against reference statistics, including percentile ranking and performance rating.

Parameters:

  • coefficient_value (float | None)

  • coefficient_value_with_area (float | None)

  • rating (str | None)

  • percentile (float | None)

  • sample_median (float | None)

  • sample_standard_deviation (float | None)

  • conservative_level (float | None)

  • nominal_level (float | None)

  • aggressive_level (float | None)

  • target_value (float | None)

coefficient_value: float | None
coefficient_value_with_area: float | None
rating: str | None
percentile: float | None
sample_median: float | None
sample_standard_deviation: float | None
conservative_level: float | None
nominal_level: float | None
aggressive_level: float | None
target_value: float | None
model_config: ClassVar[ConfigDict] = {}

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

Recommendations and Savings

class better_lbnl_os.InefficiencySymptom(*, symptom_id, description, severity=None, detected_value=None, threshold_value=None, metric=None)[source]

Bases: BaseModel

Detected inefficiency symptom from benchmarking results.

Parameters:

  • symptom_id (str)

  • description (str)

  • severity (float | None)

  • detected_value (float | None)

  • threshold_value (float | None)

  • metric (str | None)

symptom_id: str
description: str
severity: float | None
detected_value: float | None
threshold_value: float | None
metric: str | None
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.EEMeasureRecommendation(*, measure_id, name, triggered_by, priority=None)[source]

Bases: BaseModel

Energy efficiency measure recommendation.

Parameters:
measure_id: str
name: str
triggered_by: list[str]
priority: str | None
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.EERecommendationResult(*, symptoms, recommendations, metadata=<factory>)[source]

Bases: BaseModel

Complete EE recommendation result.

Parameters:
symptoms: list[InefficiencySymptom]
recommendations: list[EEMeasureRecommendation]
metadata: dict
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.SavingsEstimate(*, energy_savings_kwh, cost_savings_usd, emissions_savings_kg_co2, percent_reduction)[source]

Bases: BaseModel

Backwards-compatible savings estimate container.

Parameters:

  • energy_savings_kwh (float)

  • cost_savings_usd (float)

  • emissions_savings_kg_co2 (float)

  • percent_reduction (float)

energy_savings_kwh: float
cost_savings_usd: float
emissions_savings_kg_co2: float
percent_reduction: float
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.SavingsSummary(*, per_fuel, combined, metadata=<factory>)[source]

Bases: BaseModel

Top-level savings report.

Parameters:
per_fuel: dict[str, FuelSavingsResult]
combined: CombinedSavingsSummary
metadata: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.FuelSavingsResult(*, energy_type, months, days_in_period, period_label, current, target, typical, energy_savings_kwh, energy_savings_percent, cost_savings_usd, cost_savings_percent, ghg_savings_kg_co2, ghg_savings_percent, eui_savings_kwh_per_m2, ghg_intensity_reduction_kg_co2_per_m2, component_savings, monthly_energy_kwh, monthly_cost_usd, monthly_ghg_kg_co2, valid=True, metadata=<factory>)[source]

Bases: BaseModel

Savings summary for a single energy type.

Parameters:
energy_type: str
months: list[str]
days_in_period: list[int]
period_label: str
current: UsageTotals
target: UsageTotals
typical: UsageTotals
energy_savings_kwh: float
energy_savings_percent: float
cost_savings_usd: float
cost_savings_percent: float
ghg_savings_kg_co2: float
ghg_savings_percent: float
eui_savings_kwh_per_m2: float | None
ghg_intensity_reduction_kg_co2_per_m2: float | None
component_savings: ComponentSavings
monthly_energy_kwh: list[float]
monthly_cost_usd: list[float]
monthly_ghg_kg_co2: list[float]
valid: bool
metadata: dict[str, Any]
model_config: ClassVar[ConfigDict] = {}

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

class better_lbnl_os.CombinedSavingsSummary(*, current, target, typical, energy_savings_kwh, energy_savings_percent, cost_savings_usd, cost_savings_percent, ghg_savings_kg_co2, ghg_savings_percent, eui_savings_kwh_per_m2, ghg_intensity_reduction_kg_co2_per_m2, component_savings, valid)[source]

Bases: BaseModel

Whole-building savings summary across fuels.

Parameters:
current: UsageTotals
target: UsageTotals
typical: UsageTotals
energy_savings_kwh: float
energy_savings_percent: float
cost_savings_usd: float
cost_savings_percent: float
ghg_savings_kg_co2: float
ghg_savings_percent: float
eui_savings_kwh_per_m2: float | None
ghg_intensity_reduction_kg_co2_per_m2: float | None
component_savings: ComponentSavings
valid: bool
model_config: ClassVar[ConfigDict] = {}

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