| Name | tcprimedapi JSON |
| Version |
1.0a0
JSON |
| download |
| home_page | None |
| Summary | An API to pull TC PRIMED files based on user requests. |
| upload_time | 2024-10-29 21:02:06 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | BSD 3-Clause License Copyright (c) 2024, TC PRIMED Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
| keywords |
tools
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# TC PRIMED API
The NOAA/CSU [Tropical Cyclone PRecipitation, Infrared, Microwave, and Environmental Dataset (TC PRIMED)](https://rammb-data.cira.colostate.edu/tcprimed/) is a global amelioration of tropical cyclone centric data centered on low-Earth orbiting satellite overpasses.
The TC PRIMED data is stored in an artificial intelligence (AI)-ready format via NetCDF files. These data are hosted on an Amazon Web Services (AWS) S3 Bucket as a public dataset through the NOAA Open Data Dissemination program at https://noaa-nesdis-tcprimed-pds.s3.amazonaws.com/index.html.
This API allows users to access specific storms and sensors without having to shift through each individual storm. If you are interested in pulling the entire dataset, consider using the AWS command line interface instead.
## Install
Install the TC PRIMED API with:
```bash
$ pip install tcprimedapi
```
## Example
There are more examples on using the API available in the examples directory.
This example test will print the S3 bucket object key (i.e., the file name).
```bash
$ python
>>> import tcprimedapi
>>> tcpc = tcprimedapi.Client()
>>> tcpc.query({'atcf_id': ['al092019'],
... 'file_type': ['GMI']})
>>> for key in tcpc.object_keys:
... print(key)
```
## Interfaces
The TC PRIMED API allows users to make data requests with two different behaviors: 1) download files locally and 2) iterate through files in memory.
### Query data request
Users must first query a data request.
To request TC PRIMED data, users create a dictionary containing parameters for their request. The dictionary contains three key, value pairs:
**Storm options:**
You can either specify storm identifiers
- `atcf_id` — the Automated Tropical Cyclone Forecast System (ATCF) 8 character storm identifier
Or, you can specify one or multiple components of a storm identifier as strings
- `season` — Four digit season
- `basin` — Two character basin identifier
- `cyclone_number` — Two digit cyclone number
Leaving one out pulls everything for that option. For example, not specifying a cyclone number gives all storms for the subset of seasons and basins.
**The overpass and environmental files options:**
- `file_type` — the low-Earth orbit satellite sensor or platform abbreviation or the environmental file `env`
**Version options:**
- `version` — optional TC PRIMED version (i.e., `v01r01`)
- `version_type` — optional TC PRIMED version type (i.e., `final`, `preliminary`) with `final` being the default
**Date time group start and end range options:**
- `start_date` — optional inclusive start date (file date time stamp must be greater than or equal to this value)
- `end_date` — optional exclusive end date (file date time stamp must be less than to this value)
As with the example above, `object_keys` can be examined to see if the query matches expectations.
### Download
This option is best for repeatedly accessing a small subset of TC PRIMED files.
```bash
$ python
>>> import tcprimedapi
>>> tcpc = tcprimedapi.Client()
>>> tcpc.query({'atcf_id': ['al092019'],
... 'file_type': ['GMI']})
>>> target_dirname = 'save_here'
>>> tcpc.download(target_dirname=target_dirname)
```
### In Memory
This option is best for one-time access or for saving a subset of data from TC PRIMED files.
```bash
$ python
>>> import tcprimedapi
>>> tcpc = tcprimedapi.Client()
>>> tcpc.query({'atcf_id': ['al092019'],
... 'file_type': ['GMI']})
>>> file_iter = tcpc.inmemory()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "tcprimedapi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "tools",
"author": null,
"author_email": "TC PRIMED Development Team <CIRA_tcprimed@colostate.edu>",
"download_url": "https://files.pythonhosted.org/packages/c8/8d/38b8472deaa2e0518bea8b1021cf3f6a0501f9f713a01004443cce282d20/tcprimedapi-1.0a0.tar.gz",
"platform": null,
"description": "# TC PRIMED API\n\nThe NOAA/CSU [Tropical Cyclone PRecipitation, Infrared, Microwave, and Environmental Dataset (TC PRIMED)](https://rammb-data.cira.colostate.edu/tcprimed/) is a global amelioration of tropical cyclone centric data centered on low-Earth orbiting satellite overpasses.\n\nThe TC PRIMED data is stored in an artificial intelligence (AI)-ready format via NetCDF files. These data are hosted on an Amazon Web Services (AWS) S3 Bucket as a public dataset through the NOAA Open Data Dissemination program at https://noaa-nesdis-tcprimed-pds.s3.amazonaws.com/index.html.\n\nThis API allows users to access specific storms and sensors without having to shift through each individual storm. If you are interested in pulling the entire dataset, consider using the AWS command line interface instead.\n\n## Install\nInstall the TC PRIMED API with:\n```bash\n$ pip install tcprimedapi\n```\n\n## Example\nThere are more examples on using the API available in the examples directory.\n\nThis example test will print the S3 bucket object key (i.e., the file name).\n```bash\n$ python\n>>> import tcprimedapi\n>>> tcpc = tcprimedapi.Client()\n>>> tcpc.query({'atcf_id': ['al092019'],\n... 'file_type': ['GMI']})\n>>> for key in tcpc.object_keys:\n... print(key)\n```\n\n## Interfaces\nThe TC PRIMED API allows users to make data requests with two different behaviors: 1) download files locally and 2) iterate through files in memory.\n\n### Query data request\nUsers must first query a data request.\n\nTo request TC PRIMED data, users create a dictionary containing parameters for their request. The dictionary contains three key, value pairs:\n\n**Storm options:**\n\nYou can either specify storm identifiers\n- `atcf_id` — the Automated Tropical Cyclone Forecast System (ATCF) 8 character storm identifier\n\nOr, you can specify one or multiple components of a storm identifier as strings\n- `season` — Four digit season\n- `basin` — Two character basin identifier\n- `cyclone_number` — Two digit cyclone number\n\nLeaving one out pulls everything for that option. For example, not specifying a cyclone number gives all storms for the subset of seasons and basins.\n\n**The overpass and environmental files options:**\n- `file_type` — the low-Earth orbit satellite sensor or platform abbreviation or the environmental file `env`\n\n**Version options:**\n- `version` — optional TC PRIMED version (i.e., `v01r01`)\n- `version_type` — optional TC PRIMED version type (i.e., `final`, `preliminary`) with `final` being the default\n\n**Date time group start and end range options:**\n- `start_date` — optional inclusive start date (file date time stamp must be greater than or equal to this value)\n- `end_date` — optional exclusive end date (file date time stamp must be less than to this value)\n\nAs with the example above, `object_keys` can be examined to see if the query matches expectations.\n\n### Download\nThis option is best for repeatedly accessing a small subset of TC PRIMED files.\n```bash\n$ python\n>>> import tcprimedapi\n>>> tcpc = tcprimedapi.Client()\n>>> tcpc.query({'atcf_id': ['al092019'],\n... 'file_type': ['GMI']})\n>>> target_dirname = 'save_here'\n>>> tcpc.download(target_dirname=target_dirname)\n```\n\n### In Memory\nThis option is best for one-time access or for saving a subset of data from TC PRIMED files.\n```bash\n$ python\n>>> import tcprimedapi\n>>> tcpc = tcprimedapi.Client()\n>>> tcpc.query({'atcf_id': ['al092019'],\n... 'file_type': ['GMI']})\n>>> file_iter = tcpc.inmemory()\n```\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2024, TC PRIMED Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. ",
"summary": "An API to pull TC PRIMED files based on user requests.",
"version": "1.0a0",
"project_urls": {
"Homepage": "https://rammb-data.cira.colostate.edu/tcprimed/",
"Repository": "https://github.com/CSU-CIRA/tcprimedapi/"
},
"split_keywords": [
"tools"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1539544347b8fadaec8c12353b9f0fb650b9de71f72e01b71da9bb2d50ad5f5c",
"md5": "da13d46814030d0a2f26428341a5d1ff",
"sha256": "bb9413f06a5b27feb9a91c4bc3712b83896127633e077e6bcf7ead9205f30e2b"
},
"downloads": -1,
"filename": "tcprimedapi-1.0a0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "da13d46814030d0a2f26428341a5d1ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 9650,
"upload_time": "2024-10-29T21:02:05",
"upload_time_iso_8601": "2024-10-29T21:02:05.238646Z",
"url": "https://files.pythonhosted.org/packages/15/39/544347b8fadaec8c12353b9f0fb650b9de71f72e01b71da9bb2d50ad5f5c/tcprimedapi-1.0a0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c88d38b8472deaa2e0518bea8b1021cf3f6a0501f9f713a01004443cce282d20",
"md5": "9a9bea1291a4c504a3df9edc55b7da03",
"sha256": "b55a901e02102c832fedb341b6f15688973da8421871fa5f763b7fe69b6f0906"
},
"downloads": -1,
"filename": "tcprimedapi-1.0a0.tar.gz",
"has_sig": false,
"md5_digest": "9a9bea1291a4c504a3df9edc55b7da03",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 12558,
"upload_time": "2024-10-29T21:02:06",
"upload_time_iso_8601": "2024-10-29T21:02:06.405245Z",
"url": "https://files.pythonhosted.org/packages/c8/8d/38b8472deaa2e0518bea8b1021cf3f6a0501f9f713a01004443cce282d20/tcprimedapi-1.0a0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 21:02:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "CSU-CIRA",
"github_project": "tcprimedapi",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "tcprimedapi"
}
