Skip to contents

Prepare a Seurat Object for Uniform Downstream Analysis

PrepObject.Rd

Assigns color palettes and factor-level orderings to one or more metadata variables and stores them in seurat_object@misc$nk_settings. All downstream scSidekick functions look there first for colors and default parameters; they only fall back to automatic palette generation when a variable is not stored.

Additive by default. Calling PrepObject again for a new variable (e.g. after cell-type assignment) does not overwrite existing settings - it only adds or updates the variables you name. Set force = TRUE to regenerate a variable that is already stored.

Auto-palette selection:

  • "auto": Nour_pal("all") for variables with \(\leq 8\) levels (warm, distinct), Nour_pal("spectrum") for \(> 8\) levels (broader color range).

  • Specify per-variable, either by name palettes = c(Cluster = "all", Sample = "spectrum") or by position (one entry per variables, same order) palettes = c("spectrum", "all", "all").

Usage

PrepObject(
  seurat_object,
  variables,
  palettes = "auto",
  reverse = FALSE,
  custom_colors = list(),
  var_levels = list(),
  group.by = NULL,
  split.by = NULL,
  donor.by = NULL,
  assay_type = NULL,
  output_dir = NULL,
  object_name = NULL,
  subset_name = NULL,
  AutoSavePlots = NULL,
  force = FALSE
)

Arguments

seurat_object

A Seurat object.

variables

Character vector of metadata column names to color and prepare. Can be a single name; re-run PrepObject at any time to add more.

palettes

Palette name(s). One of:

  • A single string ("auto", "all", "spectrum", ...) applied to every variable.

  • A named character vector keyed by variable (c(Cluster = "all", Sample = "spectrum")); names not listed fall back to "auto".

  • An unnamed character vector of the same length as variables, matched by position (c("spectrum", "all", "all")).

Default "auto".

reverse

Logical, named logical vector, or an unnamed logical vector matched by position to variables. TRUE reverses the palette for all variables; a named vector reverses selectively (e.g. c(Cluster = TRUE, Sample = FALSE)). Default FALSE.

custom_colors

Named list of named character vectors that override automatic palette generation entirely for specific variables. E.g. list(Sample = c(Control = "#3B4CC0", NRF1_mRNA = "#B40426")).

var_levels

Named list of character vectors that set the factor level ordering for each variable, controlling sort order in heatmap columns, violin plots, and ggplot2 facets. E.g. list(Sample = c("Control", "NRF1_mRNA")).

group.by

Character. Store the preferred primary grouping column. Downstream scSidekick functions use this as the default group.by when none is specified in the call. Pass NA to explicitly clear a previously stored value.

split.by

Character. Store the preferred secondary split column. Downstream functions use this as the default split.by. Pass NA to explicitly disable the stored default (even if one exists).

donor.by

Character or NULL. Metadata column that identifies the biological replicate / library unit – the donor, patient, mouse, or sample from which each cell/spot was obtained. When set, plotting functions include the number of unique donors in figure legends (e.g. "8,691 cells from 36 samples"). Pass NA to clear a previously stored value.

assay_type

Character or NULL. Sequencing modality. Controls the observation-level word used in auto-generated legend and methods text. Recognized values (same vocabulary as log_analysis_params):

  • "scRNAseq" – "cells" (default)

  • "snRNAseq" – "nuclei"

  • "Visium" – "spots"

  • "VisiumHD" – "bins"

  • "Xenium" – "cells"

  • "Spatial" – "spots"

  • "scATACseq", "scMultiome" – "cells"

Pass NULL to leave unchanged; NA to clear.

output_dir

Character. Store the preferred output directory for saving PDFs and plots. All downstream scSidekick functions walk up to this value when their own output_dir argument is NULL. Pass NA to explicitly clear a stored value.

object_name

Character. Label used to prefix output file names.

subset_name

Character. Optional subset label appended to output file names (e.g. "NoNeurons").

AutoSavePlots

Logical or NULL. Controls whether plotting functions automatically save PDFs to the stored output_dir when no output_dir is passed explicitly in the function call.

  • TRUE (default when not set): plotting functions walk up and use the stored output_dir automatically – existing behavior.

  • FALSE: the walk-up is suppressed; functions return the plot object without saving unless the caller explicitly passes output_dir = "..." in the plotting call.

Pass NULL to leave the current setting unchanged.

force

Logical. If FALSE (default), variables that already have stored colors are left unchanged. If TRUE, existing colors are regenerated for every variable listed in variables.

Value

The seurat_object with @misc$nk_settings updated. Return the object and re-assign: seurat_object <- PrepObject(...).

See also

ShowColors, GetColors