ENSO.diag

This module supports the following analysis:

1. Identify El Nino and La Nina events using an SST anomaly index and apply threshold and persistence criteria (find_events(), find_enso_percentile(), find_enso_threshold())
2. Compute the skewness of SST anomaly time series
3. Compute the persistence of events (duration)
4. Compute the transition probability of events
5. Compute climatological composite of El Nino or La Nina at a certain strength (find_en_pattern())
6. Compute the number of events peaking in a calendar month (for seasonal phase locking analysis; seasonal_locking(), seasonal_locking_from_nino34())

enso_skewness(), enso_duration(), enso_transition2() , find_enso_percentile() are rewritten from the Matlab code used in Choi et al (2013). find_en_pattern() is used in Choi et al (2015). A few of these functions require the GeoDAT library.

ENSO.diag.ENSO_duration(*args, **kwargs)

Same as enso_duration

ENSO.diag.ENSO_skewness(*args, **kwargs)

Same as enso_skewness

ENSO.diag.ENSO_transition(*args, **kwargs)

Same as enso_transition

ENSO.diag.ENSO_transition2(*args, **kwargs)

Same as enso_transition2

ENSO.diag.ENSO_transition_prob(*args, **kwargs)

Same as enso_transition_prob

ENSO.diag.Persistence_check(*args, **kwargs)

Same as persistence_check

ENSO.diag.Seasonal_Locking(*args, **kwargs)

Same as seasonal_locking

ENSO.diag.Seasonal_Locking_from_nino34(*args, **kwargs)

Same as seasonal_locking_from_nino34

ENSO.diag.compute_duration(nino34, operator, locs, evt_end, remove_merge_event=True)

Compute the duration of events counting from the event peak (locations given by locs) until the termination of events (given by the first occurrence of operator(nino34,evt_end)).

See Choi et al (2013)

Parameters:

• nino34 (numpy array) – ENSO SST anomaly index
• operator (numpy operator) – e.g. numpy.less or numpy.greater
• locs (list of int or numpy array of int) – indices of event peaks
• evt_end (scalar number) – value of nino34 when an event is considered as terminated
• remove_merge_event (bool) – remove events that are joined on together due to reintensification

Returns:

list of int (same length as locs)

ENSO.diag.enso_duration(nino34, percentile, thres_std_fraction, per=5, window=[-3, 3])

Compute the duration of the warm and cold events

Parameters:

• nino34 (numpy 1D array) – ENSO SST anomalies
• percentile (numeric) – greater than 0 and less than 100
• thres_std_fraction (numeric) – the fraction times the nino34 standard deviation is used for defining the termination

Returns:

with keys “warm” and “cold” each contains a list of integers which are the duration of the events

Return type:

dict

ENSO.diag.enso_skewness(nino34)

Shortcut for calculating skewness using scipy.stats. Choose scipy.stats.mstats.skew if nino34 is a masked array (as it often is)

Parameters:nino34 (numpy 1d array) – ENSO SST anomaly index Returns:scalar

ENSO.diag.enso_transition(nino34, percentile, wait_window, thres_std_fraction, per=5, window=[-3, 3])

Compute the number of transitions However, it does not eliminate double counting due to reintensification. Therefore the results are different from those of enso_transition2()

Parameters:

• nino34 (numpy 1d array) – ENSO SST anomaly index
• percentile (numeric) –
  0. < percentile < 100.
• wait_window (int) – time lapse between an event termination and the next event peak
• thres_std_fraction (numeric) – the fraction times the nino34 standard deviation is used for defining the termination, similar to enso_duration()
• per (int) – see find_events()
• windows (iterable) – see find_events()

Returns:

transition – number of warm-to-cold transition, “warm_warm”: number of warm-to-warm transition, “cold_warm”:..., “cold_cold”:...,}

Return type:

dict

ENSO.diag.enso_transition2(nino34, percentile, wait_window, thres_std_fraction, per=5, window=[-3, 3])

Compute the transition probabilities. Word for word copy from the Matlab code, which was used in. See Choi et al (2013)

Parameters:

• nino34 (numpy 1d array) – ENSO SST anomaly index
• percentile (numeric) – greater than 0. and less than 100.
• wait_window (int) – time lapse between an event termination and the next event peak
• thres_std_fraction (numeric) – the fraction times the nino34 standard deviation is used for defining the termination, similar to enso_duration()
• per (int) – see find_events()
• windows (iterable) – see find_events()

Returns:

transition (dict), indices(dict), warm_indices(list), cold_indices(list) transition= {“warm_cold”: probability of warm-to-cold transition,

“warm_warm”: probability of warm-to-warm transition, “cold_warm”:..., “cold_cold”:...,}

indices= {“ENLN”: indices of the peaks of warm events that are

followed by a cold event,

“ENEN”: indices of the peaks of warm events that are

followed by a warm event,

“LNLN”: indices of the peaks of cold events that are

followed by a cold event,

“LNEN”: indices of the peaks of cold events that are

followed by a warm event}

warm_indices (list) is the list of warm event peak locations; cold_indices (list) is the list of cold event peak locations

ENSO.diag.enso_transition_prob(*args, **kwargs)

Compute the transition probability from the results given by enso_transition()

All arguments and keyword arguments are fed to enso_transition()

ENSO.diag.findENSO_percentile(*args, **kwargs)

Same as find_enso_percentile

ENSO.diag.findENSO_threshold(*args, **kwargs)

Same as find_enso_threshold

ENSO.diag.findEvents(*args, **kwargs)

Same as find_events

ENSO.diag.find_EN_pattern(*args, **kwargs)

Same as find_en_pattern

ENSO.diag.find_en_pattern(field, nino34, nino34_mid=0.8, nino34_tole=0.4, do_climo=True, verbose=False)

Given a field and Nino3.4 index monthly time series, extract the time at which nino34_mid-nino34_tole < peak nino34 < nino34_mid+nino34_tole; then compute the climatology for these snap shots

Parameters:

• field (geodat.nc.Variable) –
• nino34 (geodat.nc.Variable) – Nino3.4 SST anomaly index
• nino34_mid (numeric) – mid point
• nino34_tole (numeric) – half bin size
• do_climo (bool) – whether a climatology is computed for the composite, default True
• verbose (bool) –

Returns:

pattern (geodat.nc.Variable)

This function requires the library GeoDAT

ENSO.diag.find_enso_percentile(index, percentile, *args, **kwargs)

Find ENSO events using percentiles (i.e. insensitive to time mean)

Parameters:

• index (numpy.ndarray) – ENSO SST anomaly monthly index. Masked array is supported
• percentile (numeric) – percentile beyond which El Nino and La Nina events are identified

args and kwargs are fed to find_events()

Returns:(dict, dict) each has keys “locs” and “peaks”. “locs” contains the index where an event peaks. “peaks” contains the corresponding peak values

Example:

>>> warm,cold = find_enso_percentile(nino34,15.)

ENSO.diag.find_enso_threshold(index, warm_threshold, cold_threshold, *args, **kwargs)

Similar to find_enso_percentile but uses threshold to find ENSO events :param index: ENSO SST anomaly monthly index. Masked array

is supported

Parameters:

• warm_threshold (numeric) – Above which El Nino SST anomalies are
• cold_threshold (numeric) – Below which La Nina SST anomalies are

args and kwargs are fed to find_events()

Returns:(dict, dict) each has keys “locs” and “peaks”. “locs” contains the index where an event peaks. “peaks” contains the corresponding peak values

ENSO.diag.find_events(index, operator, threshold, per=5, window=[-3, 3])

Return the locations of ENSO warm/cold event peaks for a given index.

Parameters:

• index (numpy 1d array) – ENSO SST anomaly
• operator (str) – “>” (index greater than threshold) or “<” (index smaller then threshold)
• threshold (numeric) – threshold for event definition
• per (int) – minimum persistence for index >/< threshold (default=5, unit is consistent with the array grid)
• window (iterable) – range around the event peak within which the peak has to be a global minima/maxima; length = 2 (default=[-3,3])

Returns:

(pklocs, pks) = (location in the input array, values of extrema)

ENSO.diag.persistence_check(is_selected, per)

Filter is_selected where True indicating an active, persistent event

Parameters:

• is_selected (numpy boolean array) –
• per (int) – length persistence required

Returns:

numpy boolean array same shape as is_selected

ENSO.diag.seasonal_locking(pklocs, months)

Given the indices of the peak and a list of months, return the count of events in a particular month (Jan-Dec).

Parameters:

• pklocs (list of int) – indices of event peaks with reference to some time axis
• months (list of int) – calendar months of that time axis

Returns:

list of int = [number of events peaked in Jan, number of events peaked in Feb,...]

ENSO.diag.seasonal_locking_from_nino34(nino34, months, find_events_func=None, count_warm=True, count_cold=True)

Shortcut for applying seasonal_locking() manually for warm and cold events.

Parameters:

• nino34 (numpy 1d array) – ENSO SST monthly anomaly
• months (list of int or numpy 1d array of int) – calendar months for the time axis of nino34
• find_events_func (function) – a function that accepts nino34 as the only arguments for finding warm and cold events. If None, default is find_enso_threshold(nino34, 0.8, -0.8)
• count_warm (bool) – whether warm events are counted
• count_cold (bool) – whether cold events are counted

Returns:

list of int = [number of events peaked in Jan, number of events peaked in Feb,...]