RICA_S

A container-base, modular workflow for rapid pathogen identification and antimicrobial‑resistance (AMR) profiling from long‑read sequencing data, geared toward sepsis diagnostics.

RICA_S takes raw sequencing reads (e.g. Oxford Nanopore FASTA/FASTQ), filters out human DNA, classifies the remaining reads against a curated pathogen database using several independent classifiers in ensemble, profiles the sample for antimicrobial‑resistance and virulence genes, and (optionally) surfaces results through a small web UI. Every stage runs inside its own Docker container so tools with conflicting dependencies coexist cleanly and the pipeline is reproducible across machines.

---

Overview

Diagnosing bloodstream infections and sepsis quickly matters - every hour of delay in effective therapy worsens outcomes. RICA_S is built to move a sample from raw reads to an actionable identification + resistance profile with minimal manual intervention, using a metagenomic, alignment‑and‑classification approach.

The design philosophy is one tool, one container. Each bioinformatics tool (minimap2, kraken2, BLAST, ABRicate, ...) lives in its own image, and the host orchestrates them by executing scripts inside the running containers. This keeps dependency graphs isolated, makes it trivial to add or swap a classifier, and lets the same read set be evaluated against many methods at once for comparison.

A processing run is identified by a run id (runid) and all of its artifacts are written under output/<runid>/.

Requirements

• Ubuntu 24.04
  • poppler-utils
  • wget
• 32+ GB memory
• 1+ TB SSD/HDD
• NVIDIA GeForce RTX 4060 Max-Q / Mobile or better
  • NVIDIA CUDA Toolkit (https://developer.nvidia.com/cuda/toolkit)
• Docker
  • Docker-compose v2
  • NVIDIA Container Toolkit (https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
• Python 3
  • Pandas
  • plotly

Installation

1. Clone the repository to /opt/rica_s. The containers mount the project at /opt/rica_s, so cloning there keeps host and container paths identical.

   $ sudo git clone https://github.com/BilkentCompGen/rica_s /opt/rica_s
   $ sudo chown -R "$USER" /opt/rica_s
   $ cd /opt/rica_s

   If you must clone elsewhere, either symlink it to /opt/rica_s or change every mention of /opt/rica_s to your custom path.

2. Download reference data and databases These populate the git‑ignored datasets/ and tools/ directories. Other data is available if needed. It can be downloaded from: http://donut.cs.bilkent.edu.tr/rica_s/ or by modifying the data and tools variables of DownloadData.sh

   $ scripts/DownloadData.sh

3. Start the docker comtainers:

   $ cd /opt/rica_s/builder
   $ ./start_all.sh

4. Confirm the containers are running:

   $ docker ps --format '{{.Names}}' | grep rica_s

   You should see rica_s_id_minimap2, rica_s_id_kraken2, etc.

Running the pipeline

Each stage driver takes a run id and an absolute path to the input reads (the path must resolve inside the containers, i.e. under /opt/rica_s/...). Run the three stages in order.

$ cd /opt/rica_s
$ scripts/AllRun.sh <runid> </path/to/input/data.fasta>

Output files

For a given run, all the output files are collected at /opt/rica/output/<runid>/:

output/<runid>/
├── <runid>.log                                  # combined stage log
├── rica_s_fl_minimap2/                          # filtering stage
│   ├── human_mapped_sequence_names.txt
│   ├── nonhuman_unmapped_sequence_names.txt
│   └── nonhuman_unmapped_sequence_names.fasta
├── <inputfile>.minimap2.[ paf|tsv|pdf|eps ]
├── <inputfile>.kraken2.[ report|tsv|pdf|eps ]
├── <inputfile>.blastout.tab.[ 6|tsv|pdf|eps ]
├── <inputfile>.bwa.[ sam|tsv|pdf|eps ]
├── <inputfile>.ngmlr.[ sam|tsv|pdf|eps ]
├── <inputfile>.[ clark|cuclark ].csv.[ csv|tsv|pdf|eps ]
└── <inputfile>.abricate.csv                         # profiling stage

---

Notes and conventions

• Naming. Services, script directories, and containers all follow rica_s_<stage>_<tool>. The stage drivers discover work by globbing rica_s_id_* / rica_s_pr_*, so adding a new tool is as simple as adding its compose file, a script directory with a classify.sh/profile.sh, and bringing the container up.
• Paths. Inside containers the project is always /opt/rica_s; input read paths passed to the drivers must be absolute and container‑visible.
• Compose structure. builder/rica_s-compose.yml doesn't define services inline — it extends each per‑service file under builder/<stage>/. Images are pulled from alkanlab/* on Docker Hub; the build.dockerfile_inline blocks add common CLI tools (samtools, seqtk, seqkit, …) on top.
• Git‑ignored data. 16s/, amr/, datasets/, output/, reads/, reference_genomes/, and tools/ are excluded from version control (see .gitignore). They're populated by the download step and by pipeline runs.
• Reproducibility. Every classifier wraps its main command in /usr/bin/time -v, so per‑run resource usage (wall time, peak memory) is captured in the log for benchmarking.
• Not for clinical use. This is a research pipeline. Identifications and treatment mappings are for investigation and benchmarking, not diagnosis.

Authors and acknowledgements

Developed by Ricardo Roman‑Brenes (Bilkent University, Alkan Lab).

The pipeline builds on excellent open‑source tools: minimap2, kraken2, krakenuniq, BLAST, BWA, NGMLR, CLARK / CU‑CLARK, ganon, ABRicate (and its bundled databases: ResFinder, CARD, NCBI AMRFinder, VFDB, MEGARes, ARG‑ANNOT, PlasmidFinder, and others), and the PBSIM3 / TKSM long‑read simulators.