Arboviromics

Introduction

Arboviromics (formerly βHΞDI) is a computational tool designed for the identification of Arboviruses, including Dengue (DENV), Chikungunya (CHIK), and Zika (ZIKA) virus sequences, primarily within wastewater next-generation sequencing (NGS) data.

It utilizes specific, unique genomic fragments (referred to as sankets) as biomarkers to efficiently detect and quantify viral presence in complex metagenomic samples.

This repository contains the source code for:

1. API Server: Handles file uploads, manages processing jobs (locally or via SLURM), and serves results.
2. Command-Line Interface (CLI): Allows users to start the API server or perform direct file processing.
3. Processing Engine: The core logic for analyzing FASTQ files and identifying viral sankets.

Features

• Detection of DENV, CHIK, ZIKA viruses in NGS data.
• Efficient processing using unique biomarker "sankets".
• RESTful API for programmatic access and job submission.
• Command-line interface for direct processing and server management.
• Docker support for easy deployment and reproducible environments.
• Optional SLURM integration for distributing jobs on HPC clusters.

Installation

Prerequisites

• Go (version 1.18 or later recommended)
• SeqKit: Required for sequence processing operations executed by Arboviromics. Must be installed and accessible in your system's PATH.
• Docker (Optional for running the API)

Common installation methods include downloading pre-compiled binaries or using package managers like Conda: conda install -c bioconda seqkit.

Getting the Code

Clone the repository:

git clone https://github.com/BioinformaticsOnLine/arboviromics.git
cd arboviromics

Building (Optional)

While running via Docker is recommended for the API, you can build the CLI/API binary directly:

# This will create an executable named 'arbo' (or similar based on your go.mod)
# in the repository root or your $GOPATH/bin
go build ./cmd/cli/

Usage

The tool can be run in several ways:

1. Running the API Server

The API server handles uploads and manages processing jobs.

Using Go Directly

Navigate to the repository root (arbo).

# Run API server (listens on default port, e.g., 8080) without SLURM
go run ./cmd/cli/main.go

# Run API server with SLURM support enabled
go run ./cmd/cli/main.go -slurm

Using Docker (Recommended)

First, build the Docker image from the repository root (where the Dockerfile is located):

docker build -t arbo-api .

Then, run the container:

# Run API server without SLURM support (maps container port 8080 to host port 8080)
docker run -p 8080:8080 arbo-api

# Run API server with SLURM support enabled
docker run -p 8080:8080 arbo-api -slurm

The API documentation (Swagger UI) should be accessible via the running server (e.g., http://localhost:8080/swagger/index.html).

2. Using the CLI for Direct File Processing

Process a single FASTQ file directly without starting the API server.

Navigate to the repository root (arbo).

go run ./cmd/cli/main.go process-file <file_path> <viruses> <output_dir>

Parameters:

• <file_path>: Path to the input FASTQ file (e.g., /data/sample1.fastq.gz).
• <viruses>: Comma-separated list of viruses to analyze (e.g., "DENV,ZIKA,CHIK" or "DENV").
• <output_dir>: Directory where results (e.g., Parquet files) will be saved.

Example:

go run ./cmd/cli/main.go process-file /path/to/my_sample.fastq DENV,ZIKA /path/to/output_results

If you built the binary earlier (e.g., named arbo), you can run it directly:

./arbo process-file /path/to/my_sample.fastq DENV,ZIKA /path/to/output_results

API Endpoints

The following endpoints are available when the API server is running:

• GET /metrics: Prometheus metrics for monitoring.
• POST /upload: Upload FASTQ file(s) to initiate a processing job.
• GET /job-status/:jobid: Check the status of a specific job ID.
• GET /job-results/:jobid: Retrieve the results for a completed job ID.
• (Check Swagger UI at /swagger/index.html for detailed parameters and responses)

---

SimP: Plotting Arboviromics Results (Supplementary Script for Plotting cli mode)

Introduction

SimP (Simple Plotter) is a visualization tool designed to plot data processed by the Arboviromics CLI tool. It leverages Python libraries such as Pandas, Dask, HoloViews, and Plotly to generate insightful plots from Parquet files. SimP supports various plot types relevant to viral analysis.

Installation (SimP)

Prerequisites

• Python (3.8 or later recommended)
• Conda or venv (recommended for environment management)

Dependencies

Install required Python packages:

pip install pandas dask "holoviews[recommended]" plotly numpy argparse

Or using Conda/Mamba:

# Using Conda
conda create -n simp_env python=3.10 pandas dask holoviews plotly numpy argparse -c conda-forge
conda activate simp_env

# Using Mamba
mamba create -n simp_env python=3.10 pandas dask holoviews plotly numpy argparse -c conda-forge
mamba activate simp_env

Usage (SimP)

Run the SimP script (assuming it's named sim.py and located appropriately, e.g., in a plotting/ subdirectory):

python path/to/sim.py -i <input_dir> -o <output_dir>

• <input_dir>: Directory containing Parquet result files generated by Arboviromics.
• <output_dir>: Directory where plot HTML files will be saved.

Example

python plotting/sim.py -i /path/to/arboviromics_output -o /path/to/plots

Running SimP on SLURM

Example SLURM script:

#!/bin/bash
#SBATCH --job-name=SimP_Plotting
#SBATCH --output=./log/SimP_%j.log
#SBATCH --nodes=1
#SBATCH --ntasks-per-node=4
#SBATCH --mem=16G
#SBATCH --time=01:00:00 # Example time limit

# Activate Python environment
conda activate simp_env # Or source /path/to/venv/bin/activate

# Run SimP
echo "Starting SimP plotting..."
time python path/to/sim.py -i /path/to/arboviromics_output -o /path/to/plots
echo "SimP plotting finished."

---

Contributing

Contributions are welcome! Please refer to the CONTRIBUTING.md file (if available) or standard GitHub practices (fork, branch, pull request).

License

This project is licensed under the AGPL-3.0 License - see the LICENSE file for details.