Package 'CMIP6VisR'

Title: Visualization and Analysis of Coupled Model Intercomparison Project, Phase-6 (CMIP6) Hydroclimatic Data
Description: Data manipulation for Coupled Model Intercomparison Project, Phase-6 (CMIP6) hydroclimatic data. The files are archived in the Federated Research Data Repository (FRDR) (Rajulapati et al, 2024, <doi:10.20383/103.0829>). The data set is described in Abdelmoaty et al. (2025, <doi:10.1038/s41597-025-04396-z>).
Authors: Simon Michael Papalexiou [aut], Heba Abdelmoaty [aut], Konstantinos Andreadis [aut], Kevin Shook [ctb, cre]
Maintainer: Kevin Shook <[email protected]>
License: GPL-3
Version: 1.1.0
Built: 2026-06-01 11:38:09 UTC
Source: https://github.com/tychelab/cmip6visr

Help Index

Visualization and Analysis of CMIP6 Hydroclimatic Data

Description

Provides data manipulation, analyses and visualization for Coupled Model Intercomparison Project, Phase-6 (CMIP6) hydroclimatic data. The files are archived in the Federated Research Data Repository (FRDR) (Rajulapati et al., 2024)

Author(s)

Maintainer: Kevin Shook [email protected] [contributor]

Authors:

  • Simon Michael Papalexiou

  • Heba Abdelmoaty

  • Konstantinos Andreadis

References

Rajulapati, C., Abdelmoaty, H., Nerantzaki, S., Papalexiou, S. (2024). High-resolution future temperature and precipitation dataset for Canada, 2015 - 2100. Federated Research Data Repository. https://doi.org/10.20383/103.0829

See Also

Useful links:

Get zones and areas that clip rasters from a given basin polygon

Description

Takes the SpatRaster that represents zones and areas and clips them from polygon basin.

Usage

cv_clip_basin(za_rast, basin)

Arguments

za_rast

SpatRaster of the zones and areas.
basin

SpatVector of the basin to clip to.

Value

Returns a list with 3 elements:

  • raster (rasters of cell areas for each zone).

  • area (total area of each zone in the basin).

  • zone (zone numbers).

Author(s)

Kostas Andreadis

See Also

cv_extract_mean_basin_daily cv_extract_all_basin_daily

Examples

## Not run: 
library(terra)
az_raster <- cv_zone_area_raster()
fpath <- system.file("extdata", "07BF001.shp", package = "CMIP6VisR")
basin_vector <- vect(fpath)
basin_areas <- cv_clip_basin(az_raster, basin_vector)

## End(Not run)

Extracts daily precipitation or temperatures for all locations in a basin

Description

Extracts the daily precipitation or temperature values from CMIP6 NetCDF files for all locations in a specified basin.

The CMIP6 data are arranged by zone in 9 files. As a given basin may lie over more than one zone, it may necessary to read in data from more than one NetCDF file when computing the basin mean precipitation.

Usage

cv_extract_all_basin_daily(
  netcdf_directory = ".",
  scenario = "pr_day_ACCESS-CM2_ssp126_r2i1p1f1_gn_20150101-21001231_cannc_SPQM_",
  basin_zone_area = NULL,
  temp_file = TRUE,
  output_file_name = NULL
)

Arguments

netcdf_directory

Required. Directory containing NetCDF files.
scenario

Required. Full name of scenario to be used. This is the file name omitting the zone number. The first character of the scenario name is used to determine the name of the variable returned.
basin_zone_area

Required. A list object returned by cv_clip_basin() which contains the zone numbers to be used, the basin area within each zone, and rasters of each zone containing the area of each element.
temp_file

If TRUE (the default) then temporary files will be used when extracting the values from the NetCDF files. This option is slower than keeping all the values in memory (which is what occurs if temp_file = TRUE), but allows the function to work with very large basins, which may require more memory than is available.
output_file_name

If NULL, then the precipitation values will not be written to a file. If a file name is specified, then the values will be written to a file. Note that if the filename exists, then the values will be overwritten.

Value

Returns a SpatRaster object of the daily precipitation for all locations in the specified basin. Optionally writes the precipitation values to a specified NetCDF file.

Author(s)

Kevin Shook

See Also

cv_clip_basin cv_extract_mean_basin_daily

Examples

# This function is marked to not be tested as it requires local copies of the CMIP6 data files
# which are many GB in size
library(terra)
az_raster <- cv_zone_area_raster()
fpath <- system.file("extdata", "07BF001.shp", package = "CMIP6VisR")
basin_vector <- vect(fpath)
basin_areas <- cv_clip_basin(az_raster, basin_vector)
netcdf_directory <- "."
all_precip <- cv_extract_all_basin_daily(netcdf_directory = netcdf_directory,
                               basin_zone_area = basin_areas,
                               temp_file = FALSE)

Calculates basin-averaged daily precipitation or air temperature

Description

Extracts daily precipitation or temperature values from CMIP6 NetCDF files, and calculates the mean for a given basin for each time interval. The original files are in longitude-latitude projection, so the areas of the cells varies. The cell areas are used to weight the values when computing the basin mean.

The CMIP6 data are arranged by zone in 9 files. As a given basin may lie over more than one zone, it may necessary to read in data from more than one NetCDF file when computing the basin mean daily values.

Usage

cv_extract_mean_basin_daily(
  netcdf_directory = ".",
  scenario = "pr_day_ACCESS-CM2_ssp126_r2i1p1f1_gn_20150101-21001231_cannc_SPQM_",
  basin_zone_area = NULL,
  temp_file = TRUE
)

Arguments

netcdf_directory

Required. Directory containing NetCDF files.
scenario

Required. Full name of scenario to be used. This is the file name omitting the zone number. The first character of the scenario name is used to determine the name of the variable returned.
basin_zone_area

Required. A list object returned by cv_clip_basin() which contains the zone numbers to be used, the basin area within each zone, and rasters of each zone containing the area of each element.
temp_file

If TRUE (the default) then temporary files will be used when extracting the values from the NetCDF files. This option is slower than keeping all the values in memory (which is what occurs if temp_file = TRUE), but allows the function to work with very large basins, which may require more memory than is available.

Value

Returns a data frame with 2 columns: date and either precipitation or temperature, depending on the scenario name. The date is a standard R date over the interval 2015-01-01 to 2100-12-31, and the precipitation or temperature is the basin mean value for each date.

Author(s)

Kevin Shook

See Also

cv_clip_basin cv_extract_all_basin_daily

Examples

# This function is marked to not be tested as it requires local copies of the CMIP6 data files
# which are many GB in size
library(terra)
az_raster <- cv_zone_area_raster()
fpath <- system.file("extdata", "07BF001.shp", package = "CMIP6VisR")
basin_vector <- vect(fpath)
basin_areas <- cv_clip_basin(az_raster, basin_vector)
netcdf_directory <- "."
values <- cv_extract_mean_basin_daily(netcdf_directory = netcdf_directory,
                               basin_zone_area = basin_areas,
                               temp_file = FALSE)

Extracts daily precipitation or temperature for a specific location

Description

Extracts a daily time series from a single CMIP6 raster location, which can be used to compare the CMIP6 values against station values. The location of the data in the CMIP6 data (its zone and raster location) is found using cv_find_point.

Usage

cv_extract_point_daily(
  variable_file_name = NULL,
  grid_lon = NULL,
  grid_lat = NULL
)

Arguments

variable_file_name

Required. String containing the name of the NetCDF file with the CMIP6 daily precipitation or temperature, including the file path.
grid_lon

Required. Longitude of the grid cell containing the location, as returned by cv_find_point.
grid_lat

Required. Latitude of grid cell containing the location, as returned by cv_find_point.

Value

Returns a data frame with 2 columns: date and either precipitation or temperature, depending on the file name. The date is a standard R date over the interval 2015-01-01 to 2100-12-31, and the precipitation or temperature is the value at the specified grid location. The returned time series can be plotted using cv_plot_TS, cv_plot_prob, and cv_plot_season.

Author(s)

Kevin Shook

See Also

cv_find_point cv_extract_all_basin_daily cv_extract_mean_basin_daily

Examples

## Not run: 
point_long <- -110.456
point_lat <- 52.19
point_loc <- cv_find_point(point_long, point_lat)
point_loc
precip_file <- "pr_day_ACCESS-CM2_ssp126_r2i1p1f1_gn_20150101-21001231_cannc_SPQM_07.nc"
grid_lon <- point_loc[1]
grid_lat <- point_loc[2]
point_precip <- cv_extract_point_daily(precip_file, grid_lon, grid_lat)

## End(Not run)

Locates a specific point in the CMIP6 data rasters

Description

Finds the closest CMIP6 raster location (zone and raster longitude and latitude) to a point specified by its longitude and latitude. The distances from the raster centres are found using functions from geosphere.

Usage

cv_find_point(longitude, latitude, fast = TRUE)

Arguments

longitude

Required. Longitude (decimal degrees) of the point
latitude

Required. Latitude (decimal degrees) of the point
fast

Optional. If TRUE (the default), the faster, but slightly less accurate distVincentySphere method will be used to determine the distance between the coordinates of the specified point and that of all the CMIP6 raster points. If FALSE, then the more accurate distVincentyEllipsoid method is used. The difference between the distances of the two methods is very small, typically a few metres.

Value

Returns a vector containing the raster cell coordinates (grid_lon, grid_lat), zone number (zone), cell area (area) in km2^2 and the distance (distance) between the between the point and cell centre (m).

Author(s)

Kevin Shook

Examples

{
point_long <- -110.456
point_lat <- 52.195
point_loc <- cv_find_point(point_long, point_lat)
point_loc
}

Plot probability of exceedance for precipitation

Description

Plots the exceedance probabilities of non-zero values in a precipitation time series as returned by cv_extract_mean_basin_daily(), vs the precipitation value. Uses a logarithmic scale for the y-axis.

Usage

cv_plot_prob(data)

Arguments

data

A data frame with two columns: date (date or datetime) and precipitation (numeric) as returned by cv_mean_basin_daily().

Value

A ggplot object displaying the probability of exceedance of nonzero precipitation. The returned plots look best when saved at the size 16.5 x 12 cm. You can easily change the font sizes using theme().

See Also

cv_extract_mean_basin_daily cv_plot_TS cv_plot_season

Examples

cv_plot_prob(eg_TS)

Plot seasonal precipitation distribution

Description

Creates seasonal plots of a precipitation time series, as returned by cv_basin_daily_precip(). Assigns seasons based on the month, computes the proportion of zero precipitation values (P0) and seasonal means for nonzero precipitation, and generates a violin plot showing the seasonal distribution of precipitation.

Usage

cv_plot_season(data)

Arguments

data

A data frame with two columns: date (date or datetime) and precipitation (numeric) as returned by cv_extract_mean_basin_daily().

Value

A ggplot object displaying the seasonal distribution of nonzero precipitation, with mean values and P0 labelled. The returned plots look best when saved at the size 16.5 x 14 cm. You can easily change the font sizes using theme().

See Also

cv_extract_mean_basin_daily cv_plot_TS cv_plot_prob

Examples

cv_plot_season(eg_TS)

Plot precipitation time series

Description

Creates a time series plot from a data frame of precipitation data as returned by cv_extract_mean_basin_daily(). Basic statistics (mean, standard deviation, and proportion of zero values), are added to the title of the plot.

Usage

cv_plot_TS(data)

Arguments

data

A data frame with two columns: date (date or datetime) and precipitation (numeric) as returned by cv_mean_basin_daily().

Value

A ggplot object displaying the precipitation time series with summary statistics in the title. The returned plots look best when saved at the size 16.5 x 6 cm You can easily change the font sizes using theme().

See Also

cv_extract_mean_basin_daily cv_plot_prob cv_plot_season

Examples

cv_plot_TS(eg_TS)

Gets zones and areas for all grid locations

Description

Uses the data frame zone_grid_df. Returns a raster containing two layers, the zone (1-9) and the area (km^2^) for each grid location in the CMIP6 files. The raster raster returned has 415 rows (latitudes in 0.1 degrees) and 883 columns (longitudes in 0.1 degrees). The zone number is used to determine the file(s) to read in for computing the basin mean precipitation statistics for a given Canadian hydrometric basin. The

Usage

cv_zone_area_raster()

Value

Returns a terra SpatRaster object (415 rows x 883 columns x 2 layers) of all Canadian grid locations.

Author(s)

Heba Abdelmoaty Kevin Shook

Examples

zone_area_grid <- cv_zone_area_raster()
library(terra)
plot(zone_area_grid)

eg_TS

Description

A dataframe containing daily precipitation time series for a basin.

Usage

eg_TS

Format

A dataframe with 31,411 rows and 2 columns.

Details

This timeseries represents a weighted average daily precipitation time series over the basin given in the package. It comes from one simulation of the CMIP6 model ACCESS-CM2 under the SSP1-2.6 scenario.

Variables:

date

Date of the observation (YYYY-MM-DD format)

precipitation

Daily precipitation amount (mm)

Source

CMIP6 simulation: "_ACCESS-CM2_ssp126_r2i1p1f1_gn_20150101-21001231"

zone_grid_df

Description

A dataframe of zone values and areas for all CMIP6 grid cells

Usage

zone_grid_df

Format

A dateframe with 169584 rows and 4 columns.

Details

Variables:

long

Longitude

lat

Latitude

zone

Zone (0-9)

area

Grid cell area km2^2

Source

https://doi.org/10.20383/103.0829