Validation

The entry points, the report object they return, and the exceptions they raise.

Entry points

qc

qc(
    df: DataFrame,
    *,
    group_level: int | str | None = None,
    run_order=None,
    checks: tuple[str, ...] = (
        "completeness",
        "outliers",
        "mechanism",
        "codropouts",
    ),
    thresholds: dict | None = None,
    severity_overrides: dict | None = None,
    feature_type: str = "PROT",
    verbose: bool = False,
) -> MismapReport

Run a missing-data QC battery and return a MismapReport.

Parameters:

Name	Type	Description	Default
df	DataFrame	features (rows) x samples (columns). NaN = missing.	required
group_level	int or str	MultiIndex column level for per-group analyses. Required for the "batch" check and for per-group outlier z-scoring.	None
run_order	array - like	Per-sample run order (numeric). Required for the "runorder" check.	None
checks	tuple of str	Which checks to run. Available: "completeness", "outliers", "mechanism", "codropouts", "batch", "runorder".	('completeness', 'outliers', 'mechanism', 'codropouts')
thresholds	dict	Rule name -> threshold value. Triggers rule evaluation.	None
severity_overrides	dict	Rule name -> "error" | "warning" | "info". Overrides defaults.	None
feature_type	str	"PROT" | "GENE" | "PEPTIDE". Used by downstream rendering.	'PROT'
verbose	bool	Print progress per check.	False

Returns:

Type	Description
MismapReport

Examples:

>>> report = qc(df)
>>> report.passed
>>> report = qc(df, group_level="Condition")
>>> report.sample_outliers.query("flagged")
>>> report = qc(df, thresholds={"min_sample_completeness": 0.6})

assert_qc

assert_qc(
    df: DataFrame,
    *,
    thresholds: dict,
    severity_overrides: dict | None = None,
    **qc_kwargs,
) -> MismapReport

Run qc() and raise MismapQCFailure on any error-severity failure.

Warnings still emit via the warnings module but do not raise. Returns the populated MismapReport on success so the caller can keep using it.

Examples:

>>> assert_qc(df, thresholds={"min_sample_completeness": 0.1})
>>> assert_qc(df, thresholds={"max_mnar_fraction": 0.9}, group_level="Condition")

Results

MismapReport dataclass

Immutable snapshot of a QC analysis. Built by qc().

check

check(
    thresholds: dict, severity_overrides: dict | None = None
)

Re-evaluate thresholds against this report. Returns RuleResult tuple, does not raise.

passes

passes(
    thresholds: dict, severity_overrides: dict | None = None
) -> bool

True iff no error-severity rule would fail at these thresholds.

RuleResult dataclass

A single threshold-rule evaluation.

Exceptions and warnings

MismapQCFailure

Bases: AssertionError

Raised by assert_qc when one or more error-severity QC rules fail.

MismapQCWarning

Bases: UserWarning

Emitted when a warning-severity QC rule is violated.