TraitMech

Microbial ecophysiological trait knowledge base, seeded from METPO and curated incrementally.

Overview

TraitMech is the trait/phenotype counterpart of CultureMech (growth media), MediaIngredientMech (chemical ingredients), and CommunityMech (microbial communities). Each trait — Gram type, motility, pH optimum, "uses as carbon source", "halophilic", etc. — lives in its own YAML file with provenance back to its METPO source class and (optionally) to literature evidence.

Initial seed (from data/raw/metpo.owl, METPO 2025-11-25) and current curation status:

Category	REVIEWED	DEPRECATED	causal_graphs	Total
MORPHOLOGY	88	0	88	88
PHYSIOLOGY	45	0	45	45
ENVIRONMENT	121	0	121	121
ECOLOGY	26	0	26	26
GENOMICS	19	0	19	19
UPPER	8	0	5	8
METABOLISM	120	23	49	143
OBSERVATION	0	20	0	20
QUANTITATIVE_PROPERTY	0	7	0	7
TOTAL	427	50	353	477

All 477 records have a terminal curation status: 427 are REVIEWED and 50 are DEPRECATED. Of the reviewed records, 353 currently carry causal graphs. The 50 deprecated records (23 metabolism, 20 observation, 7 quantitative_property) are generic relation or measurement carriers from the upstream METPO seed that are not intended to carry mechanism graphs in TraitMech. They are retained for traceability while specific trait records capture the chemical, quality, measurement, or growth context.

(material entity subtree — chemicals / microbes / enzymes — is not seeded; those belong in MIM / CultureMech.)

Quick start

just install                  # uv sync --extra dev
just gen-schema               # generate dataclasses from LinkML
just seed-from-metpo          # dry-run; print per-category counts
just seed-apply               # write data/traits/<category>/<slug>.yaml
just validate-all             # validate every TraitRecord YAML

Schema

src/traitmech/schema/traitmech.yaml defines:

• TraitRecord — root class, one per YAML file. Carries identifier (METPO CURIE), label, definition, parent_traits, xrefs, synonyms, trait_category, term_kind, optional evidence, optional curation_history, and optional inline causal_graphs.
• CausalGraph / CausalNode / CausalEdge — evidence-backed causal mechanism graphs for trait pages. Nodes can represent traits, pathways, environmental factors, experimental factors, genes/proteins, chemicals, organelles, cellular localizations, molecular functions, or biological processes. Use ontology/database CURIEs in grounding when available; label-only draft nodes are permitted in v1.
• TraitSynonym / EvidenceItem / CurationEvent — ancillary classes.
• TraitCategoryEnum — 11 schema buckets (the 9 populated buckets above, plus DETECTION and OTHER).
• TermKindEnum — CLASS / DATATYPE_PROPERTY / OBJECT_PROPERTY / ANNOTATION_PROPERTY.
• MappingStatusEnum — SEEDED / REVIEWED / DEPRECATED.
• PriorityEnum, SynonymTypeEnum.

Layout

TraitMech/
├── data/
│   ├── raw/metpo.owl                    # vendored METPO release (2025-11-25)
│   ├── embeddings/                      # graph, nearest-neighbour, and UMAP data
│   └── traits/<category>/<slug>.yaml    # 477 curated TraitRecords
├── mappings/                                # reviewed node and predicate groundings
├── research/traits/                         # source-finding reports and sidecars
├── proposals/                               # upstream METPO proposal cohorts
├── reports/                                 # audits, residuals, and curation backlogs
├── history/                                 # append-only curation provenance
├── pages/                                   # rendered trait browser and graph views
├── app/                                     # priority and discussion dashboards
├── src/traitmech/
│   └── schema/traitmech.yaml            # LinkML schema
├── scripts/
│   └── *.py                             # seed, validate, audit, migrate, and render
├── tests/
└── docs/
    ├── CURATION_PLAYBOOK.md             # how to curate a TraitRecord
    ├── GROUNDING_POLICY.md              # which ontology to ground to
    ├── WORKFLOW_CONVENTIONS.md          # CI: action pinning, concurrency
    └── SCHEMA.md

Artifacts and outputs

The rendered TraitMech site is the main human-facing entry point. It includes the trait browser, causal graph explorer, and UMAP view. Additional views are the QC dashboard, research-priority dashboard, and curation discussions dashboard.

The complete artifact collections are:

Collection	Contents
Trait records	The authoritative per-trait YAML corpus, grouped by category
Schemas	TraitMech, shared Mech, and curation-history LinkML schemas
Vendored sources	The pinned METPO and Biolink Model inputs
Grounding mappings	Reviewed node, predicate, and UniProt grounding tables
Derived embeddings	Trait graph, DeepWalk, nearest-neighbour, and UMAP artifacts
Research artifacts	Per-trait deep-research reports and citation sidecars
METPO proposals	Upstream proposal cohorts, reviewer narratives, ROBOT tables, and SSSOM mappings
Audit and backlog reports	Quality reports, residuals, match candidates, and curation queues
Curation history	Append-only provenance for record, mapping, report, and infrastructure changes
Rendered pages	Generated trait pages, category indexes, graph data, and static assets
Dashboards and apps	Research prioritization and discussion artifacts
QC dashboard artifacts	Coverage dashboard HTML and chart
Research prompts	Reusable Claude Code and issue-cycle prompts
Research template	Causal-graph research report template
Audit configuration	Ratchet baselines, provider routing, QC, and prioritization configuration
Documentation	Schema, curation, grounding, workflow, and integration guidance
Claude skills and command	Repository-specific agent workflows and guardrails

For direct access to every committed report, see:

• Graph quality: causal graph audit, connectivity, historical paid-research snapshots for completeness and the enrichment backlog, and audit manifest.
• Validation and pipeline quality: instance summary, instance failures, schema gap audit, pipeline gap audit, writer audit, Biolink coverage, and predicate domain audit.
• Grounding quality: node residual, predicate residual, node match candidates, enriched node candidates, fuzzy node candidates, research grounding backlog, research grounding drift, UniProt audit, UniProt candidates, and label drift.
• Curation queues: gap-fix narrative, gap-fix table, knowledge-gap narrative, knowledge-gap data, promotion review, and proposal citation audit.
• Trait proposal reports: ecology, environment, genomics, metabolism, metabolism round 2, morphology, physiology, and leftovers.

Workflow

1. Refresh upstream: just refresh-metpo copies the latest metpo.owl from ../assays/assay-metadata/.
2. Seed: just seed-apply creates new YAMLs without touching existing ones (use --force to overwrite).
3. Curate: edit data/traits/<category>/<slug>.yaml directly; set mapping_status: REVIEWED, append a CurationEvent, attach EvidenceItem blocks with PMID + verbatim snippet.
4. Add causal graphs: add causal_graphs only when the trait has source-backed mechanism structure. Every CausalEdge must include edge-level evidence; prefer grounded CURIEs for nodes and predicates when a suitable ontology or database term is known.
5. Validate: just validate-all (alias for just validate-strict) runs closed-mode LinkML validation over every record; unknown fields and missing required attributes fail with exit 1 and a row in reports/instance_validation_failures.tsv.

Deep Research

TraitMech mirrors DisMech's deep-research-client workflow for agentic curation support. Use Edison (Falcon) research reports as source-finding inputs, then manually curate only DOI-backed claims into TraitRecord YAML.

edison is the default provider — a TraitMech alias for deep-research-client's falcon, the Edison Scientific research agent. The client has no provider literally named edison; see .claude/skills/research-causal-graphs/SKILL.md.

export EDISON_API_KEY=...        # Edison platform credential; also what falcon needs
just research-provider falcon
just deep-research-providers causal_mechanism
just deep-research-provider asta definition_grounding
just research-trait physiology autotrophic            # Edison (default provider)
just research-trait physiology autotrophic --dry-run
just research-trait physiology autotrophic --provider openai   # override

Reports are written under research/traits/<category>/ with separate citation files. The API key is read from the environment and is never written by the TraitMech tooling.

deep-research-providers performs TraitMech-specific triage across discovery, mechanistic synthesis, and independent edge/identifier verification. Use definition_grounding when the target is scope, synonyms, parents, or ontology mapping rather than a causal graph.

Cross-repo integration

• Records preserve their METPO CURIE in identifier so trait references in CultureMech / MediaIngredientMech / kg-microbe (where METPO terms already appear) resolve directly to a TraitMech YAML.
• xrefs carries equivalents in PATO / GO / NCIT / ENVO / CHEBI / UO for cross-ontology lookup.

License

CC0-1.0 — Public Domain Dedication.