API

BillingModel(settings=None, verbose=False)

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

BillingModel is a wrapper for the DailyModel class using billing presets.

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.

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.

fit(baseline_data, ignore_disqualification=False)

predict(reporting_data, aggregation=None, ignore_disqualification=False)

Predicts the energy consumption using the fitted model.

Parameters:

Name	Type	Description	Default
reporting_data	BillingBaselineData | BillingReportingData	The data used for prediction.	required
aggregation	str | None	The aggregation level for the prediction. One of [None, ‘none’, ‘monthly’, ‘bimonthly’].	None
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.
TypeError	If the reporting data is not of type BillingBaselineData or BillingReportingData.
ValueError	If the aggregation is not one of [None, ‘none’, ‘monthly’, ‘bimonthly’].

plot(data, aggregation=None)

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
aggregation	str | None	The aggregation level for the prediction. One of [None, ‘none’, ‘monthly’, ‘bimonthly’].	None

to_dict()

Returns a dictionary of model parameters.

Returns:

Type	Description
dict	Model parameters.

BillingBaselineData(df, is_electricity_data, settings=None)

Data class to represent Billing 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.

Billing data should have an extra month’s data appended at the to denote end of period. (Do not append NaN, any other value would work.)

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 ssues 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.

billing_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.

BillingReportingData(df, is_electricity_data, settings=None)

Data class to represent Billing 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 ssues 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.

billing_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, tzinfo=None, settings=None) classmethod

Create a BillingReportingData instance from meter data and temperature data.

Parameters:

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

Returns:

Type	Description
	An instance of the Data class.