kopardev · Sep 17, 2026 · Aug 27, 2026 · Sep 10, 2026 · Sep 11, 2026 · Sep 11, 2026
diff --git a/.gitignore b/.gitignore
@@ -6,5 +6,6 @@ aspen.bak
 site/
 tmp_test/
 plans_reviews/
+plans/
 .snakemake/log/
 node_modules
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## ASPEN development version
+
+- Generate Tn5 nicking-site and read counts matrices, and the corresponding DiffATAC/DESeq2 results, from both `dedup.bam` (PCR/optical duplicates removed) and `filtered.bam` (duplicates retained, labeled `nondedup`), written to separate `dedup`/`nondedup` output subfolders under `visualization/` and `peaks/{peakcaller}/{fixed_width/counts,DiffATAC}/`; previously only the duplicate-retaining `filtered.bam` was used. `dedup` is recommended for standard differential accessibility testing. (#138, @kopardev)
+- Fail fast with a clear, actionable error message when a replicate has 0 reads aligned to the spike-in genome, instead of crashing with an opaque `ZeroDivisionError` in `_compute_downsampling_scaling_factors.py`; the error is now also captured in a dedicated `results/spikein/compute_scaling_factors.log`. (#139, @kopardev)
+- Overhaul documentation for accuracy and clarity across `docs/overview.md`, `docs/outputs.md`, `docs/introduction.md`, `docs/deployment.md`, and `docs/index.md`: fix stale claims left over from the dedup/nondedup change, clarify how consensus peaks and ROIs are generated, add ENCODE-referenced QC rule-of-thumb callouts (library complexity, TSS enrichment, FRiP), consolidate scattered spike-in "when should I use this" guidance into a single decision-tree callout, and remove the outdated, unreferenced `docs/extra.md` page whose content is now covered by `docs/outputs.md`. (#138, @kopardev)
+
 ## ASPEN 1.2.0
 
 - Add `hs1_chrR` as a supported reference genome (T2T-CHM13 + chrR rDNA unit from [Paralkar lab](https://github.com/vikramparalkar/rDNA-Mapping-Genomes)). (#117, @kopardev)

diff --git a/VERSION b/VERSION
@@ -1 +1 @@
-1.2.0
+1.2.0-dev
diff --git a/docs/deployment.md b/docs/deployment.md
@@ -74,6 +74,8 @@ To explore all possible options of the `aspen` command you can either run it wit
 
 Here is what help looks like:
 
+> **Note**: This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation.
+
 ```bash
 
 ##########################################################################################
@@ -197,6 +199,8 @@ contrasts_fdr_cutoff: 0.05
 
 ASPEN supports spike-in normalization, which is useful for controlling technical variability or comparing global shifts in chromatin accessibility across samples. Spike-in reads (e.g., from _Drosophila melanogaster_ or _E. coli_) are aligned separately and used to compute normalization factors that are applied to host genome accessibility counts.
 
+Not sure whether you need this for your experiment? See ["Should I turn on spike-in normalization?"](overview.md#optional-spike-in-normalization) in the Overview docs for a decision guide.
+
 To enable spike-in normalization, edit the `config.yaml` file that was generated during `init`. You can find it in your output directory (`<path_to_output_folder>/config.yaml`).
 
 Open the file and locate the following lines:
@@ -236,8 +240,6 @@ Once enabled, ASPEN will:
 - Normalize accessibility counts using spike-in-derived scaling factors.
 - Report both normalized and raw counts in the output tables and reports.
 
-This step is optional but highly recommended when you expect global changes in chromatin accessibility due to treatments or perturbations.
-
 ### 🛠️ Dry Run the Pipeline
 
 Before executing the full analysis and after editing the `config.yaml` as needed, perform a dry run to visualize the workflow and identify potential issues:

diff --git a/docs/extra.md b/docs/extra.md
diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,8 @@
 ## Background
 
+!!! tip "New here?"
+If you just want to **run the pipeline**, skip ahead to
+[Running ASPEN](deployment.md). Come back here later for the
+scientific background on ATAC-seq and why ASPEN is built the way it is.
+
 The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing.
diff --git a/docs/introduction.md b/docs/introduction.md
@@ -10,12 +10,10 @@ ATAC-seq is a powerful technique that enables the identification of open chromat
 
 Despite its advantages, ATAC-seq data analysis presents several challenges:
 
-- **📊 Data Complexity**: The technique generates large datasets with varying fragment sizes corresponding to nucleosome-free regions, mono-nucleosomes, and multi-nucleosomes, necessitating sophisticated computational tools for accurate interpretation.
-
-- **✅ Quality Control**: Ensuring high-quality data requires meticulous assessment at multiple stages, including evaluating sequencing quality, fragment size distribution, and enrichment of reads in regulatory regions.
-
-- **📈 Peak Calling**: Identifying regions of open chromatin (peaks) demands precise computational methods to distinguish true signals from background noise, especially in datasets with low signal-to-noise ratios.
-
-- **🔬 Spike-in Normalization Challenges**: While spike-in controls are invaluable for normalization, their implementation requires careful consideration. Variability in spike-in recovery or differences in chromatin accessibility between samples can complicate normalization efforts, necessitating robust experimental design and computational strategies.
-
-- **🔄 Reproducibility**: Achieving consistent results across different experiments and conditions is crucial for the reliability of biological interpretations.
+| Challenge                     | Why it's hard                                                                                                                                                              | How ASPEN helps                                                                                                                                                                                                                                                  |
+| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 📊 **Data complexity**        | Datasets contain a mix of fragment sizes corresponding to nucleosome-free regions, mono-nucleosomes, and multi-nucleosomes, requiring careful computational interpretation | Reports a [fragment length distribution](overview.md#fragment-length-distribution) QC metric so you can visually confirm the expected nucleosome-free/mono-nucleosome pattern                                                                                    |
+| ✅ **Quality control**        | Requires assessing sequencing quality, fragment size distribution, and enrichment of reads in regulatory regions all together                                              | Runs FastQC/MultiQC plus ATAC-specific metrics ([FRiP](overview.md#fraction-of-reads-in-peaks-frip), [TSS enrichment](overview.md#transcription-start-site-tss-enrichment), [library complexity](overview.md#library-complexity)) automatically for every sample |
+| 📈 **Peak calling**           | Distinguishing true accessible regions from background noise is especially hard in low signal-to-noise datasets                                                            | Runs both MACS2 and Genrich (see [Peak Detection](overview.md#peak-detection)) so results can be cross-checked against each other                                                                                                                                |
+| 🔬 **Spike-in normalization** | Variability in spike-in recovery or accessibility differences between samples can complicate normalization                                                                 | Provides optional, transparent [spike-in normalization](overview.md#optional-spike-in-normalization) with a documented failure mode if spike-in reads are missing                                                                                                |
+| 🔄 **Reproducibility**        | Achieving consistent results across experiments and conditions requires more than just consistent code                                                                     | Runs entirely in versioned Docker/Singularity containers (see "Containerization" above) so the same environment is reproduced on every run                                                                                                                       |