Methods and validation

Why giftag searches these profiles, how it applies their rules, and what has been checked.

Why a dedicated annotator

gifter’s curated components accept markers from several collections: KOfam, dbCAN, NCBIfam and Pfam. Searching just one leaves the other markers unobserved. gifter receives marker rows; it cannot determine from those rows whether a missing marker was searched and absent or never searched. giftag takes the marker list from gifter’s database, searches every marker it can and writes a coverage ledger for the rest.

The profile database is built locally and includes only the profiles gifter needs, plus dbCAN competitors needed for fair overlap resolution. giftag does not redistribute upstream libraries.

Download and database construction

  • KOfam: giftag streams the archive from GenomeNet FTP first because HTTPS is much slower on this large download; HTTPS is the fallback when FTP is unavailable. It keeps only the KOs gifter uses. A full build downloads about 1.5 GB from KOfam.
  • dbCAN-sub: for the pinned release, giftag uses byte-range requests to fetch the blocks for the CAZy families gifter uses, about 1.2 GB from a 5.1 GB library. It checks each block against the shipped profile-count table. If counts disagree or a release lacks that table, it streams the whole library instead.
  • dbCAN families: giftag keeps the full family library, about 130 MB, because profiles can compete for the same region.
  • NCBIfam and Pfam: giftag fetches the requested profile files. Local source directories can be used instead with the --*-dir options.

A completed build writes giftag.json with the gifter database identity, source releases, checksums and terms; markers.tsv with the searchability of every requested marker; profiles.tsv with acceptance rules; and the HMM files. The full default build is about 1.5 GB on disk and downloads about 2.9 GB when the range requests succeed.

Search rules and specificity

The source-specific cutoffs are listed on Marker coverage. giftag records the accepted profile, rule, score and threshold in its output instead of replacing them with a single cross-source confidence value.

dbCAN competitors stay in the search. run_dbcan retains the best-scoring profile where domains overlap. If giftag searched only requested profiles, an unrequested stronger competitor could not displace a weaker requested one. That could create a false, overly specific marker. The full family library and every dbCAN-sub cluster of a requested family’s parent family remain in the search.

dbCAN E-values use the full-library Z. run_dbcan computes E-values using the profile count of its full library. giftag records that count at build time and applies it to the kept profiles, so filtering does not change the meaning of the E-value.

A subfamily model licenses its family. If a hit to an official subfamily model such as GH43_18 wins the overlap comparison, giftag also emits the broader GH43 family marker when gifter uses it. The row keeps GH43_18 in profile. A family hit never licenses a specific subfamily.

Gating is opt-in. The default searches dbCAN-sub clusters on every protein as run_dbcan does. --gate-subfamilies searches them only on proteins with a family-domain hit. It is faster, but it can miss clusters that hit without a family-level domain.

Validation snapshot

On 2026-10-04, giftag was checked on E. coli K-12 MG1655 and B. thetaiotaomicron VPI-5482 against gifter database 2026.35.1. Of 1,574 gifter markers, 1,569 were searchable. On B. thetaiotaomicron, 458 of 458 dbCAN gene-family pairs matched run_dbcan, and 157 of 157 dbCAN-sub calls matched on the kept clusters when using the same Z. With --gate-subfamilies, 144 of those 157 were retained. A genome took about 45 seconds on eight cores.

The five unsearchable markers were three KOs with no published KOfam threshold (K19098, K19099, K24159) and two EC numbers. This snapshot did not compare KOfam’s rule with KofamScan, and its dbCAN-sub comparison did not include unrelated families outside the kept clusters. The later benchmark covers both against the full libraries on eight genomes. KOfam can also miss a real enzyme under its conservative threshold; E. coli PyrC scored 192.5 against K01465, below its 320.5 cutoff. These results describe the tested releases and genomes, not all future builds.