rep_overlay: Overlay ClimaRep classifications

In ClimaRep: Estimating Climate Representativeness

Overlay ClimaRep classifications

Description

Combines multiple single-layer rasters (tif), outputs from ClimaRep::mh_rep() or ClimaRep::mh_rep_ch() for different input polygons, into a multi-layered SpatRaster.

This function handles inputs from both ClimaRep::mh_rep() (which primarily contains Representative cells) and ClimaRep::mh_rep_ch() (which includes Retained, Lost, and Novel cells). The output layers consistently represent counts of each input.

Usage

rep_overlay(folder_path, output_dir = file.path(tempdir(), "ClimaRep_overlay"))

Arguments

folder_path	character. The path to the directory containing the classification rasters (.tif) generated by ClimaRep::mh_rep() or ClimaRep::mh_rep_ch(). These rasters should primarily contain the categories: 1 (Retained/Representative), 2 (Lost), and 3 (Novel). Category 0 (Non-representative) will be ignored for the RGB output.
output_dir	character. Path to the directory where the output file will be saved.

Details

This function streamlines the aggregation of ClimaRep classifications. It is designed to work with outputs from both ClimaRep::mh_rep() and ClimaRep::mh_rep_ch.

For each of the three key categories (Lost, Retained/representative, Novel), the function:

1. Identifies and reads all .tif files within the folder_path.

2. For each input raster, it creates a binary layer: 1 if the cell's value matches the target category (e.g., 2 for 'Lost'), and 0 otherwise.

3. Sums these binary layers to generate a cumulative count for that specific category at each grid cell.

The three resulting count layers (Lost, Retained, Novel) are then consistently stacked in the following order:

• First layer (Red): Cumulative count of Lost.

• Second layer (Green): Cumulative count of Retained.

• Third layer (Blue): Cumulative count of Novel.

This fixed order ensures that the output SpatRaster is immediately ready for direct RGB visualization using terra::plotRGB(), where the color mixtures will intuitively reflect the spatial agreement of these change types.

The output SpatRaster contains raw counts. While terra::plotRGB() often handles stretching for visualization, users might normalize these counts manually (e.g., to 0-number of polygons) for finer visual contrast.

A new subfolder named ⁠overlay/⁠ will be created within the folder_path. The resulting three-layered RGB will be saved as ClimaRep_overlay.tif inside this new ⁠overlay/⁠ subfolder.

Value

Writes the following outputs within the directory specified by output_dir: When ClimaRep::mh_rep() results are used, the output layers consistently represent counts for Representative categories across all input rasters. When ClimaRep::mh_rep_ch() results are used, the output layers consistently represent counts for Lost (Red), Retained (Green), and Novel (Blue) categories across all input rasters. Designed for direct RGB plotting.

• A multi-layered SpatRaster (ClimaRep_overlay.tif) for RGB visualization.

• Individual .tif files for each band (Lost, Retained, Novel) in ⁠Individual_Bands/⁠ subdirectory.

• ⁠Additional note⁠: The ClimaRep::mh_rep() function analyzes a single period. When its output is used, representative cells are all categorized as Retained (value 1), while other categories (Lost and Novel) have a value of zero.

Examples

ClimaRep_overlay <- ClimaRep::rep_overlay(folder_path = system.file("extdata",
                                                                    package = "ClimaRep"),
                                         output_dir = file.path(tempdir(), "rep_overlay_output"))
terra::plotRGB(ClimaRep_overlay)
terra::plot(ClimaRep_overlay)

ClimaRep documentation built on Aug. 24, 2025, 5:08 p.m.