Package {NSTempRFA}

Title: Adapts the Regional Frequency Analysis to Air Temperature
Version: 0.2.0
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.
License: MIT + file LICENSE
URL: https://github.com/gabrielblain/NSTempRFA
BugReports: https://github.com/gabrielblain/NSTempRFA/issues
Depends: R (≥ 3.5)
Imports: extRemes, ismev, lmom, lmomRFA, MASS, Matrix, rrcov, spsUtil, stats, utils
Suggests: knitr, rmarkdown, spelling, testthat (≥ 3.0.0)
VignetteBuilder: knitr
Config/roxygen2/version: 8.0.0
Config/testthat/edition: 3
Config/testthat/parallel: true
Encoding: UTF-8
Language: en-US
LazyData: true
RoxygenNote: 7.3.3
NeedsCompilation: no
Packaged: 2026-07-28 11:05:50 UTC; gabrielblain
Author: Gabriel Constantino Blain ORCID iD [aut, cre], Graciela R. Sobierajski ORCID iD [aut], Leticia L. Martins ORCID iD [aut], Adam H. Sparks ORCID iD [aut]
Maintainer: Gabriel Constantino Blain <gabriel.blain@sp.gov.br>
Repository: CRAN
Date/Publication: 2026-08-06 12:50:06 UTC

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 5-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, 5-column matrix or data.frame containing regional GEV parameters: location intercept, location slope, 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 four 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(). Four nested models are considered:

  1. Stationary (constant location and scale).

  2. Time-varying location only.

  3. Time-varying scale only.

  4. Time-varying location and scale.

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–4) of the model with the lowest total AICc across all sites.

atsite.models

Data frame containing the estimated parameters (mu0, mu1, sigma0, sigma1, shape) and sample size for each site.

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 4 defining the GEV model. May be provided by Best_model().

Details

The function attempts to fit the model using ismev::gev.fit() with 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.

Value

A data.frame containing the estimated parameters (mu0, mu1, sigma0, sigma1, shape, size). If fitting fails for a site, NAs are returned for that site.

Examples

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

Estimate the parameters of the regional distribution

Description

Estimate the parameters of the regional distribution

Usage

Reg_par(best_model)

Arguments

best_model

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

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

  • Column 6: 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 5-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 sigma0 parameter,

  • 4th is the sigma1 parameter,

  • 5th 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 <- 2
site_par <- Fit_model(temperatures, model)

Site_parCI(
  atsite_temp = temperatures,
  model       = model,
  site_par    = site_par[1, 1:5],
  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/

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/