API Docs

Results

class eemeter.CandidateModel(model_type, formula, status, predict_func=None, plot_func=None, model_params=None, model=None, result=None, r_squared=None, warnings=None)

Contains information about a candidate model.

model_type

str – The type of model, e..g., 'hdd_only'.

formula

str – The R-style formula for the design matrix of this model, e.g., 'meter_value ~ hdd_65'.

status

str – A string indicating the status of this model. Possible statuses:

  • 'NOT ATTEMPTED': Candidate model not fitted due to an issue encountered in data before attempt.
  • 'ERROR': A fatal error occurred during model fit process.
  • 'DISQUALIFIED': The candidate model fit was disqualified from the model selection process because of a decision made after candidate model fit completed, e.g., a bad fit, or a parameter out of acceptable range.
  • 'QUALIFIED': The candidate model fit is acceptable can be considered during model selection.
predict_func

callable – A function of the following form: predict_func(candidate_model, inputs) -> outputs

plot_func

callable – A function of the following form: plot_func(candidate_model, inputs) -> outputs

model_params

Dictionary displays, default None – A flat dictionary of model parameters which must be serializable using the json.dumps method.

model

object – The raw model (if any) used in fitting. Not serialized.

result

object – The raw modeling result (if any) returned by the model. Not serialized.

r_squared

float – The adjusted r-squared of the candidate model.

warnings

list of eemeter.EEMeterWarning – A list of any warnings reported during creation of the candidate model.

json()

Return a JSON-serializable representation of this result.

The output of this function can be converted to a serialized string with json.dumps.

plot(*args, **kwargs)

Predict for this model. Arguments may vary by model type.

predict(*args, **kwargs)

Predict for this model. Arguments may vary by model type.

class eemeter.DataSufficiency(status, criteria_name, warnings=None, settings=None)

Contains the result of a data sufficiency check.

status

str – A string indicating the status of this result. Possible statuses:

  • 'NO DATA': No baseline data was available.
  • 'FAIL': Data did not meet criteria.
  • 'PASS': Data met criteria.
criteria_name

str – The name of the criteria method used to check for baseline data sufficiency.

warnings

list of eemeter.EEMeterWarning – A list of any warnings reported during the check for baseline data sufficiency.

settings

Dictionary displays – A dictionary of settings (keyword arguments) used.

json()

Return a JSON-serializable representation of this result.

The output of this function can be converted to a serialized string with json.dumps.

class eemeter.ModelFit(status, method_name, model=None, r_squared=None, candidates=None, warnings=None, metadata=None, settings=None)

Contains information about a model fit.

status

str – A string indicating the status of this result. Possible statuses:

  • 'NO DATA': No baseline data was available.
  • 'NO MODEL': No candidate models qualified.
  • 'SUCCESS': A qualified candidate model was chosen.
method_name

str – The name of the method used to fit the baseline model.

model

eemeter.CandidateModel or None – The selected candidate model, if any.

r_squared

float – The adjusted r-squared of the selected model.

candidates

list of eemeter.CandidateModel – A list of any model candidates encountered during the model selection and fitting process.

warnings

list of eemeter.EEMeterWarning – A list of any warnings reported during the model selection and fitting process.

metadata

Dictionary displays – An arbitrary dictionary of metadata to be associated with this result. This can be used, for example, to tag the results with attributes like an ID:

{
    'id': 'METER_12345678',
}
settings

Dictionary displays – A dictionary of settings used by the method.

json(with_candidates=False)

Return a JSON-serializable representation of this result.

The output of this function can be converted to a serialized string with json.dumps.

plot(ax=None, title=None, figsize=None, with_candidates=False, candidate_alpha=None, temp_range=None)

Plot a model fit.

Parameters:
  • ax (matplotlib.axes.Axes, optional) – Existing axes to plot on.
  • title (str, optional) – Chart title.
  • figsize (tuple, optional) – (width, height) of chart.
  • with_candidates (bool) – If True, also plot candidate models.
  • candidate_alpha (float between 0 and 1) – Transparency at which to plot candidate models. 0 fully transparent, 1 fully opaque.
Returns:

ax – Matplotlib axes.

Return type:

matplotlib.axes.Axes

CalTRACK methods

eemeter.caltrack_method(data, fit_cdd=True, use_billing_presets=False, minimum_non_zero_cdd=10, minimum_non_zero_hdd=10, minimum_total_cdd=20, minimum_total_hdd=20, beta_cdd_maximum_p_value=1, beta_hdd_maximum_p_value=1, weights_col=None, fit_intercept_only=True, fit_cdd_only=True, fit_hdd_only=True, fit_cdd_hdd=True)

CalTRACK daily method.

Parameters:
  • data (pandas.DataFrame) – A DataFrame containing at least the column meter_value and 1 to n columns each of the form hdd_<heating_balance_point> and cdd_<cooling_balance_point>. DataFrames of this form can be made using the eemeter.merge_temperature_data method.
  • fit_cdd (bool, optional) – If True, fit CDD models unless overridden by fit_cdd_only or fit_cdd_hdd flags. Should be set to False for gas meter data.
  • use_billing_presets (bool, optional) – Use presets appropriate for billing models. Otherwise defaults are appropriate for daily models.
  • minimum_non_zero_cdd (int, optional) – Minimum allowable number of non-zero cooling degree day values.
  • minimum_non_zero_hdd (int, optional) – Minimum allowable number of non-zero heating degree day values.
  • minimum_total_cdd (float, optional) – Minimum allowable total sum of cooling degree day values.
  • minimum_total_hdd (float, optional) – Minimum allowable total sum of heating degree day values.
  • beta_cdd_maximum_p_value (float, optional) – The maximum allowable p-value of the beta cdd parameter. The default value is the most permissive possible (i.e., 1). This is here for backwards compatibility with CalTRACK 1.0 methods.
  • beta_hdd_maximum_p_value (float, optional) – The maximum allowable p-value of the beta hdd parameter. The default value is the most permissive possible (i.e., 1). This is here for backwards compatibility with CalTRACK 1.0 methods.
  • weights_col (str or None, optional) – The name of the column (if any) in data to use as weights.
  • fit_intercept_only (bool, optional) – If True, fit and consider intercept_only model candidates.
  • fit_cdd_only (bool, optional) – If True, fit and consider cdd_only model candidates. Ignored if fit_cdd=False.
  • fit_hdd_only (bool, optional) – If True, fit and consider hdd_only model candidates.
  • fit_cdd_hdd (bool, optional) – If True, fit and consider cdd_hdd model candidates. Ignored if fit_cdd=False.
Returns:

model_fit – Results of running CalTRACK daily method. See eemeter.ModelFit for more details.

Return type:

eemeter.ModelFit

eemeter.caltrack_sufficiency_criteria(data_quality, requested_start, requested_end, min_days=365, min_fraction_daily_coverage=0.9, min_fraction_daily_temperature_hourly_coverage=0.9)

CalTRACK daily data sufficiency criteria.

Parameters:
  • data_quality (pandas.DataFrame) – A DataFrame containing at least the column meter_value and the two columns temperature_null, containing a count of null hourly temperature values for each meter value, and temperature_not_null, containing a count of not-null hourly temperature values for each meter value. Should have a pandas.DatetimeIndex.
  • requested_start (datetime.datetime, timezone aware (or None)) – The desired start of the period, if any, especially if this is different from the start of the data. If given, warnings are reported on the basis of this start date instead of data start date.
  • requested_end (datetime.datetime, timezone aware (or None)) – The desired end of the period, if any, especially if this is different from the end of the data. If given, warnings are reported on the basis of this end date instead of data end date.
  • min_days (int, optional) – Minimum number of days allowed in data, including extent given by requested_start or requested_end, if given.
  • min_fraction_daily_coverage (:any:, optional) – Minimum fraction of days of data in total data extent for which data must be available.
  • min_fraction_daily_temperature_hourly_coverage=0.9, – Minimum fraction of hours of temperature data coverage in a particular day. Anything below this number and the whole day is considered invalid.
Returns:

data_sufficiency – The an object containing sufficiency status and warnings for this data.

Return type:

eemeter.DataSufficiency

eemeter.caltrack_metered_savings(baseline_model, reporting_meter_data, temperature_data, degree_day_method='daily', with_disaggregated=False)

Compute modeled savings, i.e., savings in which baseline and reporting usage values are based on models. This is appropriate for annualizing or weather normalizing models.

Parameters:
  • baseline_model (eemeter.CandidateModel) – Model to use for predicting pre-intervention usage.
  • reporting_meter_data (pandas.DataFrame) – The observed reporting period data. Savings will be computed for the periods supplied in the reporting period data.
  • temperature_data (pandas.Series) – Hourly-frequency timeseries of temperature data during the reporting period.
  • degree_day_method (str, optional) – The method to use to calculate degree days using hourly temperature data. Can be either 'hourly' or 'daily'.
  • with_disaggregated (bool, optional) – If True, calculate baseline counterfactual disaggregated usage estimates. Savings cannot be disaggregated for metered savings. For that, use eemeter.caltrack_modeled_savings.
Returns:

results – DataFrame with metered savings, indexed with reporting_meter_data.index. Will include the following columns:

  • counterfactual_usage (baseline model projected into reporting period)
  • reporting_observed (given by reporting_meter_data)
  • metered_savings

If with_disaggregated is set to True, the following columns will also be in the results DataFrame:

  • counterfactual_base_load
  • counterfactual_heating_load
  • counterfactual_cooling_load

Return type:

pandas.DataFrame

eemeter.caltrack_modeled_savings(baseline_model, reporting_model, result_index, temperature_data, degree_day_method='daily', with_disaggregated=False)

Compute modeled savings, i.e., savings in which baseline and reporting usage values are based on models. This is appropriate for annualizing or weather normalizing models.

Parameters:
  • baseline_model (eemeter.CandidateModel) – Model to use for predicting pre-intervention usage.
  • reporting_model (eemeter.CandidateModel) – Model to use for predicting post-intervention usage.
  • result_index (pandas.DatetimeIndex) – The dates for which usage should be modeled.
  • temperature_data (pandas.Series) – Hourly-frequency timeseries of temperature data during the modeled period.
  • degree_day_method (str, optional) – The method to use to calculate degree days using hourly temperature data. Can be either 'hourly' or 'daily'.
  • with_disaggregated (bool, optional) – If True, calculate modeled disaggregated usage estimates and savings.
Returns:

results – DataFrame with modeled savings, indexed with the result_index. Will include the following columns:

  • modeled_baseline_usage
  • modeled_reporting_usage
  • modeled_savings

If with_disaggregated is set to True, the following columns will also be in the results DataFrame:

  • modeled_baseline_base_load
  • modeled_baseline_cooling_load
  • modeled_baseline_heating_load
  • modeled_reporting_base_load
  • modeled_reporting_cooling_load
  • modeled_reporting_heating_load
  • modeled_base_load_savings
  • modeled_cooling_load_savings
  • modeled_heating_load_savings

Return type:

pandas.DataFrame

eemeter.caltrack_predict(model_type, model_params, data, disaggregated=False)

CalTRACK predict method.

Given a set model type, parameters, and daily temperatures, return model predictions.

Parameters:
  • model_type (str) – Model type (e.g., 'cdd_hdd').
  • model_params (Dictionary displays) – Parameters as stored in eemeter.CandidateModel.model_params.
  • data (pandas.DataFrame) – Data over which to predict. Assumed to be like the format of the data used for fitting, although it need only have the columns. If not giving data with a pandas.DatetimeIndex it must have the column n_days, representing the number of days per prediction period (otherwise inferred from DatetimeIndex).
  • disaggregated (bool, optional) – If True, return results as a pandas.DataFrame with columns 'base_load', 'heating_load', and 'cooling_load'
Returns:

prediction – Returns results as series unless disaggregated=True.

Return type:

pandas.Series or pandas.DataFrame

eemeter.get_too_few_non_zero_degree_day_warning(model_type, balance_point, degree_day_type, degree_days, minimum_non_zero)

Return an empty list or a single warning wrapped in a list regarding non-zero degree days for a set of degree days.

Parameters:
  • model_type (str) – Model type (e.g., 'cdd_hdd').
  • balance_point (float) – The balance point in question.
  • degree_day_type (str) – The type of degree days ('cdd' or 'hdd').
  • degree_days (pandas.Series) – A series of degree day values.
  • minimum_non_zero (int) – Minimum allowable number of non-zero degree day values.
Returns:

warnings – Empty list or list of single warning.

Return type:

list of eemeter.EEMeterWarning

eemeter.get_total_degree_day_too_low_warning(model_type, balance_point, degree_day_type, degree_days, minimum_total)

Return an empty list or a single warning wrapped in a list regarding the total summed degree day values.

Parameters:
  • model_type (str) – Model type (e.g., 'cdd_hdd').
  • balance_point (float) – The balance point in question.
  • degree_day_type (str) – The type of degree days ('cdd' or 'hdd').
  • degree_days (pandas.Series) – A series of degree day values.
  • minimum_total (float) – Minimum allowable total sum of degree day values.
Returns:

warnings – Empty list or list of single warning.

Return type:

list of eemeter.EEMeterWarning

eemeter.get_parameter_negative_warning(model_type, model_params, parameter)

Return an empty list or a single warning wrapped in a list indicating whether model parameter is negative.

Parameters:
Returns:

warnings – Empty list or list of single warning.

Return type:

list of eemeter.EEMeterWarning

eemeter.get_parameter_p_value_too_high_warning(model_type, model_params, parameter, p_value, maximum_p_value)

Return an empty list or a single warning wrapped in a list indicating whether model parameter p-value is too high.

Parameters:
Returns:

warnings – Empty list or list of single warning.

Return type:

list of eemeter.EEMeterWarning

eemeter.get_intercept_only_candidate_models(data, weights_col)

Return a list of a single candidate intercept-only model.

Parameters:
  • data (pandas.DataFrame) – A DataFrame containing at least the column meter_value. DataFrames of this form can be made using the eemeter.merge_temperature_data method.
  • weights_col (str or None) – The name of the column (if any) in data to use as weights.
Returns:

candidate_models – List containing a single intercept-only candidate model.

Return type:

list of CandidateModel

eemeter.get_cdd_only_candidate_models(data, minimum_non_zero_cdd, minimum_total_cdd, beta_cdd_maximum_p_value, weights_col)

Return a list of all possible candidate cdd-only models.

Parameters:
  • data (pandas.DataFrame) – A DataFrame containing at least the column meter_value and 1 to n columns with names of the form cdd_<balance_point>. All columns with names of this form will be used to fit a candidate model. DataFrames of this form can be made using the eemeter.merge_temperature_data method.
  • minimum_non_zero_cdd (int) – Minimum allowable number of non-zero cooling degree day values.
  • minimum_total_cdd (float) – Minimum allowable total sum of cooling degree day values.
  • beta_cdd_maximum_p_value (float) – The maximum allowable p-value of the beta cdd parameter.
  • weights_col (str or None) – The name of the column (if any) in data to use as weights.
Returns:

candidate_models – A list of cdd-only candidate models, with any associated warnings.

Return type:

list of CandidateModel

eemeter.get_hdd_only_candidate_models(data, minimum_non_zero_hdd, minimum_total_hdd, beta_hdd_maximum_p_value, weights_col)
Parameters:
  • data (pandas.DataFrame) – A DataFrame containing at least the column meter_value and 1 to n columns with names of the form hdd_<balance_point>. All columns with names of this form will be used to fit a candidate model. DataFrames of this form can be made using the eemeter.merge_temperature_data method.
  • minimum_non_zero_hdd (int) – Minimum allowable number of non-zero heating degree day values.
  • minimum_total_hdd (float) – Minimum allowable total sum of heating degree day values.
  • beta_hdd_maximum_p_value (float) – The maximum allowable p-value of the beta hdd parameter.
  • weights_col (str or None) – The name of the column (if any) in data to use as weights.
Returns:

candidate_models – A list of hdd-only candidate models, with any associated warnings.

Return type:

list of CandidateModel

eemeter.get_cdd_hdd_candidate_models(data, minimum_non_zero_cdd, minimum_non_zero_hdd, minimum_total_cdd, minimum_total_hdd, beta_cdd_maximum_p_value, beta_hdd_maximum_p_value, weights_col)

Return a list of candidate cdd_hdd models for a particular selection of cooling balance point and heating balance point

Parameters:
  • data (pandas.DataFrame) – A DataFrame containing at least the column meter_value and 1 to n columns each of the form hdd_<heating_balance_point> and cdd_<cooling_balance_point>. DataFrames of this form can be made using the eemeter.merge_temperature_data method.
  • minimum_non_zero_cdd (int) – Minimum allowable number of non-zero cooling degree day values.
  • minimum_non_zero_hdd (int) – Minimum allowable number of non-zero heating degree day values.
  • minimum_total_cdd (float) – Minimum allowable total sum of cooling degree day values.
  • minimum_total_hdd (float) – Minimum allowable total sum of heating degree day values.
  • beta_cdd_maximum_p_value (float) – The maximum allowable p-value of the beta cdd parameter.
  • beta_hdd_maximum_p_value (float) – The maximum allowable p-value of the beta hdd parameter.
  • weights_col (str or None) – The name of the column (if any) in data to use as weights.
Returns:

candidate_models – A list of cdd_hdd candidate models, with any associated warnings.

Return type:

list of CandidateModel

eemeter.select_best_candidate(candidate_models)

Select and return the best candidate model based on r-squared and qualification.

Parameters:candidate_models (list of eemeter.CandidateModel) – Candidate models to select from.
Returns:(best_candidate, warnings) – Return the candidate model with highest r-squared or None if none meet the requirements, and a list of warnings about this selection (or lack of selection).
Return type:tuple of eemeter.CandidateModel or None and list of eemeter.EEMeterWarning

Data transformation utilities

eemeter.as_freq(meter_data_series, freq, atomic_freq='1 Min')

Resample meter data to a different frequency.

This method can be used to upsample or downsample meter data. The assumption it makes to do so is that meter data is constant and averaged over the given periods. For instance, to convert billing-period data to daily data, this method first upsamples to the atomic frequency (1 minute freqency, by default), “spreading” usage evenly across all minutes in each period. Then it downsamples to hourly frequency and returns that result.

Caveats:

  • This method gives a fair amount of flexibility in resampling as long as you are OK with the assumption that usage is constant over the period (this assumption is generally broken in observed data at large enough frequencies, so this caveat should not be taken lightly).
  • This method should not be used for sampled (e.g., temperature data) rather than recorded data (e.g., meter data), as sampled data cannot be “spread” in the same way.
Parameters:
  • meter_data_series (pandas.Series) – Meter data to resample. should have a pandas.DatetimeIndex.
  • freq (str) – The frequency to resample to. This should be given in a form recognized by the pandas.Series.resample method.
  • atomic_freq (str, optional) – The “atomic” frequency of the intermediate data form. This can be adjusted to a higher atomic frequency to increase speed or memory performance.
Returns:

resampled_meter_data – Meter data resampled to the given frequency.

Return type:

pandas.Series

eemeter.day_counts(series)

Days between index datetime values as a pandas.Series.

Parameters:series (pandas.Series with pandas.DatetimeIndex) – A series for which to get day counts.
Returns:day_counts – A pandas.Series with counts of days between periods. Counts are given on start dates of periods.
Return type:pandas.Series
eemeter.get_baseline_data(data, start=None, end=None, max_days=365, whole_periods=True)

Filter down to baseline period data.

Parameters:
  • data (pandas.DataFrame or pandas.Series) – The data to filter to baseline data. This data will be filtered down to an acceptable baseline period according to the dates passed as start and end, or the maximum period specified with max_days.
  • start (datetime.datetime) – A timezone-aware datetime that represents the earliest allowable start date for the baseline data. The stricter of this or max_days is used to determine the earliest allowable baseline period date.
  • end (datetime.datetime) – A timezone-aware datetime that represents the latest allowable end date for the baseline data, i.e., the latest date for which data is available before the intervention begins.
  • max_days (int) – The maximum length of the period. Ignored if end is not set. The stricter of this or start is used to determine the earliest allowable baseline period date.
Returns:

baseline_data – Data for only the specified baseline period.

Return type:

pandas.DataFrame

eemeter.get_reporting_data(data, start=None, end=None, max_days=365)

Filter down to reporting period data.

Parameters:
  • data (pandas.DataFrame or pandas.Series) – The data to filter to reporting data. This data will be filtered down to an acceptable reporting period according to the dates passed as start and end, or the maximum period specified with max_days.
  • start (datetime.datetime) – A timezone-aware datetime that represents the earliest allowable start date for the reporting data, i.e., the earliest date for which data is available after the intervention begins.
  • end (datetime.datetime) – A timezone-aware datetime that represents the latest allowable end date for the reporting data. The stricter of this or max_days is used to determine the latest allowable reporting period date.
  • max_days (int) – The maximum length of the period. Ignored if start is not set. The stricter of this or end is used to determine the latest allowable reporting period date.
Returns:

reporting_data – Data for only the specified reporting period.

Return type:

pandas.DataFrame

eemeter.merge_temperature_data(meter_data, temperature_data, heating_balance_points=None, cooling_balance_points=None, data_quality=False, temperature_mean=True, degree_day_method='daily', percent_hourly_coverage_per_day=0.5, use_mean_daily_values=True, tolerance=None)

Merge meter data of any frequency with hourly temperature data to make a dataset to feed to models.

Creates a pandas.DataFrame with the same index as the meter data.

Parameters:
  • meter_data (pandas.DataFrame) – DataFrame with pandas.DatetimeIndex and a column with the name value.
  • temperature_data (pandas.Series) – Series with pandas.DatetimeIndex with hourly ('H') frequency and a set of temperature values.
  • cooling_balance_points (list of int or float, optional) – List of cooling balance points for which to create cooling degree days.
  • heating_balance_points (list of int or float, optional) – List of heating balance points for which to create heating degree days.
  • data_quality (bool, optional) – If True, compute data quality columns for temperature, i.e., temperature_not_null and temperature_null, containing for each meter value
  • temperature_mean (bool, optional) – If True, compute temperature means for each meter period.
  • degree_day_method (str, 'daily' or 'hourly') – The method to use in calculating degree days.
  • percent_hourly_coverage_per_day (str, optional) – Percent hourly temperature coverage per day for heating and cooling degree days to not be dropped.
  • use_mean_daily_values (bool, optional) – If True, meter and degree day values should be mean daily values, not totals. If False, totals will be used instead.
  • tolerance (pandas.Timedelta, optional) – Do not merge more than this amount of temperature data beyond this limit.
Returns:

data – A dataset with the specified parameters.

Return type:

pandas.DataFrame

eemeter.remove_duplicates(df_or_series)

Remove duplicate rows or values by keeping the first of each duplicate.

Parameters:df_or_series (pandas.DataFrame or pandas.Series) – Pandas object from which to drop duplicate index values.
Returns:deduplicated – The deduplicated pandas object.
Return type:pandas.DataFrame or pandas.Series

Data loading

eemeter.meter_data_from_csv(filepath_or_buffer, tz=None, start_col='start', value_col='value', gzipped=False, freq=None, **kwargs)

Load meter data from a CSV file.

Default format:

start,value
2017-01-01T00:00:00+00:00,0.31
2017-01-02T00:00:00+00:00,0.4
2017-01-03T00:00:00+00:00,0.58
Parameters:
  • filepath_or_buffer (str or file-handle) – File path or object.
  • tz (str, optional) – E.g., 'UTC' or 'US/Pacific'
  • start_col (str, optional, default 'start') – Date period start column.
  • value_col (str, optional, default 'value') – Value column, can be in any unit.
  • gzipped (bool, optional) – Whether file is gzipped.
  • freq (str, optional) – If given, apply frequency to data using pandas.DataFrame.resample.
  • **kwargs – Extra keyword arguments to pass to pandas.read_csv, such as sep='|'.
eemeter.meter_data_from_json(data, orient='list')

Load meter data from json.

Default format:

[
    ['2017-01-01T00:00:00+00:00', 3.5],
    ['2017-02-01T00:00:00+00:00', 0.4],
    ['2017-03-01T00:00:00+00:00', 0.46],
]
Parameters:data (list) – List elements are each a rows of data.
Returns:df – DataFrame with a single column ('value') and a pandas.DatetimeIndex.
Return type:pandas.DataFrame
eemeter.meter_data_to_csv(meter_data, path_or_buf)

Write meter data to CSV. See also pandas.DataFrame.to_csv.

Parameters:
  • meter_data (pandas.DataFrame) – Meter data DataFrame with 'value' column and pandas.DatetimeIndex.
  • path_or_buf (str or file handle, default None) – File path or object, if None is provided the result is returned as a string.
eemeter.temperature_data_from_csv(filepath_or_buffer, tz=None, date_col='dt', temp_col='tempF', gzipped=False, freq=None, **kwargs)

Load temperature data from a CSV file.

Default format:

dt,tempF
2017-01-01T00:00:00+00:00,21
2017-01-01T01:00:00+00:00,22.5
2017-01-01T02:00:00+00:00,23.5
Parameters:
  • filepath_or_buffer (str or file-handle) – File path or object.
  • tz (str, optional) – E.g., 'UTC' or 'US/Pacific'
  • date_col (str, optional, default 'dt') – Date period start column.
  • temp_col (str, optional, default 'tempF') – Temperature column.
  • gzipped (bool, optional) – Whether file is gzipped.
  • freq (str, optional) – If given, apply frequency to data using pandas.Series.resample.
  • **kwargs – Extra keyword arguments to pass to pandas.read_csv, such as sep='|'.
eemeter.temperature_data_from_json(data, orient='list')

Load temperature data from json. (Must be given in degrees Fahrenheit).

Default format:

[
    ['2017-01-01T00:00:00+00:00', 3.5],
    ['2017-01-01T01:00:00+00:00', 5.4],
    ['2017-01-01T02:00:00+00:00', 7.4],
]
Parameters:data (list) – List elements are each a rows of data.
Returns:series – DataFrame with a single column ('tempF') and a pandas.DatetimeIndex.
Return type:pandas.Series
eemeter.temperature_data_to_csv(temperature_data, path_or_buf)

Write temperature data to CSV. See also pandas.DataFrame.to_csv.

Parameters:
  • temperature_data (pandas.Series) – Temperature data series with pandas.DatetimeIndex.
  • path_or_buf (str or file handle, default None) – File path or object, if None is provided the result is returned as a string.

Sample Data

eemeter.samples()

Load a list of sample data identifiers.

Returns:samples – List of sample identifiers for use with eemeter.load_sample.
Return type:list of str
eemeter.load_sample(sample)

Load meter data, temperature data, and metadata for associated with a particular sample identifier. Note: samples are simulated, not real, data.

Parameters:sample (str) – Identifier of sample. Complete list can be obtained with eemeter.samples.
Returns:meter_data, temperature_data, metadata – Meter data, temperature data, and metadata for this sample identifier.
Return type:tuple of pandas.DataFrame, pandas.Series, and Dictionary displays

Visualization

eemeter.plot_time_series(meter_data, temperature_data, **kwargs)

Plot meter and temperature data in dual-axes time series.

Parameters:
Returns:

axes – Tuple of (ax_meter_data, ax_temperature_data).

Return type:

tuple of matplotlib.axes.Axes

eemeter.plot_energy_signature(meter_data, temperature_data, temp_col=None, ax=None, title=None, figsize=None, **kwargs)

Plot meter and temperature data in energy signature.

Parameters:
Returns:

ax – Matplotlib axes.

Return type:

matplotlib.axes.Axes

Warnings

class eemeter.EEMeterWarning(qualified_name, description, data)

An object representing a warning and data associated with it.

qualified_name

str – Qualified name, e.g., ‘eemeter.method_abc.missing_data’.

description

str – Prose describing the nature of the warning.

data

Dictionary displays – Data that reproducibly shows why the warning was issued.

json()

Return a JSON-serializable representation of this result.

The output of this function can be converted to a serialized string with json.dumps.

Exceptions

exception eemeter.EEMeterError

Base class for EEmeter library errors.

exception eemeter.NoBaselineDataError

Error indicating lack of baseline data.

exception eemeter.NoReportingDataError

Error indicating lack of reporting data.

exception eemeter.MissingModelParameterError

Error indicating missing model parameter.

exception eemeter.UnrecognizedModelTypeError

Error indicating unrecognized model type.

Version

eemeter.get_version()