Spike-in normalization crashes with unhelpful ZeroDivisionError when a replicate has 0 spike-in reads #139

Summary

When spike-in normalization is enabled (spikein: true in config.yaml) and any replicate has zero reads aligned to the spike-in genome, the pipeline crashes with an unhandled ZeroDivisionError instead of failing with a clear, actionable message.

Where

• workflow/rules/align.smk → compute_scaling_factors rule pipes per-replicate spike-in counts through:
• workflow/scripts/_compute_downsampling_scaling_factors.py:

  min_value = min(row[1] for row in data)
  for row in data:
      scaling_factor = min_value / row[1]   # <-- ZeroDivisionError if row[1] == 0

If a replicate has 0 spike-in reads (e.g. a contamination-free host-only library, a failed spike-in dilution, or a sample where the spike-in genome alignment legitimately returns nothing), the division above raises ZeroDivisionError: division by zero and the whole run stops. This also happens if every replicate has 0 counts (min_value == 0, so 0/0).

Why this matters

• The crash happens deep inside a Snakemake rule/container, so the traceback a user sees is generic and unhelpful — it does not say "replicate X has 0 spike-in reads" or suggest a fix (e.g. disable spike-in normalization, verify spike-in genome/index, exclude the offending replicate).
• This was flagged during a documentation audit (plans/PLAN_docs_audit_eli15.md, Ambiguity Finding Add Fastqscreen #4) — the spike-in normalization docs describe the method in depth but never document this failure mode.

Suggested fix

Add an explicit, early check in _compute_downsampling_scaling_factors.py (or in the compute_scaling_factors shell block before invoking the script) that:

1. Detects any replicate with a spike-in count of 0.
2. Raises a clear SystemExit/error message naming the offending replicate(s) and suggesting next steps (e.g. "replicate '' has 0 spike-in-aligned reads — verify the spike-in genome/index path, confirm spike-in material was actually added to this library, or set spikein: false if this sample should not use spike-in normalization").

This turns an opaque crash into a diagnosable, actionable error — without silently producing Inf/NaN scaling factors that could propagate into normalized counts/bigwigs unnoticed.

Related

• plans/PLAN_docs_audit_eli15.md — Ambiguity Finding Add Fastqscreen #4 (spike-in ~0 reads failure mode)

_{⚡ Generated using AI ⚡}