berkeleylab-eetd-loadshape-50631d9ba44b.zip_eetd-loadshape_natur

#Loadshape *A Python module containing tools for analyzing electric load shapes* Generating baselines for electric loads can be tricky, this module makes it easy: ``` #!python from loadshape import Loadshape # electric load data - values are expected to be power (kW) load_data = [ ("2013-08-01 00:00:00", 5.168), ("2013-08-01 00:15:00", 6.235), ("2013-08-01 00:30:00", 5.021), ..., ("2013-09-26 23:45:00", 4.739) ] my_loadshape = Loadshape(load_data, timezone="America/Los_Angeles") my_baseline = my_loadshape.baseline() ``` ##Installation To install using pip: ```sh pip install git+https://bitbucket.org/berkeleylab/eetd-loadshape.git@master ``` ##Dependencies The loadshape module depends on R, and the 'optparse' R module Install R using homebrew on OSX: ```sh brew install R ``` [Install R using apt on Ubuntu](http://cran.r-project.org/bin/linux/ubuntu/README): ```sh sudo apt-get install r-base-core ``` Once you have R installed, open up an R console and install optparse: ```sh R > install.packages("optparse") # ... follow the instructions ``` Table of Contents: ---- + [**Introduction**](#markdown-header-introduction) + [**Input Data:**](#markdown-header-input-data) + [Timestamps](#markdown-header-timestamps) + [Timezones](#markdown-header-timezones) + [Power Data](#markdown-header-power-data) + [CSV Inputs](#markdown-header-csv-inputs) + [Outdoor Air Temperature Data](#markdown-header-outdoor-air-temperature-data) + [**Calculations:**](#markdown-header-calculations) + [Baselines](#markdown-header-baselines) + [Measurement and Verification](#markdown-header-measurement-and-verification) + [Economic Valuation](#markdown-header-economic-valuation) + [**Tariffs**](#markdown-header-tariffs) + [**Future Development**](#markdown-header-future-development) + [**Contribution**](#markdown-header-contribution) ##Introduction The loadshape module provides a quick and easy way to generate baselines and calculated quantities that are relevant for comparing actual electric loads with predicted (baseline) electric loads. The statistical model that is used by this module to generate baselines is intended to be used for electric loads that are sensitive to outdoor air temperature and which tend to follow trends based on time-of-week. The Loadshape class that is provided by this module makes it easy to manage time series electric load data, and exposes a simple interface to several underlying R functions, including the function which fits a statistical model to the input load data for the purposes of generating baselines. ##Input Data The only input data that the loadshape module requires in order to produce useful baselines is a set of time-series electric load data: ```python # electric load data should be provided as a List of tuples load_data = [ ("2013-08-01 00:00:00", 5.168), ("2013-08-01 00:15:00", 6.235), ("2013-08-01 00:30:00", 5.021), ..., ("2013-09-26 23:45:00", 4.739) ] my_loadshape = Loadshape(load_data=load_data) ``` As shown in the example above, the load data should be provided in the form of a Python List containing Tuples with two elements each. The first element of each Tuple should be a timestamp, and the second element should be a value representing power (kW). ###Timestamps For convenience, the timestamps within input data may take several different forms. All of the timestamps below are valid: ```python valid_load_data = [ ("2013-08-01 00:00:00", 5.168), # string: "YYYY-MM-DD HH:MM:SS" (1375341300, 6.235), # integer: seconds since Unix epoch (1375342200000, 5.021), # integer: milliseconds since Unix epoch ("1375343100", 5.046), # string: seconds since Unix eopoch ..., ("1380264300000", 4.739) ] # string: milliseconds since Unix epoch ``` ###Timezones It's important that you specify what timezones your timestamps refer to. If no timezone is specified, then the module will assume that you are using the timezone of your operating system, but this isn't necessarily a great assumption. Specify your timezone using the appropriate [timezone name](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) when you create a new instance of the Loadshape class. ```python my_loadshape = Loadshape(load_data, timezone="America/Los_Angeles") ``` Using the correct timezone is important because the statistical model used to generate baselines makes some assumptions that depend on its ability to make reasonable assumptions regarding time-of-day and also time-of-week. ###Power Data As noted above, the values within the provided time-series load data are assumed to prepresent power (kW). If the provided values do not represent kW, the unitless values that the module generates, including baselines, should be reasonable. Beware, though, that the units specified by the output of the event_performance method assumes that the power data has been provided in kW. ###Outdoor Air Temperature Data Passing outdoor air temperature data in addition to electric load data will allow the loadshape module to produce much more accurate baselines. Specify the units of the temperature data by setting the temp_units argument to either "C" or "F". ```python # electric load data - values are expected to be power (kW) load_data = [ ("2013-08-01 00:00:00", 5.168), ("2013-08-01 00:15:00", 6.235), ("2013-08-01 00:30:00", 5.021), ..., ("2013-09-26 23:45:00", 4.739) ] # outdoor air temperature data temp_data = [ ("2013-08-01 00:00:00", 54.23), ("2013-08-01 01:00:00", 54.60), ("2013-08-01 02:00:00", 54.65), ..., ("2013-09-26 23:45:00", 58.44) ] my_loadshape = Loadshape(load_data, temp_data, temp_units="F") ``` ###CSV Inputs As an alternative to passing input data to the Loadshape initializer as a List of Tuples, a reference to an appropriately formatted CSV file may be passed instead: ```python my_loadshape = Loadshape("path/to/load_data.csv", "path/to/temperature_data.csv") ``` The loadshape module expects CSVs to contain two colums. As with the Tuples, the first element in each column should be a valid timestamp, and the second column should be the corresponding value. Valid timestamps are discussed in the timestamps section above. ##Calculations The purpose of the Loadshape module is to simply and streamline the process of generating baselines and quantities that compare actual load performance to a calculated baseline. This section discusses this functionality and how to use it. ###Baselines The core of the Loadshape module is the Baseline calculation. The following section describes the statistical model that is used to generate baselines, as well as some options that are availalbe for generating different types of baselines. ####The Baseline Model The only input that this module requires is a time series of electric load data to which the baseline load shape model should be fit. If no other data is provided, then the baseline will be very simple: the predicted load for a given time of the week will simply be the weighted average load at that time of the week. For example, the predicted load for a particular Tuesday at 12:15 would be the weighted average load on all other Tuesdays at 12:15. The weighting_days argument defines how this average is weighted. The default value for weighting_days is 14, which puts more statistical weight on most recent two weeks of data. If outside air temperature data is provided in addition to the electric load data, a more sophisticated statistical model is fit. The temperature adjusted model assumes that the load data is that of a building with HVAC loads, and attempts to determine what times of the week the building is providing heating or cooli