boulardlab/3t-seq

A Snakemake workflow for single copy gene, transposable elements and tRNA expression analysis

Overview

Latest release: v2.0.0, Last update: 2026-11-04

Share link: https://snakemake.github.io/snakemake-workflow-catalog?wf=boulardlab/3t-seq

Quality control: linting: failed formatting: passed

Topics: bioinformatics-pipeline rna-seq-analysis snakemake transposable-elements trna

Wrappers: utils/datavzrd

Deployment

Step 1: Install Snakemake and Snakedeploy

Snakemake and Snakedeploy are best installed via the Conda package manager. It is recommended to install conda via Miniforge. Run

conda create -c conda-forge -c bioconda -c nodefaults --name snakemake snakemake snakedeploy

to install both Snakemake and Snakedeploy in an isolated environment. For all following commands ensure that this environment is activated via

conda activate snakemake

For other installation methods, refer to the Snakemake and Snakedeploy documentation.

Step 2: Deploy workflow

With Snakemake and Snakedeploy installed, the workflow can be deployed as follows. First, create an appropriate project working directory on your system and enter it:

mkdir -p path/to/project-workdir
cd path/to/project-workdir

In all following steps, we will assume that you are inside of that directory. Then run

snakedeploy deploy-workflow https://github.com/boulardlab/3t-seq . --tag v2.0.0

Snakedeploy will create two folders, workflow and config. The former contains the deployment of the chosen workflow as a Snakemake module, the latter contains configuration files which will be modified in the next step in order to configure the workflow to your needs.

Step 3: Configure workflow

To configure the workflow, adapt config/config.yml to your needs following the instructions below.

Step 4: Run workflow

The deployment method is controlled using the --software-deployment-method (short --sdm) argument.

To run the workflow with automatic deployment of all required software via conda/mamba, use

snakemake --cores all --sdm conda

To run the workflow using a combination of conda and apptainer/singularity for software deployment, use

snakemake --cores all --sdm conda apptainer

Snakemake will automatically detect the main Snakefile in the workflow subfolder and execute the workflow module that has been defined by the deployment in step 2.

For further options such as cluster and cloud execution, see the docs.

Step 5: Generate report

After finalizing your data analysis, you can automatically generate an interactive visual HTML report for inspection of results together with parameters and code inside of the browser using

snakemake --report report.zip

Configuration

The following section is imported from the workflow’s config/README.md.

See below for an example config file with explanation of each option and description of common use-cases. For a complete, exhaustive guide on all available parameters, please refer to the Full Configuration Documentation.

Coming from 3t-seq 1.x? See the migration guide for the old -> new key mapping.

Configuration Validation

3t-seq includes a built-in schema validator to ensure your config.yaml is correctly formatted before running the full pipeline. You can run the validator using:

pixi run lint

Files in this folder

File

Purpose

config.yaml

Commented template with every option. Copy it (e.g. to config/my_config.yaml) and fill in the placeholders.

examples/GSE130735.yaml

Full-genome analysis of the public GSE130735 dataset that the integration test is subsampled from.

 
cp config/config.yaml config/my_config.yaml
pixi run snakemake --profile profile/default --configfile config/my_config.yaml

A minimal example

globals:
  results_folder: results/

# A list of comparisons to process.
# Each item groups a set of samples, listed in 'sample_sheet', under a unique 'name'.
# Tool parameter overrides (trimmomatic, star, bamCoverage, starTE_random, starTE_multihit, strandedness, deseq2) are optional per-comparison
# and fall back to pipeline defaults defined in the schema if omitted.
comparisons:
  - name: GSE130735
    protocol: pe              # required: pe (paired-end) or se (single-end)
    sample_sheet: sample-sheet.csv
    # Optional comparison-level overrides:
    deseq2:
      variable: cell_type     # This overrides the global default 'genotype' for this comparison

genome:
  label: mm10

How 3t-seq resolves reads paths

The pipeline relies primarily on the paths provided in your sample sheet to locate input read files. For each sample, you can provide paths in the filename (for single-end) or filename_1 and filename_2 (for paired-end) columns. Which columns are read depends on the comparison’s protocol in the config (pe for paired-end, otherwise single-end).

These paths can be provided in several flexible formats:

  1. Absolute Paths: If an absolute path (e.g. /data/my_experiment/reads/sample1_R1.fq.gz) is provided, 3t-seq will use it directly.

  2. Relative Paths: If a relative path is provided, 3t-seq will resolve it relative to the current working directory.

Note: You do not need to provide the file extension (.fastq.gz, .fq.gz, etc.) if you don’t want to. 3t-seq will automatically test standard fastq extensions if the exact path specified doesn’t exist.

Because 3t-seq now relies on explicit paths in the sample sheet, you do not need to rename your raw data files or move them into rigid directory structures.

Sample Sheet Format

The sample sheet is a CSV file. It must contain a name column representing the sample ID, and either:

  • A filename column for single-end libraries.

  • filename_1 and filename_2 columns for paired-end libraries.

Example (Absolute Paths):

name,filename_1,filename_2,genotype
sampleA,/data/raw/batch1/A_read1.fq.gz,/data/raw/batch1/A_read2.fq.gz,WT
sampleB,/data/raw/batch1/B_read1.fq.gz,/data/raw/batch1/B_read2.fq.gz,KO

Built-in Reference Genomes via Refgenie

3t-seq now natively integrates with Refgenie to automatically retrieve and manage the supported reference genomes (mm10 and mm39).

To use this feature, simply provide the label in your configuration’s genome section and omit fasta_path and gtf_path. The pipeline will automatically fetch the FASTA and GTF files for that genome and symlink them into your results directory.

Note: You do not need to configure or set the $REFGENIE environment variable on your system; the pipeline handles initialization underneath the hood at runtime.

How to use custom local reference files

If you prefer to use your own reference files, you can override the Refgenie downloads by providing absolute paths to your local fasta_path and gtf_path. Keep the label: it is required and is still used to fetch the matching RepeatMasker and GtRNAdb annotations.

genome:
  # Required: mm10 or mm39
  label: mm10
  
  # Provide an absolute path to your fasta:
  fasta_path: /path/to/references/custom-mm10.fa
  
  # Provide an absolute path to your gtf:
  gtf_path: /path/to/references/custom-mm10.gtf
  
  # Explicitly specify the annotation type (required for custom references)
  annotation_type: ensembl

fasta_path, gtf_path and annotation_type must be provided together; the configuration validator rejects a config that sets only some of them.

Workflow parameters

The following table is automatically parsed from the workflow’s config.schema.y(a)ml file.

Parameter

Type

Description

Required

Default

globals

Global settings affecting the pipeline paths.

yes

. results_folder

string

Path to the main results folder where all pipeline outputs will be saved.

yes

defaults

Global default parameters for all sequencing libraries.

{}

. strandedness

integer

Library strandedness (0: unstranded, 1: stranded, 2: reversely stranded).

0

. starTE_random

{}

. . outFilterMultimapNmax

integer

5000

. . winAnchorMultimapNmax

integer

5000

. . alignTranscriptsPerWindowNmax

integer

300

. starTE_multihit

{}

. . outFilterMultimapNmax

integer

1

. . winAnchorMultimapNmax

integer

5000

. . alignTranscriptsPerWindowNmax

integer

3000

. deseq2

Default DESeq2 parameters.

{}

. . test

string

Wald

. . variable

string

genotype

. . reference_level

string

Control level of ‘variable’. Required for every comparison, here or in comparisons[].deseq2.

comparisons

array

List of comparisons to process. Each comparison groups a set of samples (via a sample sheet) with its alignment and differential expression settings.

yes

genome

Genome references.

yes

. label

string

Genome label, used in reference file names. Must be ‘mm10’ or ‘mm39’ when references are fetched automatically (no fasta_path/gtf_path). With custom fasta_path + gtf_path any label made of letters, digits, ‘.’, ‘_’ and ‘-’ is accepted. Required.

yes

. fasta_path

string

Local path to explicit genome fasta.

. gtf_path

string

Local path to explicit genome GTF annotation.

. annotation_type

string

Type of genome annotation. Required if custom fasta/gtf are provided.

ensembl

. selected_chromosomes

[‘array’, ‘null’]

List of chromosomes to process. If not provided, all chromosomes will be processed.

disable_TE_analysis

boolean

Disable TE analysis.

false

disable_salmonTE_analysis

boolean

Disable SalmonTE analysis.

false

disable_tRNA_analysis

boolean

Disable tRNA analysis.

false

tRNA_quantification

{}

. method

string

Method for tRNA quantification.

yes

standard

. mimseq_params

{}

. . max_mismatches

number

mimseq –max-mismatches: a fraction of read length (< 1) or a number of mismatches (>= 1).

0.1

. . cluster_identity

number

mimseq –cluster-id: identity threshold for clustering tRNA genes when building the index.

0.95

. . min_cov

integer

Minimum coverage required for a tRNA to be quantified.

10

Linting and formatting

Linting results
1/home/runner/work/snakemake-workflow-catalog/snakemake-workflow-catalog/.pixi/envs/default/lib/python3.13/site-packages/google/auth/transport/grpc.py:43: FutureWarning: grpcio < 1.83.0 does not support Post-Quantum Cryptography (PQC). Support for non-PQC environments is deprecated. In April 2027, google-auth will raise its minimum requirements to enforce grpcio >= 1.83.0. For more details on Google Cloud's post-quantum security migration, visit: https://cloud.google.com/security/resources/post-quantum-cryptography
2  warnings.warn(
3ImportError in file "/tmp/tmpi4_vtkuj/boulardlab-3t-seq-cfc778c/workflow/rules/common.smk", line 9:
4cannot import name 'Wildcards' from 'snakemake.io' (/home/runner/work/snakemake-workflow-catalog/snakemake-workflow-catalog/.pixi/envs/default/lib/python3.13/site-packages/snakemake/io/__init__.py)
5  File "/tmp/tmpi4_vtkuj/boulardlab-3t-seq-cfc778c/workflow/rules/common.smk", line 9, in <module>
Formatting results
All tests passed!