VERDY

Part of VERDANT: Vocabulary Enrichment & Resolution of Diversity Annotations via Neural Technology (BioHackathon Europe 2026).

Meet VERDY, your warrior for ontology matching. Give it your ENA IDs or free-text terms, choose the ontologies, and it predicts the matching terms in each.

1. Input: a file (or Python list) of ENA IDs and/or free text. The IDs can be samples, runs or projects. The free text can be species, habitats, parameters or measurement names.
2. ENA lookup: each ENA ID is looked up in ENA for its sample's organism and environment fields (scientific_name, broad_scale_environmental_context, local_environmental_context, environmental_medium, ...). Free text is used as it is.
3. Search: every name is searched in each ontology you choose (for example natura2000, gold, envo).
4. Output: a file with the exact match, or the most closely related terms, per name and ontology.

import verdy

matches = verdy.match("my_input.csv", ontologies=["natura2000", "gold", "envo", "ncbitaxon"])
verdy.save(matches, "my_input.matches.csv")      # .csv  .tsv  .sssom.tsv  .json  .xlsx

verdy my_input.csv -o natura2000,gold,envo --out my_input.matches.csv

Install

pip install verdy
pip install "verdy[excel]"     # to read and write Excel
pip install "verdy[embeddings]"   # to also compare by embedding similarity (SentenceTransformers, cosine)
pip install git+https://github.com/dobrevajovana/verdy.git    # the latest, unreleased version

Python 3.10 or newer; the only dependency is requests.

Input

verdy.match takes a CSV / TSV / Excel file, a text file with one value per line, a Python list or a pandas DataFrame. The column is found by its header (name, term, parameter, species, ..., or id, accession, sample_accession, run_accession) or given with column="...". One file can mix both kinds of value:

fields= chooses other ENA sample fields to search (see ENA's returnFields?result=sample). After a run, verdy.match.unresolved lists the IDs ENA did not know.

The ontologies

verdy.ONTOLOGIES (or verdy --list):

Any other ontology in OLS4 works as well: pass its ID (for example foodon, pco or ms).

What comes out

One row per match:

verdy.unmatched(terms, matches, ontologies) lists, per ontology, the terms it found nothing for.

Example

python examples/predict.py runs examples/input.csv, which has three ENA accessions and four free-text terms, against Natura 2000, GOLD, ENVO, NCBITaxon, PATO and CF. It writes examples/input.matches.csv. Part of the result:

One term at a time

verdy.search("cloud liquid water content", "cf")    # the source's best terms, best first
verdy.resolve("SAMD00132352")                      # what ENA says about an ID
verdy.read_terms("my_input.csv")                    # what VERDY read from your file
verdy.to_dataframe(matches)                         # pandas

Tests

pip install -e ".[test]" && python -m pytest -q

The tests stub every web service, so they run offline.

Licence

MIT, see LICENSE.