Run spatial gradient feature screening — RunSpatialGradientFeatures • scop

Run spatial trajectory or annotation gradient screening for Seurat objects. distance-based screening, while the "r" backend keeps full upstream SPATA2 SAS/STS behavior. Results are normalized into plain data.frames and is never stored.

Usage

RunSpatialGradientFeatures(
  srt,
  reference = c("trajectory", "annotation"),
  backend = "cpp",
  result_name = NULL,
  assay = NULL,
  layer = "data",
  variables = NULL,
  sample_name = NULL,
  platform = "Undefined",
  image = NULL,
  coord.cols = c("x", "y"),
  img_scale_fct = "lowres",
  assay_modality = "gene",
  trajectory_id = "scop_gradient",
  start = NULL,
  end = NULL,
  traj_df = NULL,
  width = NULL,
  annotation_ids = NULL,
  annotation.by = NULL,
  annotation.groups = NULL,
  annotation.variable = NULL,
  annotation.threshold = NULL,
  annotation_id = "scop_gradient",
  core = FALSE,
  distance = "dte",
  angle_span = c(0, 360),
  resolution = NULL,
  unit = NULL,
  sign_var = "fdr",
  sign_threshold = 0.05,
  model_add = NULL,
  model_subset = NULL,
  model_remove = NULL,
  n_random = 10000,
  seed = 123,
  control = NULL,
  n_bins = 50,
  min_spots = 3,
  nfeatures = 2000,
  set_variable_features = FALSE,
  store_results = TRUE,
  verbose = TRUE,
  coordinate_space = c("raw", "legacy_display"),
  ...
)

Arguments

srt: A Seurat object.
reference: Spatial reference type: "trajectory" for STS or "annotation" for SAS.
backend: Computation backend. "cpp" uses a compiled fast spatial uses SPATA2 directly for full upstream SAS/STS behavior.
result_name: Name used to store this result. If NULL, a name is generated from reference.
assay: Assay to use. NULL uses the default assay.
layer: Assay layer used for expression values.
variables: Numeric variables or genes passed to SPATA2. If NULL, srt@tools[["SpatialVariableFeatures"]] is used first, then variable features, then all assay features.
sample_name, platform, img_scale_fct, assay_modality: Arguments forwarded
image: Spatial image name. Required when multiple images are present; a single image is selected automatically when NULL.
coord.cols: Metadata coordinate columns used by the "cpp" backend when no image coordinates are available.
trajectory_id, start, end, traj_df, width: Trajectory setup passed to SPATA2::addSpatialTrajectory() and SPATA2::spatialTrajectoryScreening().
annotation_ids: Existing SPATA2 spatial annotation ids. If NULL, annotations are created from annotation.by and annotation.groups, or from annotation.variable and annotation.threshold.
annotation.by, annotation.groups: Metadata grouping used to create SPATA2 group annotations.
annotation.variable, annotation.threshold: Numeric variable and threshold used to create SPATA2 numeric annotations. Numeric thresholds are interpreted as ">{threshold}".
annotation_id: Base id used when creating annotations.
core, distance, angle_span: SAS parameters forwarded to SPATA2.
resolution, unit, sign_var, sign_threshold, model_add, model_subset, model_remove, n_random, seed, control: SPATA2 screening parameters.
n_bins: Number of distance bins used for the "cpp" backend screening curve.
min_spots: Minimum number of non-zero spots required for a variable in the "cpp" backend.
nfeatures: Number of top gradient variables retained in top_variables and optionally set as Seurat variable features.
set_variable_features: Whether to set top gradient variables as Seurat variable features.
store_results: Whether to store the normalized result in srt@tools.
verbose: Whether to print the message. Default is TRUE.
coordinate_space: Coordinate system used by the C++ distance calculations. The default is raw acquisition coordinates, so start, end, trajectory positions, widths, and C++ distances share raw coordinate units. Use "legacy_display" explicitly for pre-0.9.0 display coordinates. SPATA2-backed runs retain backend-native units.
...: Additional arguments forwarded to the SPATA2 screening function.

Value

A Seurat object with spatial gradient screening results stored in srt@tools[["SpatialGradientFeatures"]].

Examples

data(visium_human_pancreas_sub)
spatial <- visium_human_pancreas_sub
spatial <- RunSpatialGradientFeatures(
  spatial,
  reference = "trajectory",
  backend = "cpp",
  result_name = "ductal_axis",
  variables = rownames(spatial)[1:8],
  start = c(min(spatial$x), min(spatial$y)),
  end = c(max(spatial$x), max(spatial$y)),
  layer = "counts",
  coord.cols = c("x", "y"),
  n_random = 0,
  n_bins = 5,
  min_spots = 3,
  sign_threshold = 1,
  nfeatures = 4,
  verbose = FALSE
)

SpatialGradientPlot(spatial, plot_type = "summary", nfeatures = 4)

SpatialGradientPlot(spatial, plot_type = "line", nfeatures = 2)

SpatialGradientPlot(spatial, plot_type = "model", nfeatures = 2)

SpatialGradientPlot(
  spatial,
  plot_type = "surface",
  nfeatures = 2,
  overlay_image = FALSE,
  coord.cols = c("x", "y")
)