# API¶

## eemeter.structures¶

class eemeter.structures.EnergyTrace(interpretation, data=None, records=None, unit=None, placeholder=False, serializer=None, trace_id=None, interval=None)[source]

Container for time series energy data.

Parameters: interpretation (str) – The way this energy time series in the data attribute should be interpreted. The complete list of supported options is as follows: ELECTRICITY_CONSUMPTION_SUPPLIED: Represents the amount of utility-supplied electrical energy consumed on-site, as metered at a single usage point, such as a utility-owned electricity meter. Specifically does not include consumption of electricity generated on site, such as by locally installed solar photovoltaic panels. ELECTRICITY_CONSUMPTION_TOTAL: Represents the amount of electrical energy consumed on-site, including both utility-supplied and on-site generated electrical energy. Equivalent, for a single electricity meter, to ELECTRICITY_CONSUMPTION_SUPPLIED - ELECTRICITY_ON_SITE_GENERATION_CONSUMED. ELECTRICITY_CONSUMPTION_NET: Represents the amount of utility-supplied electrical energy consumed on-site minus the amount of unconsumed electrical energy generated on site and fed back into the grid at a single usage point, such as a utility-owned electricity meter. Equivalent, for a single electricity meter, to ELECTRICITY_CONSUMPTION_SUPPLIED - ELECTRICITY_ON_SITE_GENERATION_UNCONSUMED. ELECTRICITY_ON_SITE_GENERATION_TOTAL: Represents the amount of locally generated electrical energy consumed on-site plus the amount of locally generated elecrical energy returned to the grid, as metered at a single usage point. Equivalent, for a single electricity meter, to ELECTRICITY_ON_SITE_GENERATION_CONSUMED + ELECTRICITY_ON_SITE_GENERATION_UNCONSUMED. ELECTRICITY_ON_SITE_GENERATION_CONSUMED: Represents the amount of locally generated electrical energy consumed on-site, such as energy generated by solar photovoltaic panels. ELECTRICITY_ON_SITE_GENERATION_UNCONSUMED: Represents the amount of excess locally generated energy, which instead of being consumed on-site, is fed back into the grid or sold back a utility. NATURAL_GAS_CONSUMPTION_SUPPLIED: Represents the amount of energy supplied by a utility in the form of natural gas and used on site, as metered at a single usage point. Though under the labeling scheme used for electricity interpretetations the labels NATURAL_GAS_CONSUMPTION_TOTAL and NATURAL_GAS_CONSUMPTION_NET would be equivalent for natural gas, NATURAL_GAS_CONSUMPTION_SUPPLIED is prefered for its greater specificity. data (pandas.DataFrame, default None) – A pandas DataFrame with two columns and a timezone-aware DatetimeIndex. Timestamps in the index are assumed to refer to the start of each period, and the period ends are assumed to coincide with the start of the following period. Thus, the value of the last datetime should always be NaN, since is purpose is only to cap the end of the last period, and not to represent a time period over which energy was consumed. The DatetimeIndex does not need to have uniform frequency, such as those specified in pandas using the freq attribute. value: Amount of energy between this index and the next. estimated: Whether or not the value was estimated. Particularly relevant for monthly billing data. If serializer instance is provided, this should instead be records in the format expected by the serializer. unit (str) – The name of the unit in which the energy time series is given. These names are normalized to either 'KWH' or 'THERM' as follows: 'kwh' becomes 'KWH' with no unit conversion multiplier. 'kWh' becomes 'KWH' with no unit conversion multiplier. 'KWH' becomes 'KWH' with no unit conversion multiplier. 'therm' becomes 'THERM' with no unit conversion multiplier. 'therms' becomes 'THERM' with no unit conversion multiplier. 'thm' becomes 'THERM' with no unit conversion multiplier. 'THERM' becomes 'THERM' with no unit conversion multiplier. 'THERMS' becomes 'THERM' with no unit conversion multiplier. 'THM' becomes 'THERM' with no unit conversion multiplier. 'wh' becomes 'KWH' with a unit conversion multiplier of 0.001. 'Wh' becomes 'KWH' with a unit conversion multiplier of 0.001. 'WH' becomes 'KWH' with a unit conversion multiplier of 0.001. placeholder (bool) – Indicates that this instance is a placeholder - that while for some reason the data associated with it is unavailable, its existence is still important in considering a whole site. serializer (consumption.BaseSerializer) – Serializer instance to be used to deserialize records into a pandas dataframe. Must supply the to_dataframe(records) method.
class eemeter.structures.EnergyTraceSet(traces, labels=None)[source]

A container for energy traces which ensures that each is labeled.

Parameters: traces (list or dict of eemeter.structures.EnergyTrace objects) – EnergyTrace objects to be included in this list. labels (list of str) – Unique labels for traces, used only if traces is not a dictionary.
itertraces()[source]

Iterates over traces, yielding (label, trace) pairs.

class eemeter.structures.Intervention(start_date, end_date=None)[source]

Represents an intervention with a start date, and maybe an end date. Multiple interventions can be composed within a project.

Parameters: start_date (datetime.datetime) – Must be timezone aware end_date (datetime.datetime or None, default None) – Must be timezone aware. If None, intervention is assumed to be ongoing.
class eemeter.structures.ModelingPeriod(interpretation, start_date=None, end_date=None)[source]

Represents a period of time over which to select data from a Trace for contiguous modeling. Carries an “interpretation”, for which there are two options, “BASELINE” and “REPORTING”. The period is defined by a single optional start date and a single optional end date. If the start date is not given, the start date is considered to be negative infinity; if the end date is not given, the end date is considered to be positive infinity.

A ModelingPeriod is a time period, defined by start and end dates, over which the process behind a trace can be expected, for modeling purposes, to have roughly the same energy response to end use demand. Note that this criterion might not be particularly well specified without reference to a particular intervention and set of modeling conditions.

Parameters: interpretation (str, {"BASELINE", "REPORTING"}) – The way this ModelingPeriod should be interpreted. ”BASELINE” means that this modeling period represents the time before an intervention or set of interventions. ”REPORTING” means that this modeling period represents the time after an intervention or set of interventions. start_date (datetime.datetime or None) – The date marking the earliest date of the ModelingPeriod. None indicates a start_date of negative infinity. If interpretation is “REPORTING”, start_date cannot be None. end_date (datetime.datetime or None) – The date marking the latest date of the ModelingPeriod. None indicates an end_date of positive infinity. If interpretation is “BASELINE”, end_date cannot be None.
class eemeter.structures.ModelingPeriodSet(modeling_periods, groupings)[source]

Represents a set of labeled modeling periods of interest, grouped into meaningful comparison sets. Labels can be arbitrary.

Basic usage:

>>> modeling_periods = {
...     "modeling_period_1": ModelingPeriod(
...         "BASELINE",
...         end_date=datetime(2000, 1, 1, tzinfo=pytz.UTC),
...     ),
...     "modeling_period_2": ModelingPeriod(
...         "REPORTING",
...         start_date=datetime(2000, 2, 1, tzinfo=pytz.UTC),
...     ),
...     "modeling_period_3": ModelingPeriod(
...         "REPORTING",
...         start_date=datetime(2000, 2, 1, tzinfo=pytz.UTC),
...     ),
... }
...
>>> grouping = [
...     ("modeling_period_1", "modeling_period_2"),
...     ("modeling_period_1", "modeling_period_3"),
... ]
...
>>> mps = ModelingPeriodSet(modeling_periods, grouping)

class eemeter.structures.Project(energy_trace_set, interventions, site, project_id=None)[source]

Container for storing project data.

Parameters: trace_set (eemeter.structures.TraceSet) – Complete set of energy traces for this project. For a project site that has, for example, two electricity meters, each with two traces (supplied electricity kWh, and solar-generated kWh) and one natural gas meter with one trace (consumed natural gas therms), the trace_set should contain 5 traces, regardless of the availablity of that data. Traces which are unavailable should be represented as ‘placeholder’ traces. interventions (list of eemeter.structures.Intervention) – Complete set of interventions, planned, ongoing, or completed, that have taken or will take place at this site as part of this project. site (eemeter.structures.Site) – The site of this project.
class eemeter.structures.ZIPCodeSite(zipcode)[source]

ZIP-code-based site location descriptor.

Parameters: zipcode (str) – A five-digit zipcode identifier.