ClassicHCAS implements the reference-surface construction, benchmarking and calibration stages of the Habitat Condition Assessment System (HCAS). HCAS infers ecosystem condition from Earth observation data by comparing target locations with ecologically comparable high-integrity reference ecosystems.
Predicted remote sensing (RS) variables describe the ecosystem characteristics expected under reference condition, given the abiotic environment. Observed RS variables describe the measured characteristics. HCAS compares predicted and observed distances between sites, allowing multiple plausible high-integrity ecosystem expressions within similar environments. Higher scores indicate stronger alignment with comparable reference ecosystems; they are relative, proxy-based estimates, rather than direct measurements of every aspect of ecosystem integrity or evidence of a particular cause of change.
Data preparation, reference-site selection, reference ecosystem modelling, parameter tuning and selection of calibration coordinates are external to the package. ClassicHCAS uses Rcpp for computationally intensive distance calculations and supports tabular and raster workflows.
ClassicHCAS supports the main HCAS workflow:
ref_density()builds a raw reference density surface of paired predicted and observed RS distances among reference sites.normalise()smooths, trims and normalises that surface to obtain the inferential reference surface used for benchmarking.benchmark()scores target sites or rasters against the reference relationship.calibrate()rescales raw condition values to a final 0 to 1 condition scale.
It also includes operational helpers:
reference_use()summarises reference-site selection and attribution weights.variable_importance()andaggregate_importance()describe per-variable observed departures from selected references and their landscape summaries.hcas_inspection()inspects individual targets interactively.radial_count()counts nearby reference samples for each raster cell.tiling()creates balanced or rectangular tiles for large processing runs.palettes()supplies plotting colours.
The core distance-based functions accept either:
- matrices or data frames arranged as
x,y, predicted remote sensing variables, and observed remote sensing variables terra::SpatRasterobjects containing predicted layers followed by observed layers in the same variable order; reference coordinates are supplied separately
Use numeric variables and matching predicted/observed feature counts. ref_density() also checks that corresponding feature names match. All coordinates must use the same coordinate reference system (CRS); projected coordinates must be in metres. Tables carry no CRS metadata, so the package infers longitude/latitude from coordinate values. Raster grids must be aligned before processing.
Centre and scale each RS variable consistently across predictions, observations and reference/target datasets before calculating distances. Save the standardisation statistics and reuse them for subsequent epochs; the package does not standardise inputs automatically.
Training reference sites support external reference ecosystem modelling and construction of the reference density surface. Benchmark reference sites should represent variation in both environment and observed ecosystem characteristics. These sets may differ; both must represent high-integrity ecosystems. Highly modified sites inform calibration and evaluation, rather than forming the reference density surface.
ClassicHCAS is not currently on CRAN. Install it from GitHub:
install.packages("remotes")
remotes::install_github("csiro/ClassicHCAS")Building from source requires a working toolchain. On Windows this usually means Rtools. On macOS, OpenMP support may be needed for faster parallel execution.
This self-contained example uses synthetic RS values on a common scale and projected coordinates in metres. Its parameters and calibration coordinates illustrate the API; they are not recommendations for a scientific assessment.
library(ClassicHCAS)
set.seed(1)
predicted <- matrix(rnorm(120), ncol = 1,
dimnames = list(NULL, "rs1"))
observed <- predicted + rnorm(120, sd = 0.15)
reference_data <- cbind(
x = runif(120, 500000, 510000),
y = runif(120, 6100000, 6110000),
predicted, observed
)
target_data <- reference_data[1:3, ]
target_data[, 1] <- target_data[, 1] + 50
target_data[, 4] <- target_data[, 3] + c(0, 0.8, 2)
ref <- ref_density(
data = reference_data,
radius_km = 20,
bin_width = 0.1,
bin_num = 80,
num_threads = 1
)
ref_norm <- normalise(ref, trim_size = 60)
condition <- benchmark(
data = target_data,
samples = reference_data,
ref_density = ref_norm,
radius_km = 20,
k1 = 30,
k2 = 10,
offset = NULL,
num_threads = 1
)
condition_calibrated <- calibrate(
condition,
x_values = c(0, 0.01, 0.1, 0.3),
y_values = c(0, 0.1, 0.9, 1)
)
condition_calibratedIn v2.0.0, benchmark() defaults to k1 = 70, k2 = 10, a Gaussian distance kernel and boost = k2. Boosting increases the kernel weight of the retained reference with the highest reference-surface value. confidence affects the LDC blend of the maximum surface value and the kernel-weighted mean only when boost = NULL or NA. These settings require assessment for each application.
Keep the reference-surface bin width, offset and retained features consistent with benchmarking. offset = NULL reads the offset from a reference_density object; the default offset = 0 is only appropriate when no bins were removed. The public self-exclusion argument is spelt exclude_slef; it removes references with near-zero predicted RS distance, including different sites with similar predictions.
Calibration fits a Hermite spline through user-supplied coordinates. Choose increasing raw-score knots and non-decreasing ecological condition anchors using independent information or expert knowledge. Calibration does not validate the model. If make_su = TRUE, calibrate only the condition column/layer: su is a log kernel-weight support diagnostic, not a confidence interval.
For a worked example including standardisation, raster inputs, diagnostics and repeated epochs, see the tutorial, or run vignette("tutorial", package = "ClassicHCAS") after installing with build_vignettes = TRUE. Expanded temporal references via temporal_sigma are experimental and distinct from repeating the standard workflow for each epoch.
For the Australian national application of HCAS, including the official project overview, product guides, factsheets, and current data releases, see the CSIRO HCAS project page:
That page describes the continental Australian application. The Australian HCAS data-product version and the ClassicHCAS package version identify different things. HCAS 3.3 was generated using ClassicHCAS 0.2.0; current v2.x kernels and estimator defaults should not be assumed to reproduce those published outputs.
For the Australian HCAS 3.3 data collection, use its separate citation:
- Valavi R, Levick SR, Lehmann EA, Liu N, Giljohann KM, Williams KJ, Collings S, Johnson S, Botha EJ, Munroe SEM, Van Niel TG, Newnham G, Paget M, Malley C, Carlile P, Gunawardana D, Lyon P, Richards AE, Tetreault Campbell S and Ferrier S (2025c). HCAS 3.3 (1988-2024) base model estimate of habitat condition (90m grid), National Connectivity Index 2.0 (NCI) and annual time series for continental Australia. Data collection 65549. CSIRO, Canberra, Australia. Citation text from the CSIRO HCAS project page: https://research.csiro.au/biodiversity-knowledge/projects/hcas/
For the latest Australian release status, product guides, and download links, use the CSIRO project page above as the canonical source.
For the manuscript describing ClassicHCAS and the underlying method, use the following reference:
Valavi R, Williams KJ, Lehmann EA, Collings S, Levick S, Giljohann KM, Liu N, Johnson S, Munroe SEM, Van Niel TG, Paget M, Malley C, Lyon P, Harwood TD and Ferrier S (2026). A scalable workflow for ecosystem condition assessment from Earth observation data. EcoEvoRxiv [preprint]. DOI: 10.32942/X27104.