Bioinformatics analysis preflight

Bioinformatics Analysis Preflight

Overview

Run a local, deterministic preflight before spending compute or trusting biological results. The skill does not replace workflow-specific skills; it catches the cross-cutting mistakes those workflows often inherit: mismatched sample IDs, broken file paths, confounded metadata, missing alignment indexes, normalized values passed as counts, weak provenance, and privacy-risky cloud assumptions.

Core Workflow

1. Inventory inputs. Inspect the project tree and classify FASTQ, BAM/CRAM, VCF, h5ad, count matrix, metadata, sample sheet, and report files. Do not upload genomic or clinical data.
2. Run deterministic preflight. Use scripts/bio_preflight.py whenever the user has local files or asks "is this ready to analyze?"
3. Interpret severity. Treat FAIL findings as blockers, WARN findings as risks to resolve or disclose, and PASS findings as evidence, not proof.
4. Route downstream. After blockers are fixed, hand off to domain skills such as bulk RNA-seq, Scanpy/Seurat, variant annotation, ATAC/ChIP, microbiome, proteomics, or workflow-management skills.
5. Preserve provenance. Keep the generated Markdown and JSON reports with the analysis outputs.

Quick Start

python bioinformatics-analysis-preflight/scripts/bio_preflight.py \
  --root . \
  --metadata metadata.csv \
  --counts counts.csv \
  --sample-sheet samplesheet.csv \
  --condition-column condition \
  --batch-column batch \
  --output-dir preflight

If the user only provides a project directory, scan it and let the script auto-detect likely inputs:

python bioinformatics-analysis-preflight/scripts/bio_preflight.py \
  --root /path/to/project \
  --output-dir /path/to/project/preflight

For CI-style use, fail the command when blocking issues are found:

python bioinformatics-analysis-preflight/scripts/bio_preflight.py \
  --root . --metadata metadata.csv --counts counts.csv --fail-on fail

What The Script Checks

The script uses only the Python standard library and writes:

• analysis-preflight-report.md - human-readable summary and next actions.
• analysis-preflight.json - machine-readable manifest, inventory, and findings.

It checks:

• sample metadata: duplicate IDs, missing IDs, likely condition/batch columns, weak replication, and batch-condition confounding.
• count matrices: gene/sample orientation clues, duplicate genes, duplicate sample columns, negative values, non-integer values, and metadata/count sample mismatches.
• sample sheets: required sample/path columns, duplicate samples, missing FASTQ/BAM paths, mixed single/paired layout, and strandedness values.
• FASTQ files: common R1/R2 pairing patterns and first-record structure for a limited sample of files.
• BAM/CRAM files: missing .bai, .csi, or .crai sidecar indexes.
• VCF files: header presence, sample columns, and contig metadata.
• h5ad files: HDF5 magic-byte sanity check.

Agent Decision Rules

• Run the preflight before launching expensive workflows, changing data, or making biological claims from new user data.
• Ask before installing heavy bioinformatics tools; this skill's script intentionally avoids extra dependencies.
• Do not send genomic, clinical, or unpublished omics data to external services unless the user explicitly approves that specific transfer.
• Do not treat a clean preflight as scientific validation. It only validates readiness and common failure modes.
• If a workflow-specific skill has a stricter preflight, use both: this skill for cross-project audit and the workflow skill for method-specific validation.

Detailed References

• references/risk-rubric.md - severity definitions, blocker policy, and how to phrase residual risks.
• references/modality-checklists.md - domain-specific checks for bulk RNA-seq, single-cell, variants, epigenomics, microbiome, proteomics, and multi-omics.
• references/report-template.md - recommended structure for the final preflight response to the user.