Carbohydrate Active eNzyme Domain analYsis tool (CANDy) - automated analysis of domain architectures in carbohydrate-active enzymes

CANDy is a fast, FAIR and seamless protein domain analysis tool for any CAZy family.

CANDy is available as an installable Python package (CLI + Python API), replacing the original Google Colab / Jupyter Notebook implementation. The previous notebook (archive/CANDy v2.0.ipynb) is kept in this repository for reference, and the original is on Google Colab.

Installation

pip install candy-cazyme

That's it -- CANDy's default toolchain (MMseqs2 for clustering, FAMSA for alignment, VeryFastTree/FastTree for phylogenetics) is fully bundled and auto-downloads/compiles itself on first use. Nothing else to install for most users.

Windows: the first clustering run may ask for administrator permission once (MMseqs2 self-installs a small helper it needs internally) -- never again after that.

macOS (Apple Silicon): use a native arm64 Python, not an Intel-only one running under Rosetta translation:

python3 -c "import platform; print(platform.machine())"   # should print "arm64"

If it prints x86_64, install Python natively instead, e.g. via uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install candy-cazyme

(CANDy automatically uses FastTree instead of VeryFastTree on Apple Silicon, since VeryFastTree has no native build there -- this happens transparently, no extra setup needed.)

If you'd rather not have CANDy download/compile anything automatically (e.g. air-gapped environments), set CANDY_NO_AUTO_DOWNLOAD=1 and install the tools yourself, e.g. via conda env create -f environment.yml. That same environment also provides the original CD-HIT/MAFFT/FastTree tools if you want to reproduce results bit-for-bit against the published notebook (--clustering-software cd-hit --alignment-tool mafft --tree-tool fasttree).

Usage

Command line

# Query a CAZy family directly -- TARGET is auto-detected as a family code or a file path
candy GH173 --email you@example.com --tree

# Analyse your own FASTA file instead
candy my_sequences.fasta --tree

# Automatically curate domain names with Gemini instead of interactive prompts
candy GH173 --email you@example.com --tree --curation-backend gemini --curation-api-key YOUR_KEY

--email falls back to the CANDY_EMAIL environment variable, then an interactive prompt, so export CANDY_EMAIL=you@example.com once and just run candy GH173 from then on. Run candy --help for the full list of options.

Domain-name curation

Partway through a run, CANDy needs to decide which raw InterPro domain names (often several near-duplicates from different member databases) should be grouped under one umbrella name. By default (--curation-backend manual) it asks you interactively: it prints a numbered list of the domain names still to curate, then prompts twice --

1. Domain name: -- type the umbrella name you want to use (e.g. Catalytic domain)
2. Includes: -- type the comma-separated numbers of the domains that belong under it (e.g. 0,2)

It repeats this until every domain is grouped; type STOP at the Domain name: prompt at any point to leave all remaining domains as their own individual groups.

To skip this entirely, use Gemini to curate automatically instead:

1. Install the extra: pip install "candy-cazyme[gemini]" (the quotes matter in zsh, macOS's default shell)
2. Get a free API key at aistudio.google.com/app/api-keys
3. Run with --curation-backend gemini --curation-api-key YOUR_KEY, or set it once via $env:GOOGLE_API_KEY="YOUR_KEY" (PowerShell) / export GOOGLE_API_KEY=YOUR_KEY (bash) and just pass --curation-backend gemini

Python API

from candy.config import CAZyFamilyInput, PipelineConfig, Taxonomy
from candy.pipeline import run_pipeline

config = PipelineConfig(
    input=CAZyFamilyInput(enzyme_class="GH", family_number=5, email="you@example.com", taxonomy=Taxonomy.ALL),
    jobname="my_gh5_run",
    output_dir="results",
    build_tree=True,
)
result = run_pipeline(config)
print(result.database_path, result.tree_path)

Output

Results are written to {output_dir}/{jobname}/:

• FASTA files for each processing stage
• A SQLite database ({jobname}_db.db) containing the domain annotations -- open it with DB Browser for SQLite
• A protein domain co-occurrence network ({jobname}_domain_cooccurence_network.graphml) -- open it in Cytoscape (yFiles Organic Layout recommended)
• If --tree/build_tree=True: an MSA, a phylogenetic tree (Newick), and iTOL annotation files for the domain architecture and (for CAZy family queries) characterized-enzyme activity

Acknowledgements

CANDy communicates with and/or references the following separate libraries, packages and tools:

• Biopython
• pandas
• tqdm
• sqlitebrowser
• SQLAlchemy
• requests
• MMseqs2 / CD-HIT (clustering)
• FAMSA via pyfamsa / MAFFT (alignment)
• VeryFastTree via veryfasttree / FastTree (phylogenetics)
• NetworkX
• Matplotlib

Citation

If you find CANDy useful, please cite it as:

Windels A, Franceus J, Pleiss J, Desmet T. CANDy: Automated analysis of domain architectures in carbohydrate-active enzymes. PLoS One. 2024 Jul 11;19(7):e0306410. doi: 10.1371/journal.pone.0306410. PMID: 38990885; PMCID: PMC11238990.

Legal terms

License and Disclaimer

CANDy is licensed under MIT.

CANDy and other information provided is for theoretical utilisation only, caution should be exercised in its use. It is provided 'as-is' without any warranty of any kind, whether expressed or implied. Information is not intended to be a substitute for professional medical advice, diagnosis, or treatment, and does not constitute medical or other professional advice.

Third-party software

Use of the third-party software, libraries or code referred to in the Acknowledgements section in the CANDy README may be governed by separate terms and conditions or license provisions. Your use of the third-party software, libraries or code is subject to any such terms and you should check that you can comply with any applicable restrictions or terms and conditions before use.

Databases

The following databases are used by CANDy, and are available with reference to the following:

• UniProt: (unmodified), by The UniProt Consortium, available under a Creative Commons Attribution-NoDerivatives 4.0 International License.
• NCBI: (unmodified), by the National Library of Medicine, available under a Creative Commons Attribution-NoDerivatives 4.0 International License.
• CAZy: (unmodified), by http://www.cazy.org/ and Elodie Drula, Marie-Line Garron, Suzan Dogan, Vincent Lombard, Bernard Henrissat, Nicolas Terrapon, The carbohydrate-active enzyme database: functions and literature, Nucleic Acids Research, Volume 50, Issue D1, 7 January 2022, Pages D571–D577, https://doi.org/10.1093/nar/gkab1045, available under a Creative Commons Attribution-NoDerivatives 4.0 International License.
• InterPro: (unmodified), by EMBL-EBI, available under a Creative Commons Attribution-NoDerivatives 4.0 International License.