| Name | ubc-solar-data-tools JSON |
| Version |
1.3.1
JSON |
| download |
| home_page | None |
| Summary | UBC Solar's data analysis and querying tools |
| upload_time | 2024-10-19 20:13:53 |
| maintainer | None |
| docs_url | None |
| author | Joshua Riefman |
| requires_python | <4.0,>=3.10 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# UBC Solar Data Tools
<!-- marker-index-start -->
[](https://ubc-solar-data-tools.readthedocs.io/en/latest/?badge=latest)
A collection of data querying, analysis, and structuring tools.
## Requirements
Versions for dependencies (except Python) indicated are recommended
* Git [^1]
* Python >=3.9 [^2]
* Poetry >=1.8.3 [^3]
## Installation
First, clone this repository.
```bash
git clone https://github.com/UBC-Solar/data_tools.git
```
Then, create and activate a virtual environment.
This project uses Poetry for dependency management. Next, use Poetry to install dependencies, with `--no-root` so that the `data_tools` package does not itself get installed into your virtual environment. This can be omitted if you're sure you know what you are doing.
```bash
poetry install --no-root
```
Optionally, you can install dependencies for building the documentation and running tests.
```bash
poetry install --no-root --with docs --with test
```
## Getting Started
Example of querying data and plotting it as a `TimeSeries`.
> When the `InfluxClient` class is imported, `data_tools` will attempt to locate a `.env` file in order to acquire an InfluxDB API token. If you do not have a `.env` or it is missing an API token, you will not be able to query data. UBC Solar members can acquire an API token by speaking to their Team Lead.
```python
from data_tools.collections.time_series import TimeSeries
from data_tools.query.influxdb_query import DBClient
client = DBClient()
# ISO 8601-compliant times corresponding to pre-competition testing
start = "2024-07-07T02:23:57Z"
stop = "2024-07-07T02:34:15Z"
# We can, in one line, make a query to InfluxDB and parse
# the data into a powerful format: the `TimeSeries` class.
voltage_data: TimeSeries = client.query_time_series(
start=start,
stop=stop,
field="TotalPackVoltage",
units="V"
)
# Plot the data
voltage_data.plot()
```
Example of using the `FluxQuery` module to make a Flux query that selects and aggregates some data.
We will use the `FluxStatement` class to construct a custom Flux statement, as the `aggregateWindow` statement is not yet included by this API.
```python
from data_tools.query.flux import FluxQuery, FluxStatement
from data_tools.query.influxdb_query import DBClient
from data_tools.collections.time_series import TimeSeries
import pandas as pd
client = DBClient()
# ISO 8601-compliant times corresponding to pre-competition testing
start = "2024-07-07T02:23:57Z"
stop = "2024-07-07T02:34:15Z"
# The priority argument defines "where" in the Flux query the statement will get placed. Higher priority -> later
aggregate_flux_statement = FluxStatement('aggregateWindow(every: 10m, fn: mean, createEmpty: false)', priority=5)
query = FluxQuery()\
.range(start=start, stop=stop)\
.filter(field="VehicleVelocity")\
.inject_raw(aggregate_flux_statement)
# We can inspect the Flux query
print(query.compile_query())
# Make the query, getting the data as a DataFrame
query_dataframe: pd.DataFrame = client.query_dataframe(query)
# Now, convert the data into a TimeSeries
measurement_period: float = 1.0 / 5 # VehicleVelocity is a 5Hz measurement, so period is 1.0 / 5Hz.
vehicle_velocity = TimeSeries.from_query_dataframe(query_dataframe, measurement_period,
field="VehicleVelocity",
units="m/s")
# Plot the data
vehicle_velocity.plot()
```
## Appendix
[^1]: use `git --version` to verify version
[^2]: use `python3 --version` to verify version
[^3]: use `poetry --version` to verify version
<!-- marker-index-end -->
Raw data
{
"_id": null,
"home_page": null,
"name": "ubc-solar-data-tools",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Joshua Riefman",
"author_email": "joshuariefman@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/28/f6/6771833723a0c6cc4dbff1499ecacc71384c25ccbc8af0c400ffcb13e7aa/ubc_solar_data_tools-1.3.1.tar.gz",
"platform": null,
"description": "# UBC Solar Data Tools\n\n<!-- marker-index-start -->\n\n[](https://ubc-solar-data-tools.readthedocs.io/en/latest/?badge=latest)\n\nA collection of data querying, analysis, and structuring tools.\n\n## Requirements\n\nVersions for dependencies (except Python) indicated are recommended\n\n* Git [^1]\n* Python >=3.9 [^2]\n* Poetry >=1.8.3 [^3]\n\n## Installation\n\nFirst, clone this repository.\n\n```bash\ngit clone https://github.com/UBC-Solar/data_tools.git\n```\nThen, create and activate a virtual environment.\nThis project uses Poetry for dependency management. Next, use Poetry to install dependencies, with `--no-root` so that the `data_tools` package does not itself get installed into your virtual environment. This can be omitted if you're sure you know what you are doing. \n\n```bash\npoetry install --no-root\n```\n\nOptionally, you can install dependencies for building the documentation and running tests.\n```bash\npoetry install --no-root --with docs --with test\n```\n\n## Getting Started\n\nExample of querying data and plotting it as a `TimeSeries`.\n\n> When the `InfluxClient` class is imported, `data_tools` will attempt to locate a `.env` file in order to acquire an InfluxDB API token. If you do not have a `.env` or it is missing an API token, you will not be able to query data. UBC Solar members can acquire an API token by speaking to their Team Lead.\n\n```python\nfrom data_tools.collections.time_series import TimeSeries\nfrom data_tools.query.influxdb_query import DBClient\n\nclient = DBClient()\n\n# ISO 8601-compliant times corresponding to pre-competition testing\nstart = \"2024-07-07T02:23:57Z\" \nstop = \"2024-07-07T02:34:15Z\"\n\n# We can, in one line, make a query to InfluxDB and parse \n# the data into a powerful format: the `TimeSeries` class.\nvoltage_data: TimeSeries = client.query_time_series(\n start=start,\n stop=stop,\n field=\"TotalPackVoltage\",\n units=\"V\"\n)\n\n# Plot the data\nvoltage_data.plot()\n```\n\nExample of using the `FluxQuery` module to make a Flux query that selects and aggregates some data.\nWe will use the `FluxStatement` class to construct a custom Flux statement, as the `aggregateWindow` statement is not yet included by this API.\n\n```python\nfrom data_tools.query.flux import FluxQuery, FluxStatement\nfrom data_tools.query.influxdb_query import DBClient\nfrom data_tools.collections.time_series import TimeSeries\nimport pandas as pd\n\nclient = DBClient()\n\n# ISO 8601-compliant times corresponding to pre-competition testing\nstart = \"2024-07-07T02:23:57Z\" \nstop = \"2024-07-07T02:34:15Z\"\n\n# The priority argument defines \"where\" in the Flux query the statement will get placed. Higher priority -> later\naggregate_flux_statement = FluxStatement('aggregateWindow(every: 10m, fn: mean, createEmpty: false)', priority=5)\n\nquery = FluxQuery()\\\n .range(start=start, stop=stop)\\\n .filter(field=\"VehicleVelocity\")\\\n .inject_raw(aggregate_flux_statement)\n\n# We can inspect the Flux query\nprint(query.compile_query())\n\n# Make the query, getting the data as a DataFrame\nquery_dataframe: pd.DataFrame = client.query_dataframe(query)\n\n# Now, convert the data into a TimeSeries\nmeasurement_period: float = 1.0 / 5 # VehicleVelocity is a 5Hz measurement, so period is 1.0 / 5Hz.\nvehicle_velocity = TimeSeries.from_query_dataframe(query_dataframe, measurement_period, \n field=\"VehicleVelocity\", \n units=\"m/s\")\n\n# Plot the data\nvehicle_velocity.plot()\n```\n\n## Appendix\n\n[^1]: use `git --version` to verify version\n\n[^2]: use `python3 --version` to verify version\n\n[^3]: use `poetry --version` to verify version\n\n<!-- marker-index-end -->\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "UBC Solar's data analysis and querying tools",
"version": "1.3.1",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "28f66771833723a0c6cc4dbff1499ecacc71384c25ccbc8af0c400ffcb13e7aa",
"md5": "8469d38b7c5d68a9ff1c9519582ba3e7",
"sha256": "0670f0b2f22c62db57f001b6eea6486e2ed0deacb43ee15880ed330a3d56f157"
},
"downloads": -1,
"filename": "ubc_solar_data_tools-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "8469d38b7c5d68a9ff1c9519582ba3e7",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 19254,
"upload_time": "2024-10-19T20:13:53",
"upload_time_iso_8601": "2024-10-19T20:13:53.314914Z",
"url": "https://files.pythonhosted.org/packages/28/f6/6771833723a0c6cc4dbff1499ecacc71384c25ccbc8af0c400ffcb13e7aa/ubc_solar_data_tools-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-19 20:13:53",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "ubc-solar-data-tools"
}
