Automate particle analysis for spectral maps — automate_particle

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,
  sn_range = list(min = c(750, 2420), max = c(2200, 4000)),
  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,
  sn_range = list(min = c(750, 2420), max = c(2200, 4000)),
  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,
  sn_range = list(min = c(750, 2420), max = c(2200, 4000)),
  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.
sn_range: named list with numeric min and max vectors defining the wavenumber windows in cm^-1 used to calculate signal/noise. Each min pairs with the corresponding max. Broader windows include more of the spectrum and can change which pixels pass sn_threshold_min; windows that do not overlap the input axis stop the analysis.
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)
#> Particle analysis [sample_1]: read (sample 1 of 1)
#> Particle analysis [sample_1]: signal/noise
#> Particle analysis [sample_1]: particle detection and collapse
#> Particle analysis [sample_1]: library matching
#> Particle analysis [sample_1]: outputs
#> Particle analysis [sample_1]: complete
names(res)
#> [1] "samples"                  "particle_details_all_csv"
#> [3] "particle_summary_all_csv"