Skip to contents

Automate particle analysis for spectral maps

Source: R/automate_particle_analysis.R, R/automate_particle_filespecs.R
automate_particle_analysis.Rd

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,
  ...
)

# 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,
  ...
)

# 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,
  ...
)

Arguments

x

character vector of files, an OpenSpecy/Specs object, or a list of objects/files.

library

reference OpenSpecy object or trained model library passed to match_spec().

output_dir

optional directory for CSV/RDS/PNG outputs.

images

optional image path(s) or image objects aligned with x.

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.

...

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, 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"