Welcome to xbos-services-getter’s documentation!¶

Intro¶

Allows for easy retrieval of data which is relevant to XBOS projects.

A Python 3.5+ wrapper for the XBOS microservices.

Note: Only supports precision up to seconds.

Quick Setup¶

Using pip for Python 3.5+ run:

$ pip install xbos-services-getter

Quick Start¶

To start using the services, set the microservices host address. To get the addresses email me: daniel (dot) lengyel (at) berkeley (dot) edu

Generally, to get data, instantiate the stub (client) for the service to be used. Then, call the data getter function with the required parameters.

Example 1: Get a Comfortband¶

import datetime
import pytz
import xbos_services_getter

start = pytz.timezone("US/Pacific").localize(datetime.datetime(year=2018, month=1, day=1, hour=0, minute=0))
end = start + datetime.timedelta(days=7)
window = "15m"
building = "ciee"
zone = "HVAC_Zone_Eastzone"

temperature_band_stub = xbos_services_getter.get_temperature_band_stub()
comfortband = xbos_services_getter.get_comfortband(temperature_band_stub, building, zone, start, end, window)

Working microservices¶

Comfortband

Gets the comfortband for a given building and HVAC zone in a timeframe (start, end) and window.
Do Not Exceed

Gets the do not exceed setpoints for a given building and HVAC zone in a timeframe (start, end) and window.
Historic Occupancy

Gets the historic occupancy for a given building and HVAC zone in a timeframe (start, end) and window.
Price

Gets the price for a given utility in a timeframe (start, end) and window.
Discomfort

Calculates the discomfort of occupants given an indoor temperature and comfortband.
HVAC Consumption

Gets the HVAC consumption for every possible action for a given building and HVAC zone.
Outdoor Temperature Historic

Gets historic outdoor temperatures from weather.gov.
Indoor Temperature Prediction

Predicts indoor temperature.
Indoor Data Historic

Gets historic indoor temperatures and actions for a given building and zone.

Functions¶

xbos_services_getter.xbos_services_getter.get_window_in_sec(s)¶: Returns number of seconds in a given duration or zero if it fails. Supported durations are seconds (s), minutes (m), hours (h), and days(d).

xbos_services_getter.xbos_services_getter.get_building_zone_names_stub(BUILDING_ZONE_NAMES_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the building_zone_address service.

Parameters:	BUILDING_ZONE_NAMES_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_buildings(building_zone_names_stub)¶

Gets all the building names supported by the services.

Parameters:	building_zone_names_stub – grpc stub for building_zone_names service.
Returns:	list (string) building names.

xbos_services_getter.xbos_services_getter.get_zones(building_zone_names_stub, building)¶

Gets all zone names for the given building which are supported by the services.

Parameters:	building_zone_names_stub – grpc stub for building_zone_names service. building – (string) building name. Needs to be in the list returned by get_buildings.
Returns:	list (string) zone names.

xbos_services_getter.xbos_services_getter.get_all_buildings_zones(building_zone_names_stub)¶

Gets all building and corresponding zones in a dictionary.

Parameters:	building_zone_names_stub – grpc stub for building_zone_names service.
Returns:	dictionary <building name, list<zone names>> (strings)

xbos_services_getter.xbos_services_getter.get_temperature_band_stub(TEMPERATURE_BANDS_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the temperature_band service.

Parameters:	TEMPERATURE_BANDS_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_comfortband(temperature_band_stub, building, zone, start, end, window)¶

Gets comfortband as pd.df.

Parameters:	temperature_band_stub – grpc stub for temperature_band microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) start of comfortband end – (datetime timezone aware) end of comfortband window – (str) the interval in which to split the comfortband.
Returns:	pd.df columns=[“t_low”, “t_high”], valus=float, index=time

xbos_services_getter.xbos_services_getter.get_do_not_exceed(temperature_band_stub, building, zone, start, end, window)¶

Gets do_not_exceed as pd.df.

Parameters:	temperature_band_stub – grpc stub for temperature_band microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) start of do_not_exceed end – (datetime timezone aware) end of do_not_exceed window – (str) the interval in which to split the do_not_exceed.
Returns:	pd.df columns=[“t_low”, “t_high”], valus=float, index=time

xbos_services_getter.xbos_services_getter.get_occupancy_stub(OCCUPANCY_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the occupancy service.

Parameters:	OCCUPANCY_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_occupancy(occupancy_stub, building, zone, start, end, window)¶

Gets occupancy as pd.series.

Parameters:	occupancy_stub – grpc stub for occupancy microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.series valus=float, index=time

xbos_services_getter.xbos_services_getter.get_price_stub(PRICE_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the price service.

Parameters:	PRICEPRICE_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_all_tariffs(price_stub)¶

Gets all available tariffs and utilities as a list of dictionaries.

Parameters:	price_stub – grpc stub for price microservice
Returns:	list of (dictionary) keys=[“tariff”, “utility”]

xbos_services_getter.xbos_services_getter.get_tariff_and_utility(price_stub, building)¶

Gets the tariff and utility for the given building as a dictionary.

Parameters:	price_stub – grpc stub for price microservice building – (str) building name
Returns:	(dictionary) keys=[“tariff”, “utility”]

xbos_services_getter.xbos_services_getter.get_price_utility_tariff(price_stub, utility, tariff, price_type, start, end, window)¶

Gets the price as a pandas dataframe.

Parameters:	price_stub – grpc stub for price microservice building – (str) building name price_type – (str) “ENERGY” or “DEMAND” start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.DataFrame columns=[“price” (float), “unit” string] index=start to end with window intervals.

xbos_services_getter.xbos_services_getter.get_price(price_stub, building, price_type, start, end, window)¶

Gets the price as a pandas dataframe.

Parameters:	price_stub – grpc stub for price microservice building – (str) building name price_type – (str) “ENERGY” or “DEMAND” start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.DataFrame columns=[“price”, “unit”], types=[float, string] index=start to end with window intervals.

xbos_services_getter.xbos_services_getter.get_demand_response_forecast_utility(price_stub, utility, timezone=<DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>)¶

xbos_services_getter.xbos_services_getter.get_demand_response_confirmed_utility(price_stub, utility, timezone=<DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>)¶

xbos_services_getter.xbos_services_getter.get_demand_response_forecast(price_stub, building, timezone=<DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>)¶

xbos_services_getter.xbos_services_getter.get_demand_response_confirmed(price_stub, building, timezone=<DstTzInfo 'US/Pacific' LMT-1 day, 16:07:00 STD>)¶

xbos_services_getter.xbos_services_getter.get_indoor_historic_stub(INDOOR_DATA_HISTORICAL_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the indoor_data_historical service.

Parameters:	INDOOR_DATA_HISTORICAL_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_indoor_temperature_historic(indoor_historic_stub, building, zone, start, end, window, agg='MEAN')¶

Gets historic indoor temperature as pd.series.

Parameters:	indoor_historic_stub – grpc stub for historic indoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.df columns=[“temperature”, “unit”] values=[float, string], index=time

xbos_services_getter.xbos_services_getter.get_indoor_actions_historic(indoor_historic_stub, building, zone, start, end, window, agg='MAX')¶

Gets historic indoor temperature as pd.series.

Parameters:	indoor_historic_stub – grpc stub for historic indoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.df columns[“action”], types=[“float”], index=time

xbos_services_getter.xbos_services_getter.get_indoor_modes_historic(indoor_historic_stub, building, zone, start, end, window, agg='MAX')¶

Gets historic indoor temperature as pd.series.

Parameters:	indoor_historic_stub – grpc stub for historic indoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.df columns[“mode”], types=[“float”], index=time

xbos_services_getter.xbos_services_getter.get_indoor_setpoints_historic(indoor_historic_stub, building, zone, start, end, window, agg='MIN')¶

Gets historic setpoints temperature as pd.df.

Parameters:	indoor_historic_stub – grpc stub for historic indoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.df columns=[“t_low”, “t_high”] valus=float, index=time

xbos_services_getter.xbos_services_getter.get_indoor_temperature_prediction_stub(INDOOR_TEMPERATURE_PREDICTION_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the indoor_temperature_prediction service.

Parameters:	INDOOR_TEMPERATURE_PREDICTION_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_indoor_temperature_prediction(indoor_temperature_prediction_stub, building, zone, current_time, action, t_in, t_out, t_prev, other_zone_temperatures)¶

Gets prediction of indoor temperature.

Parameters:

indoor_temperature_prediction_stub – grpc stub for prediction of indoor temperature microservice
building – (str) building name
zone – (str) zone name
current_time – (datetime timezone aware)
action – (int) Action as given in utils file.
t_in – (float) current temperature inside of zone.
t_out – (float) currrent outdoor temperature.
t_prev – (float) the temperature 5 min ago.
other_zone_temperatures – {zone_i: indoor temperature of zone_i}

Returns:

(float) temperature in 5 minutes after current_time in Fahrenheit.

xbos_services_getter.xbos_services_getter.get_indoor_temperature_prediction_error(indoor_temperature_prediction_stub, building, zone, action, start=None, end=None, temperature_unit='F')¶

Gets mean and var of the error of indoor temperature predictions.

Parameters:

indoor_temperature_prediction_stub – grpc stub for prediction of indoor temperature microservice
building – (str) building name
zone – (str) zone name
action – (int) Action as given in utils file. Specifies for which action to get the error. -1 gets the error on the whole dataset, regardless of action.
start – (datetime timezone aware). If None, get the training error.
end – (datetime timezone aware). If None, get the training error.
temperature_unit – temperature unit

Returns:

mean error (float), varirance of error (float), unit of the error (string).

xbos_services_getter.xbos_services_getter.get_hvac_consumption_stub(HVAC_CONSUMPTION_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the hvac_consumption service.

Parameters:	HVAC_CONSUMPTION_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_hvac_consumption(hvac_consumption_stub, building, zone)¶

xbos_services_getter.xbos_services_getter.get_outdoor_temperature_historic_stub(OUTDOOR_TEMPERATURE_HISTORICAL_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the outdoor_temperature_historical service.

Parameters:	OUTDOOR_TEMPERATURE_HISTORICAL_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_raw_outdoor_temperature_historic(outdoor_historic_stub, building, start, end, window, aggregate='MEAN')¶

Gets historic outdoor temperature as pd.series.

Parameters:	indoor_historic_stub – grpc stub for historic outdoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.series valus=float, index=time

xbos_services_getter.xbos_services_getter.get_preprocessed_outdoor_temperature(outdoor_historic_stub, building, start, end, window)¶

Gets historic outdoor temperature as pd.series.

Parameters:	indoor_historic_stub – grpc stub for historic outdoor temperature microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.series valus=float, index=time

xbos_services_getter.xbos_services_getter.get_outdoor_temperature_prediction_stub(OUTDOOR_TEMPERATURE_PREDICTION_HOST_ADDRESS=None, secure=True)¶

Get the stub to interact with the outdoor_temperature_prediction service.

Parameters:	OUTDOOR_TEMPERATURE_PREDICTION_HOST_ADDRESS – Optional argument to supply host address for given service. Otherwise, set as environment variable.
Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_outdoor_temperature_prediction(outdoor_prediction_stub, building, start, end, window)¶

Gets prediction outdoor temperature as pd.series.

Parameters:	outdoor_prediction_stub – grpc stub for outdoor temperature prediction microservice building – (str) building name zone – (str) zone name start – (datetime timezone aware) end – (datetime timezone aware) window – (str) the interval in which to split the data.
Returns:	pd.series valus=float, index=time

xbos_services_getter.xbos_services_getter.get_meter_data_historical_stub(METER_DATA_HISTORICAL_HOST_ADDRESS=None, secure=True)¶

Get stub to interact with meter data service. :param METER_DATA_HISTORICAL_HOST_ADDRESS: Optional argument to supply host address for given service. Otherwise,

set as environment variable.

Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_meter_data_historical(meter_data_stub, bldg, start, end, point_type, aggregate, window)¶

Get meter data as a dataframe.

Parameters:

meter_data_stub – grpc stub for meter data service.
bldg – list(str) - list of buildings.
start – datetime (timezone aware)
end – datetime (timezone aware)
point_type – (str) Building_Electric_Meter or Green_Button_Meter
aggregate – (str) Values include MEAN, MAX, MIN, COUNT, SUM and RAW (the temporal window parameter is ignored)
window – (str) Size of the moving window.

Returns:

pd.DataFrame(), defaultdict(list) - Meter data, dictionary that maps meter data’s columns (uuid’s) to sites

xbos_services_getter.xbos_services_getter.get_skyspark_stub(SKYSPARK_HOST_ADDRESS=None, secure=True)¶

Get stub to interact with skyspark data. :param SKYSPARK_HOST_ADDRESS: Optional argument to supply host address for given service. Otherwise,

set as environment variable.

Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_data_from_skyspark(skyspark_stub, query)¶

Get skyspark data as a dataframe.

Parameters:	skyspark_stub – grpc stub for skyspark data service query – (str) query for skyspark
Returns:	pd.DataFrame() - skyspark data

xbos_services_getter.xbos_services_getter.get_optimizer_stub(OPTIMIZER_HOST_ADDRESS=None, secure=True)¶

Get stub to interact with optimizer service. :param OPTIMIZER_HOST_ADDRESS: Optional argument to supply host address for given service. Otherwise,

set as environment variable.

Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_mpc_optimization(optimizer_stub, building, zones, start, end, window, lambda_val, starting_temperatures, unit='F')¶

Get the optimal actions according to MPC optimization.

Parameters:

optimizer_stub – grpc stub for optimizer service
building – (str) building name
zones – (list str) zones names
start – datetime (timezone aware)
end – datetime (timezone aware)
window – (str) the intervals in which to optimize
lambda_val – (float) between 0 and 1. The lambda value to balance cost and discomfort.
starting_temperatures – (dict) {str zone: float temperature} the starting temperatures of all zones in given building.
unit – (string) the unit of the temperature.

Returns:

(dict {(str) zone: (int) action) the optimal actions to take

xbos_services_getter.xbos_services_getter.get_mpc_simulation(optimizer_stub, building, zones, start, end, window, forecasting_horizon, lambda_val, starting_temperatures, unit='F', num_runs=1)¶

Get the simulation results according to MPC optimization. Stops get_mpc_simulation when param:end is reached.

Parameters:

optimizer_stub – grpc stub for optimizer service
building – (str) building name
zones – (list str) zones names
start – datetime (timezone aware)
end – datetime (timezone aware)
window – (str) the intervals in which to optimize
forecasting_horizon – (str) the timeframe for which to simulate at every step.
lambda_val – (float) between 0 and 1. The lambda value to balance cost and discomfort.
starting_temperatures – (dict) {str zone: float temperature} the starting temperatures of all zones in given building.
unit – (string) the unit of the temperature.
num_runs – (int) the number of runs of simulation to get a better idea of the variance of the simulation.

Returns:

actions: {iter_zone: [actions]} actions that were excecuted for: every step.
temperatures: ({iter_zone: [temperatures]) temperature seen: at every step.

len(actions[zone]) = (end - start)/window len(temperatures[zone]) = (end - start)/temperatures + 1

xbos_services_getter.xbos_services_getter.check_data(data, start, end, window, check_nan=False)¶

Checks if data has right times and optionally checks for nan. This includes checking that the daterange [param:start (inculsive) - param:end (exclusive)) is included in the data. And that the time-difference between datapoints equals to param:window.

Parameters:	data – pd.df or pd.series start – datetime (timezone aware) end – datetime (timezone aware) window – (string) check_nan – If False (default) will not return an error if a datapoint is Nan. If True, will error on nan

data points. :return: str err message. If no error, returns None.

xbos_services_getter.xbos_services_getter.get_baseline_optimizer_stub(BASELINE_OPTIMIZER_HOST_ADDRESS=None, secure=True)¶

Get stub to interact with optimizer service. :param BASELINE_OPTIMIZER_HOST_ADDRESS: Optional argument to supply host address for given service. Otherwise,

set as environment variable.

Returns:	grpc Stub object.

xbos_services_getter.xbos_services_getter.get_normal_schedule_action(baseline_optimizer_stub, building, zones, start, end, window, starting_temperatures, unit, occupancy, do_not_exceed)¶

xbos_services_getter.xbos_services_getter.get_setpoint_expansion_action(baseline_optimizer_stub, building, zones, start, end, window, starting_temperatures, unit, occupancy, do_not_exceed, expansion_degrees)¶

xbos_services_getter.xbos_services_getter.get_demand_charge_action(baseline_optimizer_stub, building, zones, start, end, window, starting_temperatures, unit, occupancy, do_not_exceed, max_zones, include_all_zones)¶