@pikaa-ai/pikaa 0.3.1 → 0.3.4

package/skills/bioservices/scripts/protein_analysis_workflow.py

@@ -1,441 +0,0 @@
-#!/usr/bin/env python3
-"""
-Complete Protein Analysis Workflow
-
-This script performs a comprehensive protein analysis pipeline:
-1. UniProt search and identifier retrieval
-2. FASTA sequence retrieval
-3. BLAST similarity search
-4. KEGG pathway discovery
-5. PSICQUIC interaction mapping
-6. GO annotation retrieval
-
-Usage:
-    export NCBI_EMAIL=you@lab.org
-    python protein_analysis_workflow.py PROTEIN_NAME [EMAIL] [--skip-blast]
-
-Examples:
-    python protein_analysis_workflow.py ZAP70_HUMAN
-    python protein_analysis_workflow.py P43403 user@example.com --skip-blast
-
-Note: BLAST searches can take several minutes. Use --skip-blast to skip this step.
-Email is read from NCBI_EMAIL when the optional EMAIL argument is omitted.
-"""
-
-import os
-import re
-import sys
-import time
-import argparse
-from bioservices import UniProt, KEGG, NCBIblast, QuickGO
-
-try:
-    # PSICQUIC is not shipped by every bioservices release (it is absent from
-    # 1.16.0). Importing it unconditionally would take the whole workflow down
-    # over one optional step, so degrade instead.
-    from bioservices import PSICQUIC
-except ImportError:  # pragma: no cover - depends on the installed release
-    PSICQUIC = None
-
-_EMAIL_RE = re.compile(r"^[^@\s]+@[^@\s]+\.[^@\s]+$")
-
-
-def resolve_ncbi_email(cli_email=None):
-    """Return a validated NCBI contact email from CLI or NCBI_EMAIL."""
-    email = (cli_email or os.environ.get("NCBI_EMAIL", "")).strip()
-    if email and _EMAIL_RE.match(email):
-        return email
-    return None
-
-
-def search_protein(query):
-    """Search UniProt for protein and retrieve basic information."""
-    print(f"\n{'='*70}")
-    print("STEP 1: UniProt Search")
-    print(f"{'='*70}")
-
-    u = UniProt(verbose=False)
-
-    print(f"Searching for: {query}")
-
-    # Try direct retrieval first (if query looks like accession)
-    if len(query) == 6 and query[0] in "OPQ":
-        try:
-            entry = u.retrieve(query, frmt="tab")
-            if entry:
-                uniprot_id = query
-                print(f"✓ Found UniProt entry: {uniprot_id}")
-                return u, uniprot_id
-        except:
-            pass
-
-    # Otherwise search
-    results = u.search(query, frmt="tab", columns="id,genes,organism,length,protein names", limit=5)
-
-    if not results:
-        print("✗ No results found")
-        return u, None
-
-    lines = results.strip().split("\n")
-    if len(lines) < 2:
-        print("✗ No entries found")
-        return u, None
-
-    # Display results
-    print(f"\n✓ Found {len(lines)-1} result(s):")
-    for i, line in enumerate(lines[1:], 1):
-        fields = line.split("\t")
-        print(f"  {i}. {fields[0]} - {fields[1]} ({fields[2]})")
-
-    # Use first result
-    first_entry = lines[1].split("\t")
-    uniprot_id = first_entry[0]
-    gene_names = first_entry[1] if len(first_entry) > 1 else "N/A"
-    organism = first_entry[2] if len(first_entry) > 2 else "N/A"
-    length = first_entry[3] if len(first_entry) > 3 else "N/A"
-    protein_name = first_entry[4] if len(first_entry) > 4 else "N/A"
-
-    print(f"\nUsing first result:")
-    print(f"  UniProt ID: {uniprot_id}")
-    print(f"  Gene names: {gene_names}")
-    print(f"  Organism: {organism}")
-    print(f"  Length: {length} aa")
-    print(f"  Protein: {protein_name}")
-
-    return u, uniprot_id
-
-
-def retrieve_sequence(uniprot, uniprot_id):
-    """Retrieve FASTA sequence for protein."""
-    print(f"\n{'='*70}")
-    print("STEP 2: FASTA Sequence Retrieval")
-    print(f"{'='*70}")
-
-    try:
-        sequence = uniprot.retrieve(uniprot_id, frmt="fasta")
-
-        if sequence:
-            # Extract sequence only (remove header)
-            lines = sequence.strip().split("\n")
-            header = lines[0]
-            seq_only = "".join(lines[1:])
-
-            print(f"✓ Retrieved sequence:")
-            print(f"  Header: {header}")
-            print(f"  Length: {len(seq_only)} residues")
-            print(f"  First 60 residues: {seq_only[:60]}...")
-
-            return seq_only
-        else:
-            print("✗ Failed to retrieve sequence")
-            return None
-
-    except Exception as e:
-        print(f"✗ Error: {e}")
-        return None
-
-
-def run_blast(sequence, email, skip=False):
-    """Run BLAST similarity search."""
-    print(f"\n{'='*70}")
-    print("STEP 3: BLAST Similarity Search")
-    print(f"{'='*70}")
-
-    if skip:
-        print("⊘ Skipped (--skip-blast flag)")
-        return None
-
-    if not email:
-        print("⊘ Skipped (set NCBI_EMAIL or pass email for BLAST)")
-        return None
-
-    try:
-        print(f"Submitting BLASTP job...")
-        print(f"  Database: uniprotkb")
-        print(f"  Sequence length: {len(sequence)} aa")
-
-        s = NCBIblast(verbose=False)
-
-        jobid = s.run(
-            program="blastp",
-            sequence=sequence,
-            stype="protein",
-            database="uniprotkb",
-            email=email
-        )
-
-        print(f"✓ Job submitted: {jobid}")
-        print(f"  Waiting for completion...")
-
-        # Poll for completion
-        max_wait = 300  # 5 minutes
-        start_time = time.time()
-
-        while time.time() - start_time < max_wait:
-            status = s.getStatus(jobid)
-            elapsed = int(time.time() - start_time)
-            print(f"  Status: {status} (elapsed: {elapsed}s)", end="\r")
-
-            if status == "FINISHED":
-                print(f"\n✓ BLAST completed in {elapsed}s")
-
-                # Retrieve results
-                results = s.getResult(jobid, "out")
-
-                # Parse and display summary
-                lines = results.split("\n")
-                print(f"\n  Results preview:")
-                for line in lines[:20]:
-                    if line.strip():
-                        print(f"    {line}")
-
-                return results
-
-            elif status == "ERROR":
-                print(f"\n✗ BLAST job failed")
-                return None
-
-            time.sleep(5)
-
-        print(f"\n✗ Timeout after {max_wait}s")
-        return None
-
-    except Exception as e:
-        print(f"✗ Error: {e}")
-        return None
-
-
-def discover_pathways(uniprot, kegg, uniprot_id):
-    """Discover KEGG pathways for protein."""
-    print(f"\n{'='*70}")
-    print("STEP 4: KEGG Pathway Discovery")
-    print(f"{'='*70}")
-
-    try:
-        # Map UniProt → KEGG
-        print(f"Mapping {uniprot_id} to KEGG...")
-        kegg_mapping = uniprot.mapping(fr="UniProtKB_AC-ID", to="KEGG", query=uniprot_id)
-
-        if not kegg_mapping or uniprot_id not in kegg_mapping:
-            print("✗ No KEGG mapping found")
-            return []
-
-        kegg_ids = kegg_mapping[uniprot_id]
-        print(f"✓ KEGG ID(s): {kegg_ids}")
-
-        # Get pathways for first KEGG ID
-        kegg_id = kegg_ids[0]
-        organism, gene_id = kegg_id.split(":")
-
-        print(f"\nSearching pathways for {kegg_id}...")
-        pathways = kegg.get_pathway_by_gene(gene_id, organism)
-
-        if not pathways:
-            print("✗ No pathways found")
-            return []
-
-        print(f"✓ Found {len(pathways)} pathway(s):\n")
-
-        # Get pathway names
-        pathway_info = []
-        for pathway_id in pathways:
-            try:
-                entry = kegg.get(pathway_id)
-
-                # Extract pathway name
-                pathway_name = "Unknown"
-                for line in entry.split("\n"):
-                    if line.startswith("NAME"):
-                        pathway_name = line.replace("NAME", "").strip()
-                        break
-
-                pathway_info.append((pathway_id, pathway_name))
-                print(f"  • {pathway_id}: {pathway_name}")
-
-            except Exception as e:
-                print(f"  • {pathway_id}: [Error retrieving name]")
-
-        return pathway_info
-
-    except Exception as e:
-        print(f"✗ Error: {e}")
-        return []
-
-
-def find_interactions(protein_query):
-    """Find protein-protein interactions via PSICQUIC."""
-    print(f"\n{'='*70}")
-    print("STEP 5: Protein-Protein Interactions")
-    print(f"{'='*70}")
-
-    if PSICQUIC is None:
-        print("⊘ Skipped (this bioservices release does not ship PSICQUIC)")
-        return []
-
-    try:
-        p = PSICQUIC()
-
-        # Try querying MINT database
-        query = f"{protein_query} AND species:9606"
-        print(f"Querying MINT database...")
-        print(f"  Query: {query}")
-
-        results = p.query("mint", query)
-
-        if not results:
-            print("✗ No interactions found in MINT")
-            return []
-
-        # Parse PSI-MI TAB format
-        lines = results.strip().split("\n")
-        print(f"✓ Found {len(lines)} interaction(s):\n")
-
-        # Display first 10 interactions
-        interactions = []
-        for i, line in enumerate(lines[:10], 1):
-            fields = line.split("\t")
-            if len(fields) >= 12:
-                protein_a = fields[4].split(":")[1] if ":" in fields[4] else fields[4]
-                protein_b = fields[5].split(":")[1] if ":" in fields[5] else fields[5]
-                interaction_type = fields[11]
-
-                interactions.append((protein_a, protein_b, interaction_type))
-                print(f"  {i}. {protein_a} ↔ {protein_b}")
-
-        if len(lines) > 10:
-            print(f"  ... and {len(lines)-10} more")
-
-        return interactions
-
-    except Exception as e:
-        print(f"✗ Error: {e}")
-        return []
-
-
-def get_go_annotations(uniprot_id):
-    """Retrieve GO annotations."""
-    print(f"\n{'='*70}")
-    print("STEP 6: Gene Ontology Annotations")
-    print(f"{'='*70}")
-
-    try:
-        g = QuickGO()
-
-        print(f"Retrieving GO annotations for {uniprot_id}...")
-        annotations = g.Annotation(protein=uniprot_id, format="tsv")
-
-        if not annotations:
-            print("✗ No GO annotations found")
-            return []
-
-        lines = annotations.strip().split("\n")
-        print(f"✓ Found {len(lines)-1} annotation(s)\n")
-
-        # Group by aspect
-        aspects = {"P": [], "F": [], "C": []}
-        for line in lines[1:]:
-            fields = line.split("\t")
-            if len(fields) >= 9:
-                go_id = fields[6]
-                go_term = fields[7]
-                go_aspect = fields[8]
-
-                if go_aspect in aspects:
-                    aspects[go_aspect].append((go_id, go_term))
-
-        # Display summary
-        print(f"  Biological Process (P): {len(aspects['P'])} terms")
-        for go_id, go_term in aspects['P'][:5]:
-            print(f"    • {go_id}: {go_term}")
-        if len(aspects['P']) > 5:
-            print(f"    ... and {len(aspects['P'])-5} more")
-
-        print(f"\n  Molecular Function (F): {len(aspects['F'])} terms")
-        for go_id, go_term in aspects['F'][:5]:
-            print(f"    • {go_id}: {go_term}")
-        if len(aspects['F']) > 5:
-            print(f"    ... and {len(aspects['F'])-5} more")
-
-        print(f"\n  Cellular Component (C): {len(aspects['C'])} terms")
-        for go_id, go_term in aspects['C'][:5]:
-            print(f"    • {go_id}: {go_term}")
-        if len(aspects['C']) > 5:
-            print(f"    ... and {len(aspects['C'])-5} more")
-
-        return aspects
-
-    except Exception as e:
-        print(f"✗ Error: {e}")
-        return {}
-
-
-def main():
-    """Main workflow."""
-    parser = argparse.ArgumentParser(
-        description="Complete protein analysis workflow using BioServices",
-        formatter_class=argparse.RawDescriptionHelpFormatter,
-        epilog="""
-Examples:
-  export NCBI_EMAIL=you@lab.org
-  python protein_analysis_workflow.py ZAP70_HUMAN
-  python protein_analysis_workflow.py P43403 user@example.com --skip-blast
-        """
-    )
-    parser.add_argument("protein", help="Protein name or UniProt ID")
-    parser.add_argument(
-        "email",
-        nargs="?",
-        default=None,
-        help="NCBI contact email (optional if NCBI_EMAIL is set)",
-    )
-    parser.add_argument("--skip-blast", action="store_true",
-                       help="Skip BLAST search (faster)")
-
-    args = parser.parse_args()
-
-    print("=" * 70)
-    print("BIOSERVICES: Complete Protein Analysis Workflow")
-    print("=" * 70)
-
-    # Step 1: Search protein
-    uniprot, uniprot_id = search_protein(args.protein)
-    if not uniprot_id:
-        print("\n✗ Failed to find protein. Exiting.")
-        sys.exit(1)
-
-    # Step 2: Retrieve sequence
-    sequence = retrieve_sequence(uniprot, uniprot_id)
-    if not sequence:
-        print("\n⚠ Warning: Could not retrieve sequence")
-
-    # Step 3: BLAST search
-    ncbi_email = resolve_ncbi_email(args.email)
-    if sequence:
-        blast_results = run_blast(sequence, ncbi_email, args.skip_blast)
-
-    # Step 4: Pathway discovery
-    kegg = KEGG()
-    pathways = discover_pathways(uniprot, kegg, uniprot_id)
-
-    # Step 5: Interaction mapping
-    interactions = find_interactions(args.protein)
-
-    # Step 6: GO annotations
-    go_terms = get_go_annotations(uniprot_id)
-
-    # Summary
-    print(f"\n{'='*70}")
-    print("WORKFLOW SUMMARY")
-    print(f"{'='*70}")
-    print(f"  Protein: {args.protein}")
-    print(f"  UniProt ID: {uniprot_id}")
-    print(f"  Sequence: {'✓' if sequence else '✗'}")
-    print(f"  BLAST: {'✓' if not args.skip_blast and sequence else '⊘'}")
-    print(f"  Pathways: {len(pathways)} found")
-    print(f"  Interactions: {len(interactions)} found")
-    print(f"  GO annotations: {sum(len(v) for v in go_terms.values())} found")
-    print(f"{'='*70}")
-
-
-if __name__ == "__main__":
-    main()

package/skills/bulk-rnaseq/references/counts-and-handoff.md

@@ -1,91 +0,0 @@
-# Counts assembly and handoff to DE + enrichment
-
-Goal: turn quant output into the two files the **`pydeseq2`** skill wants, then rank/threshold the DE result for the **`pathway-enrichment`** skill.
-
-- `counts.csv` — a **gene × sample** matrix of **integers** (raw or length-scaled counts; never TPM/FPKM).
-- `metadata.csv` — one row per sample (index = sample IDs matching the count columns), columns describing the design (`condition`, `batch`, …).
-
-`scripts/build_counts_matrix.py` produces both. This file explains what it does and the nuances you must get right.
-
-## Orientation (don't trip on this)
-
-PyDESeq2 ultimately needs **samples × genes**. By convention this skill writes `counts.csv` as **genes × samples** (matches Salmon/STAR/featureCounts and nf-core outputs), and the `pydeseq2` skill's loader transposes with `.T`. Keep `counts.csv` genes × samples and let the DE step transpose — don't transpose twice.
-
-## Salmon → gene counts (pytximport)
-
-Salmon is transcript-level; sum to genes with `pytximport` (the Python port of tximport). Use `counts_from_abundance="length_scaled_tpm"` — the correct choice for gene-level DE (corrects for differential transcript-length/usage across samples and yields counts you can feed directly).
-
-```python
-from pytximport import tximport
-
-quant_files = ["quant/s1/quant.sf", "quant/s2/quant.sf", "quant/s3/quant.sf"]
-txi = tximport(
-    quant_files,
-    data_type="salmon",
-    transcript_gene_map="tx2gene.tsv",          # columns: transcript_id, gene_id
-    counts_from_abundance="length_scaled_tpm",
-    output_type="xarray",
-    ignore_transcript_version=True,              # drops the .N Ensembl version suffix
-)
-# txi holds gene x sample estimated counts; round to integers for PyDESeq2 (see below).
-```
-
-The bundled `scripts/build_counts_matrix.py --from salmon --quant-dir quant/ --tx2gene tx2gene.tsv` wraps this, names columns by sample directory, rounds, and writes `counts.csv` + `metadata_template.csv`.
-
-### Getting a tx2gene map
-
-A two-column transcript_id → gene_id table. Options:
-- `pytximport.utils.create_transcript_gene_map(species="human")` (or `human`/`mouse` etc.).
-- From the annotation GTF (authoritative — matches your quant reference):
-
-```bash
-awk -F'\t' '$3=="transcript"{ match($9,/transcript_id "([^"]+)"/,t); match($9,/gene_id "([^"]+)"/,g); print t[1]"\t"g[1] }' \
-  annotation.gtf | sort -u | sed '1i transcript_id\tgene_id' > tx2gene.tsv
-```
-
-- nf-core/rnaseq writes the tx2gene it actually used into its output — reuse that on Path A.
-
-## STAR → gene counts (ReadsPerGene)
-
-Each `*.ReadsPerGene.out.tab` has 4 columns: gene_id, unstranded, forward-strand, reverse-strand. Skip STAR's first 4 summary rows (`N_unmapped`, …) and pick the column matching your strandedness (col index 1/2/3 → unstranded/forward/reverse). `scripts/build_counts_matrix.py --from star --quant-dir star/ --strandedness reverse` does this across all samples. These are already integers.
-
-## featureCounts → gene counts
-
-`featureCounts` writes one matrix with a header comment line, then columns: `Geneid, Chr, Start, End, Strand, Length, <bam1>, <bam2>, …`. Keep `Geneid` + the per-BAM count columns, rename columns to sample IDs. `scripts/build_counts_matrix.py --from featurecounts --counts-file counts/featurecounts.txt` handles it. Already integers.
-
-## The estimated-count / integer nuance
-
-PyDESeq2 requires **integer** counts. STAR and featureCounts give integers already. Salmon/RSEM give **estimated** (fractional) counts.
-
-- **What this skill does:** use `length_scaled_tpm` and **round to the nearest integer**. With length-scaled counts the library-size and transcript-length information is already folded into the values, so rounding and treating them as counts is a well-established, defensible approximation for gene-level DE.
-- **The "proper" R route** (`tximport` → `DESeqDataSetFromTximport`) instead imports raw counts plus a per-gene **average-transcript-length offset**, letting DESeq2 model length internally. PyDESeq2 does not accept that offset, so the length-scaled-and-round approach is the standard Python equivalent and is what tools like nf-core surface for downstream use.
-- Either way: **never** feed TPM/FPKM to DESeq2 — those are normalized and break the count model.
-
-## Gene-ID mapping (do this before enrichment)
-
-DESeq2 output is typically keyed by **Ensembl gene IDs** (e.g. `ENSG00000141510`), often with a version suffix (`.17`). Enrichr/MSigDB/g:Profiler libraries expect **gene symbols** (human UPPERCASE). Mapping mismatch is the #1 cause of "nothing is enriched".
-
-- Strip version suffixes: `ids.str.replace(r"\.\d+$", "", regex=True)`.
-- Map Ensembl → symbol with the `gget` skill (`gget info`), `database-lookup`, `pybiomart`, or `mygene`. On Path A, the nf-core `gene_name` column already gives symbols — keep it alongside `gene_id`.
-- Keep mapping for *enrichment input*; you can keep Ensembl IDs through DE and map only the final gene lists.
-
-## DE → enrichment recipe
-
-After the `pydeseq2` skill produces `deseq2_results.csv` (columns include `log2FoldChange`, `pvalue`, `padj`, `stat`):
-
-- **GSEA (preranked)** — use the **full** ranked gene list, ranked by the Wald `stat` (sign = direction, magnitude = evidence; more stable than ranking by log2FoldChange). Don't threshold first.
-- **ORA** — use the **thresholded** hit list: `padj < 0.05`, optionally also `|log2FoldChange| > 1`; consider running up- and down-regulated sets separately.
-
-The `pathway-enrichment` skill's `scripts/run_enrichment.py` reads a DESeq2 results CSV directly:
-
-```bash
-# GSEA straight from the DE table (auto-builds the rank from `stat`)
-python ../pathway-enrichment/scripts/run_enrichment.py gsea \
-  --deseq2 deseq2_results.csv --organism human --outdir enrichment/ --seed 123
-
-# ORA from a symbol hit list
-python ../pathway-enrichment/scripts/run_enrichment.py ora \
-  --genes sig_symbols.txt --organism human --outdir enrichment/
-```
-
-Make sure the IDs in `deseq2_results.csv` / `sig_symbols.txt` are symbols (or map them first). Then visualize with the `scientific-visualization` skill.

package/skills/bulk-rnaseq/references/design-and-qc.md

@@ -1,68 +0,0 @@
-# Experimental design and QC
-
-The statistics downstream are only as good as the design and the QC gates. Decide design **before** sequencing; apply QC **before, during, and after** quantification. This is what makes a bulk RNA-seq result defensible.
-
-## Experimental design
-
-### Replication
-- Use **biological** replicates (independent samples), not technical (same library re-sequenced). Technical replicates measure machine noise, not biological variability, and don't license generalization.
-- **≥3 per group is the practical minimum**; 4–6 is much safer for typical effect sizes. With n=2 you cannot estimate within-group variance reliably and DESeq2's dispersion shrinkage is doing almost all the work.
-- More replicates beat more depth for detecting DE. Don't trade replicates for coverage.
-
-### Depth, length, layout
-- ~20–30M mapped reads/sample is enough for standard gene-level DE. Push higher (50M+) for lowly expressed genes, novel transcripts, or isoform-level work.
-- Paired-end and longer reads help mapping/isoforms but aren't required for gene-level DE; single-end is fine if that's what you have.
-- Keep layout, read length, kit, and depth **consistent across all samples** in a comparison.
-
-### Avoid confounding (the design killer)
-- A **batch** is anything technical that varies across samples: processing day, sequencing lane/flowcell, kit lot, operator, RNA extraction round.
-- If a batch is perfectly aligned with your condition (all treated processed Monday, all controls Tuesday), the biological effect is **mathematically unrecoverable**. No analysis fixes this.
-- Defenses: **randomize** sample-to-batch assignment, and **balance** so every batch contains every condition. Record all batch variables in the metadata.
-
-### Design formulas (hand to PyDESeq2)
-- Put adjustment variables first, the variable of interest **last**: `~batch + condition`.
-- Continuous covariate: `~age + condition` (ensure it's numeric).
-- Interaction (does the treatment effect differ by genotype?): `~genotype + condition + genotype:condition`.
-- The design matrix must be **full rank** — you can't include a batch that's perfectly confounded with condition; `pydeseq2` will error. Check `pd.crosstab(metadata.condition, metadata.batch)` for empty cells.
-
-## QC gates
-
-### Raw-read QC (FastQC / MultiQC)
-- **Per-base quality** — bulk of bases ≥ Q30; some drop at read ends is normal (trimming/soft-clipping handles it).
-- **Adapter content** — flagged adapters → trim (Path B step 2; Path A does it automatically).
-- **Over-represented sequences** — adapters, rRNA, or highly expressed transcripts. Persistent rRNA suggests poor depletion.
-- **GC content** — a bimodal/odd distribution can indicate contamination.
-- **Sequence duplication** — high duplication is *expected* in RNA-seq (highly expressed genes); see below.
-
-### Alignment / quantification QC
-- **STAR uniquely-mapped %** — typically >70–80% for a good library/reference. Low → wrong/old reference, contamination, or degraded RNA.
-- **Salmon mapping rate** (`logs/salmon_quant.log`) — usually >70%. Low → wrong transcriptome, no decoys, or contamination.
-- **featureCounts assigned %** — low "assigned" with high "unassigned_NoFeatures" often means **wrong strandedness** (`-s`).
-- **rRNA fraction** — high rRNA wastes reads; note it, and consider `--remove_ribo_rna` on Path A.
-- Verify **strandedness** matches across tools (see `upstream-manual.md`).
-
-### Don't deduplicate for standard DE
-PCR/optical duplicates look alarming but in RNA-seq mostly reflect genuine high expression. Standard gene-level DE (DESeq2) does **not** remove duplicates. Only consider dedup with UMIs (use the UMI, not coordinate dedup).
-
-### Post-quantification QC (before trusting DE)
-Always do this on the counts, ideally on variance-stabilized/log values:
-- **PCA** — do biological replicates cluster? Does the main axis separate your condition, or a batch? A batch dominating PC1 means you must model it. An obvious outlier may be a swap/failure.
-- **Sample-distance heatmap / hierarchical clustering** — confirms grouping and exposes mislabeled or swapped samples.
-- If a batch clearly structures the data, add it to the design (`~batch + condition`); if it's unknown, consider surrogate-variable / RUV approaches (out of scope here — note it).
-
-### After DE: p-value histogram
-- A well-behaved test gives a roughly **uniform** histogram with a **peak near 0** (the true positives).
-- A peak near 1, or a U-shape, signals a problem: misspecified design, unmodeled batch, or filtering issues. Fix the design rather than trusting the gene list.
-
-## Quick gate checklist
-
-```
-[ ] >=3 biological replicates per group
-[ ] batch recorded and NOT confounded with condition
-[ ] raw FastQC reviewed; adapters trimmed
-[ ] mapping/assignment rate acceptable; strandedness verified
-[ ] PCA + sample-distance heatmap inspected; outliers/swaps resolved
-[ ] design formula full-rank, adjustment vars before variable of interest
-[ ] p-value histogram sane after DE
-[ ] versions pinned (pipeline -r, tools, genome+annotation release)
-```