Documentation

rSEEK

A reproducible pipeline for rsRNA quantification, annotation, visualization, and biomarker discovery from small RNA-seq data.

Importantly, rSEEK generates rsRNA quantification and annotation results that are consistent with those provided in the rsRNADisease database. Users can therefore directly reproduce rsRNADisease-style analyses on their own small RNA-seq data, enabling straightforward comparison with curated disease-associated rsRNA profiles.

Overview

rSEEK (rsRNA Systematic Exploration Kit) is an automated pipeline for quantification and annotation of rRNA-derived small RNAs (rsRNAs). It characterizes rsRNAs by length, abundance, parental rRNA subtype, parental rRNA end, and other relevant features. Optional analysis of other small non-coding RNAs (sncRNAs), including tsRNAs, ysRNAs, miRNAs, and additional sncRNA types, is also supported.

The workflow integrates preprocessing, hierarchical mapping, read assignment, normalization, summary statistics, visualization, and machine-learning–based biomarker identification in a unified Python, Bash, R, and Snakemake framework.

Workflow Diagram

Github Icon GitHub Repository: https://github.com/BIGRICEgo/rSEEK

Installation

rSEEK requires Conda and Snakemake. We recommend Conda with Mamba (for example, via Miniforge) for efficient dependency management.

Clone the Repository and Create the Environment

git clone https://github.com/BIGRICEgo/rSEEK.git
cd rSEEK

conda env create -f config/environment.yaml
conda activate rSEEK
pip install -e .

If you prefer manual installation, create a Python 3.9 environment, install snakemake==9.3.3, then install the packages listed in the README.

Download Annotations and Test Samples

1. To download annotation references, please use this link: https://yunpan.tongji.edu.cn/link/AAB740E00847784A9DA39F2EAF256F166B

To unpack references, please use the code below:


                        cd annotation/
                        tar -xJvf annotation.tar.xz
                    

2. To download test sample data, please use this link: https://yunpan.tongji.edu.cn/link/AA71605A6F3DA24E24984C48C16704A00D

To unpack test samples, please use the code below:


                        cd data/test/
                        tar -xJvf test.tar.xz
                    

Example output is also provided in results/Sample_test_results.tar.xz; extract it to inspect the test-sample results.

Configuration

rSEEK is run through the rseek command-line interface. It writes the resolved configuration to results/{project}/rseek.config.yaml and then executes the internal Snakemake workflow. Input FASTQ files must follow {raw_data_dir}/{project}/{sample}.fastq.gz; for example, data/test/case1.fastq.gz.

You may provide parameters through the CLI or edit config/config.yaml. Update project and sample names, then assign samples to case and control groups:


                    # config/config.yaml 

                    # Directories
                    raw_data_dir: "data" # Path to raw data
                    results_dir: "results" # Path to output directory
                    scripts_dir: "scripts" # Path to script directory
                    annotations_dir: "annotation" # Path to annotation directory
                    ncRNA: false # Whether to perform analysis of ncRNAs, "true" or "false"
                    keep_intermediate: false # Whether to keep intermediate mapping details, "true" or "false"
                    
                    # Project infos
                    project: "test" # Project name
                    samples: # Sample names
                      - case1
                      - case2
                      - case3
                      - control1
                      - control2
                      - control3
                    groups: # Group to which samples belong.
                      case:
                        - case1
                        - case2
                        - case3
                      control:
                        - control1
                        - control2
                        - control3
                

Directory Structure

Ensure your folder matches the structure below.


                    rSEEK/
                    ├── assets/
                    ├── config/
                    │   ├── config.yaml
                    │   ├── environment.yaml
                    ├── annotation/
                    │   ├── genome/
                    │   ├── rRNAdb/
                    │   ├── UniVec/
                    │   └── ...
                    ├── data/
                    │   ├── test/ # Or your project name
                    │   │   ├── case1.fastq.gz
                    │   │   └── control1.fastq.gz
                    ├── results/
                    │   ├── test/
                    │   │   ├── mapped/
                    │   │   ├── stats/
                    │   │   ├── plots/
                    │   │   └── test_report.html
                    ├── scripts/
                    │   ├── align_summary.sh
                    │   ├── count_unique_sequences.sh
                    │   ├── map_rRNA.sh
                    │   ├── map_ncRNA.sh
                    │   ├── re_logs.sh
                    │   ├── process_rna_seq.py
                    │   ├── CountMatrix.py
                    │   ├── ExprMatrix.py
                    │   ├── generate_report.py
                    │   ├── RPM.py
                    │   ├── compare_Plot_rRNA_coverage.R
                    │   ├── DA.R
                    │   ├── rRNA_length_distribution.R
                    │   └── template_report.html
                    ├── rseek/
                    │   ├── __init__.py
                    │   └── cli.py
                    ├── pyproject.toml
                    └── Snakefile
                

Run rSEEK

Before running, confirm that annotation files have been downloaded and that FASTQ files match the selected project and sample names. The CLI is the recommended entry point.

Check Inputs and Dependencies

rseek check \
  --project test \
  --raw-data data \
  --annotation annotation \
  --samples case1,case2,case3,control1,control2,control3 \
  --case case1,case2,case3 \
  --control control1,control2,control3

Dry Run

rseek dry-run \
  --project test \
  --raw-data data \
  --annotation annotation \
  --samples case1,case2,case3,control1,control2,control3 \
  --case case1,case2,case3 \
  --control control1,control2,control3 \
  --cores 4

Full Execution

rseek run \
  --project test \
  --raw-data data \
  --annotation annotation \
  --samples case1,case2,case3,control1,control2,control3 \
  --case case1,case2,case3 \
  --control control1,control2,control3 \
  --cores 8

Visualize the Workflow

rseek dag \
  --project test \
  --raw-data data \
  --annotation annotation \
  --samples case1,case2,case3,control1,control2,control3 \
  --case case1,case2,case3 \
  --control control1,control2,control3 \
  --output DAG.dot

Install Graphviz if you would like to render DAG.dot as a PDF.

Other Commands

# Force rerun
rseek run --config config/config.yaml --force --cores 8

# Finish uncompleted jobs
rseek run --config config/config.yaml --rerun-incomplete --cores 8

# Initialize a new configuration file
rseek init-config --project test --raw-data data --annotation annotation \
  --samples case1,case2,case3,control1,control2,control3 \
  --case case1,case2,case3 --control control1,control2,control3 \
  --output config/my_project.yaml

Advanced users may also run the workflow directly: snakemake --configfile config/config.yaml --cores 8.

Advanced Usage

The Snakemake framework provides flexible rule definition and workflow control, allowing users to customize rules according to specific needs. For example:

1. Optional Alignment to Other ncRNA Types

Enable analysis of additional small non-coding RNAs by setting ncRNA: true in config/config.yaml. The default is false, which restricts the workflow to rsRNAs.

2. Retention of Intermediate Files

To retain intermediate alignment files stored in results/mapped/, set keep_intermediate: true in config/config.yaml, or pass --keep-intermediate to rseek run. Ensure sufficient disk space is available.

Expected Outcomes

After successful execution, results are saved under results/{project}/. The folder structure is as follows:

Folder Description
mapped/ Alignment results for genome, rRNA, and ncRNA
stats/ Expression matrices and distribution tables
logs/ Execution logs for each sample
plots/ Plots and biomarker results

Main outputs include the following files, together with an HTML report viewable in any browser:

  • stats/{project}_alignment_summary.csv: hierarchical assignment summary
  • stats/{project}_rRNA_count_matrix.txt and stats/{project}_rRNA_expression_matrix.txt: count and normalized expression matrices
  • plots/{project}_rRNA_Length_distribution_RPM.txt and plots/{project}_DA_result_noNA.txt: length-distribution and differential-analysis results
  • plots/{project}_lasso_selected_features_rpm.txt: LASSO-selected features
  • plots/{project}_*_Coverage.png, {project}_rRNA_Length_Distribution.png, {project}_rRNA_subtype_HollowPieChart.png, and {project}_rRNA_End_StackBarPlot.png: key visualizations
  • {project}_report.html: HTML report
Result Plot

Online Report

The online report consists of four sections, each showcasing different aspects of the analysis. Below are example screenshots:

Part 1: Input Information

The Input Information section at the beginning of the rSEEK Analysis Report provides an overview of the analysis setup. It displays the report completion time and project name, and summarizes the key inputs used in the analysis, including the configuration file that defines all analysis parameters, the total number of samples processed with the numbers of case and control samples, and the output directory where all generated results, figures, and intermediate files are stored.

Input Information

Part 2: rsRNA Profile

The rsRNA Profile section provides a comprehensive overview of the rsRNA expression landscape across all input samples. This part summarizes multiple aspects of rsRNA characteristics, including length distribution, subtype composition, end-position preference, genomic coverage profiles, and co-expression patterns. For each type of analysis, results are presented in a way that allows direct comparison between case and control groups, enabling users to visually assess group-specific differences in rsRNA features and expression patterns.

⚠️ Notes: Co-expression analysis is performed only when both the case and control groups contain >4 samples; otherwise, the analysis and corresponding figures are omitted from the report.

rsRNA Profile

Part 3: Biomarker Analysis

The Biomarker Analysis section summarizes the results of rsRNA biomarker screening and identification by integrating differential expression analysis, machine learning–based feature selection, and model evaluation. Differential analysis reports the numbers of up- and down-regulated rsRNAs between case and control groups and visualizes the results using a volcano plot. Machine learning analysis applies LASSO regression to select informative rsRNA features and provides an interactive table displaying their expression levels and detailed rsRNA profile information. Model evaluation assesses classification performance using Random Forest–based feature importance and ROC curve analysis.

⚠️ Notes: Biomarker Analysis is performed only when both the case and control groups contain >3 samples.
The presence of differential expression results does not necessarily guarantee biomarker identification, as LASSO regression may not select suitable rsRNA features under certain conditions.

Biomarker Analysis

Part 4: Report Summary

The Downloadable Files section provides access to result files generated from the rsRNA profiling and biomarker analysis. These files include alignment summaries, rsRNA expression and count matrices, as well as the outputs of differential analysis and LASSO-based feature selection, allowing users to perform downstream analysis or reuse the results in other workflows.

Report Summary

Example Report Download

To view a full-size report example, please click the download button below:

Parameters Used

The main parameters used in rSEEK are listed below:


                # Trim Galore
                    trim_galore --quality 30 --length 15 --max_length 50 -j 8 

                # Filter
                    bowtie -p 4 --un {output.filtered} # Keep unmmaped content

                # Alignment parameters - genome
                    bowtie -v 1 -p 10 -k 1
                
                # Alignment parameters - rRNA
                    bowtie -v 1 -a -p 8 --fullref --norc 
                
                # Alignment parameters - other sncRNA (optional)
                    bowtie -v 1 -k 3 -p 8 --fullref --norc --best --strata 

                

References

Tools used in rSEEK

Tool Name Version Description
Trim Galore 0.6.10 Adapter trimming for FASTQ files
Bowtie 1.3.1 Short-read alignment
Samtools 1.21 Manipulate alignments in the SAM format
Snakemake 7.8.0 Workflow management system
R 4.2.2 Statistical computing and graphics
Python 3.9.7 General-purpose programming language

References used in rSEEK