Using the rIACI Package for the Iberian Actuarial Climate Index Calculations

Nan Zhou

r Sys.Date()

Introduction

In our paper (Zhou et al. 2023), we follow the work of North American actuaries, [Actuaries Climate Index (ACI)], and have created an index to show how climate changes in the Iberian Peninsula, the Iberian Actuarial Climate Index. The rIACI package is designed for climatologists and researchers working with climate data, particularly those interested in calculating climate indices such as the Iberian Actuarial Climate Index (IACI). This package provides tools to:

This vignette will guide you through the steps to use the rIACI package effectively.

Accessing Example Data Files

The package includes example data files stored in the inst/extdata folder. To ensure that these files can be correctly accessed regardless of where the package is installed, you should use the system.file() function. For example:

# Get the full path of an example NetCDF file from inst/extdata/testdata
example_nc <- system.file("extdata", "testdata", "1960_1.nc", package = "rIACI")
cat("Example NetCDF file path:", example_nc, "\n")

# Get the full path of an example CSV file from inst/extdata/testcsv
example_csv <- system.file("extdata", "testcsv", "36.2_-5.6.csv", package = "rIACI")
cat("Example CSV file path:", example_csv, "\n")

Prerequisites

Before using the rIACI package, ensure you have the following:

Installation

You can install the rIACI package from GitHub using the devtools package:

# Install devtools if you haven't already
install.packages("devtools")

# Install rIACI from GitHub
devtools::install_github("https://github.com/Nan-Z-byte/rIACI")

Workflow Overview

The general workflow using rIACI involves the following steps:

  1. Download ERA5-Land data using the download_data() function.

  2. Process the downloaded data with process_data(), export_data_to_csv(), and csv_to_netcdf().

  3. Create a climate input object using climate_input().

  4. Calculate various climate indices such as TX90p, TX10p, TN90p, TN10p, Rx5day, CDD, W90p, and Sea.

  5. Integrate sea level data using sea_input().

  6. Generate the IACI output with iaci_output() or output_all().

Downloading ERA5-Land Data

The download_data() function allows you to download ERA5-Land data from the ECMWF Climate Data Store for specified variables, years, months, and geographical areas..

download_data(start_year, end_year,
              start_month = 1,
              end_month = 12,
              variables = c("10m_u_component_of_wind",
                            "10m_v_component_of_wind",
                            "2m_temperature",
                            "total_precipitation"),
              dataset = "reanalysis-era5-land",
              area = c(North, West, South, East),
              output_dir = "cds_data",
              user_id, user_key,
              max_retries = 3,
              retry_delay = 5,
              timeout = 7200)

Parameters

Example

# Set your ECMWF user ID and key
user_id <- "your_user_id"
user_key <- "your_api_key"

# Define the geographical area (North, West, South, East)
# Example: Iberian Peninsula roughly bounded by 44N, -10W, 35N, 5E
area_iberia <- c(44, -10, 35, 5)

# Download data form the year 1960 to 2023
download_data(
  start_year = 1960,
  end_year = 2023,
  area = area_iberia,
  user_id = user_id,
  user_key = user_key
)

Processing Climate Data

After downloading the data, you may need to process it before analysis. The package provides functions to handle NetCDF files and convert them to CSV format for easier manipulation.

Process Data Function

process_data()

Processes NetCDF files in the input directory and saves merged and processed data to the output directory.

Usage

process_data(input_dir, output_dir)

Parameters

  • input_dir (Character): Directory containing input NetCDF files.

  • output_dir (Character): Directory to save output files.

Example

input_directory <- "cds_data"
output_directory <- "processed_data"

process_data(input_dir = input_directory, output_dir = output_directory)

Export Data to CSV Function

export_data_to_csv()

Exports data from a NetCDF file to CSV files, one for each latitude and longitude point.

Usage

export_data_to_csv(nc_file, output_dir)

Parameters

  • nc_file (Character): Path to the NetCDF file.

  • output_dir (Character): Output directory to save CSV files.

Example

netcdf_file <- "processed_data/2020_01.nc"
csv_output_directory <- "csv_output"

export_data_to_csv(nc_file = netcdf_file, output_dir = csv_output_directory)

CSV to NetCDF Function

csv_to_netcdf()

Merges CSV files in a specified directory into a single NetCDF file.

Usage

csv_to_netcdf(csv_dir, output_file)

Parameters

  • csv_dir (Character): Directory containing CSV files. Filenames should follow the 'lat_lon.csv' format.

  • output_file (Character): Path to the output NetCDF file.

Example

csv_directory <- "csv_output"
output_netcdf_file <- "final_data/merged_data.nc"

csv_to_netcdf(csv_dir = csv_directory, output_file = output_netcdf_file)

Creating a Climate Input Object

Before calculating climate indices, create a climate input object that organizes your climate data.

climate_input()

Creates a climate input object containing processed climate data and relevant statistics.

Usage

climate_input(tmax = NULL, tmin = NULL, prec = NULL, wind = NULL,
              dates = NULL,base.range = c(1961, 1990), n = 5,
              quantiles = NULL,
              temp.qtiles = c(0.10, 0.90), wind.qtile = 0.90,
              max.missing.days = c(annual = 15, monthly = 3),
              min.base.data.fraction_present = 0.1)

Parameters

  • tmax (Numeric vector): Maximum temperature data.

  • tmin (Numeric vector): Minimum temperature data.

  • prec (Numeric vector): Precipitation data.

  • wind (Numeric vector): Wind speed data.

  • dates (Date vector): Dates corresponding to the data.

  • base.range (Numeric vector, default c(1961, 1990)): Base range years for calculations.

  • n (Integer, default 5): Window size for running averages.

  • quantiles (List, optional): Pre-calculated quantiles.

  • temp.qtiles (Numeric vector, default c(0.10, 0.90)): Temperature quantiles to calculate.

  • wind.qtile (Numeric, default 0.90): Wind quantile to calculate.

  • max.missing.days (Named numeric vector, default c(annual = 15, monthly = 3)): Maximum allowed missing days.

  • min.base.data.fraction_present (Numeric, default 0.1): Minimum fraction of data required in base range.

Example

# Assume you have a CSV file with climate data
climate_data <- read.csv("processed_data/climate_data.csv")

# Create climate input object
ci <- climate_input(
  tmax = climate_data$TMAX,
  tmin = climate_data$TMIN,
  prec = climate_data$PRCP,
  wind = climate_data$WIND,
  dates = as.Date(climate_data$DATE, format = "%Y-%m-%d")
)

Calculating Climate Indices

The rIACI package provides functions to calculate various climate indices, both standardized and non-standardized.

Available Indices

Example: Calculating TX90p

# Calculate monthly TX90p index
tx90p_values <- tx90p(ci, freq = "monthly")

# View the results
head(tx90p_values)

Example: Calculating standardized T90p

# Calculate standardized T90p index on a monthly basis
t90p_std_values <- t90p_std(ci, freq = "monthly")

# View the results
head(tx90p_std_values)

Example: Calculating monthly TX90p

# Calculate seasonal TN10p index
tx90p_seasonal <- monthly_to_seasonal(tx90p_values)

# View the results
head(tx90p_seasonal)

Integrating Sea Level Data

To incorporate sea level data into the IACI, use the sea_input() function.

sea_input()

Creates a data frame for sea level data input.

Usage

sea_input(Date = levels(ci$date_factors$monthly), Value = NA)

Parameters

  • Date (Character vector): Dates in “YYYY-MM” format.

  • Value (Numeric vector, default NA): Sea level values.

Example

# Create sea level data
sea_dates <- c("2020-01", "2020-02", "2020-03")
sea_values <- c(1.2, 1.3, 1.4)

sea_data <- sea_input(Date = sea_dates, Value = sea_values)

Generating IACI Output

The final step is to compute the IACI by integrating all standardized indices.

iaci_output()

Integrates various standardized indices to compute the IACI.

Usage

iaci_output(ci, si, freq = c("monthly", "seasonal"))

Parameters

  • ci (List): Climate input object created by climate_input().

  • si (Data frame): Sea level input data created by sea_input().

  • freq (Character, default c("monthly", "seasonal")): Frequency of calculation.

Example

# Generate IACI
iaci <- iaci_output(ci, sea_data, freq = "monthly")

# View the IACI
head(iaci)

output_all()

Processes all CSV files in the input directory and outputs the IACI results to the output directory.

Usage

output_all(si, input_dir, output_dir, freq = c("monthly",
                                               "seasonal"), 
           base.range = c(1961, 1990), time.span = c(1961, 2022))

Parameters

  • si (Data frame): Sea level input data.

  • input_dir (Character): Directory containing input CSV files.

  • output_dir (Character): Directory to save output files.

  • freq (Character, default c("monthly", "seasonal")): Frequency of calculation.

  • base.range (Numeric vector, default c(1961, 1990)): Base range years.

  • time.span (Numeric vector, default c(1961, 2022)): Time span for output data.

Example

# Define input and output directories
input_dir <- "csv_output"
output_dir <- "iaci_results"

# Run the output_all function with monthly frequency
output_all(
  si = sea_std_values,
  input_dir = input_dir,
  output_dir = output_dir,
  freq = "monthly",
  base.range = c(1961, 1990),
  time.span = c(1961, 2022)
)

Complete Workflow Example

Below is a comprehensive example demonstrating the complete workflow from downloading data to generating the IACI.

# Load the package
library(rIACI)

# Step 1: Download ERA5-Land data
user_id <- "your_user_id"
user_key <- "your_api_key"
area_iberia <- c(44, -10, 35, 5) # Approximate bounds of Iberian Peninsula

download_data(
  start_year = 2020,
  end_year = 2020,
  variables = c("2m_temperature", "total_precipitation", 
                "10m_u_component_of_wind", "10m_v_component_of_wind"),
  area = area_iberia,
  user_id = user_id,
  user_key = user_key
)

# Step 2: Process downloaded data
input_directory <- "cds_data"
output_directory <- "processed_data"

process_data(input_dir = input_directory, output_dir = output_directory)

# Step 3: Export processed NetCDF to CSV
netcdf_file <- "processed_data/2020_01.nc"
csv_output_directory <- "csv_output"

export_data_to_csv(nc_file = netcdf_file, output_dir = csv_output_directory)

# Step 4: Create climate input object
climate_data <- read.csv("processed_data/climate_data.csv")
ci <- climate_input(
  tmax = climate_data$TMAX,
  tmin = climate_data$TMIN,
  prec = climate_data$PRCP,
  wind = climate_data$WIND,
  dates = as.Date(climate_data$DATE, format = "%Y-%m-%d")
)

# Step 5: Integrate sea level data
sea_dates <- c("2020-01", "2020-02", "2020-03")
sea_values <- c(1.2, 1.3, 1.4)
sea_data <- sea_input(Date = sea_dates, Value = sea_values)
sea_std_values <- sea_std(sea_data, freq = "monthly")

# Step 6: Generate IACI
iaci <- iaci_output(ci, sea_std_values, freq = "monthly")
print(head(iaci))

# Step 7: Output all results
output_all(
  si = sea_std_values,
  input_dir = csv_output_directory,
  output_dir = "iaci_results",
  freq = "monthly",
  base.range = c(1961, 1990),
  time.span = c(1961, 2022)
)

# Step 8: Merge CSVs into NetCDF (optional)
merged_netcdf <- "iaci.nc"
csv_to_netcdf(csv_dir = iaci_results_directory, output_file = merged_netcdf)

Additional Resources

For further assistance, please refer to the package documentation or contact the package maintainer.

Conclusion

The rIACI package offers a comprehensive suite of tools for climate data analysis, enabling users to compute the Iberian Actuarial Climate Index effectively. By following this guide, you can seamlessly download, process, and analyze climate data to gain valuable insights into climate variability and extremes in the Iberian Peninsula.

Acknowledgements

This package benefited fundamentally from the collective expertise and encouragement of Jose Luis Vilar-Zanon, Jose Garrido, and Antonio Jose Heras Martinez.

Bibliography

Zhou, Nan, José Luis Vilar-Zanón, José Garrido, and Antonio-José Heras Martínez. 2023. “On the Definition of an Actuarial Climate Index for the Iberian Peninsula.” Anales Del Instituto de Actuarios Españoles, no. 29: 37–59. https://doi.org/10.26360/2023_3.

mirror server hosted at Truenetwork, Russian Federation.