# BuildingSync Asset Extractor (BAE)
This package processes a BuildingSync file to extract asset information that can then be imported into SEED
## Installation
### Install from PyPI
```bash
pip install buildingsync-asset-extractor
```
### Install from source
[Poetry](https://python-poetry.org/) is required to install buildingsync-asset-extractor.
```bash
# Copy repo
git clone https://github.com/BuildingSync/BuildingSync-asset-extractor.git
# install the package
cd BuildingSync-asset-extractor
poetry install
# Test that it works, you should see a message describing the usage
poetry run buildingsync_asset_extractor
```
## Usage
### BUILDINGSYNC ASSET EXTRACTOR
BuildingSync version 2.4.0.
The pre-importer will identify assets defined in the `asset_definitions.json` file stored in the `config` directory.
There are various methods of calculating assets:
1. `sqft`. The sqft method will calculate a 'primary' and 'secondary' value for the asset based on the area it serves.
This is calculated from the floor areas defined in each `Section` element. `Conditioned` floor area values will be
used if present; `Gross` otherwise.
1. `num`. The num method will sum up all assets of the specified type and return a single overall number.
1. `avg`. The avg method will return an average value for all assets of the specified type found.
1. `avg_sqft`. The avg_sqft method will return a weighted average value for all assets of the specified type found based
on the area they serve.
1. `age_oldest`, `age_newest`, `age_average`. The age method will retrieve the 'YearOfManufacture' (or 'YearInstalled'
if not present) element of a specified equipment type and return either the oldest or newest, or average age (year)
as specified. Average age is calculated by a weighted average using the following (in order): capacity, served space
area, regular average.
1. `custom`. Use this method for particular asset that do not fit in the other categories; i.e. Heating Efficiency. Note
that a dedicated method may need to be written to support this type of asset.
When an asset has a unit associated with it, a separate asset will be generated to store the unit information. That
asset will be named the same as the original asset, with ' Units' appended at the end.
To test usage:
```bash
python buildingsync_asset_extractor/main.py
```
This will extract assets from `tests/files/testfile.xml` and save the results to `assets_output.json`
There are 2 methods of initializing the Processor: with either a filename or data
```bash
bp = BSyncProcessor(filename=filename)
```
or
```bash
bp = BSyncProcessor(data=file_data)
```
#### Assumptions
1. Assuming 1 building per file
1. Assuming sqft method uses "Conditioned" floor area for calculations. If not present, uses "Gross"
1. Assuming averages that use served space area must be defined in Sections (LinkedSectionIDs). LinkedBuildingID is not
used.
#### TODO
1. thermal zones: when spaces are listed within them with spaces (or multiple thermal zones), this would change the
average setpoint calculations. Is this an exception or a normal case to handle?
#### Assets Definitions File
This file is used to specify what assets to extract from a BuildingSync XML file. By default, the file found in
`config/asset_definitions.json` is used, but a custom file can be specified with the `set_asset_defs_file` method in the
`BSyncProcessor` class.
There are currently 5 types of assets that can be extracted:
1. sqft: Sqft assets take into account the floor area served by a specific asset and returns 'Primary' and 'Secondary'
values. For example: Primary HVAC System and Secondary HVAC System.
1. avg_sqft: Avg_sqft assets compute a weighted average to get the an average asset value. For example: Average Heating
Setpoint.
1. num: Num assets count the total number of the specified asset found. For example, Total number of lighting systems.
1. age_oldest, age_newest, and age_average: These types return the oldest or newest asset, or average age of a specific
type. For example: Oldest Boiler.
1. custom: For asset that need particular handling, such as Heating Efficiency. The current assets that have custom
methods are:
- Heating System Efficiency
- Cooling System Efficiency
- Lighting System Efficiency
- Water Heater Efficiency
- Heating Fuel Type
The schema for the assets definition JSON file is in `schemas/asset_definitions_schema.json`.
#### Extracted Assets File
The schema for the extracted assets JSON file is in `schemas/extracted_assets_schema.json`.
This file lists the extracted assets information in name, value, units triples. Names will match the `export_name`
listed in the asset_definitions JSON file, except for assets of type 'sqft', which will be prepended by 'Primary' and '
Secondary'.
### BUILDINGSYNC to CTS Spreadsheet Processor
This functionality takes in a list of buildingsync filepaths, runs the process to extract relevant information,
aggregate at the Facility level, and generate an XLSX file in the expected CTS format. This is the
`CTS Comprehensive Evaluation Upload Template`.
To test usage:
```bash
python buildingsync_asset_extractor/cts_main.py
```
This will process the 2 primary schools XML files (that will be aggregated into 1 facility) and the office XML file (
which will be another facility) found in `tests/files/` and generate a XLSX containing 2 facilities. The resulting file
will be saved to `tests\output\cts_output.xlsx`.
###
- BuildingSync files are aggregated by facility based on the Facility ID in the file. This ID can be found in the
`<Facility>` section, within the `<UserDefinedFields>` subsection:
```xml
<UserDefinedFields>
<UserDefinedField>
<FieldName>Agency Designated Covered Facility ID</FieldName>
<FieldValue>ABC 123</FieldValue>
</UserDefinedField>
<UserDefinedField>
<FieldName>Sub-agency Acronym</FieldName>
<FieldValue>ABC</FieldValue>
</UserDefinedField>
<UserDefinedField>
<FieldName>Facility Name</FieldName>
<FieldValue>Test Facility</FieldValue>
</UserDefinedField>
</UserDefinedFields>
```
- The process will extract the measures that are part of the `cheapest` scenario within each file. The measures will be
aggregated at the Facility level and the number of measures in each category will be added to the spreadsheet. If
there is no cost, no measures will be counted.
- More information about the BuildingSync to CTS mappings can be found in
the [cts_map page](buildingsync_asset_extractor/cts/cts_map.md).
## Developing
### Pre-commit
This project uses `pre-commit <https://pre-commit.com/>`_ to ensure code consistency.
To enable pre-commit on every commit run the following from the command line from within the git checkout of the
BuildingSync-asset-extractor
```bash
pre-commit install
```
To run pre-commit against the files without calling git commit, then run the following. This is useful when cleaning up
the repo before committing.
```bash
pre-commit run --all-files
```
### Testing
poetry run pytest
## Releasing
```bash
poetry build
# config and push to testpypi
poetry config repositories.testpypi https://test.pypi.org/legacy/
poetry publish -r testpypi
# install from testpypi
pip install --index-url https://test.pypi.org/simple/ buildingsync-asset-extractor
```
If everything looks good, publish to pypi:
```bash
poetry publish
```
If you have environment variables setup for PYPI token username and password:
```bash
poetry publish --build --username $PYPI_USERNAME --password $PYPI_PASSWORD
```
Raw data
{
"_id": null,
"home_page": "https://buildingsync.net",
"name": "buildingsync-asset-extractor",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.13,>=3.9",
"maintainer_email": null,
"keywords": "BuildingSync, Building Data Exchange",
"author": "Katherine Fleming",
"author_email": "katherine.fleming@nrel.gov",
"download_url": "https://files.pythonhosted.org/packages/88/5e/66896d118f3c4839a6b7e9650280275e06f8c9b7855da99df84abe07e073/buildingsync_asset_extractor-0.2.1.tar.gz",
"platform": null,
"description": "# BuildingSync Asset Extractor (BAE)\n\nThis package processes a BuildingSync file to extract asset information that can then be imported into SEED\n\n## Installation\n\n### Install from PyPI\n\n```bash\npip install buildingsync-asset-extractor\n```\n\n### Install from source\n\n[Poetry](https://python-poetry.org/) is required to install buildingsync-asset-extractor.\n\n```bash\n# Copy repo\ngit clone https://github.com/BuildingSync/BuildingSync-asset-extractor.git\n\n# install the package\ncd BuildingSync-asset-extractor\npoetry install\n\n# Test that it works, you should see a message describing the usage\npoetry run buildingsync_asset_extractor\n```\n\n## Usage\n\n### BUILDINGSYNC ASSET EXTRACTOR\n\nBuildingSync version 2.4.0.\n\nThe pre-importer will identify assets defined in the `asset_definitions.json` file stored in the `config` directory.\nThere are various methods of calculating assets:\n\n1. `sqft`. The sqft method will calculate a 'primary' and 'secondary' value for the asset based on the area it serves.\n This is calculated from the floor areas defined in each `Section` element. `Conditioned` floor area values will be\n used if present; `Gross` otherwise.\n\n1. `num`. The num method will sum up all assets of the specified type and return a single overall number.\n\n1. `avg`. The avg method will return an average value for all assets of the specified type found.\n\n1. `avg_sqft`. The avg_sqft method will return a weighted average value for all assets of the specified type found based\n on the area they serve.\n\n1. `age_oldest`, `age_newest`, `age_average`. The age method will retrieve the 'YearOfManufacture' (or 'YearInstalled'\n if not present) element of a specified equipment type and return either the oldest or newest, or average age (year)\n as specified. Average age is calculated by a weighted average using the following (in order): capacity, served space\n area, regular average.\n\n1. `custom`. Use this method for particular asset that do not fit in the other categories; i.e. Heating Efficiency. Note\n that a dedicated method may need to be written to support this type of asset.\n\nWhen an asset has a unit associated with it, a separate asset will be generated to store the unit information. That\nasset will be named the same as the original asset, with ' Units' appended at the end.\n\nTo test usage:\n\n```bash\npython buildingsync_asset_extractor/main.py\n```\n\nThis will extract assets from `tests/files/testfile.xml` and save the results to `assets_output.json`\n\nThere are 2 methods of initializing the Processor: with either a filename or data\n\n```bash\nbp = BSyncProcessor(filename=filename)\n```\n\nor\n\n```bash\nbp = BSyncProcessor(data=file_data)\n```\n\n#### Assumptions\n\n1. Assuming 1 building per file\n1. Assuming sqft method uses \"Conditioned\" floor area for calculations. If not present, uses \"Gross\"\n1. Assuming averages that use served space area must be defined in Sections (LinkedSectionIDs). LinkedBuildingID is not\n used.\n\n#### TODO\n\n1. thermal zones: when spaces are listed within them with spaces (or multiple thermal zones), this would change the\n average setpoint calculations. Is this an exception or a normal case to handle?\n\n#### Assets Definitions File\n\nThis file is used to specify what assets to extract from a BuildingSync XML file. By default, the file found in\n`config/asset_definitions.json` is used, but a custom file can be specified with the `set_asset_defs_file` method in the\n`BSyncProcessor` class.\n\nThere are currently 5 types of assets that can be extracted:\n\n1. sqft: Sqft assets take into account the floor area served by a specific asset and returns 'Primary' and 'Secondary'\n values. For example: Primary HVAC System and Secondary HVAC System.\n\n1. avg_sqft: Avg_sqft assets compute a weighted average to get the an average asset value. For example: Average Heating\n Setpoint.\n\n1. num: Num assets count the total number of the specified asset found. For example, Total number of lighting systems.\n\n1. age_oldest, age_newest, and age_average: These types return the oldest or newest asset, or average age of a specific\n type. For example: Oldest Boiler.\n\n1. custom: For asset that need particular handling, such as Heating Efficiency. The current assets that have custom\n methods are:\n - Heating System Efficiency\n - Cooling System Efficiency\n - Lighting System Efficiency\n - Water Heater Efficiency\n - Heating Fuel Type\n\nThe schema for the assets definition JSON file is in `schemas/asset_definitions_schema.json`.\n\n#### Extracted Assets File\n\nThe schema for the extracted assets JSON file is in `schemas/extracted_assets_schema.json`.\n\nThis file lists the extracted assets information in name, value, units triples. Names will match the `export_name`\nlisted in the asset_definitions JSON file, except for assets of type 'sqft', which will be prepended by 'Primary' and '\nSecondary'.\n\n### BUILDINGSYNC to CTS Spreadsheet Processor\n\nThis functionality takes in a list of buildingsync filepaths, runs the process to extract relevant information,\naggregate at the Facility level, and generate an XLSX file in the expected CTS format. This is the\n`CTS Comprehensive Evaluation Upload Template`.\n\nTo test usage:\n\n```bash\npython buildingsync_asset_extractor/cts_main.py\n```\n\nThis will process the 2 primary schools XML files (that will be aggregated into 1 facility) and the office XML file (\nwhich will be another facility) found in `tests/files/` and generate a XLSX containing 2 facilities. The resulting file\nwill be saved to `tests\\output\\cts_output.xlsx`.\n\n###\n\n- BuildingSync files are aggregated by facility based on the Facility ID in the file. This ID can be found in the\n `<Facility>` section, within the `<UserDefinedFields>` subsection:\n\n ```xml\n <UserDefinedFields>\n <UserDefinedField>\n <FieldName>Agency Designated Covered Facility ID</FieldName>\n <FieldValue>ABC 123</FieldValue>\n </UserDefinedField>\n <UserDefinedField>\n <FieldName>Sub-agency Acronym</FieldName>\n <FieldValue>ABC</FieldValue>\n </UserDefinedField>\n <UserDefinedField>\n <FieldName>Facility Name</FieldName>\n <FieldValue>Test Facility</FieldValue>\n </UserDefinedField>\n </UserDefinedFields>\n ```\n\n- The process will extract the measures that are part of the `cheapest` scenario within each file. The measures will be\n aggregated at the Facility level and the number of measures in each category will be added to the spreadsheet. If\n there is no cost, no measures will be counted.\n- More information about the BuildingSync to CTS mappings can be found in\n the [cts_map page](buildingsync_asset_extractor/cts/cts_map.md).\n\n## Developing\n\n### Pre-commit\n\nThis project uses `pre-commit <https://pre-commit.com/>`_ to ensure code consistency.\nTo enable pre-commit on every commit run the following from the command line from within the git checkout of the\nBuildingSync-asset-extractor\n\n```bash\npre-commit install\n```\n\nTo run pre-commit against the files without calling git commit, then run the following. This is useful when cleaning up\nthe repo before committing.\n\n```bash\npre-commit run --all-files\n```\n\n### Testing\n\n poetry run pytest\n\n## Releasing\n\n```bash\npoetry build\n\n# config and push to testpypi\npoetry config repositories.testpypi https://test.pypi.org/legacy/\npoetry publish -r testpypi\n\n# install from testpypi\npip install --index-url https://test.pypi.org/simple/ buildingsync-asset-extractor\n```\n\nIf everything looks good, publish to pypi:\n\n```bash\npoetry publish\n```\n\nIf you have environment variables setup for PYPI token username and password:\n\n```bash\npoetry publish --build --username $PYPI_USERNAME --password $PYPI_PASSWORD\n```\n",
"bugtrack_url": null,
"license": "BSD4",
"summary": "BuildingSync Asset Extractor (BAE)",
"version": "0.2.1",
"project_urls": {
"Documentation": "https://github.com/BuildingSync/BuildingSync-asset-extractor",
"Homepage": "https://buildingsync.net",
"Repository": "https://github.com/BuildingSync/BuildingSync-asset-extractor"
},
"split_keywords": [
"buildingsync",
" building data exchange"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bfcd7bc40d1b93eeaf9d68adb538f83c175bf3269035edad1aa182e87aacd416",
"md5": "4e6b88a75a02b90a2232322cdd59bc04",
"sha256": "282b33cd4ce81502e2dbe66fc96ea46bdd7a0c04a2eef92fb269b3c3f6d84664"
},
"downloads": -1,
"filename": "buildingsync_asset_extractor-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4e6b88a75a02b90a2232322cdd59bc04",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.13,>=3.9",
"size": 80348,
"upload_time": "2024-10-09T21:42:37",
"upload_time_iso_8601": "2024-10-09T21:42:37.988427Z",
"url": "https://files.pythonhosted.org/packages/bf/cd/7bc40d1b93eeaf9d68adb538f83c175bf3269035edad1aa182e87aacd416/buildingsync_asset_extractor-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "885e66896d118f3c4839a6b7e9650280275e06f8c9b7855da99df84abe07e073",
"md5": "c312aade1d8c3704e9d51f6da21d598f",
"sha256": "fe7f377e12a2da01d86a83a5f63bb232242fecc64b36ecc87e467d788fcac689"
},
"downloads": -1,
"filename": "buildingsync_asset_extractor-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "c312aade1d8c3704e9d51f6da21d598f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.13,>=3.9",
"size": 76455,
"upload_time": "2024-10-09T21:42:39",
"upload_time_iso_8601": "2024-10-09T21:42:39.773788Z",
"url": "https://files.pythonhosted.org/packages/88/5e/66896d118f3c4839a6b7e9650280275e06f8c9b7855da99df84abe07e073/buildingsync_asset_extractor-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 21:42:39",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BuildingSync",
"github_project": "BuildingSync-asset-extractor",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "buildingsync-asset-extractor"
}
JSON
