# Tropycal
Tropycal is a Python package intended to simplify the process of retrieving and analyzing tropical cyclone data, both for past storms and in real time, and is geared towards the research and operational meteorology sectors.
Tropycal can read in HURDAT2 and IBTrACS reanalysis data and operational National Hurricane Center (NHC) Best Track data and conform them to the same format, which can be used to perform climatological, seasonal and individual storm analyses. For each individual storm, operational NHC and model forecasts, aircraft reconnaissance data, rainfall data, and any associated tornado activity can be retrieved and plotted.
The latest version of Tropycal is v1.2.1.
## Installation
### Conda
The currently recommended method of installation is via conda:
```sh
conda install -c conda-forge tropycal
```
### Pip
Installation is also available via pip:
```sh
pip install tropycal
```
### From source
Tropycal can also be installed from source by cloning the GitHub repository:
```sh
git clone https://github.com/tropycal/tropycal
cd tropycal
python setup.py install
```
## Dependencies
- matplotlib >= 2.2.2
- numpy >= 1.14.3
- scipy >= 1.1.0
- pandas >= 1.3.0
- xarray >= 0.10.7
- networkx >= 2.0.0
- requests >= 2.22.0
- pyshp >= 2.1
To fully leverage tropycal's plotting capabilities, it is strongly recommended to have cartopy >= 0.17.0 installed.
## Documentation
For full documentation and examples, please refer to [Tropycal Documentation](https://tropycal.github.io/tropycal/).
As of v0.3, the documentation is up-to-date following a bug that started with v0.2.5 where the documentation was not updated with each release.
## Sample Usage
As an example, read in the North Atlantic HURDAT2 reanalysis dataset, excluding Best Track (current year's storms):
```python
import tropycal.tracks as tracks
basin = tracks.TrackDataset(basin='north_atlantic')
```
### Individual Storm Analysis
Individual storms can be retrieved from the dataset by calling the "get_storm" function, which returns an instance of a Storm object. This can be done by either entering a tuple containing the storm name and year, or by the standard tropical cyclone ID (e.g., AL012019).
Let's retrieve an instance of Hurricane Michael from 2018:
```python
storm = basin.get_storm(('michael',2018))
```
This instance of Storm contains several methods that return the storm data back in different data types. The following examples will show how to retrieve 3 different data types.
Retrieve Michael's data in different data formats:
```python
storm.to_dict()
storm.to_xarray()
storm.to_dataframe()
```
Visualize Michael's observed track with the `plot` function:
Note that you can pass various arguments to the `plot` function, such as customizing the map and track aspects. The only cartopy projection currently offered is PlateCarree. Read through the documentation for more customization options.
```python
storm.plot()
```
If this storm was ever in NHC's area of responsibility, you can retrieve operational forecast data for this event provided it is available. Forecast discussions date back to 1992, and forecast tracks date back to 1950.
Retrieve a single forecast discussion for Michael - both of these methods will yield an identical result:
```python
#Method 1: Specify date closest to desired discussion
disco = storm.get_nhc_discussion(forecast=dt.datetime(2018,10,7,0))
print(disco['text'])
#Method 2: Specify forecast discussion ID
disco = storm.get_nhc_discussion(forecast=2)
print(disco['text'])
```
NHC also archives forecast tracks, albeit in a different format than the official advisory data, so the operational forecast IDs here differ from the discussion IDs. As such, the forecast cone is not directly retrieved from NHC, but is generated using an algorithm that yields a cone closely resembling the official NHC cone.
Let's plot Michael's second forecast cone:
```python
storm.plot_nhc_forecast(forecast=2)
```
Now let's look at the 12th forecast for Michael.
Note that the observed track here differs from the HURDAT2 track plotted previously! This is because this plot displays the operationally analyzed location and intensity, rather than the post-storm analysis data. This is done to account for differences between HURDAT2 and operational data.
```python
storm.plot_nhc_forecast(forecast=12)
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tropycal/tropycal",
"name": "tropycal",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "meteorology,weather",
"author": "Tomer Burg, Sam Lillo",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/71/41/eaa6d709e47469a3303ed84f3c011f0333b9323af8b4ec5aab6c612d6999/tropycal-1.2.1.tar.gz",
"platform": "any",
"description": "# Tropycal\nTropycal is a Python package intended to simplify the process of retrieving and analyzing tropical cyclone data, both for past storms and in real time, and is geared towards the research and operational meteorology sectors.\n\nTropycal can read in HURDAT2 and IBTrACS reanalysis data and operational National Hurricane Center (NHC) Best Track data and conform them to the same format, which can be used to perform climatological, seasonal and individual storm analyses. For each individual storm, operational NHC and model forecasts, aircraft reconnaissance data, rainfall data, and any associated tornado activity can be retrieved and plotted.\n\nThe latest version of Tropycal is v1.2.1.\n\n## Installation\n\n\n### Conda\n\nThe currently recommended method of installation is via conda:\n\n```sh\nconda install -c conda-forge tropycal\n```\n\n### Pip\n\nInstallation is also available via pip:\n\n```sh\npip install tropycal\n```\n\n### From source\n\nTropycal can also be installed from source by cloning the GitHub repository:\n\n```sh\ngit clone https://github.com/tropycal/tropycal\ncd tropycal\npython setup.py install\n```\n\n## Dependencies\n- matplotlib >= 2.2.2\n- numpy >= 1.14.3\n- scipy >= 1.1.0\n- pandas >= 1.3.0\n- xarray >= 0.10.7\n- networkx >= 2.0.0\n- requests >= 2.22.0\n- pyshp >= 2.1\n\nTo fully leverage tropycal's plotting capabilities, it is strongly recommended to have cartopy >= 0.17.0 installed.\n\n## Documentation\nFor full documentation and examples, please refer to [Tropycal Documentation](https://tropycal.github.io/tropycal/).\n\nAs of v0.3, the documentation is up-to-date following a bug that started with v0.2.5 where the documentation was not updated with each release.\n\n## Sample Usage\nAs an example, read in the North Atlantic HURDAT2 reanalysis dataset, excluding Best Track (current year's storms):\n\n```python\nimport tropycal.tracks as tracks\n\nbasin = tracks.TrackDataset(basin='north_atlantic')\n```\n\n### Individual Storm Analysis\n\nIndividual storms can be retrieved from the dataset by calling the \"get_storm\" function, which returns an instance of a Storm object. This can be done by either entering a tuple containing the storm name and year, or by the standard tropical cyclone ID (e.g., AL012019).\n\nLet's retrieve an instance of Hurricane Michael from 2018:\n\n```python\nstorm = basin.get_storm(('michael',2018))\n```\n\nThis instance of Storm contains several methods that return the storm data back in different data types. The following examples will show how to retrieve 3 different data types.\n\nRetrieve Michael's data in different data formats:\n\n```python\nstorm.to_dict()\nstorm.to_xarray()\nstorm.to_dataframe()\n```\n\nVisualize Michael's observed track with the `plot` function:\n\nNote that you can pass various arguments to the `plot` function, such as customizing the map and track aspects. The only cartopy projection currently offered is PlateCarree. Read through the documentation for more customization options.\n\n```python\nstorm.plot()\n```\n\nIf this storm was ever in NHC's area of responsibility, you can retrieve operational forecast data for this event provided it is available. Forecast discussions date back to 1992, and forecast tracks date back to 1950.\n\nRetrieve a single forecast discussion for Michael - both of these methods will yield an identical result:\n\n```python\n#Method 1: Specify date closest to desired discussion\ndisco = storm.get_nhc_discussion(forecast=dt.datetime(2018,10,7,0))\nprint(disco['text'])\n\n#Method 2: Specify forecast discussion ID\ndisco = storm.get_nhc_discussion(forecast=2)\nprint(disco['text'])\n```\n\nNHC also archives forecast tracks, albeit in a different format than the official advisory data, so the operational forecast IDs here differ from the discussion IDs. As such, the forecast cone is not directly retrieved from NHC, but is generated using an algorithm that yields a cone closely resembling the official NHC cone.\n\nLet's plot Michael's second forecast cone:\n\n```python\nstorm.plot_nhc_forecast(forecast=2)\n```\n\nNow let's look at the 12th forecast for Michael.\n\nNote that the observed track here differs from the HURDAT2 track plotted previously! This is because this plot displays the operationally analyzed location and intensity, rather than the post-storm analysis data. This is done to account for differences between HURDAT2 and operational data.\n\n```python\nstorm.plot_nhc_forecast(forecast=12)\n```\n",
"bugtrack_url": null,
"license": "",
"summary": "Package for retrieving and analyzing tropical cyclone data",
"version": "1.2.1",
"project_urls": {
"Documentation": "https://tropycal.github.io/tropycal/",
"Homepage": "https://github.com/tropycal/tropycal",
"Source Code": "https://github.com/tropycal/tropycal"
},
"split_keywords": [
"meteorology",
"weather"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7141eaa6d709e47469a3303ed84f3c011f0333b9323af8b4ec5aab6c612d6999",
"md5": "53558a1ec814b8aee8ff3a8f9cc24e5e",
"sha256": "957450a5218a1f4ed9930d3e076ad4dc51212514742726797e91f2d16444481a"
},
"downloads": -1,
"filename": "tropycal-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "53558a1ec814b8aee8ff3a8f9cc24e5e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 10075803,
"upload_time": "2023-09-07T21:01:59",
"upload_time_iso_8601": "2023-09-07T21:01:59.941353Z",
"url": "https://files.pythonhosted.org/packages/71/41/eaa6d709e47469a3303ed84f3c011f0333b9323af8b4ec5aab6c612d6999/tropycal-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-07 21:01:59",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tropycal",
"github_project": "tropycal",
"travis_ci": true,
"coveralls": false,
"github_actions": false,
"lcname": "tropycal"
}
JSON
