vicon 1.0.4

VICON - Viral Conserved Sequence Extraction Toolkit

VICON - Viral Sequence Analysis Toolkit

VICON is a Python package for processing and analyzing viral sequence data, with specialized tools for viral genome coverage analysis and sequence alignment.

Features

• Viral sequence alignment and coverage analysis
• K-mer analysis and sliding window coverage calculations

• Visualization tools for coverage plots
• Wrapper scripts for vsearch and viralmsa

Quick Install (pip)

vicon can be installed directly from PyPI.

---

1. Install external dependencies

Before installing vicon, make sure you have the following tools installed and available in your PATH:

• minimap2
• vsearch
• ViralMSA

Ubuntu / Debian

sudo apt-get update
sudo apt-get install -y minimap2 vsearch

macOS (Homebrew)

brew install minimap2 vsearch

ViralMSA

ViralMSA can be installed by downloading the script:

mkdir -p ~/bin && cd ~/bin
wget "https://raw.githubusercontent.com/niemasd/ViralMSA/master/ViralMSA.py"
chmod +x ViralMSA.py
ln -sf "$PWD/ViralMSA.py" ~/.local/bin/viralmsa

2. Install vicon from PyPI

python -m pip install --upgrade pip
pip install vicon

Standard Installation

1. Create and activate a conda environment:

   conda create -n vicon python=3.11
   conda activate vicon
   

2. Install VICON and its dependencies:

   conda install -c conda-forge -c bioconda -c eka97 vicon
   

3. Set required permissions:

   chmod +x "$CONDA_PREFIX/bin/vicon-run"
   chmod +x "$CONDA_PREFIX/bin/viralmsa"
   chmod +x "$CONDA_PREFIX/bin/minimap2"
   

Usage

To run the VICON pipeline, use the following command:

vicon-run --config path/to/your/config.yaml

Input FASTA Preprocessing

Note:
When you run the pipeline, VICON will automatically preprocess your input FASTA files (both sample and reference) before any analysis.
This step:

• Converts all sequences to uppercase
• Cleans and standardizes FASTA headers
• Replaces any non-ATCG characters in sequences with 'N'

The cleaned files are used for all downstream analysis, so you do not need to manually edit or check your FASTA files for these issues.

Example Configuration

Here's an example of what your configuration file (config.yaml) should look like:

project_path: "project_path"
virus_name: "orov"
input_sample: "data/orov/samples/samples.fasta"
input_reference: "data/orov/reference/reference.fasta"
email: "[e-mail]"
kmer_size: 150
threshold: 147 # shows a tolerance of 150-147 =3 degenerations
l_gene_start: 8000
l_gene_end: 16000
coverage_ratio: 0.5
min_year: 2020
threshold_ratio: 0.01
drop_old_samples: false
drop_mischar_samples: true

FASTA Header Year Extraction: Supported Formats

The pipeline automatically extracts years from FASTA headers using a two-step approach:

1. Priority extraction: Years following separators (|, _, /, -)
2. Fallback extraction: Any standalone 4-digit number between 1850-2030

Header Example	Year Extracted?	Extracted Year	Reason
`>sample	2021`	✅ Yes	2021
>sample_2020	✅ Yes	2020	After underscore separator
>sample/2019/data	✅ Yes	2019	After slash separator
>sample-2022-final	✅ Yes	2022	After dash separator
>data 2021 sequence	✅ Yes	2021	Standalone 4-digit number
>sample.2020.version	✅ Yes	2020	Standalone 4-digit number
>test2021extra	✅ Yes	2021	Standalone 4-digit number
`>sample	202`	❌ No	-
>sample_1800_old	❌ No	-	Outside valid range (1850-2030)
>sample20213long	❌ No	-	5 consecutive digits

Algorithm Details:

• Step 1: Searches for years immediately following separators (|, _, /, -)
• Step 2: If no separator-based year found, searches for any standalone 4-digit number
• Validation: All extracted years must be between 1850-2030
• Word boundaries: Ensures 4-digit numbers are standalone (letter→digit or digit→letter transitions count as word boundaries)

Best Practice: Use |YYYY, _YYYY, /YYYY, or -YYYY patterns for reliable year extraction.

License

This project is licensed under the terms of the MIT license.