Skip to content

Configuration Reference

Ali Altintas edited this page Aug 26, 2026 · 2 revisions

Configuration Reference

You only need two files to run an analysis, created from the committed .example templates (both are gitignored, so each clone is a clean project):

cp config/config.example.yaml input/config.yaml
cp config/samples.example.csv input/samples.csv

input/config.yaml

Reference paths and tool options (detailed comments and examples live in config/config.example.yaml; this table is the quick reference):

key meaning
ref.fasta genome FASTA (Ensembl/GENCODE), user-supplied in input/. Plain or gzipped.
ref.gtf gene annotation GTF, user-supplied in input/. Plain or gzipped.
ref.te_gtf curated TE GTF from the TEtranscripts authors — a generic RepeatMasker GTF will not work (download link in config/config.example.yaml). Plain or gzipped.
ref.sjdb_overhang auto (default) detects max(read length) - 1 from your fastq files; set an integer to pin it.
ref.decompressed_dir where gzipped references are decompressed to (default: results/pipeline_info/ref_decompressed — shared storage, temp()-cleaned once downstream rules finish). A node-local /tmp (or empty) value is rejected at startup while gzipped refs are in use.
star.index where the STAR index is built — optional, defaults to results/star_index (generated); an existing index is honored as-is. Use build_index to control whether it is rebuilt.
star.build_index true (default). Whether the workflow may build a STAR genome index. When false, the index must already exist at star.index or the workflow raises an error.
star.extra alignment flags; pre-set to the TEtranscripts authors' multi-mapper recommendations.
star.tmpdir STAR's per-run scratch dir (default: OS temp dir); set to big scratch on HPC.
star.two_pass STAR 2-pass mapping for more sensitive novel-junction detection: none, per_sample (--twopassMode Basic), or cohort (novel junctions pooled across every sample before any sample's final alignment; default for now -- see Strandedness and STAR 2-pass).
star.two_pass_min_unique_reads Only used when two_pass: cohort. Minimum combined (summed across all samples) uniquely-mapping reads a novel junction needs to survive pooling (default 3).
trimming.enabled run TrimGalore! before STAR (default true). false skips trimming — STAR reads merged/raw fastqs directly. While on, fastq names that already look trimmed (*_trimmed*, *_val_[12]*) are rejected at startup.
trimming.trim_nextseq --nextseq=N for NextSeq/NovaSeq poly-G trimming; 0 (default) disables it.
trimming.extra extra TrimGalore! flags passed verbatim.
strandedness.min_fraction confidence threshold for RSeQC auto-detection.
tetranscripts.* TEcount/TEtranscripts options (mode, padj, foldchange...).
tetranscripts.qc.* TEcounts sample-QC view (PCA + sample clustering, on by default): enabled, view-only filters min_samples_present/min_total_counts/min_events, pca_transform (vst/rlog/log2), and feature_class (TE default / gene / all). They never remove features from the cntTables. The assignment + TE-class summary barplots are independent and always produced.
telocal.enabled run TElocal locus-level TE quantification (default true, see TElocal).
telocal.locind path to a pre-built .locInd index. Empty (default) auto-builds it from the TE GTF into results/telocal/telocal.locInd.
telocal.qc.* TElocal sample-QC view — same keys as tetranscripts.qc.*; default pca_transform: log2 (locus matrices are too large for vst/rlog).
chimera.junction.enabled run the STAR-chimeric-junction-read gene-TE chimera screen (default true; set false to opt out, see Chimera Detection).
chimera.junction.star STAR chimeric-alignment detection params (segment_min, overhang_min, score_drop_max, extra) — defaults follow the TEtranscripts authors' recommendations for the gene-TE chimera context.
chimera.junction.breakpoint_tolerance slack (bp) allowed when matching a STAR chimeric breakpoint to an exon/TE feature edge (default 0).
chimera.junction.require_canonical_junction require STAR junction type 1 (GT/AG) for a junction to count as gene-TE (default false — TE-involved splicing is often non-canonical).
chimera.junction.qc.* sample-QC view-only filters: min_samples_present, min_total_counts, min_events and pca_transform (vst/rlog/log2). They never remove events from the catalog or counts matrix.
chimera.junction.outputs.write_igv_bed also write a per-sample IGV BED track (results/chimera_junction/igv/, default false).
chimera.junction.outputs.write_counts_matrix write the chimera counts matrix + sample-QC view (results/chimera_junction/, default true).
chimera.assembly.enabled run the StringTie-assembly gene-TE chimera screen (default true, but newer and less validated than chimera.junction — validate before relying on it; costs a second dedicated STAR pass per sample; catches ordinary-canonical-intron TE-initiated splices chimera.junction structurally cannot see, see Chimera Detection).
chimera.assembly.breakpoint_tolerance slack (bp) allowed when matching an assembled transcript's exon to a TE/gene-exon feature edge (default 5 — more generous than chimera.junction's, since StringTie's coverage-inferred exon boundaries are less precise, especially on single-end data).
chimera.assembly.min_transcript_tpm not applied automatically (candidates are always fully reported); documents the threshold used when reading results/chimera_assembly/tpm_matrix.tsv.gz yourself downstream (default 1).
chimera.assembly.outputs.write_igv_bed write a BED track of candidates' TE-overlapping exons, colored by chimera_type (results/chimera_assembly/igv/, default false).
outputs.keep_merged_fastq keep the lane-concatenated fastqs (results/fastq/). false deletes them (temp()) once alignment is done.
outputs.keep_trimmed_fastq keep the trimmed fastqs (results/trimming/). false deletes them (temp()) once alignment is done.
outputs.keep_star_index keep the STAR genome index (results/star_index/). false deletes it (rm -rf) once alignment is done.
outputs.keep_telocal_index keep the auto-built TElocal index (results/telocal/telocal.locInd). false deletes it once all TElocal runs finish. Never applies to a user-provided telocal.locind path.

input/samples.csv

The design file. Columns in this exact order (an nf-core/rnaseq samplesheet works as-is):

column required? meaning
sample yes sample name (no spaces). Repeated rows with the same sample name mean that sample's reads are split across lanes/runs (nf-core style) — they're concatenated into one fastq per read before trimming/alignment.
fastq_1 yes read 1 / single-end fastq(.gz).
fastq_2 no read 2 fastq(.gz); leave empty for single-end. Paired and single-end samples can be mixed.
strandedness no per-sample override: auto, forward, reverse, unstranded, or TEtranscripts' no. Blank = auto.
condition no biological group label. If present, TEtranscripts differential analysis runs automatically; if absent, it's skipped.

All rows of a lane-split sample must agree on strandedness and condition, and every row must include both fastq_1 and fastq_2 (single-end lanes can't be mixed with paired-end lanes for the same sample). See config/samples.example.csv for a worked example.

Clone this wiki locally