disease-classification

name: disease-classification description: > Skill for populating the classifications top-level block of a dismech Disease entry. Covers Harrison's Part assignment, mechanistic nosology, lysosomal storage, IUIS immunodeficiency, channelopathy, and ICD-O morphology fields, with a lookup table from common clinical phrasing to controlled-vocabulary keys.

Adding classifications

The classifications block carries multiple disease-taxonomy assignments, each ranged by its own enum. Curators populate the slot(s) most relevant to the disease — most entries will set harrisons_chapter plus zero or more of the more specific category slots (mechanistic_category, lysosomal_storage_category, etc.).

classifications:
  harrisons_chapter:
  - classification_value: ENDOCRINOLOGY_METABOLISM
  - classification_value: GENETICS_ENVIRONMENT_DISEASE
  mechanistic_category:
  - classification_value: tauopathy

All classification_value slots are enum-typed: free-text values will fail schema validation. Use the controlled keys below.

Harrison's Part (harrisons_chapter)

Despite the slot name, the controlled vocabulary lives at the Part level of Harrison's Principles of Internal Medicine (21st edition), not at individual chapter granularity. The full enum is defined in src/dismech/schema/dismech.yaml as HarrisonsChapterEnum. The slot is multivalued — assign every Part that contains a relevant chapter.

Lookup table (common phrasings → enum key)

Use this table to translate the natural-language category you want to express into the right enum key.

How to pick Parts

• Prefer the organ-system Part where Harrison's would publish the primary chapter on the disease (e.g., asthma → RESPIRATORY, not IMMUNE_RHEUMATOLOGIC).
• Add a second Part when the disease has a major mechanistic axis that Harrison's covers separately. Example: Familial Mediterranean Fever → IMMUNE_RHEUMATOLOGIC (primary clinical home) plus GENETICS_ENVIRONMENT_DISEASE (Mendelian inheritance is a recurring theme).
• Skeletal dysplasias and other hereditary musculoskeletal conditions generally go to GENETICS_ENVIRONMENT_DISEASE. Reserve IMMUNE_RHEUMATOLOGIC for inflammatory / immune-mediated entities.
• Cancers always go to ONCOLOGY_HEMATOLOGY; an organ-system Part is optional and usually unnecessary unless the entry is about an organ-specific paraneoplastic syndrome.

Verifying the enum

uv run python -c "
import yaml
with open('src/dismech/schema/dismech.yaml') as f:
    data = yaml.safe_load(f)
for k in data['enums']['HarrisonsChapterEnum']['permissible_values']:
    print(k)
"

Other classification slots

The same classifications block accepts several more specific taxonomies when they apply. All use classification_value: ranged by their own enum.

• mechanistic_category — pathway / mechanism-based nosology (tauopathy, synucleinopathy, proteotoxic disease, RASopathy, ciliopathy, mitochondrial disease, intermediate filament disease, etc.). Multivalued.
• lysosomal_storage_category — biochemical classification of lysosomal storage disorders (glycoproteinosis, disorder of glycogen metabolism, etc.). Single-valued.
• iuis_category — IUIS primary-immunodeficiency classification. Single-valued.
• channelopathy_category — organ-system grouping for channelopathies (cardiac channelopathy, neurological channelopathy, etc.). Single-valued.
• icdo_morphology — ICD-O cancer-morphology category (Carcinoma, Adenocarcinoma, Sarcoma, Leukemia, Lymphoma, Melanoma, Glioma, Embryonal Neoplasm, Squamous Cell Carcinoma). Apply to neoplastic entries.

When the same concept fits both Harrison's and a more specific slot, set both. Example: a tauopathy gets harrisons_chapter: NEUROLOGIC and mechanistic_category: tauopathy.

Backing classifications with evidence

Every classification_value entry is a ClassificationAssignment and carries optional evidence: and notes: slots inherited from the base class. Cite an authoritative source whenever you can — this turns the classification from "curator opinion" into a checkable annotation and prevents AI-fabricated taxonomy drift over time.

Do not quote Harrison's Principles of Internal Medicine directly: the textbook is copyrighted and snippets are not redistributable. Cite the open-access peer-reviewed alternatives below instead. The pattern is the same as any other dismech evidence block — exact-quote snippet from the cited reference's abstract or text.

harrisons_chapter:
- classification_value: GASTROINTESTINAL
  evidence:
  - reference: PMID:39101000
    supports: SUPPORT
    evidence_source: HUMAN_CLINICAL
    snippet: "Inflammatory bowel disease (IBD), comprising Crohn's disease and ulcerative colitis, is a chronic relapsing inflammatory disorder of the gastrointestinal tract."
    explanation: Recent review characterises IBD as a gastrointestinal-tract inflammatory disorder, supporting placement in Harrison's GI Part.

Authoritative classification sources per Part

For each Part, the table below names a reusable family of citable sources. Prefer the most disease-specific source available, but these are good fallbacks when a disorder-specific recent review isn't at hand.

Structured sources are first-class evidence

When the cited source is already in dismech's structured cache (currently Orphanet and ClinGen — see CLAUDE.md), prefer the structured prefix over a free-text PMID for classification evidence:

harrisons_chapter:
- classification_value: GENETICS_ENVIRONMENT_DISEASE
  evidence:
  - reference: ORPHA:558
    supports: SUPPORT
    snippet: "Marfan syndrome is a systemic disease of connective tissue"
    explanation: Orphanet classifies Marfan as a systemic connective-tissue disorder of Mendelian inheritance.

These structured snippets are deterministic (Orphadata is refreshed from a pinned XML manifest) and never drift in wording.

Workflow for adding classification evidence

1. Pick the cited source. Prefer (a) an existing reference already on the disease entry that characterises the disease's category, (b) a structured prefix (ORPHA:, CGGV:, CGDS:) if applicable, or (c) a fresh authoritative paper from the table above.
2. Cache it if it's a literature reference and not yet present:

   just fetch-reference PMID:XXXX
   

3. Write the evidence block with an exact-quote snippet from the cached abstract that itself frames the disease in the classification's terms (e.g., "is a chronic kidney disease characterised by…").
4. Validate:

   just validate kb/disorders/<File>.yaml
   just validate-references kb/disorders/<File>.yaml
   

Auditing missing classification evidence

uv run python - <<'PY'
from pathlib import Path
from ruamel.yaml import YAML
y = YAML(typ='safe')
for p in sorted(Path("kb/disorders").glob("*.yaml")):
    data = y.load(p.read_text()) or {}
    items = ((data.get("classifications") or {}).get("harrisons_chapter") or [])
    for it in items:
        if isinstance(it, dict) and not it.get("evidence"):
            print(f"{p.name}\t{it.get('classification_value')}")
PY

Validation

uv run linkml-validate -s src/dismech/schema/dismech.yaml \
  -C Disease kb/disorders/<File>.yaml

Schema validation will reject free-text Harrison's values; if you see '<value>' is not one of [...] for harrisons_chapter, look the phrasing up in the table above and switch to the enum key.