Overview
Dismech turns curated disease records into browsable disorder pages. Each page is assembled from structured data defined with Linked Data Modeling Language (LinkML), so sections appear only when that disease has curated information for them.
The current disorder pages cover disease identity, mechanisms, phenotypes, genetics, treatments, model systems, datasets, references, and supporting structure such as pathographs and differential diagnoses.
Disease Page Section Guide
The sections below reflect the headings that the current disorder template can render. Some are foundational identity sections, others are optional translational or evidence-heavy sections that only appear when curated.
Identity and structure
These sections establish what the disease is, how it is classified, and how formal criteria or subtype structure are represented.
Mechanisms and manifestations
These sections describe the biological story of the disease, from mechanistic events to phenotypic consequences and diagnostic distinctions.
Interventions and evidence surfaces
These sections cover therapeutic strategy, translational resources, and the experimental or computational systems used to study disease mechanisms.
Interface behaviors
These are page-level affordances that help readers navigate and interrogate a curated disease record.
Metadata and provenance
These sections surface generated artifacts and the audit trail around the underlying disease record.
Pathograph Example
A pathograph is the disease page’s causal graph view. Instead of summarizing a mechanism as prose, it lays out linked nodes for mechanisms, phenotypes, genetics, treatments, biomarkers, environmental factors, and model systems.
This example uses synthetic data, but it is rendered in the same interactive style as a real disease page so you can see how the different node categories appear together.
How Pages Are Made
Each disease page starts as a curated source record written in YAML. That record is checked against the Linked Data Modeling Language (LinkML) schema, then rendered into the public page and related browser data.
Structured disease records
Curated disease entries live in kb/disorders.
Shared data model
The rules for what can appear on a page are defined in src/dismech/schema/dismech.yaml.
Checked quotations
Evidence snippets are checked against fetched source text cached in references_cache.
Validation workflow
| Check | What it protects | Typical command |
|---|---|---|
| Schema validation | Ensures the YAML record conforms to the disease model and required structure. | just validate kb/disorders/Some_Disease.yaml |
| Reference validation | Checks quoted snippets against cached PubMed, trial, or structured-source content. | just validate-references kb/disorders/Some_Disease.yaml |
| Project QC | Runs the broader project quality stack including cache checks and validation layers. | just qc |
# Validate one disease record
just validate kb/disorders/Some_Disease.yaml
# Check evidence snippets
just validate-references kb/disorders/Some_Disease.yaml
# Run the broader quality-control stack
just qcExternal Resources Dismech Uses
Dismech pages do not stand alone. They link out to disease, phenotype, gene, treatment, anatomy, chemistry, trial, and literature resources so you can move from a page summary to the original terminology and evidence source.
The table below covers the main resources that appear in mappings, linked terms, references, and evidence-backed sections across the site.
| Resource | What you will see on Dismech pages | Documentation |
|---|---|---|
| Monarch Disease Ontology (MONDO) | Disease identifiers and mappings used to anchor a disorder to a shared disease vocabulary. | MONDO docs |
| Human Phenotype Ontology (HPO) | Phenotype terms for signs, symptoms, laboratory abnormalities, and cellular findings. | HPO docs |
| Gene Ontology (GO) | Biological processes, cellular components, and related mechanistic annotations. | GO documentation |
| Cell Ontology (CL) | Cell-type terms used in pathophysiology, models, and other mechanism-linked sections. | CL docs |
| Uber-anatomy Ontology (Uberon) | Anatomy and tissue terms that help place mechanisms and findings in the body. | Uberon docs |
| Chemical Entities of Biological Interest (ChEBI) | Specific drug or chemical identifiers used for treatments, biomarkers, and molecular context. | ChEBI docs |
| Medical Action Ontology (MAXO) | Treatment-action terms such as pharmacotherapy, surgery, rehabilitation, and supportive care. | MAXO docs |
| NCI Thesaurus (NCIT) | Additional disease, treatment, and drug-class terms, especially where cancer or intervention detail is helpful. | NCIT browser |
| Human Gene Nomenclature Committee (HGNC) | Stable human gene identifiers used in genetic associations and mechanistic annotations. | HGNC docs |
| International Classification of Diseases (ICD) | Clinical coding mappings used to connect Dismech records to common diagnostic code systems. | ICD docs |
| PubMed and PubMed identifiers (PMIDs) | Literature references and quoted evidence snippets used to support claims on disease pages. | PubMed |
| ClinicalTrials.gov and NCT identifiers | Clinical trial records linked from treatment and translational sections when trial data is curated. | ClinicalTrials.gov |
| Orphanet and ORPHA identifiers | Rare-disease definitions, epidemiology, phenotypes, and cross-references incorporated through structured sources. | Orphanet |
| Clinical Genome Resource (ClinGen) | Structured evidence from ClinGen Gene-Disease Validity (CGGV) and ClinGen Dosage Sensitivity (CGDS) records. | ClinGen gene validity and ClinGen dosage |
Behind the Scenes
If you want the project mechanics, these are the main tools and workflows that keep pages validated, linked, and up to date. Automated helpers can assist with drafting, but published pages still come from repository files, validation commands, and normal pull request review.
Core Tools Used in This Project
| Tool | Brief explanation | How it is used here |
|---|---|---|
| Claude and Claude Code | LLM assistant tooling used for guided curation, review responses, and targeted repository edits. | Integrated via GitHub workflows such as claude.yml and claude-code-review.yml. |
| DRAGON-AI | An ontology-aware agent workflow used for repository interactions and follow-up edits triggered from collaboration events. | Configured in .github/workflows/dragon-ai.yml for mention-driven issue, PR, and review processing. |
| Deep Research Agents | Provider-based research agents used to populate initial evidence candidates before structured curation and validation. | Run through Deep Research Client and repository commands in project.justfile. |
| GitHub Actions | Automation platform for CI checks, scheduled compliance runs, page generation, deploys, and release exports. | Workflow definitions are maintained in .github/workflows, including build/test, generation, weekly compliance, and agent workflows. |
| Just and Justfiles | A command runner for repeatable project tasks, similar to lightweight build recipes. | Project commands for validation, page generation, QC dashboards, research, and exports are defined in project.justfile and imported via justfile. |
| OAK | A unified API and toolkit for ontology lookup, traversal, and term validation across ontology sources. | Adapters are configured in conf/oak_config.yaml and used by LinkML term-validation steps. |
| LinkML | A data modeling language and tooling ecosystem for defining schemas, generating artifacts, and validating data. | The core model is defined in src/dismech/schema/dismech.yaml; Dismech uses schema, term, and reference validation in the QC pipeline. |
Main project layers
| Layer | What it does | Implementation link |
|---|---|---|
| Data model | Disease classes, slots, enums, descriptor bindings, and evidence model. | src/dismech/schema/dismech.yaml |
| Knowledge content | Curated disease and comorbidity records in YAML. | kb |
| Ontology adapters | OAK-backed ontology resolution and term validation configuration. | conf/oak_config.yaml |
| Rendering pipeline | Generates disorder, comorbidity, and classification pages plus causal graph views. | src/dismech/render.py |
| Browser UI | Faceted search app, schema-driven field config, and generated records. | app |
| Commands and recipes | Validation, generation, research, and export task entry points. | project.justfile |
| Automation workflows | Continuous integration, page generation, compliance loops, docs deploy, and release exports. | .github/workflows |
| Agentic research integration | Provider-based deep-research report generation used in curation loops. | Deep Research Client |
Automation Workflows
These workflows keep the site current and checked. They combine standard continuous integration with recurring maintenance jobs, then route the results back through normal pull request review.
| Workflow | Trigger and scope | Automated actions | Human touchpoint |
|---|---|---|---|
| main.yaml | Push to main and all pull requests; path-filtered to changed source, disorder YAML, and comorbidity YAML. | Runs linting, validates only changed disorder and comorbidity files, and runs tests when source code changes. | Reviewers inspect failing and passing checks and request edits before merge. |
| generate-pages.yaml | Push to main when KB, templates, render, export, or QC config changes, plus manual dispatch. | Regenerates pages, browser data, and dashboard output; commits outputs and opens an automated pull request when diffs exist. | Maintainers review generated-content pull requests and spot-check render and dashboard correctness. |
| weekly-compliance.yaml | Weekly cron plus manual dispatch with inputs like num_files, areas_for_improvement, and model choice. | Runs automated compliance-improvement passes using compliance metrics and validation loops, then prepares per-file fix pull requests. | Humans choose focus areas, review generated fixes, and merge or request correction. |
| post-review-agent.yml | Daily cron plus manual dispatch with days_back, dry_run, optional pull request number, and model choice. | Scans unresolved editorial review comments and chooses one action: suggested patch, thread reply, or new issue for broader work. | Pull request authors accept or reject suggested changes and continue discussion in review threads. |
| dragon-ai.yml | Issue, pull request, and comment events; runs only on qualifying mentions from allowlisted controllers. | Parses mention intent, builds a structured prompt, and runs headless agent execution tied to GitHub context. | Controllers direct tasks in threads; maintainers review resulting changes and pull requests. |
| kgx-release.yaml | Release-oriented export flow. | Builds Knowledge Graph Exchange (KGX) export artifacts and attaches versioned outputs to releases. | Release maintainers verify export quality and publish release notes and artifacts. |
Related Tooling and Integrations
Key references and entry points
The autogenerated schema reference is available at dismech.monarchinitiative.org/elements.
Project contribution workflow lives in CONTRIBUTING.md.
Ontology adapters and term-validation configuration are maintained in conf/oak_config.yaml.
Deep-research reports complement curation, but they do not replace schema, term, or reference validation.