Perturbation

storm vortex tracks (ATCF)

This module provides functionality to

extract an ATCF best track dataset (fort.22)
randomly perturb different parameters (intensity, size, track coordinates) to generate an ensemble of tracks
write out each ensemble member to the ATCF tropical cyclone vortex file (fort.22)

authors:

William Pringle, Argonne National Laboratory, Mar-May 2021
Zach Burnett, NOS/NOAA
Saeed Moghimi, NOS/NOAA

perturbed variables

class ensembleperturbation.perturbation.atcf.MaximumSustainedWindSpeed

Bases: ensembleperturbation.perturbation.atcf.VortexPerturbedVariable

max_sustained_wind_speed (Vmax) represents the maximum wind speed sustained by the storm. It is perturbed along a random gaussian distribution (0 - 1), scaled to the mean of absolute historical errors. central_pressure (pc) is then changed proportionally based on the Holland B parameter.

class ensembleperturbation.perturbation.atcf.RadiusOfMaximumWinds

Bases: ensembleperturbation.perturbation.atcf.VortexPerturbedVariable

radius_of_maximum_winds (Rmax) It is perturbed along a uniform distribution on [-1,1] between the 15th and 85th percentile CDFs of NHC historical forecast errors.

storm_errors(data_frame: pandas.core.frame.DataFrame) → pandas.core.frame.DataFrame

Historical forecast errors of the given storm, based on initial size.

Parameters: data_frame – storm data frame
Returns: errors based on size classification

class ensembleperturbation.perturbation.atcf.CrossTrack

Bases: ensembleperturbation.perturbation.atcf.VortexPerturbedVariable

cross_track represents a perpendicular offset of the tropical cyclone center track, accomplished by moving each forecast time left or right perpedicular to the track line. It is perturbed along a random gaussian distribution (0 - 1), scaled to the mean of absolute historical errors.

perturb(vortex_dataframe: pandas.core.frame.DataFrame, values: List[float], times: List[datetime.datetime], inplace: bool = False) → pandas.core.frame.DataFrame

offsets points by a given perpendicular error/distance from the original track

Parameters

vortex_dataframe – ATCF dataframe containing track info
values – cross-track errors [nm] for each forecast time (VT)
times – forecast times (VT)
inplace – modify dataframe in-place

Returns

updated ATCF dataframe with different longitude latitude locations based on perpendicular offsets set by the cross_track_errors

class ensembleperturbation.perturbation.atcf.AlongTrack

Bases: ensembleperturbation.perturbation.atcf.VortexPerturbedVariable

along_track represents a parallel offset of the tropical cyclone center track, accomplished by moving each forecast time forward or backward along the track line. It is perturbed along a random gaussian distribution (0 - 1), scaled to the mean of absolute historical errors.

perturb(vortex_dataframe: pandas.core.frame.DataFrame, values: List[float], times: List[datetime.datetime], inplace: bool = False) → pandas.core.frame.DataFrame

offsets points by a given error/distance by interpolating along the track

Parameters

vortex_dataframe – ATCF dataframe containing track info
values – along-track errors for each forecast time (VT)
times – forecast timed (VT)
inplace – modify dataframe in-place

Returns

updated ATCF dataframe with different longitude latitude locations based on interpolated errors along track

non-perturbed variables

class ensembleperturbation.perturbation.atcf.CentralPressure(default: Optional[float] = None, unit: Optional[pint.unit.Unit] = None): Bases: ensembleperturbation.perturbation.atcf.VortexVariable

class ensembleperturbation.perturbation.atcf.BackgroundPressure: Bases: ensembleperturbation.perturbation.atcf.VortexVariable

perturber class

class ensembleperturbation.perturbation.atcf.VortexPerturber(storm: str, start_date: Optional[datetime.datetime] = None, end_date: Optional[datetime.datetime] = None, file_deck: Optional[stormevents.nhc.atcf.ATCF_FileDeck] = None, mode: Optional[stormevents.nhc.atcf.ATCF_Mode] = None, record_type: Optional[str] = None)

Bases: object

VortexPerturber takes an ATCF track from an input storm and perturbs it based on several variables (of the class VortexPerturbedVariable)

# retrieve initial storm track for Florence 2018 (defaults to archival best track)
perturber = VortexPerturber(storm='florence2018')

# write 3 tracks perturbed using specified perturbation values (perturbations are of sigma values (``0`` - ``1`` for uniform or ``-1`` - ``1`` for gaussian) that are then scaled to historical errors per-variable
perturber.write(
    perturbations=[
        -1.0,
        {
            MaximumSustainedWindSpeed: -0.25,
            CrossTrack: 0.25,
            'along_track': 0.75,
            'radius_of_maximum_winds': -1,
        },
        0.75,
    ],
    variables=[MaximumSustainedWindSpeed, RadiusOfMaximumWinds, CrossTrack, AlongTrack],
    directory='./3_tracks_perturbed_specifically',
)

# write 5 randomly-perturbed tracks, drawing randomly from the distribution of each variable except for ``CrossTrack``
perturber.write(
    perturbations=5,
    variables=[MaximumSustainedWindSpeed, RadiusOfMaximumWinds, AlongTrack],
    directory='./5_tracks_perturbed_randomly_except_crosstrack',
)

# write tracks perturbed along the quadrature (`4^n` where `n` is the number of variables)
perturber.write(
    perturbations=None,
    quadrature=True,
    variables=[MaximumSustainedWindSpeed, RadiusOfMaximumWinds, CrossTrack, AlongTrack],
    directory='./256_tracks_perturbed_along_quadrature',
)

Parameters

storm – NHC storm code, for instance al062018
start_date – start time of ensemble
end_date – end time of ensemble
file_deck – letter of file deck, one of a, b
mode – either realtime / aid_public or historical / archive
record_type – record type (i.e. BEST, OFCL)

write(perturbations: Optional[Union[int, List[float], List[Dict[str, float]]]], variables: List[ensembleperturbation.perturbation.atcf.VortexVariable], directory: Optional[os.PathLike] = None, sample_from_distribution: bool = False, sample_rule: str = 'random', quadrature: bool = False, weights: Optional[List[float]] = None, overwrite: bool = False, continue_numbering: bool = False, parallel: bool = True) → List[pathlib.Path]

Parameters

perturbations – either the number of perturbations to create, or a list of floats meant to represent points on either the standard Gaussian distribution or a bounded uniform distribution
variables – list of variable names, any combination of [“max_sustained_wind_speed”, “radius_of_maximum_winds”, “along_track”, “cross_track”]
directory – directory to which to write
sample_from_distribution – override given perturbations with random samples from the joint distribution
sample_rule – rule to use for the distribution sampling. Please choose from: random [default], sobol, halton, hammersley, korobov, additive_recursion, or latin_hypercube
quadrature – add perturbations along quadrature
weights – weights to use with perturbations
overwrite – overwrite existing files
continue_numbering – continue the existing numbering scheme if files already exist in the output directory
parallel – generate perturbations concurrently

Returns

written filenames

property validation_times: List[datetime.timedelta]: get the validation time of storm

property holland_B: float: Compute Holland B at each time snap

compute_pc_from_Vmax(dataframe: pandas.core.frame.DataFrame) → float: Compute central pressure from Vmax based on Holland B

classmethod from_file(filename: os.PathLike, start_date: Optional[datetime.datetime] = None, end_date: Optional[datetime.datetime] = None)

build storm perturber from an existing fort.22 or ATCF file

Parameters

filename – file path to fort.22 / ATCF file
start_date – start time of ensemble
end_date – end time of ensemble