Domain of Unknown Function mechanism knowledge base.
DUFMech starts from Pfam families whose public InterPro metadata still looks like a domain or protein of unknown function. The first tool builds a triage worklist from the InterPro Pfam API, normalizes Pfam rows, keeps DUF short-name hits that may be historically solved, and can render TSV or JSON.
Use Python 3.13 for development.
just install
just test
just duf-puf-worklist --limit 10 --format tsvThe worklist can also read saved InterPro JSON for offline fixture runs:
just duf-puf-worklist --input-json interpro-page.json --format jsonFreeze a new InterPro/Pfam seed worklist with a matching manifest (today's UTC date):
just freeze-duf-puf-worklistThe original seed worklist was frozen on 2026-10-01. The current seed worklist is a versioned classification correction of that metadata, not a newer InterPro fetch. It retains all 6,532 families and source counters; 1,621 historical seed labels were corrected to unknown candidates. See the correction audit for the classification policy, parent hashes, and limitations.
Reclassify verified frozen metadata into a new snapshot without contacting InterPro:
just reclassify-duf-puf-worklist \
--input-json data/worklists/interpro-pfam-duf-2026-10-01.json \
--snapshot-date 2026-10-05 --out-dir /tmp/dufmech-classification-checkBoth worklist freezing and reclassification refuse existing output artifacts; choose a new date or output directory instead of rewriting a published snapshot. Seed labels reflect frozen wording, not experimental validation. Scoring remains a separate step.
Expand frozen Pfam rows to UniProtKB protein members through InterPro:
just duf-puf-members --pfam-id PF01519 --limit-members-per-family 5Freeze a Pfam member snapshot with UniProtKB metadata and UniRef clusters:
just freeze-duf-puf-members --input-json data/worklists/interpro-pfam-duf-2026-10-01.json --limit-families 1Freeze MGnify Proteins environmental representatives for Pfam rows:
just freeze-duf-puf-mgnify --input-json data/worklists/interpro-pfam-duf-2026-10-01.json --limit-families 1Freeze AlphaFold DB evidence for UniProt accessions:
just freeze-duf-puf-alphafold --uniprot-accession B2BDZ3Freeze CATH-Gene3D FunFam evidence for UniProt accessions:
just freeze-duf-puf-cath --uniprot-accession P68871Freeze NCBI Batch CD-Search conserved-domain evidence for UniProt accessions:
just freeze-duf-puf-cdsearch --uniprot-accession P68871Freeze a saved NCBIFAM HMM hit table:
just freeze-duf-puf-ncbifam --hits-tsv ncbifam-hits.tsvFreeze eggNOG-mapper annotations:
just freeze-duf-puf-eggnog --annotations-tsv out.emapper.annotationsFreeze an EFI-GNT Pfam Neighbor Mapping Table:
just freeze-duf-puf-efi-gnt --pfam-neighbors-tsv pfam-neighbors.tsvFreeze a saved JGI IMG gene-neighborhood table:
just freeze-duf-puf-jgi-img --gene-neighbors-tsv img-gene-neighbors.tsvFreeze 3D-Beacons structural coverage evidence for UniProt accessions:
just freeze-duf-puf-threedbeacons --uniprot-accession P75259Freeze RCSB PDB experimental-structure evidence for UniProt accessions:
just freeze-duf-puf-rcsb --uniprot-accession P68871 --limit-entities-per-accession 5Freeze PDBe-KB residue annotations for RCSB PDB entities:
just freeze-duf-puf-pdbe-kb --pdb-entity P68871:1A00:2 --endpoint domainsFreeze Rhea reactions for UniProt accessions:
just freeze-duf-puf-rhea --uniprot-accession P08159Freeze QuickGO molecular-function annotations for UniProt accessions:
just freeze-duf-puf-quickgo --uniprot-accession P08159Freeze STRING interaction partners for UniProt/taxon pairs:
just freeze-duf-puf-string --uniprot-taxon P68871:9606 --limit-partners-per-protein 5Freeze UniParc permanent sequence archive IDs for UniProt accessions:
just freeze-duf-puf-uniparc --uniprot-accession P75259Score frozen DUF/Pfam families with evidence snapshots:
just score-duf-puf --worklist-json data/worklists/interpro-pfam-duf-2026-10-01.jsonFreeze the DUF/PUF families and proteins already curated in sibling Mechs, then write the reuse report:
git -C ../TraitMech fetch origin main # likewise for each sibling Mech
just freeze-cross-mech --ref origin/main --uniprot-cache data/raw/cross-mech-uniprot-pfam.json
just cross-mech-reportThe scan reads tracked YAML from each sibling checkout at the given ref, so local
edits never leak in, and records every Mech commit in the manifest. ProteinTraitsMech
links come from its structured trait identifiers and canonical-example family
classifications. In the other Mechs, the scan matches Pfam IDs, DUF/UPF short names
and InterPro IDs in record text, and checks every cited UniProtKB accession for
worklist Pfam cross-references. Bare DUF names that no longer match a worklist
family, usually because Pfam renamed them after characterization, and UPF names,
which are UniProt nomenclature the Pfam-derived worklist never carries, are kept as
NOT_IN_WORKLIST rows. Compound names such as DUF3458_C match only their exact
worklist family, including next to prose such as DUF3458_C-containing. The manifest
records cache input/output checksums, fetch times for cache hits where known, and
the time and count of new UniProtKB requests. Legacy cache entries retain an explicit
unknown fetch age; a new request does not redate existing cached results. Unresolved
accessions, including merged and demerged entries, are listed separately.
A freeze refuses to replace any existing artifact for the selected date. Use a new
snapshot date or a separate output directory for another run. Both the report and
dashboard require cross-Mech evidence to match the selected worklist; a historical
report can select matching --cross-mech-json and --worklist-json inputs. Dashboard Mech counts
represent distinct source records, with trait-record availability shown separately.
The current cross-Mech snapshot derives from the original scan by applying the
corrected worklist's seed labels; see the offline derivation record.
Render and verify the committed DUFMech dashboard:
just render
just render-checkGitHub Actions runs the offline quality gate and builds the dashboard on pull
requests and pushes to main. After those checks pass, current main commits
publish the generated site to GitHub Pages. The workflow can also be run manually
on main. Publishing uses the committed frozen snapshots and does not refresh
upstream data. The repository's Pages source must be set to GitHub Actions.
Reports, README statistics, and pages validate the selected snapshot manifests.
Score snapshots must name the selected worklist in their input provenance;
use matching --worklist-json and --score-json paths when selecting older inputs.
Without a score snapshot, families remain UNSCORED, with seed status shown separately.
Missing counters remain unavailable rather than becoming zero, and per-family
protein totals are not deduplicated protein counts.
just render replaces only its four generated files and preserves unrelated files
in the output directory. just render-check compares the full output tree by content.
Run the local quality gate:
just qc6,532 DUF/Pfam families are currently committed from frozen InterPro/Pfam snapshots.
6,492 carry InterPro IDs, 820 have InterPro structure counters, and 6,478 have AlphaFold DB model counters.
Latest inputs: worklist=interpro-pfam-duf-2026-10-05.
Unknown-function seed status
| Value | Families |
|---|---|
KNOWN_HISTORICAL_DUF |
378 |
UNKNOWN_CANDIDATE |
6,154 |
Characterization status
| Value | Families |
|---|---|
UNSCORED |
6,532 |
Candidate reasons
| Value | Families |
|---|---|
description_says_unknown_function |
1,359 |
domain_of_unknown_function |
2,832 |
name_matches_duf |
155 |
name_says_unknown_function |
6,115 |
short_name_matches_duf |
6,371 |
DUFMech records domains, protein families, and evidence layers that help decide whether a family or representative protein is still uncharacterized. The initial source stack is:
- InterPro/Pfam for DUF-family discovery.
- UniProtKB and UniRef for reference-proteome members.
- UniParc for permanent sequence IDs and checksums.
- MGnify Proteins for environmental representatives.
- AlphaFold DB, PDB, PDBe-KB, CATH-Gene3D, CDD, NCBIFAM, STRING, eggNOG, EFI-GNT, JGI IMG, Rhea, GO, and QuickGO as follow-on structure, neighborhood, network, and function-evidence layers.
The first pass deliberately treats a DUFnnnn Pfam short name as a clue, not
as proof that the family is still functionally unknown.
DUFMech/
├── data/
│ ├── cross_mech/
│ └── worklists/
├── docs/
│ ├── provenance/
│ └── reports/
├── pages/
├── scripts/
├── src/dufmech/
└── tests/
Project-authored data and narrative documentation are licensed under CC BY 4.0. Project-authored code, including scripts, tests, schemas and website templates, is licensed under BSD-3-Clause. Third-party material retains its own licenses and attribution requirements. See LICENSE for scope and attribution.