spei.knmi module

Functions for calculating cumulative deficits and related metrics based on temperature and deficit time series.

spei.knmi.cumsum(deficit: Series, allow_below_zero: bool = True) → Series

Compute the cumulative sum of a deficit series.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit values.

  • allow_below_zero (bool, optional) – If True, the cumulative sum is calculated as-is, allowing negative values. If False, the cumulative sum is constrained to be non-negative, resetting to zero whenever the sum would drop below zero. Default is True.

Returns:

A pandas Series containing the cumulative sum of the deficit values, optionally constrained to be non-negative.

Return type:

pd.Series

spei.knmi.deficit_apr1(deficit: Series, enddate: Timestamp | str = '2000-09-30') → Series

Compute the maximum change in cumulative deficit within a specified date range.

This function computes the cumulative deficit for the given deficit series between April 1st and September 30th. It then calculates the maximum change in the cumulative deficit over this period.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit values. The index is expected to be datetime-like.

  • enddate (pd.Timestamp, optional) – The end date for the cumulative deficit calculation. Defaults to September 30th.

Returns:

A pandas Series containing the maximum change in cumulative deficit over the specified period, labeled as “DIapr1”.

Return type:

pd.Series

spei.knmi.deficit_gdd(deficit: Series, temp: Series, threshold: float = 440.0, enddate: Timestamp | str = '2000-09-30') → Series

Compute the maximum change in cumulative deficit.

Starts from the first day when the temperature sum (growing degree days; GDD) exceeds a specified threshold.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the daily deficit values.

  • temp (pd.Series) – A pandas Series representing the daily temperature values.

  • threshold (float, optional) – The temperature sum GDD threshold to determine the starting date for the calculation. Defaults to 440.0 degrees Celsius.

  • enddate (pd.Timestamp, optional) – The end date for the cumulative deficit calculation. Defaults to September 30th, 2000.

Returns:

A pandas Series containing the maximum change in cumulative deficit, labeled as “DIgdd”.

Return type:

pd.Series

spei.knmi.deficit_max(deficit: Series, startdate: Timestamp | str = '2000-04-01', enddate: Timestamp | str = '2000-09-30') → Series

Compute the maximum cumulative deficit within a specified period.

This function computes the maximum cumulative deficit for a given deficit time series, starting from April 1st to September 30th. The cumulative deficit is calculated using the get_cumulative_deficit function, ensuring that values below zero are not allowed.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit values over time.

  • startdate (pd.Timestamp, optional) – The start date for the cumulative deficit calculation. Defaults to April 1st.

  • enddate (pd.Timestamp, optional) – The end date for the cumulative deficit calculation. Defaults to September 30th.

Returns:

A pandas Series containing the maximum cumulative deficit within the specified period, labeled as “Dmax”.

Return type:

pd.Series

spei.knmi.deficit_oct1(deficit: Series, startdate: Timestamp | str = '2000-04-01') → Series

Compute the cumulative deficit on October 1st.

This function computes the cumulative deficit for a given time series of deficits, considering only the period between April 1st and September 30th. The cumulative deficit is reset to zero if it goes below zero during this period.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit time series. The index should be datetime-like, and the values should represent the deficit amounts.

  • startdate (pd.Timestamp, optional) – The start date for the cumulative deficit calculation. Defaults to April 1st.

Returns:

A pandas Series containing the cumulative deficit values on October 1st. The index of the returned Series corresponds to the columns of the cumulative deficit DataFrame, and the name of the Series is “Doct1”.

Return type:

pd.Series

spei.knmi.deficit_wet(deficit: Series, enddate: Timestamp | str = '2000-09-30') → Series

Compute the maximum change in cumulative deficit for a specified period.

This function computes the maximum change in cumulative deficit from January 1st to September 30th of a given year. The cumulative deficit is calculated using the get_cumulative_deficit function, allowing values below zero.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit values over time.

  • enddate (pd.Timestamp, optional) – The end date for the cumulative deficit calculation. Defaults to September 30th, 2000.

Returns:

A pandas Series containing the maximum change in cumulative deficit for the specified period, labeled as “DIwet”.

Return type:

pd.Series

spei.knmi.get_cumulative_deficit(deficit: Series, startdate: Timestamp | Series, enddate: Timestamp | Series, allow_below_zero: bool = True) → DataFrame

Compute the cumulative deficit for a given time period.

This function computes the cumulative deficit for each column in a grouped yearly DataFrame, starting from startdate to enddate. The cumulative sum can optionally allow values below zero.

Parameters:
  • deficit (pd.Series) – A pandas Series representing the deficit time series.

  • startdate (pd.Timestamp | pd.Series) – The start date(s) for the cumulative deficit calculation. If a single timestamp is provided, it is applied to all columns. If a Series is provided, it should align with the columns of the grouped DataFrame.

  • enddate (pd.Timestamp | pd.Series) – The end date(s) for the cumulative deficit calculation. Similar to startdate, it can be a single timestamp or a Series aligned with the columns.

  • allow_below_zero (bool, optional) – If True, allows the cumulative sum to include values below zero. Defaults to True.

Returns:

A DataFrame containing the cumulative deficit for each column over the specified time period. The index represents the date range, and the columns correspond to the year.

Return type:

pd.DataFrame

spei.knmi.get_yearly_temp_date(temp: Series, threshold: float) → Series

Get the first date in each year where the cumulative temperature exceeds a given threshold.

Parameters:
  • temp (pd.Series) – A pandas Series representing the temperature time series, indexed by date.

  • threshold (float) – The temperature threshold to identify the first date above it.

Returns:

A pandas Series containing the first date in each year where the cumulative temperature exceeds the threshold. The index corresponds to the years.

Return type:

pd.Series