| Title: | Passport System for Single-Cell Objects |
|---|---|
| Description: | Stamps Seurat, SingleCellExperiment, and SummarizedExperiment objects with a persistent metadata passport. For Seurat objects the passport is stored in the misc slot; for SingleCellExperiment and SummarizedExperiment objects it is stored in the metadata slot. Tracks animal info, experiment details, lineage (parent/child relationships), RDS registry numbers, processing logs, and custom fields. Includes an interactive Shiny gadget to fill and update the passport, and a read mode to print the full passport to console. The passport persists inside the RDS file with no external files needed. |
| Authors: | Sedat Kacar [aut, cre] (ORCID: <https://orcid.org/0000-0002-0671-8529>) |
| Maintainer: | Sedat Kacar <[email protected]> |
| License: | MIT + file LICENSE |
| Version: | 1.1.0 |
| Built: | 2026-05-30 09:51:31 UTC |
| Source: | https://github.com/bioc/scPassport |
Appends a processing step entry to the object's processing log.
For Seurat objects the log is stored in @misc$processing_log;
for SingleCellExperiment and SummarizedExperiment objects it
is stored in metadata(obj)$processing_log.
Each entry records the step name, timestamp, cell count, gene count,
and any parameters you pass.
log_step(obj, step, params = list())log_step(obj, step, params = list())
obj |
A Seurat, SingleCellExperiment, or SummarizedExperiment object. |
step |
A character string describing the processing step
(e.g. |
params |
A named list of parameters used in this step. Default is an empty list. |
The same object with the new log entry appended to its processing log.
# Log a step on a minimal SummarizedExperiment object if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() se <- log_step(se, "example step") } # Log steps on a Seurat object (requires an existing Seurat object 'seu') # seu <- log_step(seu, "QC filter", # params = list(min_cells = 3, min_features = 200)) # # seu <- NormalizeData(seu) # seu <- log_step(seu, "NormalizeData", # params = list(method = "LogNormalize", scale_factor = 10000)) # # seu <- RunPCA(seu) # seu <- log_step(seu, "RunPCA", params = list(npcs = 30)) # # read_passport(seu)# Log a step on a minimal SummarizedExperiment object if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() se <- log_step(se, "example step") } # Log steps on a Seurat object (requires an existing Seurat object 'seu') # seu <- log_step(seu, "QC filter", # params = list(min_cells = 3, min_features = 200)) # # seu <- NormalizeData(seu) # seu <- log_step(seu, "NormalizeData", # params = list(method = "LogNormalize", scale_factor = 10000)) # # seu <- RunPCA(seu) # seu <- log_step(seu, "RunPCA", params = list(npcs = 30)) # # read_passport(seu)
Prints the full passport stored in the object's passport slot to the console,
including all known fields, any custom fields, and the processing log.
Works with Seurat (@misc$passport), SingleCellExperiment, and
SummarizedExperiment (metadata(obj)$passport) objects.
read_passport(obj)read_passport(obj)
obj |
A Seurat, SingleCellExperiment, or SummarizedExperiment object
with a passport stamped via |
Invisibly returns NULL. Output is printed to console.
# Read passport on an unstamped object (prints "No passport found") if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() read_passport(se) } # Read passport on a stamped Seurat object (requires existing object 'WTHeme') # read_passport(WTHeme) # # Or via scPassport with read = TRUE: # scPassport(WTHeme, read = TRUE)# Read passport on an unstamped object (prints "No passport found") if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() read_passport(se) } # Read passport on a stamped Seurat object (requires existing object 'WTHeme') # read_passport(WTHeme) # # Or via scPassport with read = TRUE: # scPassport(WTHeme, read = TRUE)
Stamps Seurat, SingleCellExperiment, and SummarizedExperiment objects
with a persistent metadata passport. For Seurat objects the passport is
stored in @misc$passport; for SingleCellExperiment and
SummarizedExperiment objects it is stored in metadata(obj)$passport.
Tracks animal info, experiment details, lineage (parent/child relationships),
RDS registry numbers, processing logs, and custom fields. Includes an
interactive Shiny popup to fill and update the passport, and a read mode
to print it to console.
Opens an interactive Shiny popup that allows you to fill in metadata
(animal info, experiment details, lineage, RDS numbers, and custom fields)
and stamps it directly into the object's passport slot.
For Seurat objects the passport is stored in @misc$passport;
for SingleCellExperiment and SummarizedExperiment objects it
is stored in metadata(obj)$passport.
All information persists inside the object when saved as .rds.
If a passport already exists in the object, all previously filled fields are pre-loaded into the popup so you only need to update what changed.
scPassport(obj, parent = NULL, read = FALSE)scPassport(obj, parent = NULL, read = FALSE)
obj |
A Seurat, SingleCellExperiment, or SummarizedExperiment object to stamp. Must not be NULL. |
parent |
A parent object of the same class that this object was subset
from. If provided, |
read |
Logical. If |
The passport contains the following fields:
Identity:
object_id -Name/ID of this object (e.g. "WTHeme")
rds_self -RDS registry number of this object (e.g. 224)
created -Timestamp of when passport was stamped
Animal Info:
animal_id -Individual animal identifier (e.g. "M01")
species -Species name (e.g. "Mus musculus")
sex -Sex of the animal (e.g. "male", "female")
age -Age of the animal (e.g. "P60")
condition -Experimental condition (e.g. "control", "treated")
tissue -Tissue of origin (e.g. "prefrontal cortex")
Experiment Info:
project -Project name (e.g. "memory_study")
researcher -Name of the researcher
date -Date of the experiment
notes -Any free-text notes
Lineage:
parent_id -Object ID of the direct parent (or "root")
rds_parent -RDS number of the parent object (or "root")
lineage -Full ancestry chain as a character vector
children -Object IDs of children subset from this object
rds_children -RDS numbers of children objects
Custom Fields:
Any additional fields typed into the Custom Fields section of the popup
are automatically appended to the passport and displayed when read = TRUE.
Safety:
The function will never overwrite your object with NULL.
Cancelling the popup or any error returns the original object unchanged.
The same object with its passport slot filled in. If cancelled or an error occurs, the original object is returned unchanged
it will never return NULL.
scPassport — Open popup to fill/update passport
read_passport — Print passport to console
log_step — Log a processing step
# 1. Stamp your root object WTHeme <- scPassport(WTHeme) # 2. Log processing steps WTHeme <- NormalizeData(WTHeme) WTHeme <- log_step(WTHeme, "NormalizeData") # 3. Subset and stamp child, linking to parent EndofrHeme <- subset(WTHeme, subset = cell_type == "Endothelial") EndofrHeme <- scPassport(EndofrHeme, parent = WTHeme) # 4. Read passport anytime read_passport(EndofrHeme)
Maintainer: Sedat Kacar [email protected] (ORCID)
Useful links:
Report bugs at https://github.com/sedatkacar56/scPassport/issues
# Read passport on an unstamped object (prints "No passport found") if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() scPassport(se, read = TRUE) } # Stamp a root object (requires an existing Seurat object 'WTHeme') # WTHeme <- scPassport(WTHeme) # Stamp a child subset, linking to parent automatically # EndofrHeme <- scPassport(EndofrHeme, parent = WTHeme) # Read existing passport without opening popup # scPassport(WTHeme, read = TRUE) # Or use the dedicated read function # read_passport(WTHeme)# Read passport on an unstamped object (prints "No passport found") if (requireNamespace("SummarizedExperiment", quietly = TRUE)) { se <- SummarizedExperiment::SummarizedExperiment() scPassport(se, read = TRUE) } # Stamp a root object (requires an existing Seurat object 'WTHeme') # WTHeme <- scPassport(WTHeme) # Stamp a child subset, linking to parent automatically # EndofrHeme <- scPassport(EndofrHeme, parent = WTHeme) # Read existing passport without opening popup # scPassport(WTHeme, read = TRUE) # Or use the dedicated read function # read_passport(WTHeme)