huracanpy.load#

huracanpy.load(filename=None, source=None, variable_names=None, rename={}, units=None, baselon=None, infer_track_id=None, track_id_prefix=None, ibtracs_subset='wmo', iris_timestep=datetime.timedelta(seconds=10800), tempest_extremes_unstructured=False, tempest_extremes_header_str='start', track_calendar=None, **kwargs)[source]#

Load track data

The optional parameters for different sources of tracks (currently IBTrACS, TRACK and TempestExtremes) are named {source}_{parameter} (in lower case), e.g. “ibtracs_subset”.

Parameters:

  • filename (str or list, optional) – The file or files to be loaded. If source=”ibtracs”, this is not needed as the data is either included in huracanpy or downloaded when called. If the filename is provided for an online IBTrACS subset, then the raw downloaded data will be saved there.

  • source (str, optional) –

    If the file is not a CSV or NetCDF (identified by the file extension) then the source needs to be specified to decide how to load the data

    • track

    • track.tilt

    • te, tempest, tempestextremes, uz (For textual format, not csv)

    • witrack

    • ibtracs

    • csv

    • netcdf, nc (includes support for CHAZ & MIT-Open file provided appropriate variable_names)

    • old_hurdat, ecmwf

    • iris

  • variable_names (list of str, optional) – When loading data from an ASCII file (TRACK or TempestExtremes), specify the list of variables that have been added to the tracks. This does not include variables which are in the track by default (e.g. time/lon/lat/vorticity for TRACK). If a variable at multiple levels has been added to the tracks, then a variable name for each level needs to be included (e.g. vorticity profiles with TRACK). If the variable names are not given, then any additional variables will be named variable_n, where n goes from 0 to the number of variables

  • rename (dict, optional) –

    A mapping of variable names to rename (for netCDF files only). Defaults are

    • longitude -> lon

    • latitude -> lat

    To override any of these defaults, you can pass the same name, e.g.

    >>> tracks = huracanpy.load(..., rename=dict(longitude="longitude"))

  • units (dict, optional) –

    A mapping of variable names to units

    >>> tracks = huracanpy.load(..., units=dict(vorticity="s**-1", slp="hPa"))

  • baselon (scalar, optional) – Force the loaded longitudes into the range (baselon, baselon + 360). e.g. (0, 360) or (-180, 180)

  • infer_track_id (list, optional) – If track_id is not a variable in the file, but the individual tracks can be inferred from the combination of other variables, e.g. the file has year and storm number by year, then pass a list with those variable names, and a new track_id variable will be created

  • track_id_prefix (str, optional) – If loading from a list of tracks. Add this formattable prefix to the start of the track_ids to keep them as unique identifiers. See huracanpy.concat_tracks() for more details

  • ibtracs_subset (str, default="wmo") –

    IBTrACS subset. Two offline versions are available:

    • wmo: Data with the wmo_* variables. The data as reported by the WMO agency responsible for each basin, so methods are not consistent across basins

    • usa or JTWC: Data with the usa_* variables. The data as recorded by the USA/Joint Typhoon Warning Centre. Methods are consistent across basins, but may not be complete.

    To download online data, the subsets are the different files provided by IBTrACS.

    • ACTIVE: TCs currently active

    • ALL: Entire IBTrACS database

    • Specific basins: EP, NA, NI, SA, SI, SP, WP

    • last3years: self-explanatory

    • since1980: Entire IBTrACS database since 1980 (advent of satellite era, considered reliable from then on)

  • iris_timestep (int or datetime.timedelta, default=datetime.timedelta(hours=3)) – The timestep used in the Imperial College Storm Model (IRIS). This is 3-hours in the paper (https://www.nature.com/articles/s41597-024-03250-y/tables/1), so unlikely to need changing, but provided here in case it does.

  • tempest_extremes_unstructured (bool, default=False) – By default the first two columns in TempestExtremes files are the i, j indices of the closest gridpoint, but for unstructured grids it is a single lookup index so there is one less column

  • tempest_extremes_header_str (str, default="start") – This is an option in the Colin’s load function, so I assume this can change between files

  • track_calendar ([str, tuple] optional) –

    When loading data from a TRACK ASCII file, if the data uses a different calendar to the default datetime.datetime, then you can pass this argument to load the times in as cftime.datetime with the given calendar instead

    If the TRACK file has timesteps instead of dates. Then you can pass a tuple with the initial time and timestep e.g. (“1940-01-01”, 6)

  • **kwargs –

    When loading tracks from a standard files these will be passed to the relevant load function

    For CSV files pandas interprets “NA” as nan by default, which is overriden in this function. To restore the pandas default behavious set keep_default_NA=True and na_values=[]

Return type:

xarray.Dataset

On this page

This Page