Benchmarking

Functions for benchmarking building energy performance against reference statistics.

Building Benchmarking

better_lbnl_os.benchmark_building(change_point_results, benchmark_statistics, floor_area, savings_target='NOMINAL', building_id=None)[source]

Benchmark a building’s change-point models against reference statistics.

Parameters:

  • change_point_results (dict[str, ChangePointModelResult]) – Dictionary mapping energy types to change-point results

  • benchmark_statistics (BenchmarkStatistics) – Reference statistics to compare against

  • floor_area (float) – Building floor area

  • savings_target (str) – Savings target level (“CONSERVATIVE”, “NOMINAL”, “AGGRESSIVE”)

  • building_id (str | None) – Optional building identifier

Returns:

BenchmarkResult with complete comparison metrics

Raises:

ValueError – If required inputs are missing

Return type:

BenchmarkResult

better_lbnl_os.benchmark_with_reference(change_point_results, floor_area, country_code, building_type, custom_statistics_path=None, savings_target='NOMINAL', building_id=None)[source]

Benchmark building using reference statistics.

Allows using either built-in statistics or custom data.

Parameters:

  • change_point_results (dict[str, ChangePointModelResult]) – Dictionary mapping energy types to change-point results

  • floor_area (float) – Building floor area

  • country_code (str) – ISO country code (e.g., ‘US’, ‘MX’)

  • building_type (str | BuildingSpaceType) – Building type enum or string

  • custom_statistics_path (str | None) – Optional path to custom JSON manifest

  • savings_target (str) – Savings target level (“CONSERVATIVE”, “NOMINAL”, “AGGRESSIVE”)

  • building_id (str | None) – Optional building identifier

Returns:

BenchmarkResult with complete comparison metrics

Raises:

ValueError – If no reference statistics are available or inputs are invalid

Return type:

BenchmarkResult

Reference Statistics

better_lbnl_os.get_reference_statistics(country_code, building_type, custom_data_path=None)[source]

Get reference statistics for benchmarking.

Parameters:

  • country_code (str) – ISO country code (e.g., ‘US’, ‘MX’)

  • building_type (str | BuildingSpaceType) – Building type enum or string

  • custom_data_path (str | None) – Optional path to custom JSON manifest

Returns:

BenchmarkStatistics if available, None otherwise

Return type:

BenchmarkStatistics | None

better_lbnl_os.list_available_reference_statistics(custom_data_path=None)[source]

List all available reference statistics.

Parameters:

custom_data_path (str | None) – Optional path to custom JSON manifest

Returns:

List of (country_code, building_type) tuples

Return type:

list[tuple[str, BuildingSpaceType]]

better_lbnl_os.create_statistics_from_models(change_point_models, building_ids=None)[source]

Create benchmark statistics from a collection of change-point models.

Parameters:

  • change_point_models (list[ChangePointModelResult]) – List of fitted change-point models

  • building_ids (list[str] | None) – Optional list of building identifiers for logging

Returns:

BenchmarkStatistics with median and standard deviation for each coefficient

Raises:

ValueError – If no valid models provided

Return type:

BenchmarkStatistics

Portfolio Analysis

better_lbnl_os.calculate_portfolio_statistics(building_results)[source]

Calculate portfolio-level statistics from individual building results.

Parameters:

building_results (list[BenchmarkResult]) – List of benchmark results for buildings in portfolio

Returns:

Dictionary with portfolio-level metrics

Return type:

dict[str, float]

Module Reference

Core benchmarking engine for building energy performance analysis.

This module provides pure, framework-agnostic functions for benchmarking building energy performance against reference statistics. It handles the comparison of change-point model coefficients and provides performance ratings and targets.

better_lbnl_os.core.benchmarking.benchmark_coefficient(coefficient_name, coefficient_value, median, stdev, savings_target, floor_area)[source]

Benchmark a single coefficient against reference statistics.

Parameters:

  • coefficient_name (str) – Name of the coefficient

  • coefficient_value (float | None) – Current coefficient value

  • median (float | None) – Reference median

  • stdev (float | None) – Reference standard deviation

  • savings_target (str) – Savings target level

  • floor_area (float) – Building floor area

Returns:

CoefficientBenchmarkResult with comparison metrics

Return type:

CoefficientBenchmarkResult

better_lbnl_os.core.benchmarking.get_target_coefficient_value(coefficient_name, current_value, median, stdev, savings_target='NOMINAL')[source]

Calculate target coefficient value based on savings target level.

Parameters:

  • coefficient_name (str) – Name of the coefficient

  • current_value (float) – Current coefficient value

  • median (float) – Reference median

  • stdev (float) – Reference standard deviation

  • savings_target (str) – Target level (“CONSERVATIVE”, “NOMINAL”, “AGGRESSIVE”)

Returns:

Target coefficient value

Return type:

float