Package 'NSTempRFA'

Title: Adapts the Regional Frequency Analysis to Air Temperature
Description: Adapts the index-flood technique to extreme air temperature data. The package uses the additive approach proposed in Martins et al. (2022) <doi:10.1590/1678-4499.20220061> and adapt it to climate change conditions through the use of nonstationary parametric distributions.
Authors: Gabriel Constantino Blain [aut, cre] (ORCID: <https://orcid.org/0000-0001-8832-7734>), Graciela R. Sobierajski [aut] (ORCID: <https://orcid.org/0000-0002-7211-9268>), Leticia L. Martins [aut] (ORCID: <https://orcid.org/0000-0002-0299-3005>), Adam H. Sparks [aut] (ORCID: <https://orcid.org/0000-0002-0061-8359>)
Maintainer: Gabriel Constantino Blain <[email protected]>
License: MIT + file LICENSE
Version: 0.2.0.9000
Built: 2026-10-01 13:45:59 UTC
Source: https://github.com/gabrielblain/nstemprfa

Help Index

Discordance measures calculated from the additive approach

Description

This function calculates the Hosking and Wallis' discordance measure (discord) and the robust discordance measure (Neykov et al. 2007) https://doi.org/10.1029/2006WR005322 using the additive approach proposed in Martins et al. (2022) https://doi.org/10.1590/1678-4499.20220061.

Usage

Add_Discord(dataset)

Arguments

dataset

A numeric matrix with extreme air temperature data from multiple sites. The first column must contain the years, and the remaining columns contain temperature data from each site.

Details

The discordance measures identify sites that are potentially discordant within a regional frequency analysis framework for extreme air temperature series.

Value

A data.frame with 8 columns:

Local

Site identifier.

SampleSize

Number of observations for each site.

l_1

First L-moment (mean).

l_2

Second L-moment (L-scale).

t_3

L-skewness ratio.

t_4

L-kurtosis ratio.

t_5

Fifth-order L-moment ratio.

discord

Original discordance statistic indicating potential outlier status.

Examples

Add_Discord(TmaxCPC_SP)

Add_Heterogeneity

Description

Add_Heterogeneity

Usage

Add_Heterogeneity(dataset.add, rho, Ns)

Arguments

dataset.add

A numeric matrix of air temperature data as calculated by Dataset_add().
rho

A single numeric value describing the average inter-site correlation. Must be strictly between -1 and 1.
Ns

Number of simulated groups of series. Default is 100; at least 500 is recommended.

Value

Hosking and Wallis' heterogeneity measure using an additive approach, as proposed in Martins et al. (2022) doi:10.1590/1678-4499.20220061. Returns NA if the regional distribution cannot be fitted or if simulated statistics have zero variance.

Examples

add.data <- Dataset_add(TmaxCPC_SP)
Add_Heterogeneity(dataset.add = add.data$add_data, rho = 0.51, Ns = 500)

Add_RegProb

Description

Add_RegProb

Usage

Add_RegProb(quantiles, regional_pars, site_temp, n.year)

Arguments

quantiles

A numeric vector with no missing data containing extreme air temperatures.
regional_pars

A 6-column, 1-row data.frame or matrix as generated by Reg_par().
site_temp

A non-empty numeric vector or 1-column matrix of site air temperature data.
n.year

A single integer giving the year index for which parameters are calculated. Must be between 1 and length(site_temp).

Value

A numeric matrix of cumulative probabilities (clamped to [0.0001, 0.9999]) associated with the input quantiles from the regional GEV distribution.

Examples

quantiles <- c(37.8, 37.9, 38.0, 38.1, 38.2, 38.5, 39.0)
add.data <- Dataset_add(TmaxCPC_SP)
best.parms <- Best_model(add.data = add.data$add_data)
regional_pars <- Reg_par(best_model = best.parms$atsite.models)
Add_RegProb(
  quantiles     = quantiles,
  regional_pars = regional_pars,
  site_temp     = TmaxCPC_SP$Pixel_1,
  n.year        = 34
)

Regional Quantile Estimation for a Site Using Time-Varying GEV Parameters

Description

Computes quantiles for a given site based on regional GEV parameters and a time-varying location and scale model. Estimated quantiles are adjusted by the site's mean temperature.

Usage

Add_RegQuant(prob, regional_pars, site_temp, n.year)

Arguments

prob

A numeric vector of probabilities strictly between 0 and 1, with no missing values.
regional_pars

A 1-row, 6-column matrix or data.frame containing regional GEV parameters: location intercept, location slope, location slope (quadratic), scale intercept, scale slope, and shape.
site_temp

A numeric vector or 1-column matrix of site air temperature data.
n.year

A single integer indicating the year index for which quantiles are calculated. Must be between 1 and length(site_temp).

Value

A named numeric vector of adjusted regional quantiles for the specified year. Names are of the form "Q90", '"Q95"“, etc.

Examples

prob <- c(0.90, 0.92, 0.93, 0.94, 0.95, 0.97, 0.99)
add.data <- Dataset_add(TmaxCPC_SP)
best.parms <- Best_model(add.data = add.data$add_data)
regional_pars <- Reg_par(best_model = best.parms$atsite.models)
Add_RegQuant(
  prob          = prob,
  regional_pars = regional_pars,
  site_temp     = TmaxCPC_SP$Pixel_1,
  n.year        = 34
)

Time-varying parameters of the best fitted GEV model

Description

This function fits six time-varying GEV models (with different assumptions on non-stationarity in location and/or scale) to each temperature series, computes the AICc of each model, and selects the best one according to the lowest total AICc.

Usage

Best_model(add.data)

Arguments

add.data

A numeric matrix of air temperature data as calculated by Dataset_add().

Details

Model fitting is performed via ismev::gev.fit(), using a log link for the scale parameter (which keeps the scale positive at all times). Six models are considered:

  1. Stationary (constant location and scale).

  2. Linear time-varying location only.

  3. Log-linear time-varying scale only.

  4. Linear time-varying location and log-linear time-varying scale.

  5. Quadratic time-varying location only, GEV(2,0,0).

  6. Quadratic time-varying location and log-linear time-varying scale, GEV(2,1,0).

To reduce the collinearity between t and t^2, the models are fitted using a centred and standardised time variable. The estimates are then converted back to the original time index (t = 1, 2, ..., size), so the reported parameters refer to t, not to the standardised variable. For each site the function tries up to five optimisation methods (Nelder-Mead, BFGS, CG, L-BFGS-B, SANN) and uses the first that converges. Model selection is based on the sum of site-level AICc values.

Value

A list with:

best

Index (1–6) of the model with the lowest total AICc across all sites.

atsite.models

Data frame containing the estimated parameters (mu0, mu1, mu2, sigma0, sigma1, shape) and sample size for each site. The location is mu(t) = mu0 + mu1 * t + mu2 * t^2 and the scale is sigma(t) = sigma0 * exp(sigma1 * t), where t = 1, 2, ..., size. Thus sigma0 is the scale at t = 0 and sigma1 is the log rate of change of the scale. Parameters that are not part of the selected model are set to zero.

Examples

add.data <- Dataset_add(TmaxCPC_SP)
best.parms <- Best_model(add.data = add.data$add_data)

dataset_add

Description

dataset_add

Usage

Dataset_add(dataset)

Arguments

dataset

A numeric matrix with extreme air temperature data from multiple sites. The first column must contain the years, and the remaining columns contain temperature data from each site.

Value

A list object with the following elements:

add_data

A matrix of centered temperature values for each site.

reg_mean

Mean temperature values for each site.

Examples

Dataset_add(TmaxCPC_SP)

Time-varying parameters of a given GEV model

Description

Time-varying parameters of a given GEV model

Usage

Fit_model(temperatures, model)

Arguments

temperatures

A vector or single-column matrix of air temperature data, either original or centered by subtracting the sample mean.
model

A single integer between 1 and 6 defining the GEV model (see Best_model() for the description of each model). May be provided by Best_model().

Details

The function attempts to fit the model using ismev::gev.fit() with a log link for the scale parameter (which keeps the scale positive at all times) and the following optimisers in sequence: Nelder-Mead, BFGS, CG, L-BFGS-B, SANN. The first optimiser that converges is used; if all fail, NAs are returned for that site. Internally, the series is centred on its mean and a standardised time variable is used to reduce the collinearity between t and t^2. The estimates are converted back to the original units and to the original time index, so mu0 is expressed in the same units as temperatures.

Value

A data.frame containing the estimated parameters (mu0, mu1, mu2, sigma0, sigma1, shape, size). The location is mu(t) = mu0 + mu1 * t + mu2 * t^2 and the scale is sigma(t) = sigma0 * exp(sigma1 * t), where t = 1, 2, ..., size. Thus sigma0 is the scale at t = 0 and sigma1 is the log rate of change of the scale (sigma1 = 0 means a constant scale). Parameters that are not part of the selected model are set to zero. If fitting fails for a site, NAs are returned for that site.

Examples

temperatures <- TmaxCPC_SP$Pixel_1
model <- 4
Fit_model(temperatures, model)

# Quadratic time-varying location and log-linear time-varying scale
Fit_model(temperatures, model = 6)

Geographical coordinates of the TmaxCPC_SP series

Description

Geographical coordinates of the TmaxCPC_SP series

Usage

lonlat_Tmax

Format

lonlat_Tmax

A data.frame with 2 columns and 10 rows.

lon

Longitude in decinal degrees

lat

Latitude in decinal degrees

Source

https://psl.noaa.gov/

Estimate the parameters of the regional distribution

Description

Estimate the parameters of the regional distribution

Usage

Reg_par(best_model)

Arguments

best_model

A 7-column data.frame as generated by Best_model().

  • Columns 1–6: mu0, mu1, mu2, sigma0, sigma1, shape.

  • Column 7: size (sample size per site, used as weight).

Value

A one-row data.frame with the size-weighted regional parameters of a time-varying generalized extreme value distribution.

Examples

add.data <- Dataset_add(TmaxCPC_SP)
best.parms <- Best_model(add.data = add.data$add_data)
Reg_par(best_model = best.parms$atsite.models)

Confidence intervals for regional GEV parameters

Description

Confidence intervals for regional GEV parameters

Usage

Reg_parCI(add_data, model, reg_par, n.boots = 999, progress = NULL)

Arguments

add_data

A numeric matrix of air temperature data as calculated by Dataset_add().
model

A single integer number from 1 to 4 defining the GEV model. May be provided by Best_model().
reg_par

A 6-column and 1-row data.frame or matrix as generated by Reg_par().

  • 1st column is the mu0 parameter,

  • 2nd is the mu1 parameter,

  • 3rd is the mu2 parameter,

  • 4th is the sigma0 parameter,

  • 5th is the sigma1 parameter,

  • 6th is the shape parameter.

n.boots

A single number describing the number of bootstrap replicates. Whenever possible, n.boots should be set to 999 (default), as suggested by Burn (2003) <10.1623/hysj.48.1.25.43485> and O'Brien and Burn (2014) <10.1016/j.jhydrol.2014.09.041>.
progress

Logical scalar controlling whether a progress bar is displayed. TRUE forces the bar on, FALSE forces it off, and NULL (default) defers to getOption("NSTempRFA.progress"), which itself falls back to interactive(). Set options(NSTempRFA.progress = FALSE) to suppress the bar globally.

Value

A matrix containing the 95% confidence intervals (lower and upper bounds) of the time-varying parameter estimates. The spatial dependence between sites is preserved.

Examples

add.data <- Dataset_add(TmaxCPC_SP)
best.parms <- Best_model(add.data = add.data$add_data)
regional.parms <- Reg_par(best_model = best.parms$atsite.models)

Reg_parCI(
  add_data  = add.data$add_data,
  model     = best.parms$best,
  reg_par   = regional.parms,
  n.boots   = 100
)

Confidence intervals for site-specific GEV parameters

Description

Confidence intervals for site-specific GEV parameters

Usage

Site_parCI(atsite_temp, model, site_par, n.boots = 999, progress = NULL)

Arguments

atsite_temp

A numeric vector or single-column matrix of air temperature data.
model

A single integer from 1 to 4 defining the GEV model.
site_par

A 1-row, 5-column data.frame or matrix generated by Fit_model().
n.boots

Number of bootstrap replicates. Values smaller than 100 are not allowed. Defaults to 999.
progress

Logical scalar controlling whether a progress bar is displayed. TRUE forces the bar on, FALSE forces it off, and NULL (default) defers to getOption("NSTempRFA.progress"), which itself falls back to interactive(). Set options(NSTempRFA.progress = FALSE) to suppress the bar globally.

Value

A matrix containing the lower and upper 95% confidence limits of the estimated parameters.

Examples

temperatures <- TmaxCPC_SP$Pixel_1
model <- 5
site_par <- Fit_model(temperatures, model)

Site_parCI(
  atsite_temp = temperatures,
  model       = model,
  site_par    = site_par[1, 1:6],
  n.boots     = 100
)

Extreme air temperature data

Description

Daily extremes for air temperature data sampled from the block maxima approach. A block corresponds to one year. The data belongs to The Climate Prediction Center - NOAA. location of Ribeirao Preto, State of Sao Paulo in Brazil.

Usage

TmaxCPC_SP

Format

TmaxCPC_SP

A data.frame with 11 columns and 34 rows.

Year

Year

Pixel_1 to Pixel_10

daily extremes for air temperature

Source

https://psl.noaa.gov/