Welcome to preheat_open’s documentation!
The Preheat Open module
PreHEAT Open Python Package
This is the open Python package to consume Neogrids REST API. For a quick introduction, see demo.ipynb.
Installation
Simple installation:
Install the package directly from PyPi using:
pip install preheat_open
Configuring the toolbox
First, make sure that you have created an API key for your user. This can be done on your user profile page in the PreHEAT App.
Now, you can store the API key in a configuration file. This user configuration file should be created in the following places:
OS |
User level (recommended) |
Machine level |
|---|---|---|
Windows |
C:/Users/[your user]/.preheat/config.json |
(unsupported) |
Linux |
~/.preheat/config.json |
/etc[/opt]/preheat/config.json |
The configuration files are read in the following priority order (using the first available):
1- User level
2- Machine level (Linux only): /etc/opt/preheat/config.json
3- Machine level (Linux only): /etc/preheat/config.json
And then add the following content in this file (adjusting with your API key):
{
"PREHEAT_API_KEY": "YOUR_API_KEY_HERE"
}
Alternatively, you can also just import it explicitly in your code using the following command in your code (this is however not recommended, as you risk compromising your API key when sharing your code with others) :
from preheat_open import set_api_key
set_api_key("YOUR_API_KEY_HERE")
Contributions
We encourage pull requests if you have developed new interesting features.
The api module
This module defines the basics of the interaction with Neogrid’s web API
- exception preheat_open.api.APIDataExtractError
- exception preheat_open.api.APIKeyMissingError
- exception preheat_open.api.AccessDeniedError
- class preheat_open.api.ApiSession(*args, **kwargs)
Classs for something about Apisessions???
- addr()
- Returns
- Return type
- api_get(endpoint, out='json', payload=None, headers=None)
- Parameters
endpoint –
out –
payload –
headers –
- Returns
- Return type
- api_put(endpoint, json_payload=None)
- Parameters
endpoint –
json_payload –
- Returns
- Return type
- get_api_key()
- Returns
- Return type
- set_api_key(api_key=None)
- Parameters
api_key (
Optional[str]) –- Returns
- Return type
- set_api_url(api_url=None)
- Parameters
api_url –
- Returns
- Return type
- exception preheat_open.api.MissingConfigurationFile
- preheat_open.api.api_get(endpoint, out='json', payload=None, headers=None)
- Parameters
endpoint (
str) –out (
str) –payload –
headers –
- Returns
- Return type
- preheat_open.api.api_put(endpoint, json_payload=None)
- Parameters
endpoint (
str) –json_payload –
- Returns
- Return type
- preheat_open.api.api_string_to_datetime(t)
- Parameters
t (
str) –- Returns
- Return type
- preheat_open.api.configuration_file_path()
- Returns
- Return type
- preheat_open.api.datetime_to_api_string(t)
- Parameters
t (
datetime) –- Returns
- Return type
- preheat_open.api.ids_list_to_string(list2use, separator=',')
Helper function to turn list into string, e.g. comma separated (default).
- Parameters
list2use –
separator (
str) –
- Returns
- Return type
- preheat_open.api.load_configuration()
- Returns
- Return type
- preheat_open.api.set_api_key(api_key)
- Parameters
api_key (
str) –- Returns
- Return type
- preheat_open.api.set_api_url(api_url)
- Parameters
api_url (
str) –- Returns
- Return type
The building module
This module defines the Building class, which represents buildings containing different units and their data
- class preheat_open.building.Building(location_id)
Building defines a building in the PreHEAT sense
- clear_data()
- Returns
- Return type
- get_all_component_details()
- Returns
- Return type
- get_all_component_ids()
- Returns
- Return type
- get_supply_points()
- Returns
- Return type
- get_unit_graph()
- Returns
- Return type
- get_zone(id)
- Parameters
id (
int) –- Returns
- Return type
- get_zones(zone_ids)
- Parameters
zone_ids –
- Returns
- Return type
- load_data(start_date, end_date, time_resolution='hour', components={})
- Parameters
start_date –
end_date –
time_resolution (
str) –components (
Optional[Dict]) –
- Returns
- Return type
- load_dataset(component_map, start_date, end_date, time_resolution='hour', load_weather=True)
- Parameters
component_map –
start_date –
end_date –
time_resolution (
str) –load_weather (
bool) –
- Returns
- Return type
- qu(*args, **kwargs)
- Parameters
args –
kwargs –
- Returns
- Return type
- query_units(unit_type=None, name=None, unit_id=None)
- Parameters
unit_type (
Optional[str]) –name (
Optional[str]) –unit_id (
Optional[int]) –
- Returns
- Return type
- preheat_open.building.available_buildings()
Lists available buildings
- Returns
dataframe of buildings available
- Return type
The building_unit module
- class preheat_open.building_unit.BaseBuildingUnit(unit_type, unit_data, building_ref)
Building Unit; an extension of Unit to handle zones and parent units
- class preheat_open.building_unit.BuildingUnit(unit_type, unit_data, building_ref)
Building Unit; an extension of BaseBuildingUnit to handle subUnits
The data module
The helpers module
- preheat_open.helpers.list_to_string(list2use, separator=',')
Helper function to turn list into string, e.g. comma separated (default).
- Return type
str
The logging module
- preheat_open.logging.logging_level(level)
Converts a string to a logging level
- Parameters
level (
str) – logging level (debug, info, warning, error, critical)- Returns
logging level identifier (in logging package)
- Return type
- preheat_open.logging.set_logging_level(level)
Sets the logging level
- Parameters
level (
str) – logging level (debug, info, warning, error, critical)- Return type
None
The price module
The setpoints module
- exception preheat_open.setpoints.InvalidSchedule
The singleton module
The unit module
- class preheat_open.unit.Unit(unit_type, unit_data)
Defines a unit in the PreHEAT sense
The unit_graph module
- preheat_open.unit_graph.draw_graph(graph)
Draws graph using networkx built in draw function. This is not pretty, but will help to see if graph is constructed correctly.
- preheat_open.unit_graph.generate_unit_graph(building)
Function to build unit graph from a Building object. Iterates through units (nodes) and builds graph based on relations (sub-units). Returns a networkx directed multigraph.
- preheat_open.unit_graph.load_data_graph(graph, start_date, end_date, time_resolution)
Loads data for a graph. Loops through nodes (units) and loads data on the units with the given start, end and resolution. Does not return anything – data is held in the Unit objects.
- preheat_open.unit_graph.obtain_loop(graph, id)
Function which first finds a tree, based on id of origin unit/node. The end nodes of the tree are then connected back to the origin, to form a loop/circuit – for circuit analysis.
The weather module
- class preheat_open.weather.Weather(location_id, weather_data)
Weather; an extension of Unit to handle Weather extraction
The zone module
- class preheat_open.zone.Zone(zone_data, parent_zone=None)
Defines a building zone in the PreHEAT sense
- get_type()
Returns the type of the zone (‘room’, ‘stairway’, ‘corridor’, ‘bathroom’, ‘kitchen’) and its ‘dryness’ (‘dry’, ‘wet’, ‘?’)
- Return type
Tuple[str,str]- Returns
zone_type, wet_or_dry
- get_units(unit_type, sub_zones=True)
Returns the coupled units of a given type
- Parameters
unit_type – str
sub_zones – bool (True)
- Return type
List[BaseBuildingUnit]- Returns
list(BuildingUnit) or None