opencode-knowledge-work 0.0.0-stage → 0.1.0

package/content/bio-research/skills/bio-research-nextflow-development/references/pipelines/rnaseq.md

@@ -0,0 +1,118 @@
+# nf-core/rnaseq
+
+**Version:** 3.22.2
+
+**Official Documentation:** https://nf-co.re/rnaseq/3.22.2/
+**GitHub:** https://github.com/nf-core/rnaseq
+
+> **Note:** When updating to a new version, check the [releases page](https://github.com/nf-core/rnaseq/releases) for breaking changes and update the version in commands below.
+
+## Contents
+- [Test command](#test-command)
+- [Samplesheet format](#samplesheet-format)
+- [Parameters](#parameters)
+- [Output files](#output-files)
+- [Downstream analysis](#downstream-analysis)
+
+## Test command
+
+```bash
+nextflow run nf-core/rnaseq -r 3.22.2 -profile test,docker --outdir test_rnaseq
+```
+
+Expected: ~15 min, creates `multiqc/multiqc_report.html`.
+
+## Samplesheet format
+
+```csv
+sample,fastq_1,fastq_2,strandedness
+CONTROL_REP1,/path/to/ctrl1_R1.fq.gz,/path/to/ctrl1_R2.fq.gz,auto
+CONTROL_REP2,/path/to/ctrl2_R1.fq.gz,/path/to/ctrl2_R2.fq.gz,auto
+TREATMENT_REP1,/path/to/treat1_R1.fq.gz,/path/to/treat1_R2.fq.gz,auto
+```
+
+| Column | Required | Values |
+|--------|----------|--------|
+| sample | Yes | Alphanumeric, underscores allowed |
+| fastq_1 | Yes | Absolute path to R1 |
+| fastq_2 | No | Absolute path to R2 (empty for single-end) |
+| strandedness | Yes | `auto`, `forward`, `reverse`, `unstranded` |
+
+**Strandedness guide:**
+- `auto`: Inferred from data (recommended)
+- `forward`: TruSeq Stranded, dUTP protocols
+- `reverse`: Ligation-based protocols
+- `unstranded`: Non-stranded protocols
+
+## Parameters
+
+### Minimal run
+```bash
+nextflow run nf-core/rnaseq -r 3.22.2 -profile docker \
+    --input samplesheet.csv --outdir results --genome GRCh38
+```
+
+### Common parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--aligner` | `star_salmon` | Options: `star_salmon`, `star_rsem`, `hisat2` |
+| `--genome` | - | `GRCh38`, `GRCh37`, `mm10`, `BDGP6` |
+| `--pseudo_aligner` | - | Set to `salmon` for pseudo-alignment only |
+| `--skip_trimming` | false | Skip adapter trimming |
+| `--skip_alignment` | false | Pseudo-alignment only |
+
+### Custom reference
+```bash
+--fasta /path/to/genome.fa \
+--gtf /path/to/annotation.gtf \
+--star_index /path/to/star/  # Optional, builds if absent
+```
+
+## Output files
+
+```
+results/
+├── star_salmon/
+│   ├── salmon.merged.gene_counts.tsv    # Raw counts for DESeq2
+│   ├── salmon.merged.gene_tpm.tsv       # TPM values
+│   └── *.bam                            # Alignments
+├── multiqc/
+│   └── multiqc_report.html              # QC summary
+└── pipeline_info/
+```
+
+**Key outputs:**
+- `salmon.merged.gene_counts.tsv`: Input for DESeq2/edgeR
+- `salmon.merged.gene_tpm.tsv`: Normalized expression
+
+## Downstream analysis
+
+```r
+library(DESeq2)
+counts <- read.delim("salmon.merged.gene_counts.tsv", row.names=1)
+coldata <- data.frame(
+    condition = factor(c("control", "control", "treatment", "treatment"))
+)
+dds <- DESeqDataSetFromMatrix(
+    countData = round(counts),
+    colData = coldata,
+    design = ~ condition
+)
+dds <- DESeq(dds)
+res <- results(dds, contrast = c("condition", "treatment", "control"))
+```
+
+## Troubleshooting
+
+**STAR index fails**: Increase memory with `--max_memory '64.GB'` or provide pre-built `--star_index`.
+
+**Low alignment rate**: Verify genome matches species; check FastQC for adapter contamination.
+
+**Strandedness detection fails**: Specify explicitly with `--strandedness reverse`.
+
+## More Information
+
+- **Full parameter list:** https://nf-co.re/rnaseq/3.22.2/parameters/
+- **Output documentation:** https://nf-co.re/rnaseq/3.22.2/docs/output/
+- **Usage documentation:** https://nf-co.re/rnaseq/3.22.2/docs/usage/

package/content/bio-research/skills/bio-research-nextflow-development/references/pipelines/sarek.md

@@ -0,0 +1,145 @@
+# nf-core/sarek
+
+**Version:** 3.7.1
+
+**Official Documentation:** https://nf-co.re/sarek/3.7.1/
+**GitHub:** https://github.com/nf-core/sarek
+
+> **Note:** When updating to a new version, check the [releases page](https://github.com/nf-core/sarek/releases) for breaking changes and update the version in commands below.
+
+## Contents
+- [Test command](#test-command)
+- [Samplesheet format](#samplesheet-format)
+- [Variant calling modes](#variant-calling-modes)
+- [Parameters](#parameters)
+- [Output files](#output-files)
+
+## Test command
+
+```bash
+nextflow run nf-core/sarek -r 3.7.1 -profile test,docker --outdir test_sarek
+```
+
+Expected: ~20 min, creates aligned BAMs and variant calls.
+
+## Samplesheet format
+
+### From FASTQ
+```csv
+patient,sample,lane,fastq_1,fastq_2
+patient1,tumor,L001,/path/to/tumor_L001_R1.fq.gz,/path/to/tumor_L001_R2.fq.gz
+patient1,tumor,L002,/path/to/tumor_L002_R1.fq.gz,/path/to/tumor_L002_R2.fq.gz
+patient1,normal,L001,/path/to/normal_R1.fq.gz,/path/to/normal_R2.fq.gz
+```
+
+### From BAM/CRAM
+```csv
+patient,sample,bam,bai
+patient1,tumor,/path/to/tumor.bam,/path/to/tumor.bam.bai
+patient1,normal,/path/to/normal.bam,/path/to/normal.bam.bai
+```
+
+### With tumor/normal status
+```csv
+patient,sample,lane,fastq_1,fastq_2,status
+patient1,tumor,L001,tumor_R1.fq.gz,tumor_R2.fq.gz,1
+patient1,normal,L001,normal_R1.fq.gz,normal_R2.fq.gz,0
+```
+
+`status`: 0 = normal, 1 = tumor
+
+## Variant calling modes
+
+### Germline (single sample)
+```bash
+nextflow run nf-core/sarek -r 3.7.1 -profile docker \
+    --input samplesheet.csv --outdir results --genome GRCh38 \
+    --tools haplotypecaller,snpeff
+```
+
+### Somatic (tumor-normal pair)
+```bash
+nextflow run nf-core/sarek -r 3.7.1 -profile docker \
+    --input samplesheet.csv --outdir results --genome GRCh38 \
+    --tools mutect2,strelka,snpeff
+```
+
+### WES (exome)
+```bash
+nextflow run nf-core/sarek -r 3.7.1 -profile docker \
+    --input samplesheet.csv --outdir results --genome GRCh38 \
+    --wes --intervals /path/to/targets.bed \
+    --tools haplotypecaller,snpeff
+```
+
+### Joint germline (cohort)
+```bash
+--tools haplotypecaller --joint_germline
+```
+
+## Parameters
+
+### Available tools
+
+**Germline callers:**
+- `haplotypecaller`: GATK HaplotypeCaller
+- `freebayes`: FreeBayes
+- `deepvariant`: DeepVariant (GPU optional)
+- `strelka`: Strelka2 germline
+
+**Somatic callers:**
+- `mutect2`: GATK Mutect2
+- `strelka`: Strelka2 somatic
+- `manta`: Structural variants
+
+**CNV callers:**
+- `ascat`: Copy number
+- `controlfreec`: CNV detection
+- `tiddit`: SV calling
+
+**Annotation:**
+- `snpeff`: Functional annotation
+- `vep`: Variant Effect Predictor
+
+### Key parameters
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `--tools` | - | Comma-separated list of tools |
+| `--genome` | - | `GRCh38`, `GRCh37` |
+| `--wes` | false | Exome mode (requires `--intervals`) |
+| `--intervals` | - | BED file for targeted regions |
+| `--joint_germline` | false | Joint calling for cohorts |
+| `--skip_bqsr` | false | Skip base quality recalibration |
+
+## Output files
+
+```
+results/
+├── preprocessing/
+│   └── recalibrated/           # Analysis-ready BAMs
+│       └── *.recal.bam
+├── variant_calling/
+│   ├── haplotypecaller/        # Germline VCFs
+│   ├── mutect2/                # Somatic VCFs (filtered)
+│   └── strelka/
+├── annotation/
+│   └── snpeff/                 # Annotated VCFs
+└── multiqc/
+```
+
+## Troubleshooting
+
+**BQSR fails**: Check known sites available for genome. Skip with `--skip_bqsr` for non-standard references.
+
+**Mutect2 no variants**: Verify tumor/normal pairing in samplesheet (check `status` column).
+
+**Out of memory**: `--max_memory '128.GB'` for WGS.
+
+**DeepVariant GPU**: Ensure NVIDIA Docker runtime configured.
+
+## More Information
+
+- **Full parameter list:** https://nf-co.re/sarek/3.7.1/parameters/
+- **Output documentation:** https://nf-co.re/sarek/3.7.1/docs/output/
+- **Usage documentation:** https://nf-co.re/sarek/3.7.1/docs/usage/

package/content/bio-research/skills/bio-research-nextflow-development/references/troubleshooting.md

@@ -0,0 +1,137 @@
+# Troubleshooting
+
+Quick fixes for common nf-core pipeline issues.
+
+## Contents
+- [Exit Codes](#exit-codes)
+- [HPC/Singularity Issues](#hpcsingularity-issues)
+- [Pipeline Failures](#pipeline-failures)
+- [RNA-seq Specific](#rna-seq-specific)
+- [Sarek Specific](#sarek-specific)
+- [ATAC-seq Specific](#atac-seq-specific)
+- [Resource Management](#resource-management)
+- [Getting Help](#getting-help)
+
+## Exit Codes
+
+Common exit codes indicating resource issues (per [nf-core docs](https://nf-co.re/docs/usage/troubleshooting/crash_halfway)):
+
+| Code | Cause | Fix |
+|------|-------|-----|
+| 137 | Out of memory | `--max_memory '32.GB'` or `'64.GB'` for WGS |
+| 143 | Out of memory | `--max_memory '32.GB'` or `'64.GB'` for WGS |
+| 104, 134, 139, 247 | Out of memory | Increase `--max_memory` |
+| 1 | General error | Check `.nextflow.log` for details |
+
+Most pipelines auto-retry with 2x then 3x resources before failing.
+
+## HPC/Singularity Issues
+
+### Singularity cache issues
+```bash
+export NXF_SINGULARITY_CACHEDIR="$HOME/.singularity/cache"
+mkdir -p $NXF_SINGULARITY_CACHEDIR
+```
+
+### Using Singularity instead of Docker
+On HPC systems without Docker, use Singularity:
+```bash
+nextflow run nf-core/<pipeline> -profile singularity ...
+```
+
+> **Note**: For basic environment setup (Docker, Nextflow, Java installation), see the inline instructions in Step 1 of SKILL.md.
+
+## Pipeline Failures
+
+### Container pull failed
+- Check network connectivity
+- Try: `-profile singularity` instead of docker
+- For offline: `nf-core download <pipeline> -r <version>`
+
+### "No such file" errors
+- Use **absolute paths** in samplesheet
+- Verify files exist: `ls /path/to/file`
+
+### Resume not working
+```bash
+# Check work directory exists
+ls -la work/
+
+# Force clean restart (loses cache)
+rm -rf work/ .nextflow*
+nextflow run nf-core/<pipeline> ...
+```
+
+## RNA-seq Specific
+
+### STAR index fails
+- Increase memory: `--max_memory '64.GB'`
+- Or provide pre-built: `--star_index /path/to/star/`
+
+### Low alignment rate
+- Verify genome matches species
+- Check FastQC for adapter contamination
+- Try different aligner: `--aligner hisat2`
+
+### Strandedness detection fails
+- Specify explicitly: `--strandedness reverse`
+- Common values: `forward`, `reverse`, `unstranded`
+
+## Sarek Specific
+
+### BQSR fails
+- Check known sites for genome
+- Skip for non-standard references: `--skip_bqsr`
+
+### Mutect2 no variants
+- Verify tumor/normal pairing
+- Check samplesheet `status` column: 0=normal, 1=tumor
+
+### Out of memory for WGS
+```bash
+--max_memory '128.GB' --max_cpus 16
+```
+
+### DeepVariant GPU issues
+- Ensure NVIDIA Docker runtime configured
+- Or use CPU mode (slower)
+
+## ATAC-seq Specific
+
+### Low FRiP score
+- Check library complexity in `plotFingerprint/`
+- May indicate over-transposition
+
+### Few peaks called
+- Lower threshold: `--macs_qvalue 0.1`
+- Use broad peaks: `--narrow_peak false`
+
+### High duplicates
+- Normal for low-input samples
+- Pipeline removes by default
+- Consider deeper sequencing
+
+## Resource Management
+
+### Set resource limits
+```bash
+--max_cpus 8 --max_memory '32.GB' --max_time '24.h'
+```
+
+### Check available resources
+```bash
+# CPUs
+nproc
+
+# Memory
+free -h
+
+# Disk
+df -h .
+```
+
+## Getting Help
+
+1. Check `.nextflow.log` for error details
+2. Search nf-core Slack: https://nf-co.re/join
+3. Open issue on GitHub: https://github.com/nf-core/<pipeline>/issues