Title:	Interface to 'Zonation' for Reproducible Prioritization Workflows
Version:	1.0.1
Description:	An interface to 'Zonation' software, enabling users to run spatial conservation prioritization workflows in 'R'. It streamlines input preparation, execution, and post-processing, while supporting reproducibility and lowering the entry barrier for learning, teaching, and research in conservation planning. The methods implemented in 'Zonation' are described in Moilanen et al. (2022) <doi:10.1111/2041-210X.13819>.
License:	GPL (≥ 3)
Encoding:	UTF-8
RoxygenNote:	7.3.3
Imports:	dplyr, ggplot2, ggspatial, rlang, terra, tidyr, utils, viridis
Suggests:	knitr, mockery, rmarkdown, testthat (≥ 3.0.0), withr
Config/testthat/edition:	3
URL:	https://github.com/thiago-cav/ZonationR, https://thiago-cav.github.io/ZonationR/
BugReports:	https://github.com/thiago-cav/ZonationR/issues
Config/Needs/website:	rmarkdown
Depends:	R (≥ 4.1.0)
NeedsCompilation:	no
Packaged:	2026-04-17 10:38:10 UTC; thiag
Author:	Thiago Cavalcante [aut, cre], Bruno Ribeiro [aut], Karlo Guidoni-Martins [aut], Heini Kujala [aut]
Maintainer:	Thiago Cavalcante <thiagocav.ferreira@gmail.com>
Repository:	CRAN
Date/Publication:	2026-04-21 19:22:08 UTC

Check that an output directory is writable

Description

This helper validates that a given directory exists and that the current R process has permission to create and delete a temporary file in it. It is intended for use before writing output files.

Usage

check_dir_writable(out_dir)

Arguments

Value

Returns TRUE invisibly when the directory exists and is writable. The function otherwise throws an error describing the problem:

• if the directory does not exist, an error stating that it does not exist;

• if the directory is not writable, an error stating that it is not writable.

See Also

Other preflight: check_raster_uniformity(), check_zonation_executable()

Examples

dir <- tempdir()
check_dir_writable(dir)

Check raster uniformity

Description

Verifies that all raster files in a folder are compatible with Zonation. Compatibility requires that all rasters have:

• identical resolution (cell size)

• identical extent (number of rows and columns)

• identical projection (CRS)

Usage

check_raster_uniformity(spp_file_dir)

Arguments

Details

Supported raster formats: .tif, .tiff, .img, .asc.

Value

Prints a message confirming uniformity. Stops with an error otherwise.

See Also

Other preflight: check_dir_writable(), check_zonation_executable()

Examples

withr::with_tempdir({

  r1 <- terra::rast(nrows = 5, ncols = 5)
  terra::values(r1) <- runif(terra::ncell(r1))

  r2 <- terra::rast(r1)
  terra::values(r2) <- runif(terra::ncell(r2))

  terra::writeRaster(r1, "r1.tif", overwrite = TRUE)
  terra::writeRaster(r2, "r2.tif", overwrite = TRUE)

  check_raster_uniformity(".")
})

Check for Zonation 5 executable

Description

This function checks if the Zonation 5 executable is available on the system. It can verify a specific path provided by the user or search common installation locations. The function works on both Windows and Linux systems.

Usage

check_zonation_executable(zonation_path = NULL, os = NULL)

Arguments

Details

For Windows, the function searches for z5.exe in:

• The provided path (if given)

• ⁠C:/Program Files (x86)/Zonation5⁠

• ⁠C:/Program Files/Zonation5⁠

For Linux, the function searches for zonation5 in:

• The provided path (if given)

• Common locations like ⁠~/Applications⁠, ⁠~/bin⁠, ⁠/usr/local/bin⁠, ⁠/usr/bin⁠

• The system PATH

Value

A list with the following components:

See Also

Other preflight: check_dir_writable(), check_raster_uniformity()

Examples

check_zonation_executable()

Create a Zonation command file

Description

This function generates a command file for running Zonation and specifies the analysis options and related parameters. The file is saved with a .cmd (Windows) or .sh (Linux) suffix.

Usage

command_file(
  os = "os_detection",
  zonation_path,
  flags = "",
  marginal_loss_mode = "CAZ2",
  gui_activated = FALSE,
  settings_file = "settings_file.z5",
  output_dir = "output"
)

Arguments

Value

A Zonation command file containing the specified analysis options.

See Also

Other preprocessing: feature_list(), settings_file()

Examples

withr::with_tempdir({

  tmp_settings <- tempfile(fileext = ".z5")
  writeLines("feature list file = feature_list.txt", tmp_settings)

  command_file(
    zonation_path = "path/to/zonation",
    settings_file = tmp_settings
  )

  command_file(
    zonation_path = "path/to/zonation",
    marginal_loss_mode = "ABF",
    gui_activated = TRUE,
    settings_file = tmp_settings
  )
})

Summarize remaining cost at specified landscape proportions

Description

Reads a Zonation summary_curves.csv file (space-separated), finds the row closest to each value in landscape_prop, and returns remaining cost and percentage of maximum cost at those proportions. Optionally writes the result to dir/performance/cost_summary.csv.

Usage

cost_summary(
  dir,
  output_folder_name = "output",
  landscape_prop,
  save_output = FALSE
)

Arguments

Value

A data frame with columns:

• rank - the requested proportion

• remaining_cost - remaining cost at that rank

• percentage - remaining cost as percentage of maximum cost

See Also

Other postprocessing: coverage_distribution(), feature_curves(), feature_representation(), priority_map(), rank_similarity(), summary_curves()

Examples

withr::with_tempdir({

  dir.create("output")

  # simulate Zonation-style summary_curves.csv structure
  write.table(
    data.frame(
      rank = seq(0, 1, length.out = 10),
      remaining_cost = runif(10, 50, 100),
      dummy1 = runif(10),
      dummy2 = runif(10)
    ),
    file = file.path("output", "summary_curves.csv"),
    row.names = FALSE,
    col.names = TRUE,
    sep = " "
  )

  cost_summary(
    dir = ".",
    output_folder_name = "output",
    landscape_prop = c(0.2, 0.5, 0.8)
  )

})

Plot coverage distribution at a given rank

Description

This function reads a Zonation feature curves file and plots the distribution of feature coverage values at a specified priority rank. The output is a ggplot object, which can be further customized by the user. Optionally, the plot can be saved to disk as a high-quality figure.

Usage

coverage_distribution(
  dir,
  output_folder_name = "output",
  target_rank,
  save_path = NULL,
  dpi = 300,
  width = 8,
  height = 6
)

Arguments

Value

A ggplot object showing the distribution of feature coverage values at the specified priority rank.

See Also

Other postprocessing: cost_summary(), feature_curves(), feature_representation(), priority_map(), rank_similarity(), summary_curves()

Examples

withr::with_tempdir({

  data_path <- system.file(
    "extdata",
    "feature_curves.csv",
    package = "ZonationR"
  )

  dir.create("output")

  file.copy(
    data_path,
    file.path("output", "feature_curves.csv"),
    overwrite = TRUE
  )

  p <- coverage_distribution(
    dir = ".",
    output_folder_name = "output",
    target_rank = 0.9
  )

  print(p)

})

Plot feature performance curves

Description

Reads the Zonation feature_curves.csv and features_info.csv files, standardizes the feature names, and plots representation vs priority rank for each feature. Supports a single color with transparency or the viridis palette.

Usage

feature_curves(
  dir,
  output_folder_name = "output",
  palette = "gray",
  alpha = 0.3,
  show_legend = FALSE,
  save_path = NULL,
  dpi = 300,
  width = 8,
  height = 6
)

Arguments

Value

A ggplot object representing feature curves. If save_path is provided, also saves the plot as PNG.

See Also

Other postprocessing: cost_summary(), coverage_distribution(), feature_representation(), priority_map(), rank_similarity(), summary_curves()

Examples

withr::with_tempdir({

  data_path <- system.file(
    "extdata",
    package = "ZonationR"
  )

  dir.create("output")

  file.copy(
    file.path(data_path, "feature_curves.csv"),
    "output/feature_curves.csv",
    overwrite = TRUE
  )

  file.copy(
    file.path(data_path, "features_info.csv"),
    "output/features_info.csv",
    overwrite = TRUE
  )

  p1 <- feature_curves(
    dir = ".",
    output_folder_name = "output"
  )

  print(p1)

  # Plot using viridis palette with legend
  p2 <- feature_curves(
    dir = ".",
    output_folder_name = "output",
    palette = "viridis",
    show_legend = TRUE
  )

  print(p2)

})

Create a feature list from raster files

Description

This function generates a feature list from raster files in a specified directory, adding optional attributes to the list based on user-defined parameters. The resulting feature list is written to a text file. Supported raster formats include GeoTIFF (.tif, .tiff), ERDAS Imagine (.img), and ASCII Grid (.asc).

Usage

feature_list(spp_file_dir, weight = NULL, group = NULL, threshold = NULL)

Arguments

Value

A text file containing a feature list of rasters along with any additional attributes specified by the user.

See Also

Other preprocessing: command_file(), settings_file()

Examples

withr::with_tempdir({

  file.create("species1.tif")
  file.create("species2.tif")

  feature_list(spp_file_dir = ".")
})

Calculate feature representation within an area

Description

This function calculates the representation of each feature across raster cells, and can optionally summarize results within a specified area.

Usage

feature_representation(feature_layers, area_mask = NULL)

Arguments

Value

A list with two elements:

representation_layers

A terra::SpatRaster where each layer contains the fractional representation of the corresponding feature across the landscape. Each cell value represents the proportion of the global total representation of that feature occurring in that cell.

representation_in_area

A named numeric vector containing the representation of each feature within the specified area_mask. If no area is provided, this element returns NULL.

See Also

Other postprocessing: cost_summary(), coverage_distribution(), feature_curves(), priority_map(), rank_similarity(), summary_curves()

Examples

r <- terra::rast(nrows = 10, ncols = 10)
f1 <- terra::setValues(r, runif(terra::ncell(r)))
f2 <- terra::setValues(r, runif(terra::ncell(r)))
features <- c(f1, f2)
names(features) <- c("feature_1", "feature_2")

mask <- r
terra::values(mask) <- sample(c(0,1), terra::ncell(mask), replace = TRUE)

result <- feature_representation(features, mask)
result$representation_in_area

Plot priority ranking maps

Description

priority_map() reads a rank map raster from a specified folder and creates a ggplot2 map. It can plot the raster as continuous values or classify it into discrete categories with custom breaks and labels.

Usage

priority_map(
  dir,
  output_folder_name = "output",
  breaks = NULL,
  labels = NULL,
  palette = "viridis",
  classify = FALSE,
  show_legend = TRUE,
  save_path = NULL,
  dpi = 300,
  width = 8,
  height = 6
)

Arguments

Value

A ggplot object representing the priority map.

See Also

Other postprocessing: cost_summary(), coverage_distribution(), feature_curves(), feature_representation(), rank_similarity(), summary_curves()

Examples

withr::with_tempdir({

  data_path <- system.file(
    "extdata",
    package = "ZonationR"
  )

  dir.create("output")

  # copy example rankmap
  file.copy(
    file.path(data_path, "rankmap.tif"),
    "output/rankmap.tif",
    overwrite = TRUE
  )

  # ---- continuous map ----
  p1 <- priority_map(
    dir = ".",
    output_folder_name = "output",
    classify = FALSE
  )

  print(p1)

  # ---- classified map ----
  breaks <- c(0, 0.25, 0.5, 0.75, 1)
  labels <- c("Low", "Medium", "High", "Very High")

  p2 <- priority_map(
    dir = ".",
    output_folder_name = "output",
    classify = TRUE,
    breaks = breaks,
    labels = labels
  )

  print(p2)

})

Calculate similarity between Zonation rank maps

Description

This function calculates similarity between two spatial rank maps using Schoener's D or the Jaccard index.

Usage

rank_similarity(
  r1 = NULL,
  r2 = NULL,
  rstack = NULL,
  method = c("schoener", "jaccard"),
  threshold = NULL
)

Arguments

Value

A numeric value between 0 and 1 if comparing two rasters, or a matrix of pairwise coefficients if using rstack.

See Also

Other postprocessing: cost_summary(), coverage_distribution(), feature_curves(), feature_representation(), priority_map(), summary_curves()

Examples

# Create two example priority rank maps
r1 <- terra::rast(nrows = 5, ncols = 5)
terra::values(r1) <- runif(terra::ncell(r1))

r2 <- terra::rast(r1)
terra::values(r2) <- runif(terra::ncell(r2))

# Schoener's D
rank_similarity(r1, r2, method = "schoener")

# Jaccard index with threshold
rank_similarity(r1, r2, method = "jaccard", threshold = 0.7)

Run a Zonation command file

Description

This function runs a Zonation 5 analysis directly from R by executing a command file located in the specified folder. On Windows, the function looks for a single .cmd file; on Linux, it looks for a single .sh file.

Usage

run_command_file(folder)

Arguments

Value

Nothing is returned. The function is used to run the Zonation analysis.

Examples

## Not run: 
run_command_file("C:/path/to/folder")

## End(Not run)

Create a settings file for a Zonation analysis

Description

This function generates a settings file with various parameters related to the input data and analysis configuration. The resulting settings file is saved with a .z5 extension and can be used directly in the Zonation software.

Usage

settings_file(
  feature_list_file,
  external_solution_file = NULL,
  analysis_area_mask_layer = NULL,
  hierarchic_mask_layer = NULL,
  cost_layer = NULL
)

Arguments

Value

A .z5 file containing the specified settings.

See Also

Other preprocessing: command_file(), feature_list()

Examples

withr::with_tempdir({

  tmp <- tempfile(fileext = ".txt")
  writeLines("feature list file = feature_list.txt", tmp)

  settings_file(feature_list_file = "feature_list.txt")
})

Plot summary performance curves

Description

This function reads a Zonation summary curves file and plots one or more summary metrics against the priority rank. The output is a ggplot object, which can be further customized by the user. Optionally, the plot can be saved to disk as a high-quality figure.

Usage

summary_curves(
  dir,
  output_folder_name = "output",
  metrics,
  facet = FALSE,
  save_path = NULL,
  dpi = 300,
  width = 8,
  height = 6
)

Arguments

Value

A ggplot object visualizing one or more Zonation summary metrics plotted against priority rank.

See Also

Other postprocessing: cost_summary(), coverage_distribution(), feature_curves(), feature_representation(), priority_map(), rank_similarity()

Examples

withr::with_tempdir({

  data_path <- system.file(
    "extdata",
    package = "ZonationR"
  )

  dir.create("output")

  file.copy(
    file.path(data_path, "summary_curves.csv"),
    "output/summary_curves.csv",
    overwrite = TRUE
  )

  p1 <- summary_curves(
    dir = ".",
    output_folder_name = "output",
    metrics = c("mean", "max")
  )

  print(p1)

})