toto.plugins.extreme.do_extreme

class toto.plugins.extreme.do_extreme.Extreme(pandas_obj)

Bases: ExtremeBase

distribution_shape(mag='magnitude', drr='direction', args={'direction binning': {'centered': True, 'not-centered': False}, 'direction interval': 45.0, 'directional': True, 'display CDFs': True, 'display peaks': True, 'fitting distribution': {'GEV': False, 'GPD': False, 'Gumbel': False, 'Weibull': True}, 'folder out': '/home/docs/checkouts/readthedocs.org/user_builds/totodoc/checkouts/latest/docs', 'method': {'ml': True, 'mom': False, 'pkd': False, 'pwm': False}, 'minimum number of peaks over threshold': 30, 'minimum time interval between peaks (h)': 24.0, 'threshold type': {'percentile': True, 'value': False}, 'threshold value': 95.0, 'time blocking': {'Annual': True, 'Monthly': False, 'Seasonal (North hemisphere)': False, 'Seasonal (South hemisphere)': False}})

This function is used for distribution analysis of any type. It generates return the shape and scale of a distribution. Inputs can be:

-only magnitude (omni-directional extreme value ananlysis) -magnitute and direction (directional ARI with omni or directional POT)_

magstr

Name of the column from which to get stats.

drrstr optionnal

Column name representing the directions.

args: dict

Dictionnary with the folowing keys:

fitting distribution: str

Name of the fit to use, can be: Weibull, Gumbel, GPD or GEV.

method: str

Name of the estimation method, can be: pkd: Pickands’ estimator. pwm: PWM-method mom: Moment method ml : Maximum Likelihood method

threshold type: str

Method to find the peaks: percentile: using the th percentile value: using a treshold value

threshold value: float

Either a absolute value or percentile value depending on the threshold type

directional: bool

Can be True or False, to calculate stats for each direction. Needs drr variable

direction binning: str

Can be centered or not-centered depending if the directionnal are centered over 0

direction interval: int

Dirctionnal interval for the bins in degrees

minimum number of peaks over threshold: int minimum time interval between peaks (h): int display peaks: bool

True or False to display peaks over threshold

display CDFs: bool

True or False to display CFDs image

folder out: str

Path to save the output

time blocking: str

if Time blocking=='Annual',

Statistics will be calculated for the whole timeserie

if Time blocking=='Seasonal (South hemisphere)',

Statistics will be calculated for each South hemisphere seasons

if Time blocking=='Seasonal (North hemisphere)',

Statistics will be calculated for each North hemisphere seasons

if Time blocking=='Monthly',

Statistics will be calculated for each 12 months

>>> df=tf['test1']['dataframe'].Extreme.distribution_shape(mag='U',drr='drr',args={'directional':'On',Time blocking':'Annual'})
>>> 

Distribution shape

Filename	Scale	Shape

do_extreme(mag='magnitude', tp='tp_optional', drr='direction_optional', tm='tm_optional', water_depth='water_depth_optional', args={'direction binning': {'centered': True, 'not-centered': False}, 'direction interval': 45.0, 'directional': False, 'display CDFs': True, 'display peaks': True, 'estimate Hmax & Cmax RPVs': {'Off': True, 'On': False}, 'fitting distribution': {'GEV': False, 'GPD': False, 'Gumbel': False, 'Weibull': True}, 'folder out': '/home/docs/checkouts/readthedocs.org/user_builds/totodoc/checkouts/latest/docs', 'method': {'ml': True, 'mom': False, 'pkd': False, 'pwm': False}, 'minimum number of peaks over threshold': 30, 'minimum time interval between peaks (h)': 24.0, 'return period': [1, 10, 25, 50, 100], 'slope fitting distribution': {'Gumbel': False, 'Weibull': True}, 'slope treshold': 0.005, 'threshold type': {'percentile': True, 'value': False}, 'threshold value': 95.0, 'time blocking': {'Annual': True, 'Monthly': False, 'Seasonal (North hemisphere)': False, 'Seasonal (South hemisphere)': False}, 'water depth': 5000.0})

This function is used for extreme value analysis of any type. It generates return period values for any parameters. Inputs can be:

-only magnitude (omni-directional extreme value ananlysis) -magnitute and direction (directional ARI with omni or directional POT)_ -wave magnitude and period (omni-directional analysis and bi-variate,

Hs vs. Tp, extremes, estimated using the FORM method)

-wave magnitude, period and direction (directional ARI with omni or

directional POT and bi-variate extremes, Hs vs. Tp, estimated using the FORM method for each selected directions)

Parameters

magstr

Name of the column from which to get stats.

tpstr optionnal

Column name representing the peak period.

tmstr optionnal

Column name representing Tm02.

drrstr optionnal

Column name representing the directions.

water_depthstr optionnal

Column name representing the water elevation.

args: dict

Dictionnary with the folowing keys:

fitting distribution: str

Name of the fit to use, can be: Weibull, Gumbel, GPD or GEV.

method: str

Name of the estimation method, can be: pkd: Pickands’ estimator. pwm: PWM-method mom: Moment method ml : Maximum Likelihood method

threshold type: str

Method to find the peaks: percentile: using the th percentile value: using a treshold value

threshold value: float

Either a absolute value or percentile value depending on the threshold type

slope fitting distribution: str

Can be: Weibull, Gumbel

slope threshold: float return period: list

Return period values.

estimate Hmax & Cmax RPVs: str

Can be On or Off

water depth: float

Total water depth if not specified in the input

directional: str

Can be True or False, to calculate stats for each direction. Needs drr variable

direction binning: str

Can be centered or not-centered depending if the directionnal are centered over 0

direction interval: int

Dirctionnal interval for the bins in degrees

minimum number of peaks over threshold: int minimum time interval between peaks (h): int display peaks: str

On or Off to display peaks over threshold

display CDFs: str

On or Off to display CFDs image

folder out: str

Path to save the output

time blocking: str

if Time blocking=='Annual',

Statistics will be calculated for the whole timeserie

if Time blocking=='Seasonal (South hemisphere)',

Statistics will be calculated for each South hemisphere seasons

if Time blocking=='Seasonal (North hemisphere)',

Statistics will be calculated for each North hemisphere seasons

if Time blocking=='Monthly',

Statistics will be calculated for each 12 months

Examples:

>>> df=tf['test1']['dataframe'].Extreme.do_extreme(mag='U',args={'directional':'On',Time blocking':'Annual'})
>>> 

Outputs:

Extreme value

	Omni	N	E	W	S
1
10
100

do_extreme_adjusted(hs='magnitude', wspd='wind_optional', args={'display CDFs': True, 'estimation method for Hs': {'ml': True, 'mom': False, 'pkd': False, 'pwm': False}, 'estimation method for Wspd': {'ml': True, 'mom': False, 'pkd': False, 'pwm': False}, 'fitting distribution for Hs': {'GEV': False, 'GPD': False, 'Gumbel': False, 'Weibull': True}, 'fitting distribution for Wspd': {'GEV': False, 'GPD': False, 'Gumbel': False, 'Weibull': True}, 'folder out': '/home/docs/checkouts/readthedocs.org/user_builds/totodoc/checkouts/latest/docs', 'max limiting Hs': 5, 'risk level': [10], 'time blocking': {'Annual': True, 'Monthly': False, 'Seasonal (North hemisphere)': False, 'Seasonal (South hemisphere)': False}, 'transport distance (km)': 1000.0, 'transport speed (m/s)': 2.572})

This function is used for adjusted extreme value analysis (Hs and wind speed) accuonting for time of exposure (typically for transportation metocean extremes). It generates return period values for Hs and Wspd. Inputs are: %Hs and Wsp (optional). Reference: GL Noble Denton, 2010. TECHNICAL POLICY BOARD, GUIDELINES FOR MARINE TRANSPORTATIONS. GL Noble Denton Group Ltd.

Parameters

hsstr

Column name representing the wave height

wspdstr optionnal

Column name representing the wind speed.

args: dict

Dictionnary with the folowing keys:

fitting distribution for Hs: str

Name of the fit to use, can be: Weibull, Gumbel, GPD or GEV.

fitting distribution for Wspd: str

Name of the fit to use, can be: Weibull, Gumbel, GPD or GEV.

estimation method for Hs: str

Name of the estimation method, can be: pkd: Pickands’ estimator. pwm: PWM-method mom: Moment method ml : Maximum Likelihood method

estimation method for Wspd: str

Name of the estimation method, can be: pkd: Pickands’ estimator. pwm: PWM-method mom: Moment method ml : Maximum Likelihood method

risk level: list

percentage for the risk level

max limiting Hs: float

Typically 5 m for barge tow and 8 m for ships

transport speed (m/s): float

Boat in speed in m/s

transport distance (km): float display CDFs: str

On or Off to display CFDs image

folder out: str

Path to save the output

time blocking: str

if Time blocking=='Annual',

Statistics will be calculated for the whole timeserie

if Time blocking=='Seasonal (South hemisphere)',

Statistics will be calculated for each South hemisphere seasons

if Time blocking=='Seasonal (North hemisphere)',

Statistics will be calculated for each North hemisphere seasons

if Time blocking=='Monthly',

Statistics will be calculated for each 12 months

Examples:

>>> df=tf['test1']['dataframe'].Extreme.do_extreme_adjusted(hs='hs',args={'transport speed (m/s)':2.5,'transport distance (km)': 100,'time blocking':'Annual'})
>>> 

Outputs:

Extreme value

	Omni	N	E	W	S
1
10
100

extreme_water_elevation(tide='tide', surge='surge', args={'display CDFs': True, 'display peaks': True, 'fitting distribution': {'GEV': False, 'GPD': False, 'Gumbel': False, 'Weibull': True}, 'folder out': '/home/docs/checkouts/readthedocs.org/user_builds/totodoc/checkouts/latest/docs', 'method': {'ml': True, 'mom': False, 'pkd': False, 'pwm': False}, 'minimum number of peaks over threshold': 30, 'minimum time interval between peaks (h)': 24.0, 'return period': [1, 10, 25, 50, 100], 'surge': {'Both (neg and pos)': True, 'Negative only': False, 'Positive only': False}, 'threshold type': {'percentile': True, 'value': False}, 'threshold value': 95.0, 'time blocking': {'Annual': True, 'Monthly': False, 'Seasonal (North hemisphere)': False, 'Seasonal (South hemisphere)': False}})

This function is used for extreme value analysis of total still water elevation (surge + tide). Inputs must be surge and tide level (in the same unit). The method complies with ISO recommendations: return period values are estimated by fitting a distribution to the empirical distribution obtained by combining the joint frequency distribution of tidal and surge elevations.

Parameters

tide: str

Column name representing the tide.

surge: str optionnal

Column name representing the surge.

args: dict

Dictionnary with the folowing keys:

fitting distribution: str

Name of the fit to use, can be: Weibull, Gumbel, GPD or GEV.

method: str

Name of the estimation method, can be: pkd: Pickands’ estimator. pwm: PWM-method mom: Moment method ml : Maximum Likelihood method

surge: str

Can be: Positive only: use only positive surge Negative only:use only negative surge Both (neg and pos): use both

return period: list

Return period values.

threshold type: str

Method to find the peaks: percentile: using the th percentile value: using a treshold value

threshold value: float

Either a absolute value or percentile value depending on the threshold type

minimum number of peaks over threshold: int minimum time interval between peaks (h): int display peaks: bool

True or False to display peaks over threshold

display CDFs: bool

True or False to display CFDs image

folder out: str

Path to save the output

time blocking: str

if Time blocking=='Annual',

Statistics will be calculated for the whole timeserie

if Time blocking=='Seasonal (South hemisphere)',

Statistics will be calculated for each South hemisphere seasons

if Time blocking=='Seasonal (North hemisphere)',

Statistics will be calculated for each North hemisphere seasons

if Time blocking=='Monthly',

Statistics will be calculated for each 12 months

Examples:

>>> df=tf['test1']['dataframe'].Extreme.extreme_water_elevation(tide='Et',surge='Eo',args={'Time blocking':'Annual'})
>>> 

Outputs:

Extreme water elevation

positive surge	Omni
1
10
25
negative surge	Omni
1
10
25