Python API

icclim.indice() – Compute indice

This is the main function to compute an indice:

icclim.icclim.indice(in_files, var_name, indice_name=None, slice_mode='year', time_range=None, out_file='./icclim_out.nc', threshold=None, N_lev=None, lev_dim_pos=1, transfer_limit_Mbytes=None, callback=None, callback_percentage_start_value=0, callback_percentage_total=100, base_period_time_range=None, window_width=5, only_leap_years=False, ignore_Feb29th=False, interpolation='linear', out_unit='days', netcdf_version='NETCDF3_CLASSIC', user_indice=None, save_percentile=False)
Parameters:
  • indice_name (str) – Climate index name.
  • in_files (str OR list of str OR list of lists) – Absolute path(s) to NetCDF dataset(s) (including OPeNDAP URLs).
  • var_name (str OR list of str) – Target variable name to process corresponding to in_files.
  • slice_mode (str) – Type of temporal aggregation: “year”, “month”, “DJF”, “MAM”, “JJA”, “SON”, “ONDJFM” or “AMJJAS”. If None, the index will be calculated as monthly values.
  • time_range ([datetime.datetime, datetime.datetime]) – Temporal range: upper and lower bounds for temporal subsetting. If None, whole period of input files will be processed.
  • out_file (str) – Output NetCDF file name (default: “icclim_out.nc” in the current directory).
  • threshold (float or list of floats) – User defined threshold for certain indices.
  • N_lev (int) – Level number if 4D variable.
  • lev_dim_pos (int) – Position of Level dimension, either 0 or 1. 0 is leftmost dimension, 1 is second to the leftmost. Default 1.
  • transfer_limit_Mbytes (float) – Maximum OPeNDAP/THREDDS request limit in Mbytes in case of OPeNDAP datasets.
  • callback (callback.defaultCallback()) – Progress bar printing. If None, progress bar will not be printed.
  • callback_percentage_start_value (int) – Initial value of percentage of the progress bar (default: 0).
  • callback_percentage_total (int) – Total persentage value (default: 100).
  • base_period_time_range ([datetime.datetime, datetime.datetime]) – Temporal range of the base period.
  • window_width (int) – Window width, must be odd (default: 5).
  • only_leap_years (bool) – Option for February 29th (default: False).
  • ignore_Feb29th (bool) – Ignoring or not February 29th (default: False).
  • interpolation (str) – Interpolation method to compute percentile values: “linear” or “hyndman_fan” (default: “hyndman_fan”).
  • out_unit (str) – Output unit for certain indices: “days” or “%” (default: “days”).
  • user_indice (dict) – A dictionary with parameters for user defined index
  • netcdf_version (str) – NetCDF version to create (default: “NETCDF3_CLASSIC”).
Return type:

path to NetCDF file

Warning

If out_file already exists, icclim will overwrite it!

Note

For the variable names see the correspondence table “indice - source variable”

Below some additional information about input parameters.

in_files and var_name

The in_files parameter could be string, list of strings or list of lists of strings:

  single input file per variable several input files per variable
simple indice (based on a single variable) var_name = ‘tasmax’ var_name = ‘tasmax’
in_files = ‘tasmax_1990-2010.nc’ in_files = [‘tasmax_1990-2000.nc’, ‘tasmax_2000-2010.nc’]
multivariable indice (based on several variables) var_name = [‘tas’, ‘pr’] var_name = [‘tas’, ‘pr’]
in_files = [‘tas_1990-2010.nc’, ‘pr_1990-2010.nc’] in_files = [[‘tas_1990-2000.nc’, ‘tas_2000-2010.nc’], [‘pr_1990-2000.nc’], ‘pr_2000-2010.nc’]]

Warning

The order of variables in var_name/in_files must be [‘tasmax’, ‘tasmin’] for indices DTR, ETR and vDTR and [‘tas’, ‘pr’] for indices CD, CW, WD and WW.

slice_mode

The slice_mode parameter defines a desired temporal aggregation. Thus, each indice can be calculated at annual, winter half-year, summer half-year, winter, spring, summer, autumn and monthly frequency:

Value (string) Description
year (default) annual
month monthly (all months)
ONDJFM winter half-year
AMJJAS summer half-year
DJF winter
MAM spring
JJA summer
SON autumn

Note

The winter season (DJF) of 2000 is composed of December 2000, January 2001 and February 2001. Likewise, the winter half-year (ONDJFM) of 2000 includes October 2000, November 2000, December 2000, January 2001, February 2001 and March 2001.

Monthly time series with months selected by user:

>>> slice_mode = ['month',[4,5,11]] # indice will be computed only for April, May and November

or

>>> slice_mode = ['month',[4]] # indice will be computed only for April

User defined seasons:

>>> slice_mode = ['season',[4,5,6,7]]

or

>>> slice_mode = ['season',([11,12],[1])]

Note

For a season composed of two years, months must be separated in two lists and united in a tuple: ([months of YYYY], [months of YYYY+1])

Note

If slice_mode is None: whole period of time range will be processed.

threshold

It is possible to set a user define threshold for indices SU (default threshold: 25), CSU (default threshold: 25), TR (default threshold: 20). The threshold could be one value:

>>> threshold = 30

or a list of values:

>>> threshold = [20,25,30]

Note

Currently, temperature thresholds are only avaliable and units of threshold must be in degrees Celsius.

transfer_limit_Mbytes

In case of OPeNDAP datasets, if requested datasets exceed the transfer limit, ICCLIM applies chunking method to transfer and process. Chunk size is dynamically adapted to the data maximum transfer size. Data cutting is realized along the time dimension (spatial chunking).

The transfer_limit_Mbytes parameter, required to estimate the optimal data chunksize, should be set to the request limit value:

>>> transfer_limit_Mbytes = 500

Note

If that does not work, try to reduce the transfer_limit_Mbytes value.

Note

Example of error message, if transfer_limit_Mbytes is not set or its value is overvalued:

context: Error { code = 403; message = "Request too big=1875.0 Mbytes, max=500.0"^;};

...

RuntimeError: NetCDF: Malformed or inaccessible DAP DATADDS

Note

If transfer_limit_Mbytes is set, chunking is applied even for local datasets that could be useful for machines with little RAM.

callback

The percentage progress bar is printed if the callback parameter is set to a callback function. The default callback functions are defined in icclim.util.callback.py.

>>> from icclim import icclim.util.callback as callback
>>> cb = callback.defaultCallback

ignore_Feb29th

If it is True, we kick out February 29th.

Computing percentile thresholds

Percentile thresholds are used as thresholds for calculation of percentile-based indices and are computed from values inside a reference period, named base period which is usually 30 years (base_period_time_range parameter).

There are two methods for calculation of percentile thresholds:

1. For temperature indices, theses thresholds are computed for each calendar day from samples (5-day window centred on the calendar day in the base period) which depend on window_width, only_leap_years and ignore_Feb29th parameters.

In ICCLIM these thresholds represent a dictionary with 365 (if ignore_Feb29th is True) or 366 (if ignore_Feb29th is False) calendar days as keys, and 2D arrays as values.

Note

A calendar day key of the dictionary is composed from the corresponding month and day, separated by a comma. For example, getting of the 2D array with percentiles for April 13th, looks like my_perc_dict[4,13].

The percentile thresholds are different for “in-base” years (years inside the base period) and “out-of-base” years. For “in-base” years, ICCLIM uses the bootstrapping procedure, which is explained in this article: Avoiding Inhomogeneity in Percentile-Based Indices of Temperature Extremes (Zhang et al.) - see the resampling algorithm in the section 4. Removing the “jump”.

Warning

Computing of percentile thresholds with the bootstrapping procedure may take some time! For example, a 30-yr base period requires (30-1) times of computing percentiles for each “in-base” year!, i.e. 30*(30-1) times in total (+1 time without bootstrapping for “out-of-base” years).

2. For precipitation indices, the thresholds are computed from the set of wet days (i.e. days when daily precipitation amount >= 1.0 mm) in the base period. In ICCLIM these thresholds represent an 2D array.

Both methods could use 2 types of interpolation.

The calc_percentiles.py module contains get_percentile_dict and get_percentile_arr functions for the described methods.

window_width

The window width is used for getting samples for percentiles computing and is set to 5: percentiles-based indices use 5-day window. The window is centred on a certain calendar day, for example: - April 13th, we take the values for April 11th, April 12th, April 13th, April 14th and April 15th of each year of the base period. - January 1st, we take all days of December 30th, December 31st, January 1st, January 2nd and January 3rd.

Hence, for a base period of 30 years and 5-day window width for each calendar day (except February 29th), there are 150 values ( 30 * 5 ) to compute its percentile value.

only_leap_years

The only_leap_years parameter selects which of two methods to use for calculating a percentile value for the calendar day of February 29th:

  • if True, we take only leap years, i.e. for example for the base period of 1980-1990 and 5-day window width, we take the values corresponding to the following dates:

    1980-02-27, 1980-02-28, 1980-02-29, 1980-03-01, 1980-03-02,

    1984-02-27, 1984-02-28, 1984-02-29, 1984-03-01, 1984-03-02,

    1988-02-27, 1988-02-28, 1988-02-29, 1988-03-01, 1988-03-02

  • if False, for the same base period and window width, we have:

    1980-02-27, 1980-02-28, 1980-02-29, 1980-03-01, 1980-03-02,

    1981-02-27, 1981-02-28, 1981-03-01, 1981-03-02,

    1982-02-27, 1982-02-28, 1982-03-01, 1982-03-02,

    1983-02-27, 1983-02-28, 1983-03-01, 1983-03-02,

    1984-02-27, 1984-02-28, 1984-02-29, 1984-03-01, 1984-03-02,

    1985-02-27, 1985-02-28, 1985-03-01, 1985-03-02,

    1986-02-27, 1986-02-28, 1986-03-01, 1986-03-02,

    1987-02-27, 1987-02-28, 1987-03-01, 1987-03-02,

    1988-02-27, 1988-02-28, 1988-02-29, 1988-03-01, 1988-03-02

    1989-02-27, 1989-02-28, 1989-03-01, 1989-03-02,

    1990-02-27, 1990-02-28, 1990-03-01, 1990-03-02

The second way is preferable, because we have more samples.

Warning

If ignore_Feb29th is True, the only_leap_years does not make sense!

interpolation

Computing of a percentile value could use linear interpolation or the interpolation proposed by Hyndman and Fan (1996), named in ICCLIM as hyndman_fan interpolation.

out_unit

Percentile-based indices (TX10p, TX90p, TN10p, TN90p, TG10p, TG90p, R75p, R95p and R99p) could be returned as number of days (out_unit = “days”) or as percentage of days (out_unit = “%”).

Custom indices

You can also calculate custom climate indices by setting all necessary parameters to user_indice.

user_indice

user_indice is a dictionary with possible keys:

Key Type of value Description
“indice_name” str Name of custom indice.
“calc_operation” str Type of calculation. See below for more details.
“logical_operation” str “gt”, “lt”, “get”, “let” or “e”
“thresh” float or str In case of percentile-based indice, must be string which starts with “p” (e.g. ‘p90’).
“link_logical_operations” str “and” or “or”
“extreme_mode” str “min” or “max” for computing min or max of running mean/sum.
“window_width” int Used for computing running mean/sum.
“coef” float Constant for multiplying input data array.
“date_event” bool To keep or not the date of event. See below for more details.
“var_type” str “t” or “p”. See below for more details.
“ref_time_range” [datetime.datetime, datetime.datetime] Time range of reference (baseline) period for computing anomalies.

Additional information about user_indice keys are given below.

  • key calc_operation
value description
‘max’ maximum
‘min’ minimum
‘sum’ sum
‘mean’ mean
‘nb_events’ number of relevant events fulfilling given criteria
‘max_nb_consecutive_events’ maximum number of consecutive events fulfilling given criteria
‘run_mean’ max or min of running mean
‘run_sum’ max or min of running sum
‘anomaly’ mean(future period) - mean(past period)
  • The key date_event allows to keep date(s) of the event, it if is True:

    • For simple statistics (min, max) in output netCDF file will be created “date_event” variable with numerical dates of the first occurrence of the event for each pixel.
    • For other operations in output netCDF file will be created “date_event_start” and “date_event_end” variables with numerical dates of the event for each pixel.

    Note

    The “date_event”, “date_event_start” and “date_event_end” netCDF variables have the same shape as indice’s one.

    Warning

    “Date_event”/”date_event_start”/”date_event_end” has no value:

    • for certain pixels, if event is not found,
    • for all pixels of “in-base” years (years in base period) for temperature percentile-based indices - it is not possible to determine the correct date of the event because of averaging of indice in “in-base” year.
  • The key var_type is used to chose the method for computing percentile thresholds. The methods are different for temperature and precipitation variables (more detailed here):

    • If ‘t’ (temperature variable), percentile thresholds are computed for each calendar day, using the bootstrapping procedure.
    • If ‘p’ (precipitation variable), percentile threshold are calculated for whole set of values corresponding to wet days (i.e. days with daily precipitation amount >= 1.0 mm) in base period.

Correspondence table “cal_operation” – required/optional parameters:

“calc_operation” value required parameters optional_parameters
‘max’/’min’   ‘coef’, ‘logical_operation’, ‘thresh’, ‘date_event’
‘mean’/’sum’   ‘coef’, ‘logical_operation’, ‘thresh’,
‘nb_events’

‘logical_operation’, ‘thresh’,

‘link_logical_operations’ (if multivariable indice),

‘var_type’ (if percentile-based indices)

‘coef’, ‘date_event’
‘max_nb_consecutive_events’ ‘logical_operation’, ‘thresh’ ‘coef’, ‘date_event’
‘run_mean’/’run_sum’ ‘extreme_mode’, ‘window_width’ ‘coef’, ‘date_event’

Warning

The ‘window_width’ here is a parameter for calculation of statistics in running window. Do not confuse with ‘window_width’ of icclim.indice(), which is used for computing of temperature percentiles and set to 5 as default.

Note

See examples for computing custom indices here.

Examples

>>> from icclim import icclim
>>> import datetime

Example 1: indice SU

>>> files = ['tasmax_day_CNRM-CM5_historical_r1i1p1_19950101-19991231.nc', 'tasmax_day_CNRM-CM5_historical_r1i1p1_20000101-20041231.nc', 'tasmax_day_CNRM-CM5_historical_r1i1p1_20050101-20051231.nc']
>>>
>>> dt1 = datetime.datetime(1998,1,1)
>>> dt2 = datetime.datetime(2005,12,31)
>>>
>>> out_f = 'SU_JJA_CNRM-CM5_historical_r1i1p1_1998-2005.nc' # OUTPUT FILE: summer season values of SU
>>>
>>> icclim.indice(indice_name='SU', in_files=files, var_name='tasmax', time_range=[dt1, dt2], slice_mode='JJA', out_file=out_f)

Example 2: indice ETR

>>> files_tasmax = ['tasmax_day_CNRM-CM5_historical_r1i1p1_19300101-19341231.nc', 'tasmax_day_CNRM-CM5_historical_r1i1p1_19350101-19391231.nc']
>>> files_tasmin = ['tasmin_day_CNRM-CM5_historical_r1i1p1_19300101-19341231.nc', 'tasmin_day_CNRM-CM5_historical_r1i1p1_19350101-19391231.nc']
>>>
>>> out_f = 'ETR_year_CNRM-CM5_historical_r1i1p1_1930-1939.nc' # OUTPUT FILE: annual values of ETR
>>>
>>> icclim.indice(indice_name='ETR', in_files=[files_tasmax, files_tasmin], var_name=['tasmax', 'tasmin'], slice_mode='year', out_file=out_f)

Warning

The order of var_name must be [‘tasmax’, ‘tasmin’] and NOT [‘tasmin’, ‘tasmax’]. The same for in_files.

Example 3: indice TG90p with callback

>>> from icclim import icclim.util.callback as callback
>>>
>>> f = 'tas_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
>>>
>>> # base period
>>> base_dt1 = datetime.datetime(1961,01,01)
>>> base_dt2 = datetime.datetime(1970,12,31)
>>>
>>> # studied period
>>> dt1 = datetime.datetime(1980,01,01)
>>> dt2 = datetime.datetime(2000,12,31)
>>>
>>> out_f = 'TG90p_AMJJAS_CNRM-CM5_historical_r1i1p1_1980-2000.nc' # OUTPUT FILE: summer half-year values of TG90p
>>>
>>> icclim.indice(indice_name='TG90p', in_files=f, var_name='tas', slice_mode='AMJJAS', time_range=[dt1, dt2], base_period_time_range=[base_dt1, base_dt2], out_file=out_f, out_unit='%', callback=callback.defaultCallback2)

Example 4: multivariable percentile-based indices CD, CW, WD, WW

These indices could be defined as costum indices, See an example here

Example 5: Custom indice (max)

from icclim import icclim.util.callback as callback

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'max'
                   }

file_tas = 'tas_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_tas, var_name='tas', slice_mode='year', out_file=out_f, callback=callback.defaultCallback2)

Example 6: Custom indice (min positive + date)

Get minimum temperature which is above zero Celsius and find its date.

Warning

If input data are in Kelvin, then thresh must be in Kelvin too.

Note

An additional variable will be created in output netCDF file: “date_event” with the date of the first occurrence of min positive.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'min',
                    'logical_operation': 'gt',
                    'thresh': 0 + 273.15, ### input data in Kelvin ==> threshold in Kelvin!
                    'date_event': True
                   }

file_tasmin = 'tasmin_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_tasmin, var_name='tasmin', slice_mode='year', out_file=out_f, callback=callback.defaultCallback2)

Example 7: Custom indice (mean of selected period)

Note

slice_mode must be None to apply the operation to the whole period of selected time range.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'mean'
                   }

file_tas = 'tas_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

tr = [datetime.datetime(1901,01,01), datetime.datetime(1920,12,31)]

icclim.indice(user_indice=my_indice_params, in_files=file_tas, var_name='tas', slice_mode=None, time_range=tr, out_file=out_f, callback=callback.defaultCallback2)

Example 8: Custom indice (number of days when tas < 15 degrees Celsius)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': 'lt',
                    'thresh': 15 + 273.15 ### input data in Kelvin ==> threshold in Kelvin!
                   }

file_tas = 'tas_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_tas, var_name='tas', slice_mode='SON', out_unit='days', out_file=out_f, callback=callback.defaultCallback2)

Example 9: Custom indice (percentage of days when tasmax > 80th pctl + date)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

Note

80th pctl: 80th percentile of tasmax in base period

Note

Two additional variables will be created in output netCDF file: “date_event_start” (the date of the first occurence of tasmax > 80th pctl) and “date_event_end” (the date of the last occurence of tasmax > 80th pctl).

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': 'gt',
                    'thresh': 'p80',
                    'var_type': 't',
                    'date_event': True
                   }

file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'
bp = [datetime.datetime(1960,01,01), datetime.datetime(1969,12,31)]

icclim.indice(user_indice=my_indice_params, in_files=file_tasmax, var_name='tasmax', slice_mode='year', base_period_time_range=bp, out_unit='%', out_file=out_f, callback=callback.defaultCallback2)

Example 10: Custom indice (number of days when daily precipitation amount > 85th pctl)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

Note

daily precipitation amount: daily precipitation amount on a wet day (RR >= 1.0 mm)

Note

85th pctl: percentile of precipitation on wet days in base period

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': 'gt',
                    'thresh': 'p85',
                    'var_type': 'p'
                   }

file_pr = 'pr_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_pr, var_name='pr', slice_mode='year', base_period_time_range=bp, out_unit='days', out_file=out_f, callback=callback.defaultCallback2)

Example 11: Custom indice (max number of consecutive days when tasmax >= 25 degrees Celsius + date)

Note

Two additional variables will be created in output netCDF file: “date_event_start” (the first date of the found sequence) and “date_event_end” (the last date of the found sequence).

Warning

If there are several sequences of the same length, the “date_event_start” and “date_event_end” will correspond to the first sequence.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'max_nb_consecutive_events',
                    'logical_operation': 'get',
                    'thresh': 25 + 273.15, ### input data in Kelvin ==> threshold in Kelvin!
                    'date_event': True
                   }

file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_tasmax, var_name='tasmax', slice_mode='year', out_file=out_f, callback=callback.defaultCallback2)

Example 12: Custom indice (max of sum of precipitation in 10 consecutive days)

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'run_sum',
                    'extreme_mode': 'max',
                    'window_width': 10
                   }

file_pr = 'pr_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_pr, var_name='pr', slice_mode=['season',[4,5,6,7,8]], out_file=out_f, callback=callback.defaultCallback2)

Example 13: Custom indice (min of mean of tasmin in 7 consecutive days + date)

Note

Two additional variables will be created in output netCDF file: “date_event_start” (the date corrsponding to the beggining of the “window” satisfying the condition) and “date_event_end” (the date corrsponding to the end of the “window” satisfying the condition).

Warning

If several “windows” with the same result are found, the “date_event_start” and “date_event_end” will correspond to the first one.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'run_mean',
                    'extreme_mode': 'min',
                    'window_width': 7,
                    'date_event': True
                   }

file_tasmin = 'tasmin_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=file_tasmin, var_name='tasmin', slice_mode=['season',([11,12],[1,2])], out_file=out_f, callback=callback.defaultCallback2)

Example 14: Custom indice (anomaly of tasmax between 2 period of 30 years)

Note

Result could be returned as percentage value relative to mean value of reference period, if out_unit='%'.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'anomaly'
                   }

file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'
tr = [datetime.datetime(1971,01,01), datetime.datetime(2000,12,31)] ### studied period: future period
tr_base = [datetime.datetime(1901,01,01), datetime.datetime(1930,12,31)] ### reference period: past period

icclim.indice(user_indice=my_indice_params, in_files=file_tasmax, var_name='tasmax', time_range=tr, base_period_time_range=tr_base, out_file=out_f, callback=callback.defaultCallback2)

Example 15: Multivariable custom indice (number of days when tasmin >= 10 degrees Celsius and tasmax > 25 degrees Celsius)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': ['get', 'gt'],
                    'thresh': [10+273.15, 25+273.15], ### input data in Kelvin ==> threshold in Kelvin!
                    'link_logical_operations': 'and'
                   }

file_tasmin = 'tasmin_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

icclim.indice(user_indice=my_indice_params, in_files=[file_tasmin, file_tasmax], var_name=['tasmin', 'tasmax'], slice_mode='JJA', out_unit='days', out_file=out_f, callback=callback.defaultCallback2)

Example 16: Multivariable custom indice (percentage of days when tasmin >= 10 degrees Celsius and tasmax > 90th pctl + date)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

Note

It is possible to use numeric and percentile threshold at the time.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': ['get', 'gt'],
                    'thresh': [10+273.15, 'p90'], ### input data in Kelvin ==> threshold in Kelvin!
                    'var_type': 't',  ### or ['-','t']
                    'link_logical_operations': 'and',
                    'date_event': True
                   }

file_tasmin = 'tasmin_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

bp = [datetime.datetime(1960,01,01), datetime.datetime(1969,12,31)]
icclim.indice(user_indice=my_indice_params, in_files=[file_tasmin, file_tasmax], var_name=['tasmin', 'tasmax'], slice_mode='JJA', base_period_time_range=bp, out_unit='%', out_file=out_f, callback=callback.defaultCallback2)

Example 17: CW as a custom indice (number of days when tas < 25th pctl and precip. > 75th pctl)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

4 compound indices defined in http://eca.knmi.nl/documents/atbd.pdf (see the section 5.3.3 “Compound indices”) are based on daily precipitation (RR) and mean temperature (TG) variables:

  • CD (cold/dry days): (TG < 25th pctl) and (RR < 25th pctl)
  • CW (cold/wet days): (TG < 25th pctl) and (RR > 75th pctl)
  • WD (warm/dry days): (TG > 75th pctl) and (RR < 25th pctl)
  • WW (warm/wet days): (TG > 75th pctl) and (RR > 75th pctl)

Note

RR is a daily precipitation on a wet day, and its percentile value is computed from set of wet days also.

Note

Percentiles thresholds computing uses differents methods as it was described here.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': ['lt', 'gt'],
                    'thresh': ['p25', 'p75'],
                    'var_type': ['t', 'p'],
                    'link_logical_operations': 'and'
                    }

file_pr= 'pr_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
file_tas = 'tas_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

bp = [datetime.datetime(1960,01,01), datetime.datetime(1969,12,31)]
icclim.indice(user_indice=my_indice_params, in_files=[file_tas, file_pr], var_name=['tas', 'pr'], slice_mode='year', out_unit='days', base_period_time_range=bp, out_file=out_f, callback=callback.defaultCallback2)

Example 18: Multivariable custom indice (number of days when tasmax > 90th pctl and tasmin >= 10 and precipitation < 30th pctl)

Note

If ‘calc_operation’ is ‘max_nb_consecutive_events’, then max number of consecutive days for the same condition will be computed.

my_indice_params = {'indice_name': 'my_indice',
                    'calc_operation': 'nb_events', ### 'calc_operation': 'max_nb_consecutive_events'
                    'logical_operation': ['gt', 'get', 'lt'],
                    'thresh': ['p90', 10+273.15, 'p30'],
                    'var_type': ['t', '-', 'p'],
                    'link_logical_operations': 'and'
                    }
file_pr= 'pr_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
file_tasmax = 'tasmax_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
file_tasmin = 'tasmin_day_CNRM-CM5_historical_r1i1p1_19010101-20001231.nc'
out_f = 'my_indice.nc'

bp = [datetime.datetime(1960,01,01), datetime.datetime(1969,12,31)]
icclim.indice(user_indice=my_indice_params, in_files=[file_tasmax, file_tasmin, file_pr], var_name=['tasmax', 'tasmin', 'pr'], slice_mode='SON', out_unit='days', base_period_time_range=bp, out_file=out_f, callback=callback.defaultCallback2)

Correspondence table “indice - source variable”

Indice Source variable
TG, GD4, HD17, TG10p, TG90p daily mean temperature
TN, TNx, TNn, TR, FD, CFD, TN10p, TN90p, CSDI daily minimum temperature
TX, TXx, TXn, SU, CSU, ID, TX10p, TX90p, WSDI daily maximum temperature
DTR, ETR, vDTR daily maximum + daily minimum temperature
PRCPTOT, RR1, SDII, CWD, CDD, R10mm, R20mm, RX1day, RX5day, R75p, R75pTOT, R95p, R95pTOT, R99p, R99pTOT daily precipitation flux (liquide phase)
SD, SD1, SD5cm, SD50cm daily snowfall flux (solid phase)
CD, CW, WD, WW daily mean temperature + daily precipitation flux (liquide phase)

Basic functions for computing indices

The calc_indice.py module contains basic routines for manipulating 3D arrays. Below are some of them.

Note

A function name is composed of an indice name and “_calculation” (example: FD_calculation).

Note

Input array(s) could be filled (numpy.ndarray) or masked (numpy.ma.MaskedArray). The output array type corresponds to the input array type.

Warning

If input array is filled, a fill_value (parameter “fill_val”) must be provided:

>>> FD_calculation(my_3D_array, fill_val=99999)

If input array is masked, the “fill_val” is ignored:

>>> FD_calculation(my_3D_masked_array)
icclim.calc_indice.TNx_calculation(arr, fill_val=None)

Calculates the TNx indice: maximum of daily minimum temperature.

Parameters:
  • arr (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily min temperature (e.g. “tasmin”)
  • fill_val (float) – fill value
Return type:

numpy.ndarray (2D) (if “arr” is numpy.ndarray) or numpy.ma.MaskedArray (2D) (if “arr” is numpy.ma.MaskedArray)

icclim.calc_indice.CSU_calculation(arr, fill_val=None, threshold=25)

Calculates the CSU indice: maximum number of consecutive summer days (i.e. days with daily maximum temperature > 25 degrees Celsius) [days].

Parameters:
  • arr (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily maximum temperature (e.g. “tasmax”) in Kelvin
  • fill_val (float) – fill value
  • threshold (float) – user defined temperature threshold in degrees Celsius (default: threshold=25)
Return type:

numpy.ndarray (2D) (if “arr” is numpy.ndarray) or numpy.ma.MaskedArray (2D) (if “arr” is numpy.ma.MaskedArray)

Warning

Units of “arr” must be Kelvin.

Warning

Units of “threshold” must be in Celsius.

icclim.calc_indice.DTR_calculation(arr1, arr2, fill_val1=None, fill_val2=None)

Calculates the DTR indice: mean of daily temperature range.

Parameters:
  • arr1 (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily max temperature (e.g. “tasmax”)
  • arr2 (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily min temperature (e.g. “tasmin”)
  • fill_val1 (float) – fill value of arr1
  • fill_val2 (float) – fill value of arr2
Return type:

numpy.ndarray (2D) (if “arr1” and “arr2” are numpy.ndarray) or numpy.ma.MaskedArray (2D) (if “arr1” and “arr2” are numpy.ma.MaskedArray)

Warning

“arr1” and “arr2” must be the same type, shape and correspond to the same time step vector.

icclim.calc_indice.TN10p_calculation(arr, dt_arr, percentile_dict, fill_val=None, out_unit='days')

Calculate the TN10p indice: number of cold nights (i.e. days with daily min temperature < 10th percentile of daily min temperature in the base period).

Parameters:
  • arr (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily min temperature (e.g. “tasmin”)
  • dt_arr (numpy.ndarray (1D) of datetime objects) – corresponding time steps vector
  • percentile_dict (dict) – 10th percentile of daily min temperature
  • fill_val (float) – fill value
Return type:

numpy.ndarray (2D) (if “arr” is numpy.ndarray) or numpy.ma.MaskedArray (2D) (if “arr” is numpy.ma.MaskedArray)

icclim.calc_indice.WSDI_calculation(arr, dt_arr, percentile_dict, fill_val=None, N=6, out_unit='days')

Calculate the WSDI indice (warm-spell duration index): number of days where, in intervals of at least 6 consecutive days, daily max temperature > 90th percentile of daily max temperature in the base period).

Parameters:
  • arr (numpy.ndarray (3D) or numpy.ma.MaskedArray (3D)) – daily max temperature (e.g. “tasmax”)
  • dt_arr (numpy.ndarray (1D) of datetime objects) – corresponding time steps vector
  • percentile_dict (dict) – 90th percentile of daily max temperature
  • fill_val (float) – fill value
  • N (int) – number of consecutive days (default: 6)
Return type:

numpy.ndarray (2D) (if “arr” is numpy.ndarray) or numpy.ma.MaskedArray (2D) (if “arr” is numpy.ma.MaskedArray)

Utility functions

util.regrid – Regridding

It is possible to do simple regridding (only rectangular “lat/lon” grid), using the util.regrid.py module:

icclim.util.regrid.get_regridded_var(f_src, f_dst, varname)

Returns a result of regridding.

Parameters:
  • f_src (str) – netCDF file containing the variable to be regridded
  • f_dst – netCDF file containing the destination grid
  • varname (str) – name of variable to process
Return type:

numpy.ndarray (3D)

Note

If the variable has dimensions (a, b, c) with a as time dimention and the destination grid is (d, e), then the output array will have the dimensions (a, d, e)

icclim.util.regrid.write2netCDF_after_regridding(arr, f_src, f_dst, f_out, var_src, var_dst=None)

Writes a regridded variable in new netCDF file.

Parameters:
  • arr (numpy.ndarray (3D)) – array containing the result of regridding
  • f_src (str) – netCDF file containing the variable to be regridded
  • f_dst (str) – netCDF file containing the destination grid
  • f_out (str) – new netCDF file name containing the regridded variable
  • var_src – variable name in f_src
  • var_dst (str) – name of the regridded variable in f_out, if None then it will be the same as var_src
>>> from icclim import icclim.util.regrid as regrid

For example, we have 2 files with different resolutions:

>>> f1 = 'tasmax_Amon_bcc-csm1-1_historical_r1i1p1_185001-201212.nc' # source grid (64 x 128), will be regridded to the destination grid
>>> f2 = 'tasmax_day_CNRM-CM5_historical_r1i1p1_18500101-20121231.nc' # destination grid (128 x 256)
>>> arr = regrid.get_regrided_var(f_src=f1, f_dst=f2, varname='tasmax') # numpy array with spatial dimensions (128,256)
>>> f1_regridded = 'regridded_tasmax_Amon_bcc-csm1-1_historical_r1i1p1_185001-201212.nc' # name of the new netCDF file
>>> regrid.write2netCDF_after_regridding(arr, f_src=f1, f_dst=f2, f_out=f1_regridded, var_src='tasmax')

See also more detailed example.

Warning

The package ESMF/ESMPy must be installed.

util.spatial_stat – Spatial statistics

Utility functions for spatial statistics such as computing of spatial average, spatial standard deviation, etc:

  1. util.spatial_stat.get_weight_matrix() computes weights, giving more weight to the pixels on the poles
  2. util.spatial_stat.multiply_to_weight_matrix() returns new values to be used for spatial statistics
icclim.util.spatial_stat.get_weight_matrix(lat_arr, lon_arr)

Computes a weight matrix for rectilinear grid.

Parameters:
  • lat_arr (numpy.ndarray (1D)) – vector of latitudes in radians
  • lon_arr (numpy.ndarray (1D)) – vector of longitudes
Return type:

numpy.ndarray (2D)

Warning

Latitudes must be in radians.

icclim.util.spatial_stat.multiply_to_weight_matrix(arr, weight_matrix)

Returns the result of the multiplication of “arr” by “weight_matrix”.

Parameters:
  • arr (numpy.ndarray) – values
  • weight_matrix (numpy.ndarray (2D)) – weights
Return type:

numpy.ndarray of the same shape as “arr”

Warning

if “arr” is a 2D array, “arr” and “weight_matrix” must have the same shape; if “arr” is a 3D array, then arr.shape[1] = weight_matrix.shape[0] and arr.shape[2] = weight_matrix.shape[1]

Warning

Only for rectangular “lat/lon” grid.