nbtools.ts

Functions/classes relative to time-series

Functions

compute_daily_anom(data, date, clim) Computes daily anomalies relative to a daily climatology.
compute_daily_clim(data, date[, smooth, nharm]) Computes a daily seasonal cycle from a daily dataset.
compute_monthly_anom(data, yyyymm, clim) Computes anomalies relative to a monthly climatology.
compute_monthly_clim(data, yyyymm) Compute a monthly seasonal cycle from a monthly dataset.
corr_ND(xdata, ydata[, use_covariance]) Computes the correlation/covariance between the xdata and ydata arrays at 0-lag.
day_of_year(yymmdd) Returns the day of year of
doy_to_date(year, doy) Converts from day of year into date
make_monthly_means(data, yymmdd) Computes monthy means from daily values
make_yymm(date) Converts a list/array of date objects into YYYYMM integers.
make_yymmdd(date) Converts a list/array of dates into YYYYMMDD integers.
remove_mean(xdata) Remove the mean from the dataset.
smooth_data_fft(data, nharm) Smooth an input data array by using a FFT filter.
standardize(xdata[, ddof]) Standardizes the xdata array
xcorr_1d(xdata, ydata[, maxlag, ...]) Computes the cross-correlation/cross-covariance two one-dimensional arrays.
xcorr_ND(xdata, ydata[, maxlag, use_covariance]) Computes the cross-correlation/cross-covariance between the xdata and ydata arrays.

Classes

Lanczos(filt_type, nwts, pca[, pcb, delta_t]) Class for Lanczos filtering.
class nbtools.ts.Lanczos(filt_type, nwts, pca, pcb=None, delta_t=1)[source]

Class for Lanczos filtering. Inspired from NCL’s filwgts_lanczos and wgt_runave functions.

Parameters:
  • filt_type (str) – The type of filter (“lp”=Low Pass, “hp”=High Pass, “bp”=Band Pass
  • nwts (int) – Number of weights (must be an odd number)
  • pca (float) – First cut-off period
  • pcb (float) – Second cut-off period (only for band-pass filters)
  • delta_t (float) – Time-step
wgt_runave(data)[source]

Compute the running mean of a ND input array using the filter weights.

Parameters:data (numpy.array) – Array to filter out (time must be the first dimension)
nbtools.ts.compute_daily_anom(data, date, clim)[source]

Computes daily anomalies relative to a daily climatology. Inspired from NCL’s calcDayAnomTLL function

Parameters:
  • data (numpy.array) – data from which to extract daily anom (time must be the first dimension)
  • date (int) – the date vector (format YYYYMMDD, with YYYY=year, MM=month, DD=day).
  • clim (numpy.array) – the daily climatology, computed with the nbtools.ts.compute_clim() function
Returns:

a numpy array that contains the daily anomalies. Same dimensions as data

Return type:

numpy.array

nbtools.ts.compute_daily_clim(data, date, smooth=True, nharm=2)[source]

Computes a daily seasonal cycle from a daily dataset. The user has the possibility to smooth the seasonal cycle, for instance by keeping the first two harmonics (annual and semi annual cycles). This script is largely inspired from NCL’s calcDayAnomTLL and smthClmDayTLL functions

Parameters:
  • data (numpy.ndarray) – dataset whose seasonal cycle to extract (time must be the first dimension)
  • date (int) – the date vector (format YYYYMMDD, with YYYY=year, MM=month, DD=day). Obtained by using the nbtools.ts.make_yymmdd() function.
  • smooth (bool) – defines whether the seasonal cycle should be smoothed by using Fast Fourier Transform
  • nharm (int) – number of harmonics to retain if smooth is True. Use 2 to keep annual and semi-annual harmonics
Returns:

a numpy array that contains the daily seasonal cycle. Same dimensions as data, except for the first dimension which is 366.

Return type:

numpy.array

nbtools.ts.compute_monthly_anom(data, yyyymm, clim)[source]

Computes anomalies relative to a monthly climatology. This script is largely inspired from NCL’s calcMonAnomTLL function

Parameters:
  • data (numpy.array) – data from which to extract monthly anom (data must be first dimension).
  • date (int) – the date vector (format YYYYMM, with YYYY=year, MM=month)
  • dataclim (numpy.array) – the montly climatology, computed with the nbtools.ts.compute_clim() function.
Returns:

a numpy array that contains the monthly anomalies. Same dimensions as data

Return type:

numpy.array

nbtools.ts.compute_monthly_clim(data, yyyymm)[source]

Compute a monthly seasonal cycle from a monthly dataset.

This script is largely inspired from the NCL clmMonTLL function

Parameters:
  • data (numpy.ndarray) – dataset whose seasonal cycle to extract (time must be the first dimension)
  • date (int) – the date vector (format YYYYMM, with YYYY=year, MM=month). For instance obtained with the nbtools.ts.make_yymm() function.
Returns:

a numpy array that contains the monthly seasonal cycle. Same dimensions as data, except for the first dimension which is 12

Return type:

numpy.array

nbtools.ts.corr_ND(xdata, ydata, use_covariance=False)[source]

Computes the correlation/covariance between the xdata and ydata arrays at 0-lag. Calculation is performed on first dimension (usually time). Loop is optimized by using special loops.

Parameters:
  • numpy.array (ydata) – x-array (time must be the first dim.)
  • numpy.array – y-array (time must be the first dim.)
  • use_covariance (bool) – True if covariance should be computed instead of

correlation

Returns:A tuple with the cross-correlation or cross-covariance array, and the lag array.

Cross-correlation has dimensions (xdata.shape[1:], ydata.shape[1:]).

Return type:tuple
nbtools.ts.day_of_year(yymmdd)[source]

Returns the day of year of

a date vector in format YYYYMMDD

Parameters:date (int) – Input date (format YYYYMMDD, with YYYY=year, MM=month, DD=day)
Returns:a numpy.array containing the day of year (1st of January=1, etc)
Return type:int
nbtools.ts.doy_to_date(year, doy)[source]

Converts from day of year into date

Parameters:
  • year (int) – Year
  • doy (int) – Day of year
nbtools.ts.make_monthly_means(data, yymmdd)[source]

Computes monthy means from daily values

Parameters:
  • yymmdd (numpy.array) – Dates in format YYYYMMDD
  • data (numpy.array) – Dataset (time must be first dimension)
Returns:

a tuple, containing the monthly output dates (format YYYYMM), and the monthly data output.

Return type:

tuple

nbtools.ts.make_yymm(date)[source]

Converts a list/array of date objects into YYYYMM integers.

YYYY = year
MM = month
Parameters:date (list) – A list/array of datetime.datetime
Returns:A numpy array containing the dates in format YYYYMM
Return type:numpy.array
nbtools.ts.make_yymmdd(date)[source]

Converts a list/array of dates into YYYYMMDD integers.

YYYY=year
MM=month
DD=day
Parameters:date (list) – A list/array of datetime.datetime objects
Returns:A numpy array containg the dates in format YYYYMMDD
Return type:numpy.array
nbtools.ts.remove_mean(xdata)[source]

Remove the mean from the dataset.

\[output = \frac{x-\overline{x}}\]

Made on the first dimension (usually time).

Parameters:xdata (numpy.array) – Input data
Returns:A numpy array with the anomalies

of the input array

Return type:numpy.array
nbtools.ts.smooth_data_fft(data, nharm)[source]

Smooth an input data array by using a FFT filter.

Inspired from NCL’s smthClmDayTLL<https://www.ncl.ucar.edu/Document/Functions/Contributed/smthClmDayTLL.shtml> _ function

The FFT coefficients are extracted, and the signal is reconstructed by using only the first nharm harmonics. Is used in the nbtools.ts.compute_daily_clim function to smooth a daily seasonal cycle.

Parameters:
  • data (numpy.ndarray) – dataset whose seasonal cycle to extract (time must be the first dimension)
  • nharm (int) – number of harmonics to retain
nbtools.ts.standardize(xdata, ddof=0)[source]

Standardizes the xdata array

\[output = \frac{x-\overline{x}}{\sigma_x}\]

Made on the first dimension (usually time).

Parameters:
  • xdata (numpy.array) – Input data
  • int (ddof) – Number of degrees of freedom to remove

for the calculation of \(\sigma\) (see the numpy.std() documentation.

Returns:A numpy array with the standardized values

of the input array

Return type:numpy.array
nbtools.ts.xcorr_1d(xdata, ydata, maxlag=None, use_covariance=False, ddof=1)[source]

Computes the cross-correlation/cross-covariance two one-dimensional arrays. xdata leads at positive lags. Inspired from the pyplot.xcorr() function

Parameters:
  • numpy.array (ydata) – x-array (leads at positive lags)
  • numpy.array – y-array (leads at negative lags)
  • maxlag (int) – Number of maximum lag to return. If None,

maxlag=len(xdata)-1 :param bool use_covariance: Whether covariance (True) or correlation (False) should be returned :param int ddof: Number of degrees of freedom to remove if covariance is computed. If 1, then covariance is divided by (N-1).

Returns:A tuple with the lags and the cross-correlation array
Return type:tuple
nbtools.ts.xcorr_ND(xdata, ydata, maxlag=None, use_covariance=False)[source]

Computes the cross-correlation/cross-covariance between the xdata and ydata arrays. Calculation is performed on first dimension (usually time). xdata leads for positive lags.

Parameters:
  • numpy.array (ydata) – x-array (time must be the first dim.)
  • numpy.array – y-array (time must be the first dim.)
  • use_covariance (bool) – True if covariance should be computed instead of

correlation

Parameters:maxglag (int) – number of lag to consider. If None, maxlag=ntime
Returns:A tuple with the cross-correlation or cross-covariance array, and the lag array.

Cross-correlation has dimensions (xdata.shape[1:], ydata.shape[1:], 2*maxlag+1).

Return type:tuple