ProteinTraitsMech

Knowledge base of protein sequence and structure traits, curated one YAML per trait with evidence-backed causal graphs.

Sibling to dismech (disease mechanisms), TraitMech (microbial ecophysiological traits), CultureMech (growth media), and MediaIngredientMech (chemical ingredients). Same curation model: one YAML per record, LinkML-validated, provenance + audit trail, optional evidence-bearing causal mechanism graphs.

Scope

ProteinTraitsMech covers traits along five axes:

SEQUENCE — motifs, signal peptides, propeptides, cleavage sites, low-complexity / disordered regions, tandem repeats, compositional biases, conserved regions, epitopes, PTM sites.
STRUCTURE — folds, structural domains, secondary-structure arrangements, topology classes, quaternary state, subunit interfaces, active / binding / allosteric / metal sites, disulfide bonds, cavities, symmetry, dynamics, structural stability, surface properties.
SEQUENCE_STRUCTURE (mixed) — traits meaningful in both axes: transmembrane spans, coiled coils, structural tandem repeats.
FUNCTION — entry-level (non-localised) traits: enzymatic activity, binding capacity, cofactor requirement, subcellular localisation, environmental response, interaction partner. Grounded by EC / Rhea / ChEBI / GO / UniProt SubCell. Complements the localised sequence/structure records rather than replacing them.
EVOLUTION — comparative-genomics traits: conservation and distribution across taxa (conserved / clade-specific / variable) and pangenome partition (core / soft-core / shell / cloud / persistent / singleton).

Records anchor to authoritative resources: Pfam, InterPro, PROSITE, SMART, MEROPS, CATH, SCOP, PDB, GO, PR, UniProtKB.

Quick start

Use Python 3.13, pinned in .python-version, for development and GitHub CI. CI runs each check on this single minor to avoid duplicate jobs; package compatibility metadata remains in pyproject.toml.

just install                  # uv sync --extra dev
just gen-schema               # generate dataclasses from LinkML
just validate-all             # closed LinkML + UniProt grounding semantics

Schema

src/proteintraitsmech/schema/proteintraitsmech.yaml defines:

ProteinTraitRecord — root class, one per YAML file. Carries identifier (preferably an existing InterPro / Pfam / PROSITE / CATH / SCOP / MEROPS / PR CURIE), label, definition, parent_traits, xrefs, synonyms, trait_axis (SEQUENCE / STRUCTURE / SEQUENCE_STRUCTURE / FUNCTION / EVOLUTION), trait_category, term_kind, optional canonical_examples, optional evidence, optional curation_history, and optional inline causal_graphs.
CausalGraph / CausalNode / CausalEdge — evidence-backed causal mechanism graphs. Nodes represent proteins, domains, motifs, residues, PTMs, ligands, pathways, molecular functions, biological processes, phenotypes, or diseases. Every CausalEdge must carry at least one EvidenceItem.
CanonicalExample — reference exemplar proteins (UniProtKB accession + taxon) that archetypally exhibit the trait.
ProteinReference / TraitOccurrence — release-pinned UniProt sequence/organism registry rows and record-specific localized or whole-protein grounding assertions.
TraitSynonym / EvidenceItem / CurationEvent — ancillary classes.
TraitAxisEnum — SEQUENCE / STRUCTURE / SEQUENCE_STRUCTURE / FUNCTION / EVOLUTION.
ProteinTraitCategoryEnum — SEQ_*, STRUCT_*, MIXED_* fine-grained buckets (see schema for the full list).
TermKindEnum — CLASS / DATATYPE_PROPERTY / OBJECT_PROPERTY / ANNOTATION_PROPERTY.
MappingStatusEnum — SEEDED / PROPOSED / REVIEWED / DEPRECATED.
PriorityEnum, SynonymTypeEnum, CausalNodeTypeEnum.

Layout

ProteinTraitsMech/
├── data/
│   ├── raw/                                     # gitignored, regenerable upstream downloads
│   └── traits/
│       ├── sequence/<category>/<slug>.yaml
│       ├── structure/<category>/<slug>.yaml
│       ├── sequence_structure/<category>/<slug>.yaml
│       ├── function/<category>/<slug>.yaml
│       └── evolution/<category>/<slug>.yaml
├── src/proteintraitsmech/
│   └── schema/proteintraitsmech.yaml            # LinkML schema
├── scripts/                                     # seed / validate / audit tooling
├── tests/
└── docs/

Axis / category pairing is enforced by LinkML rules on ProteinTraitRecord: any SEQ_* category requires trait_axis: SEQUENCE, STRUCT_* requires STRUCTURE, MIXED_* requires SEQUENCE_STRUCTURE, and FUNC_* requires FUNCTION. UPPER / OTHER are administrative and may appear on any axis. just validate-all will reject a mismatched pair.

The axis follows the representation, not the biology. Domain/family classifications defined by a sequence signature — profile HMMs / PSSMs / patterns (Pfam, InterPro, CDD, NCBIfam, MEROPS, PROSITE ProRule) — live on the SEQUENCE axis (SEQ_DOMAIN, SEQ_FAMILY, SEQ_HOMOLOGOUS_SUPERFAMILY), because a domain detected by a sequence model is a sequence trait even though a domain is a structural unit. Only structure-derived classifications (CATH, SCOPe, ECOD, TED — grouped from 3D coordinates) use STRUCT_DOMAIN / STRUCT_HOMOLOGOUS_SUPERFAMILY. Whole-protein families whose defining property is a conserved function (NCBIfam/TIGRFAM equivalog, subfamily) are FUNC_PROTEIN_FAMILY on the FUNCTION axis.

FUNCTION vs localised STRUCTURE. These axes are complementary, not exclusive. A UniProt entry with an ATP-binding site emits both a STRUCT_BINDING_SITE record (localised — where ATP binds, residues 45–52) and a FUNC_BINDING_CAPACITY record (entry-level — that the protein binds ATP). Likewise a catalytic residue emits both STRUCT_ACTIVE_SITE and FUNC_ENZYMATIC_ACTIVITY. Curators should not merge these; they answer different questions.

Workflow

Seed — import candidate traits from an authoritative resource (Pfam / InterPro / PROSITE / CATH / SCOP / MEROPS). Seeded records land with mapping_status: SEEDED and axis + category inferred from the source.
Curate — edit data/traits/<axis>/<category>/<slug>.yaml directly; set mapping_status: REVIEWED, append a CurationEvent, attach EvidenceItem blocks with PMID / DOI + verbatim snippet.
Add causal graphs — attach causal_graphs when the trait has source-backed mechanism structure (e.g. "this active-site residue coordinates the substrate carbonyl"). Every CausalEdge must carry edge-level evidence; prefer grounded CURIEs for nodes and predicates (RO for predicates; PR / GO / CHEBI / MOD / HP / MONDO for nodes).
Validate — just validate-all runs the in-process closed-mode validator (scripts/validate_strict.py) over every record, rejecting unknown top-level and nested fields as well as the usual required/pattern/enum checks, and writes per-file failures to reports/instance_validation_failures.tsv. Scope to a subset with a path or glob (just validate-all data/traits/sequence/motif).

What `--force` does and does not overwrite

--force re-seeds records that already exist. It is not a plain overwrite: every write goes through record_io.merge_on_reseed, which keeps

any top-level key the seeder does not emit (causal_graphs, curation_history, …),
xrefs and trait_relations, which are unioned rather than replaced, and
definition, definition_source, mapping_status and definitions[] on a record that is curated, or whose definition_source disagrees with what the seeder emits today. On the second of those the whole definition story is held: definitions[] is kept as-is rather than merged, so the record cannot end up with a scalar saying one thing and a catalogue entry saying another.

That last clause is #455. Enrichers rewrite definitions in place and leave records mapping_status: SEEDED — no curator was involved, so claiming otherwise would launder the provenance — which made them invisible to the curation check. A measured seed_pfam.py --force shortened 27,784 definitions before this, e.g. atrophin-1 from 1,043 characters of InterPro abstract to a 68-character stub.

The trade-off, and the one case that wants the old behaviour. A seeder whose definition_source embeds a release version (ECOD v295, Prosite Release 2026_02 of 10-Jun-2026) looks like an enricher to this rule after a version bump, and holds its definitions at the old text. When you have genuinely bumped a release and want the new prose:

PTM_RESEED_REFRESH_DEFINITIONS=1 just seed-ecod --apply --force

Set it only for that run. It disables the protection for every record in the sweep, including genuinely enriched ones.

Two things to know before you rely on this:

definition_source is held along with the definition, so after a bump a held record's other fields say v296 while its source still claims v295. That is the honest reading — the definition really is the v295 text — but it means the source string is not a reliable indicator of which release the rest of the record came from.
The count of held definitions is reported at the end of a run, but only when records were actually written. A dry run (without --apply) writes nothing and so reports nothing, which is the one moment you would most want to see the number.

Enrichment fields

Two slots are populated automatically by the seeders when the source supports them, and can also be added by curators:

residue_sequence — the concrete amino-acid substring covered by a localised trait (SEQUENCE / STRUCTURE / SEQUENCE_STRUCTURE axes). Emitted by seed_uniprot.py for every FT record with a parsable coordinate range, sliced from the entry's SQ block (DISULFID is skipped — its coordinates encode a bond, not a substring). Complements sequence_pattern, which stays reserved for symbolic motif/regex syntax.
parent_traits — links to broader/parent traits. Populated automatically:
- Not from seed_uniprot.py: a UniProt entry's DR family/domain signatures (PROSITE/Pfam/InterPro/SMART/CATH/HAMAP) are the protein's memberships, so they are emitted as xrefs, not parent_traits — a family signature is not a broader class of a specific feature-trait (caught by the review-source-categories skill's FAMILY_AS_PARENT).
- seed_prosite.py promotes each signature's PDOC documentation entry (from the DO line) to parent_traits: [PROSITE:PDOCxxxxx] — multiple ACs can share a PDOC (e.g. PS00796 and PS01180 → PDOC00633 "14-3-3 proteins"), giving family-level grouping in the docs browser.
Ontology xrefs — every record's trait_category is grounded to an authoritative ontology term (SO for sequence / structure features, MOD for specific PTMs, GO for functional classes) as an xref entry by scripts/ground_categories.py (just ground-categories). Mappings are curated in the script and verified against both the OAK local sqlite:obo:<onto> adapter (default, one download per ontology) and the EBI OLS4 REST API — pass --source ols to switch backends. --audit prints the resolved table without touching files.
```
just ground-categories --audit                   # audit only
just ground-categories --apply                   # write xrefs
just ground-categories --source ols --audit      # cross-check via OLS
```
Current mapping table covers 33 of ~40 categories (STRUCT_CAVITY / STRUCT_SYMMETRY / STRUCT_DYNAMICS / STRUCT_STABILITY / STRUCT_SURFACE / STRUCT_ALLOSTERIC_SITE / SEQ_DISORDER / SEQ_EPITOPE / SEQ_NONSTANDARD_RESIDUE / FUNC_COFACTOR_REQUIREMENT are intentionally unmapped — extend CATEGORY_MAPPINGS when a non-obsolete term is identified).
canonical_examples — reference proteins that exhibit the exact record trait. The grounding workflow is fail-closed: existing examples without qualification_status are interpreted as LEGACY_UNVERIFIED, while a newly promoted example must carry qualification_status: QUALIFIED and at least one matching TraitOccurrence. A qualified occurrence is tied to the same exact UniProt accession, pinned full sequence/checksum, organism, source release, and record-specific evidence. Whole-protein annotations use scope: WHOLE_PROTEIN; they never fabricate a [1, sequence_length] localized interval.

Full sequences are normalized in the versioned ProteinReference JSONL registry under data/grounding/; trait files retain the checksum and occurrence assertion. Exact whole-protein UniProt cross-references are normalized separately in the content- addressed uniprot_memberships.jsonl registry and replayed by semantic validation. Generic UniProt feature tracks or discovery-query hits remain useful for display but do not prove that the record's exact trait occurs on that protein.

Discovery commands are candidate-only. just fetch-examples queries exact UniProt signature cross-references and just suggest-examples ranks carriers from the Swiss-Prot profile matrix; neither command writes trait records, and both reject the retired --apply behavior. Evidence-tier-D profile/co-occurrence results remain in the candidate ledger.
```
# 1. Audit and produce explicitly labelled candidate/blocked ledgers.
just audit-uniprot-grounding

# 2. Select one bounded, source-stratified review batch. The first command is a
#    dry-run; --apply writes the ignored candidate ledger plus bound manifests.
batch=ready-local-review-001
just select-uniprot-review-batch "$batch"
just select-uniprot-review-batch "$batch" --apply

# 3. Fetch a same-response UniProt metadata+sequence registry for exactly that
#    batch, then resolve it without touching traits or durable registries.
just fetch-uniprot-review-batch "$batch"
just fetch-uniprot-review-batch "$batch" --apply
just resolve-uniprot-review-batch "$batch"

# 4. Review <batch>.review.tsv source by source and save decisions as
#    <batch>.approved.tsv. Promotion requires reviewer/date/notes, >=25 decided
#    records per promoted source (or every available record when fewer exist), every
#    flagged special case decided, every alternative decided for a promoted record,
#    at most one approved exemplar per record, and <=1,000 records. Preflight first;
#    only the second command installs durable registry rows and validated trait changes.
just promote-uniprot-review-batch "$batch"
just promote-uniprot-review-batch "$batch" --apply
```
promote-uniprot-grounding is the sole grounding writer. It rechecks release-stamped providers and review digests, runs closed LinkML plus sequence-dependent semantic validation, and uses the repository's validated atomic write route. See research/uniprot-organism-protein-grounding-plan.md for source tiers, long-tail queues, review rules, and completion criteria.

The checked command recipes pin the UniProt release through the justfile's uniprot_grounding_release, which must match the local residue frame. If the live API advances, registry fetch intentionally stops; rebuild and re-audit the local frames before updating that pin.

Seeds

Source	Records	Bucket
eLife metallophores (Zenodo 18866949, CC-BY-4.0)	20	`data/traits/sequence/{family,domain}/elife_metallophores/`; analysis and example provenance
LinkML `LocalStructuralFeature`	19	`data/traits/structure/{secondary,active_site,binding_site,cavity,disulfide,metal_site,dynamics,interface}/`
PROSITE patterns (`prosite.dat`, PATTERN)	1311	`data/traits/sequence/pattern/` (1279 generic) + `data/traits/sequence/{modified_residue,glycosylation,crosslink}/` (32 PTM subtypes)
PROSITE profiles (`prosite.dat`, MATRIX)	1434	`data/traits/sequence/profile/`
PROSITE ProRules (`prorule.dat`)	1449	`data/traits/sequence/domain/prosite/` (1445 DC=Domain → SEQ_DOMAIN) + `data/traits/sequence/{modified_residue,glycosylation,prorule}/` (2 phospho + 1 N-glyco + 1 attachment motif)
PROSITE PDOC documentation groups (`seed_prosite_pdoc.py`)	1980	`data/traits/sequence/family/prosite/` (family-level parent of the PROSITE signature records → SEQ_FAMILY)
TED novel folds (Zenodo v5, DOI:10.5281/zenodo.13908086, CC-BY 4.0)	7427	`data/traits/structure/fold/novel/`
TED highly-symmetric folds (same Zenodo record)	6433	`data/traits/structure/fold/high_symmetry/`
UniProtKB FT/CC/GO demultiplexer (`seed_uniprot.py`)	0 (demo retired)	per-protein records are instance-level, not trait classes — retired; real entries follow the candidate → resolve → validate → promote grounding workflow
PSI-MOD (HUPO-PSI protein modification CV, CC-BY-4.0)	1971	`data/traits/sequence/{modified_residue,glycosylation,lipidation,crosslink,ptm_ontology}/`
ECOD (Evolutionary Classification Of protein Domains, v295)	45113	`data/traits/structure/{architecture,homologous_superfamily,topology,fold/ecod}/` (21 + 6,178 + 3,955 + 34,959)
CATH-Gene3D hierarchy (`seed_cath.py`, CC-BY 4.0)	8151	`data/traits/structure/{class,architecture,topology,homologous_superfamily}/cath/` (unnamed nodes kept, labelled by CATH id + rep-domain xref)
SCOPe 2.08 (`seed_scope.py`)	22810	`data/traits/structure/{class,fold,homologous_superfamily,domain}/scope/` (px/sp instances excluded — occurrences, not trait classes)
Reactome pathways (`seed_reactome.py`, CC0)	2883	`data/traits/function/pathway/reactome/` (Homo sapiens reference set → FUNC_PATHWAY)
CARD/ARO resistance ontology (`seed_obo.py aro`, CC-BY 4.0)	7451	`data/traits/function/resistance/aro/` (determinants + mechanisms → FUNC_RESISTANCE)
InterPro entries (integrative; public domain; GO-grounded via interpro2go)	26264	`data/traits/{sequence/domain,sequence/homologous_superfamily,sequence/repeat,sequence/conservation,structure/active_site,structure/binding_site,sequence/ptm_ontology}/interpro/` (Domain→SEQ_DOMAIN, superfamily→SEQ_HOMOLOGOUS_SUPERFAMILY, Repeat→SEQ_REPEAT, Conserved-site→SEQ_CONSERVATION, Active-/Binding-site stay STRUCT_*, PTM; `Family` excluded)
Pfam-A families (`seed_pfam.py` + clans `seed_pfam_clans.py`, public domain)	30134	`data/traits/{sequence/domain,sequence/family,sequence/homologous_superfamily,sequence/repeat,mixed/coiled_coil,sequence/disorder,sequence/motif}/pfam/` (routed by family type: Domain→SEQ_DOMAIN, Family→SEQ_FAMILY, clans→SEQ_HOMOLOGOUS_SUPERFAMILY; GO- + InterPro-grounded; Pfam-B discontinued)
M-CSA (Mechanism & Catalytic Site Atlas, CC-BY-4.0)	1003	`data/traits/structure/active_site/mcsa/`
DisProt intrinsic disorder (`seed_disprot.py`, CC-BY 4.0) — pivoted	35	`data/traits/sequence/disorder/` (32 IDPO disorder classes + 3 groups; 3,199 proteins as capped examples)
PSI-MI (HUPO-PSI molecular-interaction CV, CC-BY-4.0)	146	`data/traits/function/interaction_partner/psi_mi/` (only the `interaction type` branch, MI:0190)
METPO (Microbial Ecophysiological Trait & Phenotype Ontology, CC-BY-4.0)	118	`data/traits/function/{environmental_response,enzymatic_activity}/metpo/` (growth-preference / tolerance + metabolism / enzyme-test branches)
PATO (Phenotype And Trait Ontology, CC-BY-4.0)	28	`data/traits/structure/{stability,dynamics,surface}/pato/` (curated physicochemical quality whitelist)
Curated stability taxonomy (`seed_stability.py`, CC0-1.0)	33	`data/traits/structure/stability/conditions/` (11 stressors × {base, increased, decreased}, parented to PATO stability)
Curated evolutionary / pangenome taxonomy (`seed_evolution.py`, CC0-1.0)	9	`data/traits/evolution/{conservation,pangenome}/` (EVOLUTION axis: conserved / clade-specific / variable + pangenome core/soft-core/shell/cloud/persistent/singleton)
TCDB transport classification (`seed_tcdb.py`, CC-BY-SA 3.0)	2285	`data/traits/function/transport/tcdb/` (Class/Subclass/Family → FUNC_TRANSPORT; 946 families ChEBI-grounded)
COG 2020 orthologous groups (`seed_cog.py`, US Gov public domain)	4903	`data/traits/function/ortholog_group/cog/` (4,877 COGs + 26 functional categories → FUNC_ORTHOLOG_GROUP)
Rhea reactions (`seed_rhea.py`, CC-BY 4.0)	18558	`data/traits/function/enzymatic_activity/rhea/` (master reactions → FUNC_ENZYMATIC_ACTIVITY; ChEBI participants; EC via rhea2ec)
ExPASy ENZYME complete EC hierarchy (`seed_ec.py`, CC-BY 4.0)	7375	`data/traits/function/enzymatic_activity/ec/` (6,965 leaves + 410 nodes; GO/RHEA mapped, KEGG direct, DR examples — supersedes trait-onto-map EC)
RepeatsDB structural tandem repeats (`seed_repeatsdb.py`, CC-BY 4.0)	122	`data/traits/sequence_structure/structural_repeat/repeatsdb/` (Class/Topology/Fold/Clan → MIXED_STRUCTURAL_REPEAT)
NCBIfam ex-TIGRFAMs (`seed_ncbifam.py`, US-gov PD)	38394	`data/traits/{sequence/domain,sequence/homologous_superfamily,sequence/repeat}/ncbifam/` + `data/traits/function/protein_family/ncbifam/` (prokaryotic family HMMs routed by TIGRFAM isology: domain/*_domain/signature→SEQ_DOMAIN, superfamily→SEQ_HOMOLOGOUS_SUPERFAMILY, equivalog/subfamily/exception/paralog→FUNC_PROTEIN_FAMILY; EC/GO xrefs)
PANTHER protein families (`seed_panther.py`, CC-BY 4.0)	15489	`data/traits/sequence/family/panther/` (full-length family HMMs → SEQ_FAMILY; families only — the release's 128,012 subfamilies are deliberately not seeded, see `seed_panther.py`; definitions from the integrating InterPro entry's curated abstract (7,691) else composed from name+GO+protein class (7,798); unreviewed LLM InterPro abstracts kept in `definitions[]` as GENERATED, never promoted; GO + panther.pathway xrefs)
CDD NCBI-curated (`seed_cdd.py`, US-gov PD)	38218	`data/traits/{sequence/domain,sequence/homologous_superfamily,function/ortholog_group}/cdd/` (cd/PRK/… → SEQ_DOMAIN; cl superfamilies → SEQ_HOMOLOGOUS_SUPERFAMILY; KOG → FUNC_ORTHOLOG_GROUP; pfam/COG/TIGR skipped)
IDEAL protean segments (`seed_ideal.py`, CC-BY 4.0) — pivoted	1	`data/traits/sequence/disorder/` (ProS trait; 1,448 IDPs as examples)
ELM linear-motif classes (`seed_elm.py`, ⚠ non-commercial)	353	`data/traits/sequence/{targeting_signal,cleavage_site,ptm_site,motif}/elm/` (TRG→SEQ_TARGETING_SIGNAL, CLV→SEQ_CLEAVAGE_SITE, …; regex→sequence_pattern)
MEROPS peptidase families (`seed_merops.py`, academic)	370	`data/traits/sequence/family/merops/` (S01→chymotrypsin, …; catalytic type → SEQ_FAMILY)
Curated RiPP leader classes (`seed_ripp.py`, CC0)	20	`data/traits/sequence/leader_peptide/` (lanthipeptide/lasso/… → SEQ_LEADER_PEPTIDE)

The last three are ingested by the generic seed_obo.py importer, which reads any OBO ontology and imports only the branch-scoped subset declared in its SOURCES config (a term is kept iff it is an is_a descendant of a configured root, and it inherits that root's axis/category). This is deliberately narrower than a whole-ontology dump — PSI-MI is mostly experimental methods, PATO qualities are generic modifiers, and METPO is organismal, so only the terms with genuine protein-trait analogues are seeded.

Refetch and re-seed:

just fetch-prosite            # writes data/raw/prosite.dat + prorule.dat (gitignored)
just fetch-ted                # writes data/raw/ted_*.tsv.gz (gitignored)
just fetch-psimod             # PSI-MOD.obo from HUPO-PSI GitHub (CC-BY-4.0)
just fetch-obo                # PSI-MI / PATO / METPO .obo files (all CC-BY-4.0)
just fetch-ecod               # ECOD domain list (~689 MB, weekly PDB-synced)
just seed-lsf --apply         # 19 LinkML LocalStructuralFeature records
just seed-prosite --apply     # 4194 PROSITE records; idempotent, skips existing
just seed-ted --apply         # 13860 TED fold records; idempotent
just seed-psimod --apply      # 1971 PSI-MOD PTM records; tags each CC-BY-4.0
just seed-ecod --apply        # 45113 ECOD hierarchy nodes (A/X/H/T/F)
just seed-mcsa --apply        # 1003 M-CSA catalytic mechanisms
just seed-disprot --apply     # 3199 DisProt IDP profiles with regions
just seed-obo all --apply     # 292 OBO records (PSI-MI 146 + METPO 118 + PATO 28)

# UniProtKB FT-line seed — pass accessions or a local flat file
just seed-uniprot --accession B0R5N7 --accession P25888 --apply

# SCOPe seeder is written but Berkeley's server is behind an anti-bot
# challenge — download dir.des.scope.*.txt and dir.hie.scope.*.txt
# manually from https://scop.berkeley.edu/downloads/ into
# data/raw/scope/, then run:
just seed-scope --apply

UniProtKB supported FT types → axis / category:

UniProt FT type	Axis	Category	Notes
`TRANSMEM`, `INTRAMEM`	—	—	skipped — per-protein membrane spans are redundant with the general transmembrane trait
`SIGNAL`	SEQUENCE	`SEQ_SIGNAL_PEPTIDE`
`TRANSIT`	SEQUENCE	`SEQ_TRANSIT_PEPTIDE`	mitochondrial / chloroplast / peroxisome targeting
`PROPEP`	SEQUENCE	`SEQ_PROPEPTIDE`	zymogen activation segment
`INIT_MET`	SEQUENCE	`SEQ_INITIATOR_METHIONINE`	N-terminal Met removed post-translationally
`CHAIN`, `PEPTIDE`	SEQUENCE	`SEQ_MATURE_CHAIN`	mature polypeptide product
`NON_STD`	SEQUENCE	`SEQ_NONSTANDARD_RESIDUE`	selenocysteine, pyrrolysine, curator-annotated
`REGION` /note="Disordered"	SEQUENCE	`SEQ_DISORDER`	other `REGION` free-text is skipped
`COMPBIAS`	SEQUENCE	`SEQ_COMPOSITION`	`/note` carries residue class (Gly-rich, basic, acidic, …)
`MOTIF`	SEQUENCE	`SEQ_MOTIF`	curator-defined; overlaps with PROSITE where cross-referenced
`MOD_RES`	SEQUENCE	`SEQ_MODIFIED_RESIDUE`	phosphorylation, methylation, acetylation, hydroxylation, sulfation, …
`CARBOHYD`	SEQUENCE	`SEQ_GLYCOSYLATION_SITE`	N-/O-linked, C-mannosylation, GPI anchor attachment
`LIPID`	SEQUENCE	`SEQ_LIPIDATION_SITE`	myristoylation, palmitoylation, prenylation, GPI-lipid
`CROSSLNK`	SEQUENCE	`SEQ_CROSSLINK_SITE`	isopeptide, ubiquitin/SUMO branch, sortase — bond not span, so no `residue_sequence`
`DOMAIN`	STRUCTURE	`STRUCT_DOMAIN`
`ACT_SITE`	STRUCTURE	`STRUCT_ACTIVE_SITE`
`SITE`	STRUCTURE	`STRUCT_BINDING_SITE`
`BINDING` (non-metal ligand)	STRUCTURE	`STRUCT_BINDING_SITE`	ligand ChEBI added to `xrefs`
`BINDING` (metal ligand) / `METAL`	STRUCTURE	`STRUCT_METAL_SITE`	metal keyword detection on `/ligand` + `/ligand_note`
`DISULFID`	STRUCTURE	`STRUCT_DISULFIDE`	bond, not span — no `residue_sequence`
`HELIX`, `STRAND`, `TURN`	STRUCTURE	`STRUCT_SECONDARY`	requires an experimental structure in the entry

Skipped (out-of-scope for this schema): TOPO_DOM, VARIANT, VAR_SEQ, MUTAGEN, CONFLICT, UNSURE, NON_CONS, NON_TER.

UniProtKB entry-level blocks (FUNCTION axis) → category:

UniProt block or ref	Category	Grounding
`CC CATALYTIC ACTIVITY` (per `Reaction=`)	`FUNC_ENZYMATIC_ACTIVITY`	EC, Rhea, participating ChEBIs
`DR GO; F:…activity`	`FUNC_ENZYMATIC_ACTIVITY`	GO MF
`DR GO; F:…binding`	`FUNC_BINDING_CAPACITY`	GO MF
`CC COFACTOR` (per `Name=`)	`FUNC_COFACTOR_REQUIREMENT`	ChEBI
`CC SUBCELLULAR LOCATION` (per compartment)	`FUNC_LOCALIZATION`	UniProt SubCell
`DR GO; C:…`	`FUNC_LOCALIZATION`	GO CC
`CC INDUCTION` (keyword-matched)	`FUNC_ENVIRONMENTAL_RESPONSE`	keyword vocabulary (cold, heat, oxidative stress, hypoxia, anaerobic/aerobic, osmotic, UV, …)
`DR GO; P:response to …`	`FUNC_ENVIRONMENTAL_RESPONSE`	GO BP
`CC SUBUNIT` (per "Interacts with X")	`FUNC_INTERACTION_PARTNER`	partner name; PMIDs in evidence

Worked example — how one UniProtKB entry demultiplexes across the axes

Illustrated with P25888 (ATP-dependent RNA helicase RhlE, E. coli K12). This shows the FT/CC → axis / category mapping the seeder encodes; the per-protein records themselves are not seeded standalone (they are instance-level, not trait classes — see the note in docs/example.md). A real protein is instead attached as a canonical_example on the relevant class-level trait:

Axis	Records	Categories
SEQUENCE	6	1 SEQ_DISORDER, 3 SEQ_COMPOSITION (Gly / basic+acidic / basic), 2 SEQ_MOTIF (Q motif + DEAD box)
STRUCTURE	3	2 STRUCT_DOMAIN (Helicase ATP-binding + Helicase C-terminal), 1 STRUCT_BINDING_SITE (ATP → CHEBI:30616)
FUNCTION	11	3 FUNC_ENZYMATIC_ACTIVITY (Rhea:13065 ATP hydrolysis, GO:0016887, GO:0003724), 2 FUNC_BINDING_CAPACITY (ATP + RNA), 2 FUNC_LOCALIZATION (Cytoplasm + GO:0005829), 2 FUNC_ENVIRONMENTAL_RESPONSE (cold shock + heat via GO:0009408), 2 FUNC_INTERACTION_PARTNER (PcnB + RNase E)

Each record carries identifier → proteintraitsmech:UNIPROTKB_<ACC>_<TYPE>_<KEY>, canonical_examples linking to the source entry + NCBITaxon, xrefs (GO / EC / Rhea / ChEBI / partner labels), and evidence with the source PMIDs where the flat file cites them.

All seeded records land with mapping_status: SEEDED; curator review flips them to REVIEWED and adds evidence / causal graphs.

Deep Research

ProteinTraitsMech now has the same provider-based research surface as public DisMech, specialized for sequence/structure/function evidence. mechanism targets residues, structural features, reaction chemistry, cofactors, exemplar proteins, and causal edges; family_grounding targets hierarchy, equivalence, overlap, and mapping-product provenance.

just deep-research-providers
just deep-research-providers family_grounding
just deep-research-provider claude_code mechanism
just research-protein-trait falcon data/traits/structure/cavity/pocket.yaml
just research-protein-trait falcon data/traits/structure/cavity/pocket.yaml --apply

research-protein-trait is dry-run by default — it prints the resolved deep-research-client command instead of running it. Pass --apply to actually invoke the provider; that is a live, possibly billed network call.

deep-research-provider(s) rank/inspect providers against this Mech's own conf/deep_research_provider.yaml profile (mechanism / family_grounding scoring). research-provider(s) (no deep- prefix) is the unfiltered deep-research-client providers passthrough — raw upstream availability and parameters, with no Mech-specific scoring applied.

Reports are written below research/traits/, preserving the record's directory layout. They are evidence proposals only: verify accessions, residue numbering, protein/taxon scope, chemical participants, and every proposed causal edge.

Merge queue

See the native merge-queue guide for the reviewed merge workflow when queue enforcement is enabled on main.

License

CC0-1.0 — Public Domain Dedication.

Name		Name	Last commit message	Last commit date
.claude/skills		.claude/skills
.github/workflows		.github/workflows
audit		audit
conf		conf
data		data
docs		docs
history		history
prompts		prompts
research		research
scripts		scripts
src/proteintraitsmech		src/proteintraitsmech
templates		templates
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
NEXT_TASKS.md		NEXT_TASKS.md
NEXT_TASKS_LOOP.md		NEXT_TASKS_LOOP.md
NEXT_TASK_peptides.md		NEXT_TASK_peptides.md
README.md		README.md
download.yaml		download.yaml
justfile		justfile
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Navigation Menu

Repository files navigation

ProteinTraitsMech

Scope

Quick start

Schema

Layout

Workflow

What `--force` does and does not overwrite

Enrichment fields

Seeds

Worked example — how one UniProtKB entry demultiplexes across the axes

Deep Research

Merge queue

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

ProteinTraitsMech

Scope

Quick start

Schema

Layout

Workflow

What --force does and does not overwrite

Enrichment fields

Seeds

Worked example — how one UniProtKB entry demultiplexes across the axes

Deep Research

Merge queue

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

What `--force` does and does not overwrite