Merge pull request #459 from jfenna/feature/international

Feature/international

CHANGELOG.md

@@ -16,6 +16,17 @@ Development
 * Clarify the functioning of start, end and max_days parameters to `get_reporting_data()` and `get_baseline_data()`.
 
 
+* 3.1.2
+-----
+
+* Addition of modules and amendments in support of international facility for EEMeter, including principally:
+* Addition of quickstart.py; updating setup.py and __init__/py accordingly.
+* Inclusion of temperature conversion amendments to design_matrices; features; and derivatives.
+* Addition of new tests and samples.
+* Amendments to tutorial.ipynb.
+* Addition of eemeter international.ipynb.
+
+
 3.1.1
 -----
 

Dockerfile

@@ -16,4 +16,4 @@ COPY eemeter/ /app/eemeter/
 RUN set -ex && pip install -e /app
 RUN set -ex && cd /usr/local/lib/ && python /app/setup.py develop
 
-WORKDIR /app
+WORKDIR /app

docs/api.rst

@@ -43,6 +43,8 @@ methods. See also :ref:`caltrack-hourly-quickstart`.
 
 .. autofunction:: eemeter.fit_caltrack_hourly_model
 
+.. autofunction:: eemeter.caltrack_hourly
+
 .. _caltrack-billing-daily-api:
 
 CalTRACK Daily and Billing (Usage per Day)
@@ -95,6 +97,7 @@ and Billing methods. See also :ref:`caltrack-billing-daily-quickstart`.
 
 .. autofunction:: eemeter.select_best_candidate
 
+.. autofunction:: eemeter.caltrack_daily
 
 Savings
 -------
@@ -225,6 +228,15 @@ These functions are used to various common data transformations based on pandas
 
 .. autofunction:: eemeter.overwrite_partial_rows_with_nan
 
+.. autofunction:: eemeter.format_temperature_data_for_caltrack
+
+.. autofunction:: eemeter.format_energy_data_for_caltrack
+
+.. autofunction:: eemeter.sum_gas_and_elec
+
+.. autofunction:: eemeter.trim
+
+.. autofunction:: eemeter.add_freq
 
 Version
 -------

eemeter/caltrack/__init__.py

@@ -20,3 +20,4 @@
 from .design_matrices import *
 from .hourly import *
 from .usage_per_day import *
+from .quickstart import *

eemeter/caltrack/design_matrices.py

@@ -27,6 +27,7 @@
 )
 from eemeter.segmentation import iterate_segmented_dataset
 from eemeter.caltrack.hourly import caltrack_hourly_fit_feature_processor
+from pkg_resources import resource_filename
 
 
 __all__ = (
@@ -37,7 +38,9 @@
 )
 
 
-def create_caltrack_hourly_preliminary_design_matrix(meter_data, temperature_data):
+def create_caltrack_hourly_preliminary_design_matrix(
+    meter_data, temperature_data, degc: bool = False
+):
     """A helper function which calls basic feature creation methods to create an
     input suitable for use in the first step of creating a CalTRACK hourly model.
 
@@ -47,20 +50,26 @@ def create_caltrack_hourly_preliminary_design_matrix(meter_data, temperature_dat
         Hourly meter data in eemeter format.
     temperature_data : :any:`pandas.Series`
         Hourly temperature data in eemeter format.
+    degc : :any 'bool'
+        Relevant temperature units; defaults to False (i.e. Fahrenheit).
 
     Returns
     -------
     design_matrix : :any:`pandas.DataFrame`
-        A design matrix with meter_value, hour_of_week, hdd_50, and cdd_65 features.
+        A design matrix with meter_value, hour_of_week, hdd_(hbp_default), and cdd_(cbp_default) features.
     """
+
+    if degc == True:
+        temperature_data = 32 + (temperature_data * 1.8)
+
     time_features = compute_time_features(
         meter_data.index, hour_of_week=True, hour_of_day=False, day_of_week=False
     )
     temperature_features = compute_temperature_features(
         meter_data.index,
         temperature_data,
         heating_balance_points=[50],
-        cooling_balance_points=[65],
+        cooling_balance_points=[65], #note both HBP this will require further work in future iterations of eemeter - CBP in particular assumes all buildings have cooling, which is a strong assumption.
         degree_day_method="hourly",
     )
     design_matrix = merge_features(
@@ -69,24 +78,31 @@ def create_caltrack_hourly_preliminary_design_matrix(meter_data, temperature_dat
     return design_matrix
 
 
-def create_caltrack_billing_design_matrix(meter_data, temperature_data):
+def create_caltrack_billing_design_matrix(
+    meter_data, temperature_data, degc: bool = False
+):
     """A helper function which calls basic feature creation methods to create a
     design matrix suitable for use with CalTRACK Billing methods.
 
     Parameters
     ----------
     meter_data : :any:`pandas.DataFrame`
-        Hourly meter data in eemeter format.
+        Monthly meter data in eemeter format.
     temperature_data : :any:`pandas.Series`
         Hourly temperature data in eemeter format.
+    degc : :any 'bool'
+        Relevant temperature units; defaults to Fahrenheit.
 
     Returns
     -------
     design_matrix : :any:`pandas.DataFrame`
-        A design matrics with mean usage_per_day, hdd_30-hdd_90, and cdd_30-cdd_90
+        A design matrix with mean usage_per_day, hdd_min-hdd_max, and cdd_min-cdd_max
         features.
     """
     usage_per_day = compute_usage_per_day_feature(meter_data, series_name="meter_value")
+    if degc == True:
+        temperature_data = 32 + (temperature_data * 1.8)
+
     temperature_features = compute_temperature_features(
         meter_data.index,
         temperature_data,
@@ -101,24 +117,31 @@ def create_caltrack_billing_design_matrix(meter_data, temperature_data):
     return design_matrix
 
 
-def create_caltrack_daily_design_matrix(meter_data, temperature_data):
+def create_caltrack_daily_design_matrix(
+    meter_data, temperature_data, degc: bool = False
+):
     """A helper function which calls basic feature creation methods to create a
     design matrix suitable for use with CalTRACK daily methods.
 
     Parameters
     ----------
     meter_data : :any:`pandas.DataFrame`
-        Hourly meter data in eemeter format.
+        Daily meter data in eemeter format.
     temperature_data : :any:`pandas.Series`
         Hourly temperature data in eemeter format.
+     degc : :any 'bool'
+        Relevant temperature units; defaults to Fahrenheit.
 
     Returns
     -------
     design_matrix : :any:`pandas.DataFrame`
-        A design matrics with mean usage_per_day, hdd_30-hdd_90, and cdd_30-cdd_90
+        A design matrix with mean usage_per_day, hdd_30-hdd_90, and cdd_30-cdd_90
         features.
     """
     usage_per_day = compute_usage_per_day_feature(meter_data, series_name="meter_value")
+    if degc == True:
+        temperature_data = 32 + (temperature_data * 1.8)
+
     temperature_features = compute_temperature_features(
         meter_data.index,
         temperature_data,
@@ -139,7 +162,6 @@ def create_caltrack_hourly_segmented_design_matrices(
 ):
     """A helper function which calls basic feature creation methods to create a
     design matrix suitable for use with segmented CalTRACK hourly models.
-
     Parameters
     ----------
     preliminary_design_matrix : :any:`pandas.DataFrame`
@@ -156,7 +178,6 @@ def create_caltrack_hourly_segmented_design_matrices(
         form returned by :any:`eemeter.fit_temperature_bins`.
     unoccupied_temperature_bins : :any:``
         Ditto, for unoccupied.
-
     Returns
     -------
     design_matrix : :any:`dict` of :any:`pandas.DataFrame`

eemeter/caltrack/hourly.py

@@ -17,7 +17,6 @@
    limitations under the License.
 
 """
-import numpy as np
 import pandas as pd
 import statsmodels.formula.api as smf
 
@@ -26,9 +25,14 @@
     compute_temperature_bin_features,
     compute_occupancy_feature,
     merge_features,
+
 )
 from ..metrics import ModelMetrics
-from ..segmentation import CalTRACKSegmentModel, SegmentedModel, fit_model_segments
+from ..segmentation import (
+    CalTRACKSegmentModel,
+    SegmentedModel,
+    fit_model_segments,
+)
 from ..warnings import EEMeterWarning
 
 
@@ -594,3 +598,5 @@ def fit_caltrack_hourly_model(
         seg_model.segment_name: seg_model.totals_metrics for seg_model in segment_models
     }
     return model_results
+
+