Metadata-Version: 2.4
Name: vConTACT3
Version: 3.2.4
Summary: Viral CONTig Automatic Clustering and Taxonomy 3
Author: Jiarong Guo
Author-email: Benjamin Bolduc <bolduc.10@osu.edu>
Project-URL: Bug Reports, https://bitbucket.org/MAVERICLab/vcontact3/issues
Project-URL: Funding, https://www.nsf.gov/awardsearch/showAward?AWD_ID=2149505
Project-URL: Homepage, https://bitbucket.org/MAVERICLab/vcontact3/
Project-URL: Source, https://bitbucket.org/MAVERICLab/vcontact3/
Keywords: iVirus,metagenomics,viral taxonomy,virus
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: <3.12,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: biopython>=1.81
Requires-Dist: dill>=0.3.6
Requires-Dist: ete3>=3.1.2
Requires-Dist: fastcluster<=1.2.6
Requires-Dist: jinja2>=3.1.6
Requires-Dist: joblib>=1.2.0
Requires-Dist: markupsafe>=2.0.1
Requires-Dist: matplotlib>=3.7.1
Requires-Dist: networkit<=11.0
Requires-Dist: numpy<2.0.0,>=1.23.5
Requires-Dist: pandas>=2.1.1
Requires-Dist: psutil>=5.9.5
Requires-Dist: pyarrow>=14.0.1
Requires-Dist: pyrodigal-gv>=0.3.1
Requires-Dist: pyrodigal>=2.3.0
Requires-Dist: scikit-bio>=0.5.8
Requires-Dist: scikit-learn==1.5.0
Requires-Dist: scipy>=1.10.1
Requires-Dist: seaborn>=0.12.1
Requires-Dist: setuptools==70.0.0
Requires-Dist: swifter>=1.3.4
Requires-Dist: tables>=3.8.0
Requires-Dist: tqdm==4.66.3
Requires-Dist: upsetplot>=0.7.0
Provides-Extra: docs
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-argparse; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: sphinx-copybutton; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Dynamic: license-file

![vConTACT3 logo](logo.png)

[![Anaconda-Server Badge](https://anaconda.org/bioconda/vcontact3/badges/version.svg)](https://anaconda.org/bioconda/vcontact3)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/vcontact3/badges/latest_release_date.svg)](https://anaconda.org/bioconda/vcontact3)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/vcontact3/badges/platforms.svg)](https://anaconda.org/bioconda/vcontact3)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/vcontact3/badges/license.svg)](https://anaconda.org/bioconda/vcontact3)
[![Anaconda-Server Badge](https://anaconda.org/bioconda/vcontact3/badges/downloads.svg)](https://anaconda.org/bioconda/vcontact3)
[![Documentation Status](https://readthedocs.org/projects/vcontact3/badge/?version=latest)](https://vcontact3.readthedocs.io/en/latest/?badge=latest)

vConTACT3 is the latest iteration in the vConTACT family. Each version improves upon the foundational philosophy: more 
related virus genomes should share more genes - **V**iral **CONT**ig **A**utomatic **C**lustering and **T**axonomy.

vConTACT3 is faster, more scalable, more accurate, and features more outputs than prior versions. Databases are now handled
more efficiently and are more portable than before.

UPDATE (2025-May): A major code update has been performed. Old databases (v220 and v223) will no longer work with recent 
versions and many of the options have been changed.

Complete documention is available at the NEW ReadTheDocs website [here](https://vcontact3.readthedocs.io/en/latest/).

## Installation

### Bioconda via Mamba/Anaconda (Easiest)

The easiest way to install vConTACT3 is using the Anaconda-based package handlers of [Mamba](https://github.com/conda-forge/miniforge) or 
[Anaconda](https://docs.anaconda.com/free/anaconda/install/index.html)

```bash
mamba create --name vcontact3 python=3.10
mamba activate vcontact3
mamba install -c bioconda vcontact3
```

```bash
mamba install -c bioconda vcontact3
```

If users wish to use the `ani` exports option, please install `vclust` separately.

```bash
python -m pip install vclust
```

*Added version 3.1.0*

**If there is an issue with Bioconda, pip (e.g. bitbucket) will always be the first to contain bugfixes**


### Pip

**The latest version is always available via the pip installation method!**

```bash
git clone https://bitbucket.org/MAVERICLab/vcontact3.git
cd vcontact3
python -m pip install .
```

Additionally, since MMSeqs2 is not available on PyPi, you need to install it for your system. Please follow their 
[instructions](https://github.com/soedinglab/MMseqs2#installation). In the case of Apple Silicon (M1 and M2), you will need to install their OSX-universal binaries 
and then move that to a location in your $PATH.

As above, users wanting to use `ani` will need to install `vclust` as described above.

### Requirements file

```bash
git clone https://bitbucket.org/MAVERICLab/vcontact3.git
cd vcontact3
mamba install -c bioconda --file requirements.txt
python -m pip install --no-deps .
```

These installs were verified to work on Linux x86_64. They are expected to work on Apple Intel Macs. For Apple Silicon,
you may need to emulate a terminal with Rosetta support or build [failed] packages using "pip git+" and installing from 
source.

As above, users wanting to use `ani` will need to install `vclust` as described above.

## Quick Usage

### Prepare database

Latest version: **v232** [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.19198397.svg)](https://doi.org/10.5281/zenodo.19198397)

(This is only the latest version, others still exist)

vConTACT3 databases are available through Zenodo. vConTACT3 can list and retrieve the latest versions, and specify the 
version when running.

```bash
vcontact3 prepare_databases --list-versions
vcontact3 prepare_databases --get-version "latest" --set-location /path/to/download/location
```

Starting with version 3.0.5, `prepare_databases` is now aware of the installed version and will display only compatible 
databases.

If users wish to directly download a database of their choice, they can use *wget* to download the latest OR earlier 
versions.

```bash
wget -O v232.tar.xz https://zenodo.org/api/records/19198397/files/v232.tar.xz/content
tar xf v232.tar.xz
```

Place the directory and point to it during Run.

See [Full Database Notes](https://vcontact3.readthedocs.io/en/latest/databases.html) for version history and additional details.

### Run

vConTACT3 now handles all aspects of input file processing, so no need to create "Gene-to-Genome mapping files." (as was 
the case in vConTACT1-2). The only requirement is a single FASTA-formatted nucleotide file.

```bash
vcontact3 run --nucleotide virus_genomes.fasta --output output_directory
```

(By default, vConTACT3 will identify the latest database version and run that, but generally you should specify the 
version you downloaded.)

**Note:** `--db-domain` defaults to "prokaryotes". Please ensure that this is correct for the host type of your genomes. 
Alternatives can be eukaryotes, bacteria or archaea. vConTACT3 can produce incorrect assignments if this is not set 
correctly. Genomes *not* in the correct domain may not be correct!

### Outputs Overview

Results are saved to the specified output directory, including:

- Cluster assignments (CSV: realm, order, family, subfamily, genus)
- Network visualizations (GraphML, D3js, Cytoscape, Cosmograph)
- Protein cluster profiles (SVG, CSV)
- Performance metrics
- ANI Heatmaps and Rank-Group Centroids

## Documentation

Full usage details, CLI reference, export formats, and workflows are available at:
[vConTACT3 Documentation (ReadTheDocs)](https://vcontact3.readthedocs.io/)

## Citation

If you find vConTACT3 useful, please cite it. (NEW 19-DEC-2025)

Bolduc, B. et al. Machine learning enables scalable and systematic hierarchical virus taxonomy. Nat Biotechnol https://doi.org/10.1038/s41587-025-02946-9 (2025) doi:10.1038/s41587-025-02946-9.

## Other acknowledgements

vConTACT3 wouldn't be at its current state without feedback from the community. Below is a list of those who helped 
contribute via email and/or in-person suggestions/discussions:

* Placeholder, but coming soon!

Thank you!

# Funding acknowledgements

vConTACT3 wouldn't even exist without funding to support both its development and its developers' time.

* NSF [DBI-2149505](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2149505)
* NSF [DBI-2022070](https://www.nsf.gov/awardsearch/showAward?AWD_ID=2022070) (BII-Implementation: The EMERGE Institute)

