AnnData schema registry

smftools maintains a versioned AnnData schema registry to document the expected structure of each processing stage (raw, preprocess, spatial, hmm, and future). The registry captures the intended keys, data types, creators, and notes for each AnnData slot (obs, var, obsm, varm, layers, obsp, uns).

The runtime pipeline also records a live schema snapshot in adata.uns["smftools"]["schema"], along with a schema_registry_version field to link each file to the registry version used for documentation.

Schema registry version: 1

raw

Stage requires: None

obs

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
Experiment_name	category	smftools.cli.load_adata	``	None	None	Experiment identifier applied to all reads.
Experiment_name_and_barcode	category	smftools.cli.load_adata	``	obs.Experiment_name + obs.Barcode	None	Concatenated experiment name and barcode.
Barcode	category	smftools.informatics.modkit_extract_to_adata	``	None	None	Barcode assigned during demultiplexing or extraction.
read_length	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	Read length in bases.
mapped_length	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	Aligned length in bases.
reference_length	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	Reference length for alignment target.
read_quality	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	Per-read quality score.
mapping_quality	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	Mapping quality score.
reference_start	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	0-based reference start position for the alignment.
reference_end	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	None	None	0-based reference end position (exclusive) for the alignment.
read_length_to_reference_length_ratio	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	obs.read_length + obs.reference_length	None	Read length divided by reference length.
mapped_length_to_reference_length_ratio	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	obs.mapped_length + obs.reference_length	None	Mapped length divided by reference length.
mapped_length_to_read_length_ratio	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	``	obs.mapped_length + obs.read_length	None	Mapped length divided by read length.
Raw_modification_signal	float	smftools.informatics.h5ad_functions.add_read_length_and_mapping_qc	smftools.cli.load_adata	X OR layers.raw_mods	None	Summed modification signal per read.
pod5_origin	string	smftools.informatics.h5ad_functions.annotate_pod5_origin	``	obs_names	None	POD5 filename source for each read.
demux_type	category	smftools.informatics.h5ad_functions.add_demux_type_annotation	``	obs_names	None	Classification of demultiplexing status.
max_insertion_length	float	smftools.cli.raw_adata._attach_obs_metadata	``	obs.cigar	None	Longest internal insertion (bp) from the alignment CIGAR; consumed by preprocess's CIGAR-indel filter.
max_deletion_length	float	smftools.cli.raw_adata._attach_obs_metadata	``	obs.cigar	None	Longest internal deletion (bp) from the alignment CIGAR; consumed by preprocess's CIGAR-indel filter.
ct_event_count	int	smftools.informatics.ragged_store.alignment_to_ragged_record	``	obs.cigar	None	Per-read C->T (top-consistent) deamination event count, from the alignment CIGAR. Deaminase modality only.
ga_event_count	int	smftools.informatics.ragged_store.alignment_to_ragged_record	``	obs.cigar	None	Per-read G->A (bottom-consistent) deamination event count, from the alignment CIGAR. Deaminase modality only.
strand_segment_purity	float	smftools.informatics.ragged_store.alignment_to_ragged_record	``	obs.ct_event_count + obs.ga_event_count	None	Best two-segment purity of the ordered C->T/G->A vote track; ~1.0 for a pure read or a clean PCR chimera, lower for a noisy read. Deaminase modality only.
strand_switch_position	int	smftools.informatics.ragged_store.alignment_to_ragged_record	``	obs.ct_event_count + obs.ga_event_count	None	Reference coordinate of the best opposite-majority C->T/G->A split, or -1 if none. Deaminase modality only.

var

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
reference_position	int	smftools.informatics.modkit_extract_to_adata	``	None	None	Reference coordinate for each column.
reference_id	category	smftools.informatics.modkit_extract_to_adata	``	None	None	Reference contig or sequence name.

obsm

No entries defined.

varm

No entries defined.

layers

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
raw_mods	float	smftools.informatics.modkit_extract_to_adata	``	None	None	Raw modification scores (modality-dependent).

obsp

No entries defined.

uns

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
smftools	mapping	smftools.metadata.record_smftools_metadata	``	None	None	smftools metadata including history, environment, provenance, schema snapshot.

preprocess

Stage requires: raw

obs

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
sequence__merged_cluster_id	category	smftools.preprocessing.flag_duplicate_reads	``	layers.nan0_0minus1	obs.demux_type	Cluster identifier for duplicate detection.
deaminase_PCR_chimera	bool	smftools.preprocessing.label_deaminase_pcr_chimeras	``	obs.ct_event_count + obs.ga_event_count + obs.strand_segment_purity	None	Flags reads whose deamination signature switches from a C->T span to a G->A span partway through the read (PCR chimera evidence). Reads are labeled, not removed. Deaminase modality only.

var

No entries defined.

obsm

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
X_umap	float	smftools.tools.calculate_umap	``	X	None	UMAP embedding for preprocessed reads.

varm

No entries defined.

layers

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
nan0_0minus1	float	smftools.preprocessing.binarize	smftools.preprocessing.clean_NaN	X	None	Binarized methylation matrix (nan=0, 0=-1).

obsp

No entries defined.

uns

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
duplicate_read_groups	mapping	smftools.preprocessing.flag_duplicate_reads	``	obs.sequence__merged_cluster_id	None	Duplicate read group metadata.

spatial

Stage requires: raw, preprocess

obs

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
leiden	category	smftools.tools.calculate_leiden	``	obsm.X_umap	None	Leiden cluster assignments.

var

No entries defined.

obsm

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
X_umap	float	smftools.tools.calculate_umap	``	X	None	UMAP embedding for spatial analyses.

varm

No entries defined.

layers

No entries defined.

obsp

No entries defined.

uns

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
positionwise_result	mapping	smftools.tools.position_stats.compute_positionwise_statistics	``	X	obs.reference_column	Positionwise correlation statistics for spatial analyses.

hmm

Stage requires: raw, preprocess, spatial

obs

No entries defined.

var

No entries defined.

obsm

No entries defined.

varm

No entries defined.

layers

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
hmm_state_calls	int	smftools.hmm.call_hmm_peaks	``	layers.nan0_0minus1	None	HMM-derived state calls per read/position.

obsp

No entries defined.

uns

Key	Dtype	Created by	Modified by	Requires	Optional inputs	Notes
hmm_annotated	bool	smftools.cli.hmm_adata	``	layers.hmm_state_calls	None	Flag indicating HMM annotations are present.