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.
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 summarystats/{project}_rRNA_count_matrix.txtandstats/{project}_rRNA_expression_matrix.txt: count and normalized expression matricesplots/{project}_rRNA_Length_distribution_RPM.txtandplots/{project}_DA_result_noNA.txt: length-distribution and differential-analysis resultsplots/{project}_lasso_selected_features_rpm.txt: LASSO-selected featuresplots/{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
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.
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.
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.
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.
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
| Reference | Source | 🔗 Link |
|---|---|---|
| UniVec | NCBI UniVec | https://www.ncbi.nlm.nih.gov/tools/vecscreen/univec/ |
| genome | UCSC hg38 | http://hgdownload.soe.ucsc.edu/ |
| rRNA | NCBI GenBank | https://www.ncbi.nlm.nih.gov/nuccore |
| YRNA | NCBI GenBank | https://www.ncbi.nlm.nih.gov/nuccore |
| tRNA | GtRNAdb, mitotRNAdb | http://gtrnadb.ucsc.edu/; http://mttrna.bioinf.uni-leipzig.de/mtDataOutput/ |
| miRNA | miRBase V22 | http://www.mirbase.org/ |
| piRNA | piRBase v3.0 | http://bigdata.ibp.ac.cn/piRBase/ |
| snoRNA | snoDB v2.0.0 | https://bioinfo-scottgroup.med.usherbrooke.ca/snoDB/ |
| snRNA | RNAcentral | https://rnacentral.org/ |
| vaultRNA | RNAcentral | https://rnacentral.org/ |