sc_tools.validate — Checkpoint Validation#

Validates AnnData checkpoint files against the metadata contracts defined in Architecture.md Section 2.2.

from sc_tools.validate import validate_checkpoint

# Validate a Phase 1 checkpoint
validate_checkpoint("results/adata.raw.h5ad", phase="qc_filter")

# Validate with auto-fix (renames obs['batch'] -> obs['raw_data_dir'])
validate_checkpoint("results/adata.raw.h5ad", phase="qc_filter", fix=True)
sc_tools.validate.validate_checkpoint(adata, phase, *, strict=True, fix=False)[source]#

Validate an AnnData checkpoint against phase requirements.

Parameters:

  • adata (AnnData) – AnnData object to validate.

  • phase (str) –

    Phase identifier. Preferred — semantic slugs (new nomenclature): "qc_filter", "metadata_attach", "preprocess", "scoring", "celltype_manual".

    Legacy p-codes (old nomenclature, deprecated) are still accepted and emit a DeprecationWarning: "p1" → qc_filter, "p2" → metadata_attach, "p3" → preprocess, "p35" → scoring, "p4" → celltype_manual.

  • strict (bool) – If True, raise CheckpointValidationError on failures.

  • fix (bool) – If True, attempt auto-fixes (e.g., rename batch -> raw_data_dir).

Return type:

List of validation issue messages. Empty list means valid.

Raises:
sc_tools.validate.validate_file(path, phase, *, strict=True, fix=False)[source]#

Load an h5ad file and validate against phase requirements.

Parameters:

  • path (str | Path) – Path to .h5ad file.

  • phase (str) – Phase identifier. Preferred — semantic slugs (new nomenclature): "qc_filter", "metadata_attach", "preprocess", "scoring", "celltype_manual". Legacy p-codes (old nomenclature, deprecated): "p1" through "p4" and "p35" are still accepted but emit a DeprecationWarning.

  • strict (bool) – If True, raise CheckpointValidationError on failures.

  • fix (bool) – If True, attempt auto-fixes and re-save the file.

Return type:

List of validation issue messages.

sc_tools.validate.validate_p1(adata, *, fix=False)[source]#

Validate qc_filter / Phase 1 checkpoint (QC-filtered, concatenated data).

Deprecated since version old: nomenclature Call via validate_checkpoint(adata, phase="qc_filter") using the semantic slug. The name validate_p1 / phase code "p1" is old nomenclature retained for backward compatibility.

Checks that the following are present:

  • obs['sample']

  • obs['raw_data_dir'] (fix: rename from batch if present)

  • obsm['spatial']

  • X contains non-negative values (raw counts)

Return type:

list[str]

Parameters:
sc_tools.validate.validate_p2(adata, *, fix=False)[source]#

Validate metadata_attach / Phase 2 checkpoint (clinical metadata attached).

Deprecated since version old: nomenclature Call via validate_checkpoint(adata, phase="metadata_attach") using the semantic slug. The name validate_p2 / phase code "p2" is old nomenclature retained for backward compatibility.

Checks that the following are present:

  • All of qc_filter (p1)

  • At least one clinical metadata column beyond default obs columns

Return type:

list[str]

Parameters:
sc_tools.validate.validate_p3(adata, *, fix=False)[source]#

Validate preprocess / Phase 3 checkpoint (normalized, integrated, clustered).

Deprecated since version old: nomenclature Call via validate_checkpoint(adata, phase="preprocess") using the semantic slug. The name validate_p3 / phase code "p3" is old nomenclature retained for backward compatibility.

Checks that the following are present:

  • An integration/reduction representation in obsm (X_scvi, X_pca_harmony, X_cytovi, or X_pca)

  • A cluster column in obs (leiden, cluster, or louvain)

  • adata.raw is not None (backup of raw counts)

Return type:

list[str]

Parameters:
sc_tools.validate.validate_p35(adata, *, fix=False)[source]#

Validate scoring / Phase 3.5b checkpoint (gene signatures scored).

Deprecated since version old: nomenclature Call via validate_checkpoint(adata, phase="scoring") using the semantic slug. The name validate_p35 / phase code "p35" is old nomenclature retained for backward compatibility.

Checks that the following are present:

  • obsm['signature_score']

  • obsm['signature_score_z']

  • uns['signature_score_report']

Return type:

list[str]

Parameters:
sc_tools.validate.validate_p4(adata, *, fix=False)[source]#

Validate celltype_manual / Phase 4 checkpoint (cell types applied).

Deprecated since version old: nomenclature Call via validate_checkpoint(adata, phase="celltype_manual") using the semantic slug. The name validate_p4 / phase code "p4" is old nomenclature retained for backward compatibility.

Checks that the following are present:

  • All of scoring (p35)

  • obs['celltype']

  • obs['celltype_broad']

Return type:

list[str]

Parameters:
class sc_tools.validate.CheckpointValidationError[source]#

Bases: Exception

Raised when a checkpoint fails validation in strict mode.