Get started¶
ViroSync requires Linux x86-64, Git, and Pixi. The core workflow uses CPUs and does not need a GPU.
Install ViroSync¶
git clone https://github.com/NeLLi-team/virosync.git
cd virosync
pixi install --locked
pixi run setup-prodigal-gv
Native setup builds Prodigal-GV 2.11.0 with the pinned node-capacity correction
and locked compiler environment. It reports Corrected Prodigal-GV ready:
followed by the executable path. Repeating setup verifies the existing build.
The runtime and its required libraries live under
~/.local/share/virosync/prodigal-gv/. To choose another owned directory, set
VIROSYNC_PRODIGAL_RUNTIME to an absolute path before setup and keep that value
for subsequent runs. Do not move the completed directory: its library paths
refer to the original location. Failed builds retain their source and build log
for diagnosis.
The full compiler environment path must fit in 255 filesystem bytes, including
the subdirectories for the recipe. Setup checks the resolved path before
creating an installation or downloading source. If the path is too long, choose
a shorter permanent owned directory through VIROSYNC_PRODIGAL_RUNTIME, for
example export VIROSYNC_PRODIGAL_RUNTIME="$HOME/.vs-native". A symlink alias
does not shorten the resolved path.
The run and example Pixi tasks check native setup automatically. Help and
version commands remain available without compilation. Gene calling requires
the corrected runtime and never selects a Prodigal executable from PATH.
For direct console or Python use in the documented Pixi environment, run:
The source distribution and wheel include the recipe, patch, build lock, and upstream license. Installing the Python package alone does not provision the native runtime or the other Pixi dependencies.
Environments¶
The default environment includes the CPU pipeline, frameshift screening, and
executed notebook reports with their figures. Select an environment with
pixi install --locked -e NAME and pixi run -e NAME COMMAND.
| Environment | Purpose |
|---|---|
optional |
Core runtime plus RepeatMasker and TRF masking; scikit-learn and XGBoost taxonomy models. |
structural |
All optional tools plus Foldseek and the TMVec2 runtime with GPU support. Boltz uses its own runtime. |
dev |
Core runtime plus optional CPU tools, CPU PyTorch, pytest, Ruff, mypy, and pre-commit. |
docs |
Isolated documentation build tools, without the pipeline runtime. |
Run development checks with pixi run -e dev lint and
pixi run -e dev python -m pytest. PyTorch is optional in the default
environment; virosync info reports whether it is installed.
See optional analyses for configuration and data setup.
Install the core resources¶
Resources download about 5.3 GB, use about 11.4 GB when installed, and need about 17 GB during setup. Allow more space for the Pixi environment and results.
Setup installs resource bundle v1.2.0 in resources/virosync by default.
See Databases to use another location.
Verify the install:
The output must include Version: v1.2.0.
Run the example¶
The test-1 row must report status=success, predictions=7, and
accepted=2.
Run your genome¶
Use one FASTA file:
pixi run virosync \
-i genome.fna \
-o results/my_genome \
--config config/orchestration.yaml \
-w 1 \
--threads-per-worker 16
For several genomes, set -i to a directory and increase -w. ViroSync
accepts uncompressed .fna, .fasta, and .fa files. Directory input scans
only top-level files with these lowercase extensions. You can also pass a text
file with one FASTA path per line.
The output root contains batch_summary.tsv and one directory per genome.
Each genome has accepted calls in
phase3_synthesis/virosync_predictions.tsv and
phase3_synthesis/virosync_predictions.gff3. Use
virosync_predictions_detailed.tsv to inspect all scored candidates.
The default repeat assessment writes pairs to virosync_repeat_candidates.tsv.
Runs that end before Phase 3 write empty prediction tables at the genome root.
See Outputs for the other result files and the command-line reference for all options.