# TAIL-Rating-Py
TAIL-Rating-Py is a Python package designed to assess TAIL (Thermal, Acoustic, Indoor Air Quality, and Lighting) for buildings. The package provides data models and functions to facilitate the TAIL project.
It follows the development made by Prof. Pawel Wargocki and his team at the International Centre for Indoor Environment and Energy, Technical University of Denmark.
> **WARNING**: This package is still under development and should be used with caution. The implementation is based on the original script provided by @asitkm76 . The package is not yet verified and tested. The documentation and examples are still in progress. The performance and the code quality will be improved in the future.
## Original Script
The original script can be found [here](https://github.com/asitkm76/TAILRatingScheme).
## Features
The package includes the following modules:
- `model`: Contains the data models for buildings, rooms, sensor data, data points, and sensor attributes.
- `parser`: Contains functions to parse sensor data from CSV files.
- `categorise`: Contains functions to categorise buildings and rooms based on sensor data.
- `tail`: Contains functions to assign TAIL ratings to buildings and rooms.
- `dummy_data`: Contains functions to create dummy data for testing purposes.
## Installation
To install the package, run:
```sh
pip install tail-rating-py
```
## Release History
You can find the release history in the [CHANGELOG.md](CHANGELOG.md) file.
## Data Models
### Building
The `Building` model represents a building in the TAIL project. It includes attributes such as `id`, `name`, `floorArea`, `occupants`, `buildingType`, `coordinates`, `schedule`, `rooms`, and `tail_rating`.
### Room
The `Room` model represents a room within a building. It includes attributes such as `id`, `name`, `floorArea`, `occupants`, `pollutionLevel`, `roomType`, `schedule`, `sensors`, `room_df`, and `tail`.
### SensorData
The `SensorData` model represents data collected by a sensor. It includes attributes such as `id`, `sensorName`, `attributes`, `data`, `schedule`, `sensor_df`, and `quality`.
### DataPoint and SensorAttribute
The `DataPoint` model represents a data point collected by a sensor. It includes attributes such as `timestamp` and `records`.
The `SensorAttribute` model represents the attributes that can be collected by sensors, such as `AIR_TEMPERATURE`, `RELATIVE_HUMIDITY`, `ILLUMINANCE`, etc.
## Example Usage
Here's an example of how to create and use these models:
```python
from datetime import datetime
from TAIL.model import Building, BuildingType, Room, SensorData, DataPoint, SensorAttribute, Attribute, Unit
# Create a Building
building = Building(
name="Office Building",
floorArea=1000.0,
occupants=50,
buildingType=BuildingType.OFFICE,
coordinates="40.7128° N, 74.0060° W"
)
# Create a Room
room = Room(
name="Conference Room",
floorArea=50.0,
occupants=10,
roomType="Conference",
building=building
)
# Create a SensorAttribute
sensor_attribute = SensorAttribute(
attribute=Attribute.AIR_TEMPERATURE,
unit=Unit.CELSIUS
)
# Create a DataPoint
data_point = DataPoint(
timestamp=datetime.now(),
records=[{"sensorAttr": sensor_attribute, "value": 23.0}]
)
# Create SensorData
sensor_data = SensorData(
sensorName="Temperature Sensor",
attributes=[sensor_attribute],
data=[data_point],
room=room
)
# Add the room to the building
building.add_room(room)
# Add the sensor data to the room
room.add_sensor(sensor_data)
# Print the building
print(building.model_dump_json(indent=2))
```
## Assessing TAIL for Buildings
This guide explains how to assess TAIL for buildings using the provided Python code.
### Steps to Assess TAIL
1. **Create the Building Model**
Use the `parse_original_csv` function to create the building model from a CSV file containing sensor data.
```python
from TAIL.parser import parse_original_csv
building = parse_original_csv("TAILSampleData.csv")
```
2. **Categorise the Building Model**
Categorise the building model using the `categorise` function.
```python
from TAIL.categorise import categorise
building = categorise(building[0])
```
3. **Assign TAIL Ratings to the Rooms**
Assign TAIL ratings to the rooms in the building using the `assign_tail_rating` function.
```python
from TAIL.tail import assign_tail_rating
building = assign_tail_rating(building)
```
4. **Assign TAIL Rating to the Building**
Assign an overall TAIL rating to the building using the `assign_tail_rating_to_building` function.
```python
from TAIL.tail import assign_tail_rating_to_building
building = assign_tail_rating_to_building(building)
```
5. **Print the Building Model**
Print the building model in JSON format.
```python
print(building.model_dump_json(indent=2))
```
6. **Save the Building Model to a File**
Save the building model to a file in JSON format.
```python
with open('building_model.json', 'w') as f:
f.write(building.model_dump_json(indent=2))
```
### Example Usage in a Script
Here's an example of how you might use these steps in a script:
```python
# %% Import necessary functions
from TAIL.dummy_data import create_building_model
from TAIL.categorise import categorise
from TAIL.tail import assign_tail_rating, assign_tail_rating_to_building
# %% [1] Example usage - using dummy data
# Create a building model
building = create_building_model()
# Categorise the building model
building = categorise(building)
# Assign TAIL ratings to the rooms in the building
building = assign_tail_rating(building)
# Assign TAIL rating to the building
building = assign_tail_rating_to_building(building)
# Print the building model
print(building.model_dump_json(indent=2))
# Save the building model to a file in JSON format
with open('dummy_data.json', 'w') as f:
f.write(building.model_dump_json(indent=2))
# %% [2] Example usage - using sensor data from a CSV file
from TAIL.parser import parse_original_csv
buildings = parse_original_csv("TAILSampleData.csv")
building = buildings[0]
# Categorise the building model
building = categorise(building)
# Assign TAIL ratings to the rooms in the building
building = assign_tail_rating(building)
# Assign TAIL rating to the building
building = assign_tail_rating_to_building(building)
# Print the building model
print(building.model_dump_json(indent=2))
# Save the building model to a file in JSON format
with open('TAILSampleData.json', 'w') as f:
f.write(building.model_dump_json(indent=2))
```
This example demonstrates how to create a building model from sensor data, categorise it, assign TAIL ratings, and save the results.
## License
GNU General Public License v3.0
## Future development
- [ ] Verification of the implementation and testing.
- [ ] Add the graphical representation of the TAIL ratings.
- [ ] Improve the categorisation and rating at the building level based on the original script.
- [ ] Implement more roomType, buildingType
- [ ] Improve the documentation and examples.
- [ ] Clean the code and improve the performance.
- [ ] Unit tests.
## References
[Pawel Wargocki et al.](https://www.sciencedirect.com/science/article/pii/S0378778821003133), TAIL: A new scheme for rating indoor environmental quality in offices and hotels undergoing deep energy renovation (EU ALDREN project), Energy and Buildings, Volume 244, 2021, 111029, ISSN 0378-7788, https://doi.org/10.1016/j.enbuild.2021.111029.
## Acknowledgements
- [Prof. Pawel Wargocki](https://www.researchgate.net/profile/Pawel-Wargocki)
- @asitkm76, for the initial implementation of the TAIL rating in R and Juptyer notebook.
## Contact
For any questions or suggestions, please contact the author at [bruno.adam@pm.me](mailto:bruno.adam@pm.me).
Raw data
{
"_id": null,
"home_page": null,
"name": "tail-rating-py",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "tail thermal acoustic indoor air quality lighting",
"author": "Bruno Adam",
"author_email": "bruno.adam@pm.me",
"download_url": "https://files.pythonhosted.org/packages/bf/d8/cbd4b0249bb690454b5c7785e50d8c41f1eeefa6e7601a813f2370ab126f/tail-rating-py-0.1.2.tar.gz",
"platform": null,
"description": "# TAIL-Rating-Py\r\n\r\nTAIL-Rating-Py is a Python package designed to assess TAIL (Thermal, Acoustic, Indoor Air Quality, and Lighting) for buildings. The package provides data models and functions to facilitate the TAIL project.\r\n\r\nIt follows the development made by Prof. Pawel Wargocki and his team at the International Centre for Indoor Environment and Energy, Technical University of Denmark.\r\n\r\n> **WARNING**: This package is still under development and should be used with caution. The implementation is based on the original script provided by @asitkm76 . The package is not yet verified and tested. The documentation and examples are still in progress. The performance and the code quality will be improved in the future.\r\n\r\n## Original Script\r\n\r\nThe original script can be found [here](https://github.com/asitkm76/TAILRatingScheme).\r\n\r\n## Features\r\n\r\nThe package includes the following modules:\r\n- `model`: Contains the data models for buildings, rooms, sensor data, data points, and sensor attributes.\r\n- `parser`: Contains functions to parse sensor data from CSV files.\r\n- `categorise`: Contains functions to categorise buildings and rooms based on sensor data.\r\n- `tail`: Contains functions to assign TAIL ratings to buildings and rooms.\r\n- `dummy_data`: Contains functions to create dummy data for testing purposes.\r\n\r\n## Installation\r\n\r\nTo install the package, run:\r\n```sh\r\npip install tail-rating-py\r\n```\r\n\r\n## Release History\r\n\r\nYou can find the release history in the [CHANGELOG.md](CHANGELOG.md) file.\r\n\r\n## Data Models\r\n\r\n### Building\r\n\r\nThe `Building` model represents a building in the TAIL project. It includes attributes such as `id`, `name`, `floorArea`, `occupants`, `buildingType`, `coordinates`, `schedule`, `rooms`, and `tail_rating`.\r\n\r\n### Room\r\n\r\nThe `Room` model represents a room within a building. It includes attributes such as `id`, `name`, `floorArea`, `occupants`, `pollutionLevel`, `roomType`, `schedule`, `sensors`, `room_df`, and `tail`.\r\n\r\n### SensorData\r\n\r\nThe `SensorData` model represents data collected by a sensor. It includes attributes such as `id`, `sensorName`, `attributes`, `data`, `schedule`, `sensor_df`, and `quality`.\r\n\r\n### DataPoint and SensorAttribute\r\n\r\nThe `DataPoint` model represents a data point collected by a sensor. It includes attributes such as `timestamp` and `records`.\r\n\r\nThe `SensorAttribute` model represents the attributes that can be collected by sensors, such as `AIR_TEMPERATURE`, `RELATIVE_HUMIDITY`, `ILLUMINANCE`, etc.\r\n\r\n## Example Usage\r\n\r\nHere's an example of how to create and use these models:\r\n\r\n```python\r\nfrom datetime import datetime\r\nfrom TAIL.model import Building, BuildingType, Room, SensorData, DataPoint, SensorAttribute, Attribute, Unit\r\n\r\n# Create a Building\r\nbuilding = Building(\r\n name=\"Office Building\",\r\n floorArea=1000.0,\r\n occupants=50,\r\n buildingType=BuildingType.OFFICE,\r\n coordinates=\"40.7128\u00c2\u00b0 N, 74.0060\u00c2\u00b0 W\"\r\n)\r\n\r\n# Create a Room\r\nroom = Room(\r\n name=\"Conference Room\",\r\n floorArea=50.0,\r\n occupants=10,\r\n roomType=\"Conference\",\r\n building=building\r\n)\r\n\r\n# Create a SensorAttribute\r\nsensor_attribute = SensorAttribute(\r\n attribute=Attribute.AIR_TEMPERATURE, \r\n unit=Unit.CELSIUS\r\n)\r\n\r\n# Create a DataPoint\r\ndata_point = DataPoint(\r\n timestamp=datetime.now(),\r\n records=[{\"sensorAttr\": sensor_attribute, \"value\": 23.0}]\r\n)\r\n\r\n# Create SensorData\r\nsensor_data = SensorData(\r\n sensorName=\"Temperature Sensor\",\r\n attributes=[sensor_attribute],\r\n data=[data_point],\r\n room=room\r\n)\r\n\r\n# Add the room to the building\r\nbuilding.add_room(room)\r\n\r\n# Add the sensor data to the room\r\nroom.add_sensor(sensor_data)\r\n\r\n# Print the building\r\nprint(building.model_dump_json(indent=2))\r\n```\r\n\r\n## Assessing TAIL for Buildings\r\n\r\nThis guide explains how to assess TAIL for buildings using the provided Python code.\r\n\r\n### Steps to Assess TAIL\r\n\r\n1. **Create the Building Model**\r\n\r\n Use the `parse_original_csv` function to create the building model from a CSV file containing sensor data.\r\n\r\n ```python\r\n from TAIL.parser import parse_original_csv\r\n\r\n building = parse_original_csv(\"TAILSampleData.csv\")\r\n ```\r\n\r\n2. **Categorise the Building Model**\r\n\r\n Categorise the building model using the `categorise` function.\r\n\r\n ```python\r\n from TAIL.categorise import categorise\r\n\r\n building = categorise(building[0])\r\n ```\r\n\r\n3. **Assign TAIL Ratings to the Rooms**\r\n\r\n Assign TAIL ratings to the rooms in the building using the `assign_tail_rating` function.\r\n\r\n ```python\r\n from TAIL.tail import assign_tail_rating\r\n\r\n building = assign_tail_rating(building)\r\n ```\r\n\r\n4. **Assign TAIL Rating to the Building**\r\n\r\n Assign an overall TAIL rating to the building using the `assign_tail_rating_to_building` function.\r\n\r\n ```python\r\n from TAIL.tail import assign_tail_rating_to_building\r\n\r\n building = assign_tail_rating_to_building(building)\r\n ```\r\n\r\n5. **Print the Building Model**\r\n\r\n Print the building model in JSON format.\r\n\r\n ```python\r\n print(building.model_dump_json(indent=2))\r\n ```\r\n\r\n6. **Save the Building Model to a File**\r\n\r\n Save the building model to a file in JSON format.\r\n\r\n ```python\r\n with open('building_model.json', 'w') as f:\r\n f.write(building.model_dump_json(indent=2))\r\n ```\r\n\r\n### Example Usage in a Script\r\n\r\nHere's an example of how you might use these steps in a script:\r\n\r\n```python\r\n# %% Import necessary functions\r\nfrom TAIL.dummy_data import create_building_model\r\nfrom TAIL.categorise import categorise\r\nfrom TAIL.tail import assign_tail_rating, assign_tail_rating_to_building\r\n\r\n# %% [1] Example usage - using dummy data\r\n# Create a building model\r\nbuilding = create_building_model()\r\n\r\n# Categorise the building model\r\nbuilding = categorise(building)\r\n\r\n# Assign TAIL ratings to the rooms in the building\r\nbuilding = assign_tail_rating(building)\r\n\r\n# Assign TAIL rating to the building\r\nbuilding = assign_tail_rating_to_building(building)\r\n\r\n# Print the building model\r\nprint(building.model_dump_json(indent=2))\r\n\r\n# Save the building model to a file in JSON format\r\nwith open('dummy_data.json', 'w') as f:\r\n f.write(building.model_dump_json(indent=2))\r\n\r\n# %% [2] Example usage - using sensor data from a CSV file\r\nfrom TAIL.parser import parse_original_csv\r\n\r\nbuildings = parse_original_csv(\"TAILSampleData.csv\")\r\nbuilding = buildings[0]\r\n\r\n# Categorise the building model\r\nbuilding = categorise(building)\r\n\r\n# Assign TAIL ratings to the rooms in the building\r\nbuilding = assign_tail_rating(building)\r\n\r\n# Assign TAIL rating to the building\r\nbuilding = assign_tail_rating_to_building(building)\r\n\r\n# Print the building model\r\nprint(building.model_dump_json(indent=2))\r\n\r\n# Save the building model to a file in JSON format\r\nwith open('TAILSampleData.json', 'w') as f:\r\n f.write(building.model_dump_json(indent=2))\r\n```\r\n\r\nThis example demonstrates how to create a building model from sensor data, categorise it, assign TAIL ratings, and save the results.\r\n\r\n## License\r\nGNU General Public License v3.0\r\n\r\n## Future development\r\n- [ ] Verification of the implementation and testing.\r\n- [ ] Add the graphical representation of the TAIL ratings.\r\n- [ ] Improve the categorisation and rating at the building level based on the original script.\r\n- [ ] Implement more roomType, buildingType\r\n- [ ] Improve the documentation and examples.\r\n- [ ] Clean the code and improve the performance.\r\n- [ ] Unit tests.\r\n\r\n## References\r\n[Pawel Wargocki et al.](https://www.sciencedirect.com/science/article/pii/S0378778821003133), TAIL: A new scheme for rating indoor environmental quality in offices and hotels undergoing deep energy renovation (EU ALDREN project), Energy and Buildings, Volume 244, 2021, 111029, ISSN 0378-7788, https://doi.org/10.1016/j.enbuild.2021.111029.\r\n\r\n## Acknowledgements\r\n- [Prof. Pawel Wargocki](https://www.researchgate.net/profile/Pawel-Wargocki)\r\n\r\n- @asitkm76, for the initial implementation of the TAIL rating in R and Juptyer notebook.\r\n\r\n## Contact\r\n\r\nFor any questions or suggestions, please contact the author at [bruno.adam@pm.me](mailto:bruno.adam@pm.me).\r\n\r\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "A Python package designed to assess TAIL (Thermal, Acoustic, Indoor Air Quality, and Lighting) for buildings.",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [
"tail",
"thermal",
"acoustic",
"indoor",
"air",
"quality",
"lighting"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "188bb773d5df05ffe18b88530fed2bbc3c9aa99880306f89404177b351a0e374",
"md5": "b144df3b12ec76ea4f42fc319fa8ea21",
"sha256": "daa6ca430216ffa37b221cc1ef5091b64849401bb247aab0f8ccb9e17d8727bf"
},
"downloads": -1,
"filename": "tail_rating_py-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b144df3b12ec76ea4f42fc319fa8ea21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 33415,
"upload_time": "2025-01-15T17:04:51",
"upload_time_iso_8601": "2025-01-15T17:04:51.620465Z",
"url": "https://files.pythonhosted.org/packages/18/8b/b773d5df05ffe18b88530fed2bbc3c9aa99880306f89404177b351a0e374/tail_rating_py-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bfd8cbd4b0249bb690454b5c7785e50d8c41f1eeefa6e7601a813f2370ab126f",
"md5": "48a4dc37912abf3b5d1662d630bcdca0",
"sha256": "e624529e4a21dcf73fd9acca45f8f8dc44f1791ae7f55d51bd830c9d2962d1a9"
},
"downloads": -1,
"filename": "tail-rating-py-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "48a4dc37912abf3b5d1662d630bcdca0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 32556,
"upload_time": "2025-01-15T17:04:53",
"upload_time_iso_8601": "2025-01-15T17:04:53.775780Z",
"url": "https://files.pythonhosted.org/packages/bf/d8/cbd4b0249bb690454b5c7785e50d8c41f1eeefa6e7601a813f2370ab126f/tail-rating-py-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-15 17:04:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "tail-rating-py"
}
JSON