viral-ngs: Skill for Claude Code

Assembly Regression Testing

End-to-end regression testing for assembly pipeline changes against Terra submissions.

When to Use

Use this playbook when a PR makes functional changes to the assembly or variant-calling pipeline (e.g., swapping variant callers, changing alignment parameters, modifying consensus logic). It compares assembly outputs from old vs new code across hundreds of real samples to validate equivalence or improvement.

Prerequisites

• gcloud CLI -- authenticated with access to Terra workspace GCS buckets
• mafft -- for pairwise sequence alignment
• Python with pandas and matplotlib (e.g., a dataviz venv)
• dsub -- for running VADR batch jobs on GCP (see the dsub-batch-jobs skill)

Workflow

Step 1: Set Up Terra Submissions (Manual)

The user must manually launch Terra submissions with old and new code:

1. Run the pipeline on a representative dataset using the main branch Docker image
2. Run the same pipeline on the same dataset using the feature branch Docker image
3. Note the submission IDs and workspace bucket for both runs

Step 2: Discover Paired Samples

Use discover_pairs.py to find all comparable old/new sample pairs by crawling GCS Cromwell output directories.

python discover_pairs.py \
  --bucket <workspace-bucket-id> \
  --old-sub <old-submission-id> \
  --new-sub <new-submission-id> \
  --output pairs.json

This produces a JSON mapping sample_name -> {old_tsv, new_tsv} for all samples present in both submissions.

Step 3: Compare Assembly Outputs

Use compare_sample_pair.py to compare each sample pair. This script:

• Downloads assembly_stats TSVs from GCS
• Compares metrics (coverage, % reference covered, length, etc.)
• Downloads FASTA assemblies and aligns them with mafft
• Reports SNPs, indels (events and bp), ambiguity diffs, and terminal extensions

python compare_sample_pair.py \
  --old-tsv <gcs_uri> --new-tsv <gcs_uri> \
  --work-dir ./results/<sample> \
  --output-json ./results/<sample>.json