automate_particle_analysis: Automate particle analysis for spectral maps

In OpenSpecy: Analyze, Process, Identify, and Share Raman and (FT)IR Spectra

Automate particle analysis for spectral maps

Description

automate_particle_analysis() generalizes the batch map workflow used for particle detection, spectral matching, particle details, summaries, and optional base-graphics particle images. Visual images attached to map objects or read from supported H5 mosaics are used for particle color extraction when feature definition is requested. It keeps file output optional and returns all results as R objects. S/N thresholds that remove every pixel return an empty analysis without library matching. Thresholds that retain every pixel continue normally; a connected collapse treats the full extent of each source map as one particle. Both threshold extremes emit an informational message.

Usage

automate_particle_analysis(
  x,
  library,
  output_dir = NULL,
  images = NULL,
  bottom_left = NULL,
  top_right = NULL,
  origins = NULL,
  material_col = "material_class",
  library_id_col = "sample_name",
  particle_id_strategy = c("collapse", "partial_collapse", "nonspatial_collapse",
    "all_cell_id", "raw"),
  spectral_smooth = FALSE,
  sigma1 = c(1, 1, 1),
  sigma2 = c(3, 3),
  close = FALSE,
  close_kernel = c(4, 4),
  sn_threshold_min = 0.04,
  sn_threshold_max = Inf,
  cor_threshold = 0.7,
  area_threshold = 1,
  label_unknown = FALSE,
  remove_materials = NULL,
  remove_unknown = FALSE,
  pixel_length = 25,
  metric = "sig_times_noise",
  abs = FALSE,
  collapse_function = stats::median,
  outputs = c("details", "summary"),
  process_args = list(),
  specs_steps = c("pca", "kmeans"),
  specs_centers = NULL,
  file_processing = c("stream", "memory"),
  ...
)

## Default S3 method:
automate_particle_analysis(
  x,
  library,
  output_dir = NULL,
  images = NULL,
  bottom_left = NULL,
  top_right = NULL,
  origins = NULL,
  material_col = "material_class",
  library_id_col = "sample_name",
  particle_id_strategy = c("collapse", "partial_collapse", "nonspatial_collapse",
    "all_cell_id", "raw"),
  spectral_smooth = FALSE,
  sigma1 = c(1, 1, 1),
  sigma2 = c(3, 3),
  close = FALSE,
  close_kernel = c(4, 4),
  sn_threshold_min = 0.04,
  sn_threshold_max = Inf,
  cor_threshold = 0.7,
  area_threshold = 1,
  label_unknown = FALSE,
  remove_materials = NULL,
  remove_unknown = FALSE,
  pixel_length = 25,
  metric = "sig_times_noise",
  abs = FALSE,
  collapse_function = stats::median,
  outputs = c("details", "summary"),
  process_args = list(),
  specs_steps = c("pca", "kmeans"),
  specs_centers = NULL,
  file_processing = c("stream", "memory"),
  ...
)

## S3 method for class 'FileSpecs'
automate_particle_analysis(
  x,
  library,
  output_dir = NULL,
  images = NULL,
  bottom_left = NULL,
  top_right = NULL,
  origins = NULL,
  material_col = "material_class",
  library_id_col = "sample_name",
  particle_id_strategy = c("collapse", "partial_collapse", "nonspatial_collapse",
    "all_cell_id", "raw"),
  spectral_smooth = FALSE,
  sigma1 = c(1, 1, 1),
  sigma2 = c(3, 3),
  close = FALSE,
  close_kernel = c(4, 4),
  sn_threshold_min = 0.04,
  sn_threshold_max = Inf,
  cor_threshold = 0.7,
  area_threshold = 1,
  label_unknown = FALSE,
  remove_materials = NULL,
  remove_unknown = FALSE,
  pixel_length = 25,
  metric = "sig_times_noise",
  abs = FALSE,
  collapse_function = stats::median,
  outputs = c("details", "summary"),
  process_args = list(),
  specs_steps = c("pca", "kmeans"),
  specs_centers = NULL,
  file_processing = c("stream", "memory"),
  ...
)

Arguments

x	character vector of files, an OpenSpecy/Specs object, or a list of objects/files. H5/HDF5 paths can be analyzed as bounded file-backed FileSpecs sources or materialized in memory before analysis.
library	reference OpenSpecy object or trained model library passed to match_spec().
output_dir	optional directory for CSV/RDS/PNG outputs. Per-source filenames retain the complete input basename (without its extension); multi-region sources append the region after that basename.
images	optional image path(s) or image objects aligned with x. When omitted for an ENVI DAT/IMG path, an unambiguous same-basename JPG, JPEG, or PNG in the same directory is discovered automatically.
bottom_left, top_right	optional lists of image corners; if missing and an image is supplied, detect_image_origin() is attempted.
origins	optional list with x and y origin offsets for map-unit outputs.
material_col	material/class column in matched library metadata.
library_id_col	library metadata column used to join match metadata.
particle_id_strategy	one of "collapse", "partial_collapse", "nonspatial_collapse", "all_cell_id", or "raw".
spectral_smooth, sigma1	apply 3D Gaussian smoothing to spectral maps; file readers apply this while reading and in-memory maps are smoothed after coercion.
sigma2	shape kernel passed to def_features().
close, close_kernel	passed to def_features().
sn_threshold_min, sn_threshold_max	signal/noise thresholds.
cor_threshold	minimum match value for confident particle labels.
area_threshold	minimum feature area in pixels (inclusive).
label_unknown	logical; label low-correlation matches as "unknown".
remove_materials	optional material labels to remove after matching.
remove_unknown	logical; remove "unknown" after matching.
pixel_length	map pixel length used for output dimensions.
metric, abs	signal/noise arguments passed to sig_noise().
collapse_function	function used by collapse_spec().
outputs	character vector containing any of "details", "summary", "particle_image", "particle_heatmap", "particle_heatmap_thresholded", "cor_heatmap", "sn_histogram", "cor_histogram", "raw", "processed", or "time". Short aliases "heatmap", "thresholded", and "correlation" are also accepted.
process_args	optional named list overriding process_spec() arguments for spectra before matching.
specs_steps	retained for signature compatibility; clustering strategies require the concrete c("pca", "kmeans") workflow.
specs_centers	requested K-means cluster count for clustering strategies; the effective count is clamped to the eligible data.
file_processing	file-backed execution policy. "stream" (the default) reads bounded chunks and supports the file-backed strategies; "memory" materializes every region before using the full in-memory workflow. The memory mode can be faster for smaller files but requires enough RAM for all spectra and their analysis intermediates.
...	catches removed legacy arguments and otherwise is reserved.

Value

A list with samples, particle_details_all_csv, and particle_summary_all_csv. Each per-sample entry has particle_details_csv, particle_summary_csv, particles_raw_rds, particles_rds, and time_rds, and uses the same filename-based sample_id stem as its per-source output files (including an appended region for multi-region sources), with summary rows reporting full map area, particle count, observed percentage, 95% percentage confidence-interval half-width and bounds, total concentration RSD, and total, mean, and median particle area in square micrometres for each material class, plus one plot-data list for each requested plot output: particle_image, particle_heatmap, particle_heatmap_thresholded, cor_heatmap, sn_histogram, and cor_histogram. Each plot-data list carries the grid or histogram values needed to build a custom plot()/plotly/ggplot2 view (a type field plus x/y/z, values, thresholds, or levels as appropriate), or type = "empty" with a reason string when nothing passed filtering. output_dir still writes the matching static PNG/JPG for each requested plot. The result has class OpenSpecyParticleAnalysis; use its plot() method to draw one of these plots with base graphics.

Examples

tiny_map <- read_extdata("CA_tiny_map.zip") |> read_any()
data("test_lib")
res <- automate_particle_analysis(tiny_map, test_lib,
                                  outputs = c("details", "summary"),
                                  sn_threshold_min = 0.1)
names(res)

OpenSpecy documentation built on Oct. 6, 2026, 1:07 a.m.