Table Of Contents

Previous topic

ENSO Information

Next topic

ClimateSeries

This Page

ENSOIndicator

class scikits.hydroclimpy.enso.ENSOIndicator

Define ENSO indicators objects, as a subclass of ReferencedSeries.

ENSO indices are calculated with the ENSOIndicator.set_indices method. Values of the indicator meeting some thresholds condition are clustered, and indices are allocated depending on the size (duration) of these clusters. The thresholds and minimum duration are respectively set through the attributes thresholds and minimum_size respectively.

The indices are typically calculated on a monthly basis and cached for convenience in the _cachedmonthly private attribute. This attribute is a dictionary with keys:

  • 'indices_monthly' for indices allocated with each month.
  • 'indices_annual' for indices allocated with period of 12 months.

Note that the indices cached in _cachedmonthly have always a monthly frequency.

Monthly indices converted to the frequency of the indicator, with the same date range and shape as the indicator, are stored in the private attribute _cachedcurrent.

Parameters:
data : {array-like}

Data portion of the array. Any data that is valid for constructing a MaskedArray can be used here:

  • a sequence of objects (numbers, characters, objects);
  • a ndarray or one of its subclass. In particular, MaskedArray and TimeSeries are recognized.
dates : {DateArray}

A DateArray instance storing the date information.

mask : {nomask, sequence}, optional

Mask.

refperiod : {None, tuple}, optional

Reference period, as a tuple (starting date, ending date). If None, the reference period is set to the whole range of dates.

freq : {None, string or integer}, optional

A valid frequency specification.

start_date : {None, Date}, optional

Starting date of the series. This parameter is only useful if dates is None.

ensotag : {‘’, string}, optional

Short string acting as ‘Memo’ field.

thresholds : {None, tuple}, optional

Tuple (lower threshold, upper threshold) for the definition of ENSO phases. If None, the thresholds are set to the lower and upper quartiles.

minsize : {None, int}, optional

Minimum size for the clusters of consecutive data.

fill_value : {float}, optional

Code for missing values in the raw data file.

Attributes

As a subclass of ReferencedSeries, ENSOIndicator inherits all its attributes, as described in the attributes section. In addition, each instance of the class has the following specific attributes:

thresholds

Characteristic thresholds for the definition of ENSO phases. By default, the thresholds correspond to the lower and upper quartiles. Setting the attribute to None reverts the thresholds to these defaults.

Note

Modifying this value resets any cached indices previously computed.

full_year
Boolean indicating whether indices are calculated for a whole year (twelve consecutive months) or until the conditions are met.
ensotag
Short string describing the indicator.
minimum_size

Returns the minimum numbers of consecutive months for the definition of ENSO indices.

Note

Modifying this value resets any cached indices previously computed.

reference_season

Reference season for the definition of ENSO indices.

Note

Modifying this value resets any cached indices previously computed.

refseason
Alias for reference_season.
ENSOIndicator.ensoindices
Indices corresponding to each ENSO phase:
  • +1 for El Niño (warm) phases;
  • 0 for Neutral phases;
  • -1 for La Niña (cold) phases.
indices
Alias to ensoindices.

Private attributes

The following attributes are private, and are not meant to be used directly. They are described here for the sake of completion.

_cachedmonthly
Dictionary storing the values of monthly ('indices_monthly') or annual ('indices_annual') indices.
_cachedclustered
Stores groups of consecutive indices, as a Cluster object.
_optinfo
Dictionary storing various attribute values.

Methods

In addition to all the methods inherited from ReferencedSeries and described in the Methods section, any instance of ENSOIndicator has the following specific methods.

ENSOIndicator.set_indices(full_year=None, reference_season=None, minimum_size=None, lag=0)

Sets the ENSO indices for the ENSO indicator.

Results are cached for convenience: if the method is called without arguments, the monthly indices are returned, provided they had been already computed.

Parameters:

full_year : {None, False, True}, optional

Whether the ENSO indices are set for a period of 12 months (True) or by valid episodes (False). If None, defaults to full_year.

reference_season : {None, string or sequence}, optional

Reference season. If None, defaults to reference_season.

minimum_size : {None, int}, optional

Minimum size for the groups of consecutive values. If None, defaults to minimum_size.

lag : {integer}, optional

Number of months of lag for ENSO indices. For example, if lag=6, the ENSO phase starting in Oct. 2001 is applied starting on Apr. 2002.

Notes

  • If full_year is False, this method calls set_monthly_indices. Otherwise, it calls set_annual_indices.

  • Results are cached for convenience. The cached results are always with a monthly frequency, and converted to the current frequency freq as needed, with the command

    >>> scikits.timeseries.lib.backward_fill(_cached.convert(freq, func=ma.mean))
    
  • The cached indices have a monthly frequency by default. When the ENSOIndicator is converted to a lower frequency with a given conversion function, the ENSO indices are converted using scipy.stats.mstats.mode as conversion function.

ENSOIndicator.set_monthly_indices(reference_season=None, minimum_size=None, lag=0)

Sets the ENSO indices per groups of months.

In a first step, each month is first qualified as +1 (-1) if the corresponding value of the indicator is greater (less) than the upper (lower) threshold, or as 0 otherwise. Consecutive values are then grouped according to their value. If the size of a group is less than the minimum_size parameters, the value of each element of this group is set to 0.

In a third step, groups of size larger than minimum_size are checked whether they cover the reference season. If they don’t, the value of each of their elements is then also set to 0.

Parameters:

minimum_size : {None, int}, optional

Minimum size for the groups of consecutive values. If None, defaults to self.minimum_size.

reference_season : {None, string or sequence}, optional

Reference season. If None, defaults to self.reference_season.

lag : {integer}, optional

Number of months of lag for ENSO indices. For example, if lag=6, the ENSO phase starting in Oct. 2001 is applied starting on Apr. 2002.

Notes

  • If the reference_season parameter is a string, it should be correspond to a series of consecutive months. For example, ‘JFM’, ‘OND’, ‘NDJF’ are all valid reference seasons (Jan. to Mar., Oct. to Dec., Nov. to Feb. respectively), but ‘JAM’, ‘SND’ or ‘XYZ’ are not.
  • If the reference_season parameter is a sequence, it should be a sequence of integers between 1 (Jan.) and 12 (dec.)
ENSOIndicator.set_annual_indices(minimum_size=None, reference_season=None, lag=0)

Sets the ENSO indices per periods of 12 months, starting at the first month of the reference season if any, otherwise at October.

The same steps are followed as for set_monthly_indices.

Parameters:

minimum_size : {None, int}, optional

Minimum size for the groups of consecutive values. If None, defaults to minimum_size.

reference_season : {None, string or sequence}, optional

Reference season. If None, defaults to self.reference_season.

lag : {integer}, optional

Number of months of lag for ENSO indices. For example, if lag=6, the ENSO phase starting in Oct. 2001 is applied starting on Apr. 2002.

See also

set_monthly_indices
Sets the ENSO indices for each month.