gynecoloji/snakemake_ATACseq_spikein

Reproducible Snakemake workflow for spike-in–normalized ATAC-seq — concatenated-genome alignment, MACS2 peaks, a consensus fragment-count matrix, an interactive QC report, and DESeq2 differential binding. Docker/Apptainer-ready.

Overview

Latest release: v1.2.0, Last update: 2026-07-20

Share link: https://snakemake.github.io/snakemake-workflow-catalog?wf=gynecoloji/snakemake_ATACseq_spikein

Quality control: linting: failed formatting: failed

Topics: apptainer atac-seq atacseq bioinformatics deeptools docker epigenomics reproducible-research snakemake spike-in-normalization deseq2 differential-binding peak-calling

Workflow Rule Graph

This visualization of the workflow’s rule graph was automatically generated using Snakevision

Rule Graph light

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/gynecoloji/snakemake_ATACseq_spikein . --tag v1.2.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 using apptainer/singularity, use

snakemake --cores all --sdm apptainer

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

snakemake --cores all --sdm conda apptainer

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

snakemake --cores all --sdm conda

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.

Configuration

This workflow is configured through two files in this directory:

  • config.yaml — all workflow parameters (see below)

  • samples.csv — the sample sheet

plus reference data you download into ref/ (not tracked in git; see Reference data).

Sample sheet (config/samples.csv)

CSV with one row per sample and these columns:

column

description

sample_id

Sample name. Raw reads must be data/<sample_id>_R1_001.fastq.gz / _R2_001.fastq.gz.

type

Free-text condition label (e.g. Control, NICD3).

group

Replicate group. Reproducibility handling is chosen from group size (below).

Example:

sample_id,type,group
GSF4007-Control_1_S11,Control,group1
GSF4007-Control_2_S13,Control,group1
GSF4007-Control_3_S15,Control,group1
GSF4007-NICD3-V5_1_S12,NICD3,group2
GSF4007-NICD3-V5_2_S14,NICD3,group2
GSF4007-NICD3-V5_3_S16,NICD3,group2

Per-group reproducibility is derived automatically from the number of replicates in each group:

  • ≥ 3 replicates → majority vote (a peak is kept if it recurs in ≥ consensus_min_replicates replicates).

  • exactly 2 replicates → IDR (idr_threshold).

  • 1 replicate → the sample’s own peaks are used as-is.

Parameters (config/config.yaml)

Every parameter — with its type, default, and description — is defined once in the config schema, workflow/schemas/config.schema.yaml. That schema is the single source of truth: the workflow validates config.yaml against it on every run (and fills in defaults for anything you omit), and the Snakemake Workflow Catalog renders it as a parameter table on the workflow page.

To configure a run, edit config.yaml directly — it ships with working defaults and an inline comment on every parameter. At minimum, point the reference-file paths (human_fasta, spikein_fasta, blacklist, gtf, promoter_bed, enhancer_bed) at the files you provide (see Reference data).

Reference data

Genomes, indexes and large annotations are not shipped in the repo (they are .gitignored). Download / place them under ref/ before running, matching the paths in config.yaml:

  • ref/hg38.fa — chr-prefixed UCSC human genome

  • ref/dm6.fa (or another spike-in genome)

  • ref/hg38_blacklist_regions.bed — ENCODE hg38 blacklist (shipped)

  • ref/gencode.v36.annotation.gtf — GENCODE annotation (for TSS QC)

  • ref/hg38.2bit — for computeGCBias

  • ref/picard.jar — Picard (used by MarkDuplicates)

The combined Bowtie2 index (ref/COMBINED/) is built automatically by the build_combined_genome rule from human_fasta + spikein_fasta.

See the top-level README.md for full setup and run instructions.

Workflow parameters

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

Parameter

Type

Description

Required

Default

samples_table

string

Path to the sample sheet CSV. Columns: sample_id, type, group. Per-group reproducibility (majority vote / IDR / single) is derived from group size.

yes

config/samples.csv

adapter_r1

string

Optional. Explicit R1 adapter sequence that OVERRIDES fastp auto-detection. Leave unset to auto-detect adapters for paired-end reads (–detect_adapter_for_pe).

adapter_r2

string

Optional. Explicit R2 adapter sequence (used together with adapter_r1).

human_fasta

string

Human genome FASTA. Must be chr-prefixed UCSC (chr1..chrX) to match the blacklist.

yes

ref/hg38.fa

spikein_fasta

string

Spike-in genome FASTA (any species, e.g. Drosophila dm6, yeast, E. coli).

yes

ref/dm6.fa

spikein_prefix

string

Prefix prepended to spike-in chromosome names before concatenation, so spike-in reads can be split out after alignment.

yes

spikein_

combined_index

string

Bowtie2 index prefix for the built human + spike-in reference (created automatically by the build_combined_genome rule).

yes

ref/COMBINED/genome

align_chroms

array

Human chromosomes kept when building the index (reads then align only to these plus the spike-in). Use an empty list to keep all human chromosomes.

yes

keep_chroms

array

Analysis keep-set for the final human BAM (mito-% QC is recorded first). Must be a subset of align_chroms and consistent with keep_chroms_regex.

yes

blacklist

string

ENCODE-style blacklist BED (chr-prefixed).

yes

ref/hg38_blacklist_regions.bed

peak_types

array

Peak types to analyze (narrowPeak for standard ATAC-seq; add broadPeak if needed).

[‘narrowPeak’]

effective_genome_size

integer

Effective genome size for deepTools RPGC normalization (hg38 default).

yes

2913022398

bin_size

integer

bigWig bin size in bp.

yes

25

consensus_window

integer

Fixed consensus peak width around each summit, in bp.

yes

500

consensus_min_replicates

integer

Majority-vote threshold for conditions with >=3 replicates.

yes

2

idr_threshold

number

IDR threshold for conditions with exactly 2 replicates.

yes

0.05

idr_relaxed_pvalue

number

MACS2 -p value for the relaxed peak calls used as IDR input.

yes

0.1

idr_top_n_peaks

integer

Number of top relaxed peaks retained per replicate for IDR.

yes

150000

keep_chroms_regex

string

Regex used by the consensus step to filter chromosomes; keep consistent with keep_chroms.

yes

^chr([1-9]

macs2_genome

string

MACS2 -g effective genome preset (e.g. hs, mm, ce, dm).

yes

hs

gtf

string

GENCODE GTF (chr-prefixed) used for TSS-enrichment QC.

yes

ref/gencode.v36.annotation.gtf

promoter_bed

string

Promoter BED used for the reads-in-annotation QC.

yes

ref/promoter_chr1-22X.bed

enhancer_bed

string

Enhancer BED used for the reads-in-annotation QC.

yes

ref/enhancer_chr1-22X.bed

spikein_pct_min

number

Lower bound (%) of the expected spike-in read fraction; drives the QC status flag.

yes

2

spikein_pct_max

number

Upper bound (%) of the expected spike-in read fraction; drives the QC status flag.

yes

10

ctcf_bed

string

Constitutive-CTCF anchor BED used by the ctcf differential-openness normalization and the anchor+shape hybrid. Built by workflow/scripts/build_constitutive_ctcf.py: the union of ENCODE CTCF ChIP-seq peaks across 59 cell types, restricted to regions bound in >=90% of them. Genome coordinates only, so it is reusable for any human sample.

ref/constitutive_ctcf_hg38.bed

diffopen_modes

array

Normalization modes run by the opt-in diffopen_all target, each written to its own results/diffopen// directory: none = DESeq2 median-of-ratios over all peaks, spikein = size factors from Drosophila spike-in depth, ctcf = median-of-ratios restricted to CTCF anchors (spike-in free).

[‘none’, ‘spikein’, ‘ctcf’]

diffopen_ref_label

string

Reference level of the sample sheet’s type column (the denominator of the contrast), e.g. “Control” for a NICD3-vs-Control comparison.

Control

ctcf_trim_k

number

ctcf mode: MAD multiplier for the invariance trim — anchors whose between-condition shift is more than this many MADs from the median shift are dropped before re-estimating size factors. Large values disable it.

2.5

ctcf_trim_iter

integer

ctcf mode: number of trim / re-estimate iterations (0 = no trimming).

2

anchor_shape_span

number

loess span for the intensity-dependent shape curve (anchor+shape hybrid).

0.6

anchor_shape_trim_k

number

MAD multiplier for trimming CTCF anchors that move between conditions, so only invariant sites shape the correction (anchor+shape hybrid).

2.5

anchor_shape_iter

integer

Shape-fit / anchor-trim refinement iterations (anchor+shape hybrid).

2

Linting and formatting

Linting results
  1No validator found for JSON Schema version identifier 'http://json-schema.org/draft-07/schema#'
  2Defaulting to validator for JSON Schema version 'https://json-schema.org/draft/2020-12/schema'
  3Note that schema file may not be validated correctly.
  4Lints for snakefile /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/common.smk:
  5    * Mixed rules and functions in same snakefile.:
  6      Small one-liner functions used only once should be defined as lambda
  7      expressions. Other functions should be collected in a common module, e.g.
  8      'rules/common.smk'. This makes the workflow steps more readable.
  9      Also see:
 10      https://snakemake.readthedocs.io/en/latest/snakefiles/modularization.html#includes
 11
 12Lints for snakefile /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk:
 13    * Absolute path "/^@/ || $3 !~ p" in line 162:
 14      Do not define absolute paths inside of the workflow, since this renders
 15      your workflow irreproducible on other machines. Use path relative to the
 16      working directory instead, or make the path configurable via a config
 17      file.
 18      Also see:
 19      https://snakemake.readthedocs.io/en/latest/snakefiles/configuration.html#configuration
 20    * Absolute path "/^@/ || $3 ~ p" in line 385:
 21      Do not define absolute paths inside of the workflow, since this renders
 22      your workflow irreproducible on other machines. Use path relative to the
 23      working directory instead, or make the path configurable via a config
 24      file.
 25      Also see:
 26      https://snakemake.readthedocs.io/en/latest/snakefiles/configuration.html#configuration
 27
 28Lints for rule fastqc (line 53, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
 29    * Param outdir is a prefix of input or output file but hardcoded:
 30      If this is meant to represent a file path prefix, it will fail when
 31      running workflow in environments without a shared filesystem. Instead,
 32      provide a function that infers the appropriate prefix from the input or
 33      output file, e.g.: lambda w, input: os.path.splitext(input[0])[0]
 34      Also see:
 35      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 36      https://snakemake.readthedocs.io/en/stable/tutorial/advanced.html#tutorial-input-functions
 37
 38Lints for rule fastp (line 74, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
 39    * Shell command directly uses variable FASTP_DIR from outside of the rule:
 40      It is recommended to pass all files as input and output, and non-file
 41      parameters via the params directive. Otherwise, provenance tracking is
 42      less accurate.
 43      Also see:
 44      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 45
 46Lints for rule bowtie2_align (line 106, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
 47    * No log directive defined:
 48      Without a log directive, all output will be printed to the terminal. In
 49      distributed environments, this means that errors are harder to discover.
 50      In local environments, output of concurrent jobs will be mixed and become
 51      unreadable.
 52      Also see:
 53      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#log-files
 54    * Shell command directly uses variable ALIGN_DIR from outside of the rule:
 55      It is recommended to pass all files as input and output, and non-file
 56      parameters via the params directive. Otherwise, provenance tracking is
 57      less accurate.
 58      Also see:
 59      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 60    * Shell command directly uses variable TMP_DIR from outside of the rule:
 61      It is recommended to pass all files as input and output, and non-file
 62      parameters via the params directive. Otherwise, provenance tracking is
 63      less accurate.
 64      Also see:
 65      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 66    * Shell command directly uses variable TMP_DIR from outside of the rule:
 67      It is recommended to pass all files as input and output, and non-file
 68      parameters via the params directive. Otherwise, provenance tracking is
 69      less accurate.
 70      Also see:
 71      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 72    * Param index is a prefix of input or output file but hardcoded:
 73      If this is meant to represent a file path prefix, it will fail when
 74      running workflow in environments without a shared filesystem. Instead,
 75      provide a function that infers the appropriate prefix from the input or
 76      output file, e.g.: lambda w, input: os.path.splitext(input[0])[0]
 77      Also see:
 78      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 79      https://snakemake.readthedocs.io/en/stable/tutorial/advanced.html#tutorial-input-functions
 80
 81Lints for rule samtools_sort_filter_index (line 136, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
 82    * Shell command directly uses variable FILTERED_DIR from outside of the rule:
 83      It is recommended to pass all files as input and output, and non-file
 84      parameters via the params directive. Otherwise, provenance tracking is
 85      less accurate.
 86      Also see:
 87      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 88    * Shell command directly uses variable TMP_DIR from outside of the rule:
 89      It is recommended to pass all files as input and output, and non-file
 90      parameters via the params directive. Otherwise, provenance tracking is
 91      less accurate.
 92      Also see:
 93      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
 94    * Shell command directly uses variable FILTERED_DIR from outside of the rule:
 95      It is recommended to pass all files as input and output, and non-file
 96      parameters via the params directive. Otherwise, provenance tracking is
 97      less accurate.
 98      Also see:
 99      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
100    * Shell command directly uses variable TMP_DIR from outside of the rule:
101      It is recommended to pass all files as input and output, and non-file
102      parameters via the params directive. Otherwise, provenance tracking is
103      less accurate.
104      Also see:
105      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
106    * Shell command directly uses variable TMP_DIR from outside of the rule:
107      It is recommended to pass all files as input and output, and non-file
108      parameters via the params directive. Otherwise, provenance tracking is
109      less accurate.
110      Also see:
111      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
112    * Shell command directly uses variable TMP_DIR from outside of the rule:
113      It is recommended to pass all files as input and output, and non-file
114      parameters via the params directive. Otherwise, provenance tracking is
115      less accurate.
116      Also see:
117      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
118    * Shell command directly uses variable TMP_DIR from outside of the rule:
119      It is recommended to pass all files as input and output, and non-file
120      parameters via the params directive. Otherwise, provenance tracking is
121      less accurate.
122      Also see:
123      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
124    * Shell command directly uses variable TMP_DIR from outside of the rule:
125      It is recommended to pass all files as input and output, and non-file
126      parameters via the params directive. Otherwise, provenance tracking is
127      less accurate.
128      Also see:
129      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
130    * Shell command directly uses variable TMP_DIR from outside of the rule:
131      It is recommended to pass all files as input and output, and non-file
132      parameters via the params directive. Otherwise, provenance tracking is
133      less accurate.
134      Also see:
135      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
136    * Shell command directly uses variable TMP_DIR from outside of the rule:
137      It is recommended to pass all files as input and output, and non-file
138      parameters via the params directive. Otherwise, provenance tracking is
139      less accurate.
140      Also see:
141      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
142    * Shell command directly uses variable TMP_DIR from outside of the rule:
143      It is recommended to pass all files as input and output, and non-file
144      parameters via the params directive. Otherwise, provenance tracking is
145      less accurate.
146      Also see:
147      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
148    * Shell command directly uses variable TMP_DIR from outside of the rule:
149      It is recommended to pass all files as input and output, and non-file
150      parameters via the params directive. Otherwise, provenance tracking is
151      less accurate.
152      Also see:
153      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
154
155Lints for rule remove_duplicates (line 192, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
156    * Shell command directly uses variable DEDUP_DIR from outside of the rule:
157      It is recommended to pass all files as input and output, and non-file
158      parameters via the params directive. Otherwise, provenance tracking is
159      less accurate.
160      Also see:
161      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
162
163Lints for rule filter_blacklist (line 218, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
164    * Shell command directly uses variable BLACKLIST_FILTERED_DIR from outside of the rule:
165      It is recommended to pass all files as input and output, and non-file
166      parameters via the params directive. Otherwise, provenance tracking is
167      less accurate.
168      Also see:
169      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
170    * Shell command directly uses variable TMP_DIR from outside of the rule:
171      It is recommended to pass all files as input and output, and non-file
172      parameters via the params directive. Otherwise, provenance tracking is
173      less accurate.
174      Also see:
175      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
176
177Lints for rule call_peaks (line 295, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
178    * Param outdir is a prefix of input or output file but hardcoded:
179      If this is meant to represent a file path prefix, it will fail when
180      running workflow in environments without a shared filesystem. Instead,
181      provide a function that infers the appropriate prefix from the input or
182      output file, e.g.: lambda w, input: os.path.splitext(input[0])[0]
183      Also see:
184      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
185      https://snakemake.readthedocs.io/en/stable/tutorial/advanced.html#tutorial-input-functions
186
187Lints for rule build_combined_genome (line 324, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
188    * Param index is a prefix of input or output file but hardcoded:
189      If this is meant to represent a file path prefix, it will fail when
190      running workflow in environments without a shared filesystem. Instead,
191      provide a function that infers the appropriate prefix from the input or
192      output file, e.g.: lambda w, input: os.path.splitext(input[0])[0]
193      Also see:
194      https://snakemake.readthedocs.io/en/stable/snakefiles/rules.html#non-file-parameters-for-rules
195      https://snakemake.readthedocs.io/en/stable/tutorial/advanced.html#tutorial-input-functions
196
197Lints for rule spikein_extract_count (line 363, /tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk):
198    * Shell command directly uses variable SPIKEIN_ALIGN_DIR from outside of the rule:
199      It is recommended to pass all files as input and output, and non-file
200      parameters via the params directive. Otherwise, provenance tracking is
201
202... (truncated)
Formatting results
 1[DEBUG] 
 2[DEBUG] In file "/tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/common.smk":  Formatted content is different from original
 3[DEBUG] 
 4[DEBUG] 
 5[DEBUG] In file "/tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/qc.smk":  Formatted content is different from original
 6[DEBUG] 
 7[DEBUG] In file "/tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/diffopen.smk":  Formatted content is different from original
 8[DEBUG] 
 9[DEBUG] In file "/tmp/tmp3p8khvp7/gynecoloji-snakemake_ATACseq_spikein-0921519/workflow/rules/atacseq.smk":  Formatted content is different from original
10[INFO] 4 file(s) would be changed 😬
11[INFO] 1 file(s) would be left unchanged 🎉
12
13snakefmt version: 0.11.5