Get Started with the
OpenEE Meter Desktop App

How to Run the OpenEEmeter From Your Desktop. No Code or Servers Required!

The OpenEEmeter is an open source platform that allows anyone with access to energy to data to calculate normalized metered energy consumption (NMEC). This makes it ideal for automating M&V, tracking portfolios, and creating markets based on confidence in savings.

Now the OpenEEmeter can be run locally, from your desktop. No programing is required, but you will need to be comfortable using your computer's Command Line Interface (CLI) Terminal (ain't so bad) and have some familiarity with pre/post weather-normalized energy savings calculation methods to get the most use from the tool. This version of the OpenEEmeter is a standalone executable intended for one-off M&V analysis of buildings, evaluation, testing, and validation.

The OpenEEmeter is 100% open source, so you’ll never have to pay or worry about licensing - for any purpose. The open calculation engine runs as described above through your command line on your computer, or can be integrated into software applications using well documented APIs.

For enterprise deployments, Open Energy Efficiency offers a cloud-hosted SaaS OpenEEmeter solution which includes backend, ETL, reporting dashboards, etc. Both versions perform the same calculations. Learn more

The OpenEEmeter Desktop App is intended for:

  • M&V professionals
  • Program administrators and implementors
  • Evaluators
  • Pay-for-performance participants
  • Efficiency Aggregators (aka companies)
  • Regulators
  • Researchers
  • Application developers

How to install and run the OpenEEmeter

The OpenEEmeter can be downloaded from GitHub, along with sample data.

The eemeter package contains a set of routines to load energy and project data, enrich it with weather data, and estimate savings realized from a given project. The eemeter can be run on its own from the command line using properly-formatted CSV files as inputs. This is a useful way of testing and validating the code, and for running one-off analyses of archival data.

This document will describe the basic eemeter command line tool provided as part of the package. The command line interface is implemented in eemeter/cli.py, and is intended to serve as a template to be modified by analysts to support their specific use case.

Sample data

Note:

The eemeter package can handle projects which cannot be fully specified in this simplified format; for example, it supports projects with more than one trace per project per interpretation, and can handle estimated meter reads. If this functionality is needed, users should refer to the documentation to modify the example cli.py as needed.

For purposes of testing, a sample data set is provided in eemeter/sample_data. The sample data set contains a single project undertaken at a single site, and includes two-year-long hourly electricity and natural gas “traces” (energy usage timestreams) synthesized from typical usage patterns provided by the Department of Energy.

projects.csv contains project metadata for all projects, and includes the following columns:

  • project_id, a string that serves as a unique identifier.
  • zipcode, a 5-digit ZIP code for the project site used to select a weather station.
  • project_start, a timestamp in the form YYYY-MM-DD HH:MM:SS specifying the date at which work started at the site (and thus the end date of the baseline period).
  • project_end, a timestamp in the same form specifying the date at which work ended at the site (and thus the beginning of the reporting period).

traces.csv contains the metered gas and/or electric usage for all projects, and includes the following columns:

  • traces.csv contains the metered gas and/or electric usage for all projects, and includes the following columns:
  • start, a timestamp in the form YYYY-MM-DD HH:MM:SS that identifies the beginning of the measurement period.
  • value, the metered usage for the measurement period, assumed to be unestimated. Electric usage should be provided in kWh, and gas usage in Therms.
  • project_id identifies the project, which should be one of those included in projects.csv.
  • interpretation identifies the usage type, which should be “gas” for natural gas and “electricity” for electricity.

Running eemeter

Note:

The eemeter core library and CLI tool are installed as a python package. If you do not have an existing python installation, we recommend downloading and installing the free, open-source anaconda python distribution before proceeding with eemeter installation.

If you have an existing installation and would prefer not to alter your existing python environment, you may wish to isolate your python environment. This is not strictly necessary, but can be accomplished using either a Virtualenv or a Conda environment.

Start by installing the eemeter package:

$ pip install eemeter

You can verify that it has been installed successfully by starting an interactive python session and running:

>>> import eemeter; eemeter.get_version()

'1.2.0'

Running with sample data

From the shell, type:

$ eemeter sample

‍(The eemeter sample command is a shortcut for eemeter analyze sample_data/.)

Outputs

You should see output that looks like this:

$ eemeter sample
Running a meter for ABC NATURAL_GAS_CONSUMPTION_SUPPLIED
Normal year savings estimate:  
  1216.948071  
  68% confidence interval: (1163.898845, 1269.997296)
Reporting period savings estimate:  
  1170.606076  
  68% confidence interval: (1117.637227, 1223.574925)

Running a meter for ABC ELECTRICITY_CONSUMPTION_SUPPLIED
Normal year savings estimate:  
  10465.511272  
  68% confidence interval: (10297.508645, 10633.513899)
Reporting period savings estimate:  
  10394.802426  
  68% confidence interval: (10227.045114, 10562.559737)

These outputs correspond to the annualized weather normalized savings (i.e., the baseline period model applied to the site’s TMY3 normal year weather, minus the reporting model applied to the site’s TMY3 normal year weather) and to the realized savings over the reporting year (i.e., the baseline period model applied to the site’s reporting period observed weather, minus the observed reporting period usage).

In addition to these two cumulative savings estimates, many additional outputs can be reported by eemeter, including daily time series and best-fit model parameters. To see a full menu of options, refer to the documentation, or inspect the meter_output dictionary returned from the _analyze() routine:

>>> from eemeter import cli
>>> retval = cli._analyze('sample_data')

Pay particular attention to the list of derivatives, i.e. derived outputs from the meter estimation:

>>> print([i['series'] for i in retval[0]['derivatives']])

Running with your own data

From the shell, type:

$ eemeter analyze <directory_name></directory_name>

This should point to a directory with trace and project data in CSV files formatted according to the description above. It may also be helpful to inspect the sample data.