The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

 / 
Weather-NHC-TropicalCyclone-0.34
River stage zero No dependents
/ Weather::NHC::TropicalCyclone::StormTable

NAME

Weather::NHC::TropicalCyclone::StormTable - convenient access to the list of historical storms https://ftp.nhc.noaa.gov/atcf/archive/storm.table, which is in ATCF format. Although it looks like and can be treated in many cases as CSV, field width is importan when considering this type of data operationally.

DESCRIPTION

The NHC maintains a table of all past storms going back to 1851. Information is added at the end of each year. So during an active season, the historical information for the current season will not be known this module. However, one may use the get_latest_table to retrieve the latest state of the storm.table if the data seems to be out of date.

SYNOPSIS


            

              
              
my $obj = Weather::NHC::TropicalCyclone::StormTable->new;
foreach my $year ( @{ $obj->years } ) {
    print qq{$year\n};
}
foreach my $basin ( @{ $obj->basins } ) {
    print qq{$basin\n};
}}
foreach my $name ( @{ $obj->names } ) {
    print qq{$name\n};
}
foreach my $kind ( @{ $obj->storm_kinds } ) {
    print qq{$kind\n};
}
foreach my $nhc_designation ( @{ $obj->nhc_designations } ) {
    print qq{$nhc_designation\n};
}
print $obj->get_history_archive_url(2012, q{al}, q{01}), qq{\n};
print $obj->get_best_track_archive_url(2012, q{al}, q{01}), qq{\n};
print $obj->get_fixes_archive_url(2012, q{al}, q{01}), qq{\n};
print $obj->get_archive_url(2012, q{al}, q{01}), qq{\n};

METHODS

new

Constructor.

years

Returns a list of all years in the history file.

by_year

Accessor for all storm records for the provided year, all basins.

names

Returns a list of all storm names in the history file.

by_name

Accessor for all storm records for the provided name, all basins.

basins

Returns a list of all basis in the history file.

by_basin

Accessor for all storm records for the provided basin.

get_by_year_basin

Accessor for all storm records for the provided basin and year.

nhc_designations

Returns a list of all full NHC storm designations, e.g. al222020.

by_nhc_designation

Returns the storm record for the provided year, basin, and storm number.

storm_kinds

Returns a list of all kinds of storms in the history file, e.g. HU, TD, etc.

by_storm_kind

Accessor for all storms of the povided kind.

get_storm_numbers

Given the year and basin, returns the storm numbers for that year.

get_history_archive_url

For the given year, basin, and storm number; returns the full URL including file name for the archived history file; e.g., aal112019.dat.gz.

get_best_track_archive_url

For the given year, basin, and storm number; returns the full URL including file name for the archived best track file; e.g., bal112019.dat.gz.

get_fixes_archive_url

For the given year, basin, and storm number; returns the full URL including file name for the archived fixes file; e.g., fal112019.dat.gz.

get_archive_url

For the given year, returns the URL for the directory containing all archived files and subdirectories.

storm_table

Returns the entire text of the NHC storm.history file being used by this module.

get_latest_table

Updates the data used for the query methods with the latest version of the table being hosted by the NHC at https://ftp.nhc.noaa.gov/atcf/archive/storm.table, underneath utilizes HTTP::Tiny.

Internal Methods

_ingest_storm_table

Takes storm.table in raw text and shoves it into the reference fields that support the other methods. Used by new and get_latest_table.

_return_arrayref

Helper method for converting interal data representation into array references.

_get_storm_designation

Helper method to format provided year, basin, and storm number into the designation format.

_data

Internal method that encapsulates the raw storm.history file.

_parse_line

Parses a storm record and returns an array ref.

ADDITIONAL INFORMATION

ATCF Storm Archive Information

ATCF Database Description Homepage https://www.nrlmry.navy.mil/atcf_web/docs/database/new/database.html#datasources
storm.table format description

https://www.nrlmry.navy.mil/atcf_web/docs/database/new/abdeck.txt

storm.table ATCF Data Format Description

Presented here from https://www.nrlmry.navy.mil/atcf_web/docs/database/new/abdeck.txt for convenience.


            

              
              
ATCF best track, aids, bogus format 8/31/2016
See the notes on missing and deprecated data at the end of this document.
Common section, fields 1-36, followed by user-data section which is not predefined.
BASIN, CY, YYYYMMDDHH, TECHNUM/MIN, TECH, TAU, LatN/S, LonE/W, VMAX, MSLP, TY, RAD, WINDCODE, RAD1, RAD2, RAD3, RAD4, POUTER, ROUTER, RMW, GUSTS, EYE, SUBREGION, MAXSEAS, INITIALS, DIR, SPEED, STORMNAME, DEPTH, SEAS, SEASCODE, SEAS1, SEAS2, SEAS3, SEAS4, USERDEFINED, userdata
COMMON FIELDS
BASIN      - basin, e.g. WP, IO, SH, CP, EP, AL, LS
CY         - annual cyclone number: 1 - 99
YYYYMMDDHH - Warning Date-Time-Group, yyyymmddhh: 0000010100 through 9999123123.
TECHNUM/MIN- objective technique sorting number, minutes for best track: 00 - 99
TECH       - acronym for each objective technique or CARQ or WRNG,
             BEST for best track, up to 4 chars.
TAU        - forecast period: -24 through 240 hours, 0 for best-track, 
             negative taus used for CARQ and WRNG records.
LatN/S     - Latitude for the DTG: 0 - 900 tenths of degrees,
             N/S is the hemispheric index.
LonE/W     - Longitude for the DTG: 0 - 1800 tenths of degrees,
             E/W is the hemispheric index.
VMAX       - Maximum sustained wind speed in knots: 0 - 300 kts.
MSLP       - Minimum sea level pressure, 850 - 1050 mb.
TY         - Highest level of tc development:
             DB - disturbance, 
             TD - tropical depression, 
             TS - tropical storm, 
             TY - typhoon, 
             ST - super typhoon, 
             TC - tropical cyclone, 
             HU - hurricane, 
             SD - subtropical depression,
             SS - subtropical storm,
             EX - extratropical systems,
             PT - post tropical,
             IN - inland,
             DS - dissipating,
             LO - low,
             WV - tropical wave,
             ET - extrapolated,
             MD - monsoon depression,
             XX - unknown.
RAD        - Wind intensity for the radii defined in this record: 34, 50 or 64 kt.
WINDCODE   - Radius code:
             AAA - full circle
             NEQ, SEQ, SWQ, NWQ - quadrant 
RAD1       - If full circle, radius of specified wind intensity, or radius of
             first quadrant wind intensity as specified by WINDCODE.  0 - 999 n mi
RAD2       - If full circle this field not used, or radius of 2nd quadrant wind
             intensity as specified by WINDCODE.  0 - 999 n mi.
RAD3       - If full circle this field not used, or radius of 3rd quadrant wind
             intensity as specified by WINDCODE.  0 - 999 n mi.
RAD4       - If full circle this field not used, or radius of 4th quadrant wind
             intensity as specified by WINDCODE.  0 - 999 n mi.
POUTER     - pressure in millibars of the last closed isobar, 900 - 1050 mb.
ROUTER     - radius of the last closed isobar, 0 - 999 n mi.
RMW        - radius of max winds, 0 - 999 n mi.
GUSTS      - gusts, 0 - 999 kt.
EYE        - eye diameter, 0 - 120 n mi.
SUBREGION  - subregion code: W,A,B,S,P,C,E,L,Q.
             A - Arabian Sea
             B - Bay of Bengal
             C - Central Pacific
             E - Eastern Pacific
             L - Atlantic
             P - South Pacific (135E - 120W)
             Q - South Atlantic
             S - South IO (20E - 135E)
             W - Western Pacific
MAXSEAS    - max seas: 0 - 999 ft.
INITIALS   - Forecaster's initials used for tau 0 WRNG or OFCL, up to 3 chars.
DIR        - storm direction, 0 - 359 degrees.
SPEED      - storm speed, 0 - 999 kts.
STORMNAME  - literal storm name, number, NONAME or INVEST, or TCcyx where:
             cy = Annual cyclone number 01 - 99
             x  = Subregion code: W,A,B,S,P,C,E,L,Q.
DEPTH      - system depth, 
             D - deep, 
             M - medium, 
             S - shallow, 
             X - unknown
SEAS       - Wave height for radii defined in SEAS1 - SEAS4, 0 - 99 ft.
SEASCODE   - Radius code:
             AAA - full circle
             NEQ, SEQ, SWQ, NWQ - quadrant 
SEAS1      - first quadrant seas radius as defined by SEASCODE,  0 - 999 n mi.
SEAS2      - second quadrant seas radius as defined by SEASCODE, 0 - 999 n mi.
SEAS3      - third quadrant seas radius as defined by SEASCODE,  0 - 999 n mi.
SEAS4      - fourth quadrant seas radius as defined by SEASCODE, 0 - 999 n mi.
USERDEFINE1- 1 to 20 character description of user data to follow.
userdata1  - user data section as indicated by USERDEFINED parameter (up to 100 char).
USERDEFINE2- 1 to 20 character description of user data to follow.
userdata2  - user data section as indicated by USERDEFINED parameter (up to 100 char).
USERDEFINE3- 1 to 20 character description of user data to follow.
userdata3  - user data section as indicated by USERDEFINED parameter (up to 100 char).
USERDEFINE4- 1 to 20 character description of user data to follow.
userdata4  - user data section as indicated by USERDEFINED parameter (up to 100 char).
USERDEFINE5- 1 to 20 character description of user data to follow.
userdata5  - user data section as indicated by USERDEFINED parameter (up to 100 char).
------------------------------------------------------------------------------
userdata   - user data section as indicated by USERDEFINED parameter.
Examples of USERDEFINED/userdata pairs:
- An invest spawned from a genesis area:
    SPAWNINVEST, wp712015 to wp902015
- An invest area transitioning to a TC:
    TRANSITIONED, shE92015 to sh152015
- A TC dissipated to an invest area:
    DISSIPATED, sh162015 sh982015 
- A genesis area number:
    genesis-num, 001
------------------------------------------------------------------------------
Notes:
1) No missing data allowed for first eight common fields.  Missing data for other fields are expected to be blank characters between the comma delimiters.  Although the files are not column dependent please insure that the proper number of blank characters is included in missing data so the columns line up.  This makes the files easier to read and troubleshoot.
2) The USERDEFINED section is for inclusion of items not already in the common fields.  The USERDEFINED parameter is 1 to 20 characters, so there should be sufficient space to include some text describing what comes next.
3) Wind records merged in from preexisting wind files (r-decks) were assigned a TECH of CNTR.  Wind records created during normal use of this combined data format are assigned the TECH corresponding to the center name as defined in $ATCFINC/atcfsite.nam.
4) WINDCODE and SEASCODE other than AAA, NEQ, SEQ, SWQ and NWQ exist in older data but have been deprecated.
5) RAD values of 100 exist in old data (earlier than 2005) but have been deprecated.  Currently only 34, 50 and 64 are valid for RAD.
6) The fields are not column dependent, but the files are easier to read and troubleshoot if the columns line up.  The fields are comma and space delimited.  
The desired field widths and preferred ATCF application ranges are as follows:
        field    number of chars        range
        -----    ---------------        -----
        BASIN        2                  WP, EP, CP, IO, SH, AL, SL as defined in basin.dat
        CY           2                  01 to 99, 01 to 49 are real storms, 80 to 89 are test storms, 90 to 99 are INVESTS
        YYYYMMDDHH  10                  only valid DTGs
        TECHNUM/MIN  2                  00 <= TECHNUM <= 99,  00 <= MIN < 60
        TECH         4                  up to four alphanumeric characters
        TAU          3                  -24 <= TAU <= 240 hours
        LatN/S       4                  0 <= Lat <= 900  N/S, in tenths of degrees
        LonE/W       5                  0 <= Lon <=1800  E/W, in tenths of degrees
        VMAX         3                  10 <= VMAX <= 250 kt
        MSLP         4                  850 to 1050 mb
        TY           2                  as defined in tcdevel.dat
        RAD          3                  34, 50, 64 kt
        WINDCODE     3                  AAA, NEW, SEQ, SWQ, NWQ
        RAD1         4                  MRD < RAD1 <= 999 n mi, 
                                        64 kt RAD1 < 50 kt RAD1 < 34 kt RAD1
                                        0 for no radius in quadrant, blank for unknown
        RAD2         4                  See RAD1
        RAD3         4                  See RAD1
        RAD4         4                  See RAD1
        POUTER       4                  MSLP < RADP < 1050 mb
        ROUTER       4                  EYE <  RRP  <= 999 n mi
        RMW          3                  0   <  MRD  <= RAD1, RAD2, RAD3, and RAD4
        GUSTS        3                  VMAX < GUSTS < 300 kt
        EYE          3                  RRP < EYE < 120 n mi
        SUBREGION    3                  W,E,C,A,B,S,P,L,Q   - basin.dat
        MAXSEAS      3                  0 < MAXSEAS < 200 ft
        INITIALS     3
        DIR          3                  0 <= DIR < 360
        SPEED        3                  0 <= SPEED < 100 kt
        STORMNAME   10  
        DEPTH        1                  D, M, S, X
        SEAS         2                  0 < SEAS < 100 ft
        SEASCODE     3                  AAA, NEW, SEQ, SWQ, NWQ
        SEAS1        4                  0 < SEAS1 <= 999 n mi
        SEAS2        4                  See SEAS1
        SEAS3        4                  See SEAS1
        SEAS4        4                  See SEAS1
        USERDEFINED up to 20            1 to 20 characters of alphanumeric data 
        userdata    up to 200