API

DailyModel(model='current', settings=None, verbose=False)

A class to fit a model to the input meter data.

Attributes:

Name	Type	Description
settings	dict	A dictionary of settings.
seasonal_options	list	A list of seasonal options (su: Summer, sh: Shoulder, wi: Winter). Elements in the list are seasons separated by ‘_’ that represent a model split. For example, a list of [‘su_sh’, ‘wi’] represents two splits: summer/shoulder and winter.
day_options	list	A list of day options.
combo_dictionary	dict	A dictionary of combinations.
df_meter	DataFrame	A dataframe of meter data.
error	dict	A dictionary of error metrics.
combinations	list	A list of combinations.
components	list	A list of components.
fit_components	list	A list of fit components.
wRMSE_base	float	The mean bias error for no splits.
best_combination	list	The best combination of splits.
model	Pipeline	The final fitted model.
id	str	The index of the meter data.

Parameters:

Name	Type	Description	Default
model	str	The model to use (either ‘current’ or ‘legacy’).	'current'
settings	dict | None	DailySettings to be changed.	None
verbose	bool	Whether to print verbose output.	False

fit(baseline_data, ignore_disqualification=False)

Fit the model using baseline data.

Parameters:

Name	Type	Description	Default
baseline_data	DailyBaselineData	DailyBaselineData object.	required
ignore_disqualification	bool	Whether to ignore disqualification errors / warnings.	False

Returns:

Type	Description
DailyModel	The fitted model.

Raises:

Type	Description
TypeError	If baseline_data is not a DailyBaselineData object.
DataSufficiencyError	If the model can’t be fit on disqualified baseline data.

predict(reporting_data, ignore_disqualification=False)

Predicts the energy consumption using the fitted model.

Parameters:

Name	Type	Description	Default
reporting_data	Union[DailyBaselineData, DailyReportingData]	The data used for prediction.	required
ignore_disqualification	bool	Whether to ignore model disqualification. Defaults to False.	False

Returns:

Type	Description
DataFrame	Dataframe with input data along with predicted energy consumption.

Raises:

Type	Description
RuntimeError	If the model is not fitted.
DisqualifiedModelError	If the model is disqualified and ignore_disqualification is False.
ValueError	If the reporting data has a different timezone than the model.
TypeError	If the reporting data is not of type DailyBaselineData or DailyReportingData.

to_dict()

Returns a dictionary of model parameters.

Returns:

Type	Description
dict	Model parameters.

to_json()

Returns a JSON string of model parameters.

Returns:

Type	Description
str	Model parameters.

from_dict(data) classmethod

Create a instance of the class from a dictionary (such as one produced from the to_dict method).

Parameters:

Name	Type	Description	Default
data	dict	The dictionary containing the model data.	required

Returns:

Type	Description
DailyModel	An instance of the class.

from_json(str_data) classmethod

Create an instance of the class from a JSON string.

Parameters:

Name	Type	Description	Default
str_data	str	The JSON string representing the object.	required

Returns:

Type	Description
DailyModel	An instance of the class.

plot(data)

Plot a model fit with baseline or reporting data. Requires matplotlib to use.

Parameters:

Name	Type	Description	Default
df_eval		The baseline or reporting data object to plot.	required

DailySettings

Settings for creating the daily model.

These settings should be converted to a dictionary before being passed to the DailyModel class. Be advised that any changes to the default settings deviates from OpenEEmeter standard methods and should be used with caution.

Attributes:

Name	Type	Description
developer_mode	bool	Allows changing of developer settings
algorithm_choice	str	Optimization algorithm choice. Developer mode only.
initial_guess_algorithm_choice	str	Initial guess optimization algorithm choice. Developer mode only.
full_model	str	The largest model allowed. Developer mode only.
smoothed_model	bool	Allow smoothed models.
allow_separate_summer	bool	Allow summer to be modeled separately.
allow_separate_shoulder	bool	Allow shoulder to be modeled separately.
allow_separate_winter	bool	Allow winter to be modeled separately.
allow_separate_weekday_weekend	bool	Allow weekdays and weekends to be modeled separately.
reduce_splits_by_gaussian	bool	Reduces splits by fitting with multivariate Gaussians and testing for overlap.
reduce_splits_num_std	list[float]	Number of standard deviations to use with Gaussians.
alpha_minimum	float	Alpha where adaptive robust loss function is Welsch loss.
alpha_selection	float	Specified alpha to evaluate which is the best model type.
alpha_final_type	str	When to use ‘alpha_final: ‘all’: on every model, ‘last’: on final model, ‘None’: don’t use.
alpha_final	float | str | None	Specified alpha or ‘adaptive’ for adaptive loss in model evaluation.
final_bounds_scalar	float | None	Scalar for calculating bounds of ‘alpha_final’.
regularization_alpha	float	Alpha for elastic net regularization.
regularization_percent_lasso	float	Percent lasso vs (1 - perc) ridge regularization.
segment_minimum_count	int	Minimum number of data points for HDD/CDD.
maximum_slope_OoM_scalar	float	Scaler for initial slope to calculate bounds based on order of magnitude.
initial_smoothing_parameter	float | None	Initial guess for the smoothing parameter.
initial_step_percentage	float | None	Initial step-size for relevant algorithms.
split_selection_criteria	str	What selection criteria is used to select data splits of models.
split_selection_penalty_multiplier	float	Penalty multiplier for split selection criteria.
split_selection_penalty_power	float	What power should the penalty of the selection criteria be raised to.
season	Dict[int, str]	Dictionary of months and their associated season (January is 1).
is_weekday	Dict[int, bool]	Dictionary of days (1 = Monday) and if that day is a weekday (True/False).
uncertainty_alpha	float	Significance level used for uncertainty calculations (0 < float < 1).
cvrmse_threshold	float	Threshold for the CVRMSE to disqualify a model.

DailyBaselineData(df, is_electricity_data, settings=None)

Data class to represent Daily Baseline Data.

Only baseline data should go into the dataframe input, no blackout data should be input. Checks sufficiency for the data provided as input depending on OpenEEMeter specifications and populates disqualifications and warnings based on it.

Parameters:

Name	Type	Description	Default
df	DataFrame	A dataframe having a datetime index or a datetime column with the timezone also being set. It also requires 2 more columns - ‘observed’ for meter data, and ‘temperature’ for temperature data. The temperature column should have values in Fahrenheit. Please convert your temperatures accordingly.	required
is_electricity_data	bool	Flag to ascertain if this is electricity data or not. Electricity data values of 0 are set to NaN.	required

Attributes:

Name	Type	Description
df	DataFrame	Immutable dataframe that contains the meter and temperature values for the baseline data period.
disqualification	list[EEMeterWarning]	A list of serious issues with the data that can degrade the quality of the model. If you want to go ahead with building the model while ignoring them, set the ignore_disqualification = True flag in the model. By default disqualifications are not ignored.
warnings	list[EEMeterWarning]	A list of issues with the data, but none that will severely reduce the quality of the model built.

is_electricity_data = is_electricity_data instance-attribute

tz = None instance-attribute

warnings = [] instance-attribute

disqualification = [] instance-attribute

settings = self._settings_class() instance-attribute

df: pd.DataFrame | None property

Get the corrected input data stored in the class. The actual dataframe is immutable, this returns a copy.

from_series(meter_data, temperature_data, is_electricity_data, settings=None) classmethod

Create an instance of the Data class from meter data and temperature data.

Public method that can can handle two separate series (meter and temperature) and join them to create a single dataframe. The temperature column should have values in Fahrenheit.

Parameters:

Name	Type	Description	Default
meter_data	Series | DataFrame	The meter data.	required
temperature_data	Series | DataFrame	The temperature data.	required
is_electricity_data	bool	A flag indicating whether the data represents electricity data. This is required as electricity data with 0 values are converted to NaNs.	required

Returns:

Type	Description
	An instance of the Data class with the dataframe populated with the corrected data, along with warnings and disqualifications based on the input.

DailyReportingData(df, is_electricity_data, settings=None)

Data class to represent Daily Reporting Data.

Only reporting data should go into the dataframe input, no blackout data should be input. Checks sufficiency for the data provided as input depending on OpenEEMeter specifications and populates disqualifications and warnings based on it.

Meter data input is optional for the reporting class.

Parameters:

Name	Type	Description	Default
df	DataFrame	A dataframe having a datetime index or a datetime column with the timezone also being set. It also requires 2 more columns - ‘observed’ for meter data, and ‘temperature’ for temperature data. The temperature column should have values in Fahrenheit. Please convert your temperatures accordingly.	required
is_electricity_data	bool	Flag to ascertain if this is electricity data or not. Electricity data values of 0 are set to NaN.	required

Attributes:

Name	Type	Description
df	DataFrame	Immutable dataframe that contains the meter and temperature values for the baseline data period.
disqualification	list[EEMeterWarning]	A list of serious issues with the data that can degrade the quality of the model. If you want to go ahead with building the model while ignoring them, set the ignore_disqualification = True flag in the model. By default disqualifications are not ignored.
warnings	list[EEMeterWarning]	A list of issues with the data, but none that will severely reduce the quality of the model built.

is_electricity_data = is_electricity_data instance-attribute

tz = None instance-attribute

warnings = [] instance-attribute

disqualification = [] instance-attribute

settings = self._settings_class() instance-attribute

df: pd.DataFrame | None property

Get the corrected input data stored in the class. The actual dataframe is immutable, this returns a copy.

from_series(meter_data, temperature_data, is_electricity_data=None, tzinfo=None, settings=None) classmethod

Create an instance of the Data class from meter data and temperature data.

Parameters:

Name	Type	Description	Default
meter_data	Series | DataFrame | None	The meter data to be used for the DailyReportingData instance.	required
temperature_data	Series | DataFrame	The temperature data to be used for the DailyReportingData instance.	required
is_electricity_data	bool | None	Flag indicating whether the meter data represents electricity data.	None
tzinfo	tzinfo | None	Timezone information to be used for the meter data.	None

Returns:

Type	Description
DailyReportingData	An instance of the Data class.

example: