methylscape_methods

This repo contains the scripts used to process and analyse the sequencing data in the Methylscape manuscript.

The repository currently includes:

• a shell pipeline for read alignment, transcript assembly, transcript merging, and abundance estimation
• an R plotting workflow for differential expression visualisation
• three additional legacy/standalone R scripts for DESeq-based analysis, tweeDEseq-based analysis, and standalone volcano plot generation

The code is designed to be modular, reproducible, and runnable on HPC systems or local environments using Conda.

Repository structure

methylscape_methods/
│   .gitignore
│   environment.yml
│   LICENSE
│   README.md
│
├── data/                  # Input data (not version-controlled)
├── results/               # Output files (not version-controlled)
├── sample_data/           # Small example files for testing/documentation
│   ├── metadata/
│   │   └── sample_metadata.csv
│   └── results/
│       └── emtMeth_001_Hisat2_alignmentSummary.xlsx
│
└── scripts/
    ├── 01_map_transcripts.sh
    ├── generate_plots.r
    ├── DESeq.R
    ├── tweeDEseq.R
    └── VolcanoPlot.R

---

Included scripts

scripts/01_map_transcripts.sh

Shell pipeline for transcript-level RNA-seq processing. This script performs:

• alignment of paired-end FASTQ files with HISAT2
• SAM to BAM conversion and sorting with SAMtools
• transcript assembly with StringTie
• merged transcript generation with StringTie --merge
• transcript comparison with gffcompare
• abundance estimation for Ballgown-compatible output

scripts/generate_plots.r

R script for downstream differential expression visualisation. In its current form, it is used to generate volcano plots from count matrix and metadata inputs using a modernised plotting workflow.

scripts/DESeq.R

Legacy differential expression analysis script based on the original DESeq package. It supports:

• two-group differential expression testing
• optional advanced mode with multi-factor design
• optional GLM-style modelling
• optional RUVSeq correction for unwanted variation
• summary plotting of significant up/downregulated genes

scripts/tweeDEseq.R

Alternative differential expression analysis script based on tweeDEseq, which models RNA-seq counts using the Poisson-Tweedie family of distributions. It performs:

• count normalisation
• low-expression filtering
• differential expression testing
• MA plot generation
• volcano plot generation
• summary counts of up/downregulated genes

scripts/VolcanoPlot.R

Standalone ggplot2-based volcano plot script for visualising differential expression results from a table containing fold-change and p-value columns.

---

Installation

1. Clone the repository

git clone https://github.com/traulab/methylscape_methods.git
cd methylscape_methods

2. Create the Conda environment

conda env create -f environment.yml
conda activate methylscape_methods

3. Verify key tools

hisat2 --version
samtools --version
stringtie --version
gffcompare --version
R --version

---

Software requirements

The repository environment includes:

• HISAT2
• SAMtools
• StringTie
• gffcompare
• R
• edgeR
• DESeq
• DESeq2
• RUVSeq
• tweeDEseq
• ggplot2
• gplots
• RColorBrewer

---

Input Data

The pipeline expects:

• Paired-end FASTQ files (_R1.fastq.gz, _R2.fastq.gz)
• Reference genome index (HISAT2)
• Gene annotation (GTF)
• Sample metadata
• Example metadata headings: (sampleID,tissue_type,disease,subtype)

Usage

1. RNA-seq alignment and transcript assembly

# 
bash scripts/01_map_transcripts.sh \
  -i /path/to/hisat2_index \
  -g /path/to/genome \
  -f /path/to/fastq.gz \
  -s /path/to/sam_output \
  -b /path/to/bam_output \
  -a /path/to/assembly_output \
  -o /path/to/ballgown_output \
  -t 6

This step does the following: sequence alignment (HISAT2), BAM processing (SAMtools), Transcript assembly (StringTie), Transcript merging and comparison, count estimation.

2. Differential expression and plotting

Rscript scripts/generate_plots.r \
  --project_dir /path/to/project

Optional arguments:

--input_dir     Path to input data
--output_dir    Path to output directory
--count_matrix  Count matrix file
--metadata      Metadata file


Outputs include:
- Differential expression tables
- Volcano plots

---

3. Legacy scripts

The three added legacy scripts are best treated as reference methods scripts until they are refactored to remove the VisRSeq wrapper dependency.

---

Important note about legacy scripts

DESeq.R, tweeDEseq.R, and VolcanoPlot.R appear to have originated from a VisRSeq-style wrapper workflow and rely on helper functions such as:

• visr.applyParameters()
• visr.biocLite()
• visr.library()
• source("visrutils.R")

These helper utilities are not currently present in this repository. As a result:

• the software environment in environment.yml installs the required R/Bioconductor packages
• but the legacy scripts may still require refactoring before they can be run directly as standalone command-line scripts

For reproducible manuscript use, the recommended path is to:

1. preserve the original scripts in the repository for reference
2. progressively refactor them into standalone scripts with explicit arguments and standard R package calls

Legacy scripts are included in this repo, as these scripts were used to perform the original analysis in the Methylscape manuscript.

Example Data

The sample_data/ directory contains:

- Example metadata (sample_metadata.csv)
- Example alignment summary output (alignmentSummary.xlsx)

Reproducibility

• All dependencies are defined in environment.yml.
• All scripts are parameterised via command-line arguments.
• No hardcoded paths are required.
• Large data files are excluded via .gitignore

Notes

• Raw sequencing data are not included due to size constraints
• FASTQ files must follow standard naming conventions (R1 / R2)
• The pipeline assumes paired-end sequencing data.
• For datasets without replicates, a biological coefficient of variation (BCV) is specified in the R script.

Citation
If you use this repository, please cite: Zhang, Z., Ahmed, E., Constantin, N., Lu, J., Korbie,D.A., Wuethrich, A., Sina, A., Trau, M. (2025). Tracking breast cancer progression using Methylscape. bioRxiv*. https://doi.org/10.1101/2025.07.09.664004

*The manuscript is currently undergoing advanced review. Once published, we will update the citation with the proper reference.