Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

minor updates #17

Merged
9 commits merged into from
Feb 15, 2022
Merged

minor updates #17

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
d646448
catch time interval errors
zacharyburnett Feb 15, 2022
c376121
change to multilinestring
zacharyburnett Feb 15, 2022
2a767e0
minor fixes
zacharyburnett Feb 15, 2022
adf2200
revamp README docs
zacharyburnett Feb 15, 2022
d7ce57f
suppress `SettingWithCopyWarning`
zacharyburnett Feb 15, 2022
4943992
default to best track for simplicity
zacharyburnett Feb 15, 2022
f797052
sort linestrings by datetime
zacharyburnett Feb 15, 2022
f54e4ab
update tests
zacharyburnett Feb 15, 2022
c3906a5
update tests
zacharyburnett Feb 15, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
280 changes: 79 additions & 201 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,215 +17,132 @@ Full documentation can be found at https://stormevents.readthedocs.io

## Usage

### storm interface
### `StormEvent`

You can instantiate a new `StormEvent` object from its identifiers:
#### instantiate from NHC storm name and year

```python
from stormevents import StormEvent

# from NHC storm name and year
StormEvent('florence', 2018)

# from NHC storm code
StormEvent.from_nhc_code('EP172016')

# from USGS flood event ID
StormEvent.from_usgs_id(310)
```

```
StormEvent('FLORENCE', 2018)
StormEvent('PAINE', 2016)
StormEvent('HENRI', 2021)
```

#### storm time interval

To constrain the time interval, do the following:
#### instantiate from NHC storm code

```python
from stormevents import StormEvent
from datetime import datetime, timedelta

# constrain to an absolute datetime range
paine2016 = StormEvent('paine', 2016, start_date='2016-09-18', end_date=datetime(2016, 9, 19, 12))

# constrain to relative times (compared to storm start and end times provided by the NHC)
florence2018 = StormEvent('florence', 2018, start_date=timedelta(days=2)) # <- start 2 days after NHC start time
henri2021 = StormEvent(
'henri',
2021,
start_date=timedelta(days=-3), # start 3 days before NHC end time
end_date=timedelta(days=-2), # <- end 2 days before NHC end time
)
ida2021 = StormEvent('ida', 2021, end_date=timedelta(days=2)) # <- end 2 days after NHC start time
StormEvent.from_nhc_code('EP172016')
```

```
StormEvent('PAINE', 2016, end_date='2016-09-19 12:00:00')
StormEvent('FLORENCE', 2018, start_date='2018-09-01 06:00:00')
StormEvent('HENRI', 2021)
StormEvent('IDA', 2021)
StormEvent('PAINE', 2016)
```

#### storm data

You can then retrieve data for this storm:
#### instantiate from USGS flood event ID

```python
from stormevents import StormEvent

florence2018 = StormEvent('florence', 2018)

# track dataset from the NHC
florence2018.track()
florence2018.track(file_deck='b')

# high-water mark data from the USGS
florence2018.high_water_marks

# water level products from NOAA CO-OPS tidal buoys
florence2018.tidal_data_within_isotach(
wind_speed=34,
start_date='20180913230000',
end_date='20180914',
)
StormEvent.from_usgs_id(310)
```

```
VortexTrack('AL062018', Timestamp('2018-08-29 06:00:00'), Timestamp('2018-09-22 18:00:00'), ATCF_FileDeck.a, ATCF_Mode.historical, None, None)
StormEvent('HENRI', 2021)
```

```
VortexTrack('AL062018', Timestamp('2018-08-29 06:00:00'), Timestamp('2018-09-22 18:00:00'), ATCF_FileDeck.b, ATCF_Mode.historical, None, None)
```
#### constrain time interval to an absolute range

```
latitude ... siteZone
hwm_id ...
33496 37.298440 ... NaN
33502 35.342089 ... NaN
33503 35.378963 ... NaN
33505 35.216282 ... NaN
33508 35.199859 ... NaN
... ... ... ...
34191 33.724722 ... NaN
34235 34.936308 ...
34840 34.145930 ... NaN
34871 35.424707 ... NaN
34876 35.301135 ... NaN
```python
from stormevents import StormEvent
from datetime import datetime

[509 rows x 51 columns]
StormEvent('paine', 2016, start_date='2016-09-18', end_date=datetime(2016, 9, 19, 12))
```

```
Dimensions: (t: 11, nos_id: 10)
Coordinates:
* t (t) datetime64[ns] 2018-09-13T23:00:00 ... 2018-09-14
* nos_id (nos_id) int64 8639348 8651370 8652587 ... 8661070 8662245 8665530
nws_id (nos_id) <U5 'MNPV2' 'DUKN7' 'ORIN7' ... 'MROS1' 'NITS1' 'CHTS1'
x (nos_id) float64 -76.31 -75.75 -75.56 ... -78.94 -79.19 -79.94
y (nos_id) float64 36.78 36.19 35.78 35.22 ... 33.66 33.34 32.78
Data variables:
v (nos_id, t) float32 7.271 7.274 7.27 7.27 ... 1.549 1.587 1.624
s (nos_id, t) float32 0.005 0.004 0.005 0.004 ... 0.005 0.007 0.006
f (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '0,0,0,0' '0,0,0,0'
q (nos_id, t) object 'v' 'v' 'v' 'v' 'v' 'v' ... 'v' 'v' 'v' 'v' 'v'
StormEvent('PAINE', 2016, end_date='2016-09-19 12:00:00')
```

By default, these functions operate within the time interval defined by the NHC.

### storm data from the National Hurricane Center (NHC)

#### list storm events defined by the NHC
#### constrain time interval to relative times (compared to storm start and end times provided by the NHC)

```python
from stormevents.nhc import nhc_storms
from stormevents import StormEvent
from datetime import timedelta

nhc_storms = nhc_storms()
StormEvent('florence', 2018, start_date=timedelta(days=2)) # <- start 2 days after NHC start time
```

```
name class ... start_date end_date
nhc_code ...
AL021851 UNNAMED HU ... 1851-07-05 12:00:00 1851-07-05 12:00:00
AL031851 UNNAMED TS ... 1851-07-10 12:00:00 1851-07-10 12:00:00
AL041851 UNNAMED HU ... 1851-08-16 00:00:00 1851-08-27 18:00:00
AL051851 UNNAMED TS ... 1851-09-13 00:00:00 1851-09-16 18:00:00
AL061851 UNNAMED TS ... 1851-10-16 00:00:00 1851-10-19 18:00:00
... ... ... ... ... ...
EP922021 INVEST DB ... 2021-06-05 06:00:00 NaT
AL952021 INVEST DB ... 2021-10-28 12:00:00 NaT
AL962021 INVEST EX ... 2021-11-07 12:00:00 NaT
EP712022 GENESIS001 DB ... 2022-01-20 12:00:00 NaT
EP902022 INVEST LO ... 2022-01-20 12:00:00 NaT
StormEvent('FLORENCE', 2018, start_date='2018-09-01 06:00:00')
```

```python
from stormevents import StormEvent
from datetime import timedelta

[2729 rows x 8 columns]
StormEvent(
'henri',
2021,
start_date=timedelta(days=-3), # <- start 3 days before NHC end time
end_date=timedelta(days=-2), # <- end 2 days before NHC end time
)
```

#### retrieve storm tracks provided by the NHC
```
StormEvent('HENRI', 2021, start_date='2021-08-24 18:00:00', end_date='2021-08-25 18:00:00')
```

```python
from stormevents.nhc import VortexTrack
from stormevents.nhc.atcf import ATCF_FileDeck
from stormevents import StormEvent
from datetime import timedelta

# retrieve vortex data from the Internet from its ID
vortex = VortexTrack('AL112017')
StormEvent('ida', 2021, end_date=timedelta(days=2)) # <- end 2 days after NHC start time
```

# you can specify the file deck with `file_deck`
vortex = VortexTrack('AL112017', file_deck=ATCF_FileDeck.b)
```
StormEvent('IDA', 2021, end_date='2021-08-29 18:00:00')
```

# you can also use the storm name and year in the lookup
vortex = VortexTrack('irma2017')

# write to a file in the ADCIRC `fort.22` format
vortex.write('fort.22')
#### retrieve storm track data from the National Hurricane Center (NHC)

# read vortex data from an existing ATCF track file (`*.trk`)
vortex = VortexTrack.from_atcf_file('atcf.trk')
```python
from stormevents import StormEvent

# read vortex data from an existing file in the ADCIRC `fort.22` format
vortex = VortexTrack.from_fort22('fort.22')
```
florence2018 = StormEvent('florence', 2018)

### high water mark (HWM) surveys from the United States Geological Survey (USGS)
florence2018.track()
```

#### list storm flood events that have HWM surveys
```
VortexTrack('AL062018', Timestamp('2018-08-30 06:00:00'), Timestamp('2018-09-18 12:00:00'), <ATCF_FileDeck.a: 'a'>, <ATCF_Mode.historical: 'ARCHIVE'>, None, None)
```

```python
from stormevents.usgs import usgs_highwatermark_storms
from stormevents import StormEvent

hwm_storms = usgs_highwatermark_storms()
```
florence2018 = StormEvent('florence', 2018)

florence2018.track(file_deck='b')
```
year usgs_name nhc_name nhc_code
usgs_id
7 2013 FEMA 2013 exercise None None
8 2013 Wilma None None
18 2012 Isaac Aug 2012 ISAAC AL092012
19 2005 Rita RITA AL182005
23 2011 Irene IRENE AL092011
... ... ... ... ...
303 2020 2020 TS Marco - Hurricane Laura MARCO AL142020
304 2020 2020 Hurricane Sally SALLY AL192020
305 2020 2020 Hurricane Delta DELTA AL262020
310 2021 2021 Tropical Cyclone Henri HENRI AL082021
312 2021 2021 Tropical Cyclone Ida IDA AL092021

[24 rows x 4 columns]
```
VortexTrack('AL062018', Timestamp('2018-08-30 06:00:00'), Timestamp('2018-09-18 12:00:00'), <ATCF_FileDeck.b: 'b'>, <ATCF_Mode.historical: 'ARCHIVE'>, 'BEST', None)
```

#### retrieve HWM data for a specific storm
#### retrieve high-water mark surveys conducted provided by the United States Geological Survey (USGS)

```python
from stormevents.usgs import StormHighWaterMarks
from stormevents import StormEvent

hwm_florence2018 = StormHighWaterMarks('florence', 2018)
florence2018 = StormEvent('florence', 2018)

hwm_florence2018.data
hwm_florence2018.data.columns
florence2018.high_water_marks
```

```
Expand All @@ -236,7 +153,7 @@ hwm_id ...
33503 35.378963 ... NaN
33505 35.216282 ... NaN
33508 35.199859 ... NaN
... ... ... ...
... ... ... ...
34191 33.724722 ... NaN
34235 34.936308 ...
34840 34.145930 ... NaN
Expand All @@ -246,73 +163,34 @@ hwm_id ...
[509 rows x 51 columns]
```

```
Index(['latitude', 'longitude', 'eventName', 'hwmTypeName', 'hwmQualityName',
'verticalDatumName', 'verticalMethodName', 'approvalMember',
'markerName', 'horizontalMethodName', 'horizontalDatumName',
'flagMemberName', 'surveyMemberName', 'site_no', 'siteDescription',
'sitePriorityName', 'networkNames', 'stateName', 'countyName',
'sitePermHousing', 'site_latitude', 'site_longitude', 'waterbody',
'site_id', 'event_id', 'hwm_type_id', 'hwm_quality_id',
'hwm_locationdescription', 'latitude_dd', 'longitude_dd', 'survey_date',
'elev_ft', 'vdatum_id', 'vcollect_method_id', 'bank', 'marker_id',
'hcollect_method_id', 'hwm_environment', 'flag_date', 'stillwater',
'hdatum_id', 'flag_member_id', 'survey_member_id', 'uncertainty',
'hwm_uncertainty', 'hwm_label', 'files', 'approval_id',
'height_above_gnd', 'hwm_notes', 'siteZone'],
dtype='object')
```

### tidal station data from the Center for Operational Oceanographic Products and Services (CO-OPS)

#### list CO-OPS tidal stations
##### retrieve water level products from tidal buoys maintained by the National Oceanic and Atmospheric Administration (NOAA) Center for Operational Oceanographic Products and Services (CO-OPS)

```python
from stormevents.coops import coops_stations

stations = coops_stations()
```
from stormevents import StormEvent

```
nws_id x y name state removed
nos_id
1600012 46125 122.6250 37.750000 QREB buoy NaT
1611400 NWWH1 -159.3750 21.953125 Nawiliwili HI NaT
1612340 OOUH1 -157.8750 21.312500 Honolulu HI NaT
1612480 MOKH1 -157.7500 21.437500 Mokuoloe HI NaT
1615680 KLIH1 -156.5000 20.890625 Kahului, Kahului Harbor HI NaT
... ... ... ... ... ...
9759394 MGZP4 -67.1875 18.218750 Mayaguez PR NaT
9759938 MISP4 -67.9375 18.093750 Mona Island NaT
9761115 BARA9 -61.8125 17.593750 Barbuda NaT
9999530 FRCB6 -64.6875 32.375000 Bermuda, Ferry Reach Channel NaT
9999531 -93.3125 29.765625 Calcasieu Test Station LA NaT
florence2018 = StormEvent('florence', 2018)

[363 rows x 6 columns]
florence2018.tidal_data_within_isotach(
wind_speed=34,
start_date='20180913230000',
end_date='20180914',
)
```

#### list CO-OPS tidal stations within a region

```python
from shapely.geometry import Polygon
from stormevents.coops import coops_stations_within_region

polygon = Polygon(...)

stations = coops_stations_within_region(region=polygon)
```

#### retrieve CO-OPS tidal data within a region

```python
from datetime import datetime, timedelta

from shapely.geometry import MultiPolygon
from stormevents.coops import coops_data_within_region

polygon = MultiPolygon(...)

coops_data_within_region(region=polygon, start_date=datetime.now() - timedelta(days=2), end_date=datetime.now())
Dimensions: (nos_id: 10, t: 11)
Coordinates:
* t (t) datetime64[ns] 2018-09-13T23:00:00 ... 2018-09-14
* nos_id (nos_id) int64 8639348 8651370 8652587 ... 8661070 8662245 8665530
nws_id (nos_id) <U5 'MNPV2' 'DUKN7' 'ORIN7' ... 'MROS1' 'NITS1' 'CHTS1'
x (nos_id) float64 -76.31 -75.75 -75.56 ... -78.94 -79.19 -79.94
y (nos_id) float64 36.78 36.19 35.78 35.22 ... 33.66 33.34 32.78
Data variables:
v (nos_id, t) float32 7.271 7.274 7.27 7.27 ... 1.549 1.587 1.624
s (nos_id, t) float32 0.005 0.004 0.005 0.004 ... 0.005 0.007 0.006
f (nos_id, t) object '0,0,0,0' '0,0,0,0' ... '0,0,0,0' '0,0,0,0'
q (nos_id, t) object 'v' 'v' 'v' 'v' 'v' 'v' ... 'v' 'v' 'v' 'v' 'v'
```

## Related Projects
Expand Down
3 changes: 3 additions & 0 deletions stormevents/nhc/atcf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@

ATCF_RECORD_START_YEAR = 1850

# suppress `SettingWithCopyWarning`
pandas.options.mode.chained_assignment = None


def atcf_files(
file_deck: 'ATCF_FileDeck' = None, mode: 'ATCF_Mode' = None, year: int = None
Expand Down
Loading