dosdp-design-patterns

What this skill does

# DOSDP Design Patterns Guide

This skill helps you understand, identify, and apply Dead Simple Ontology Design Patterns (DOSDP) when creating or editing ontology terms.

## What are DOSDP Patterns?

DOSDP patterns are templates that ensure consistent naming, definitions, and logical axioms across similar types of ontology terms. They encode best practices for term construction and help maintain consistency in:

- **Term naming conventions** - How terms should be named
- **Text definitions** - Standard definition templates
- **Logical definitions** - OWL equivalence axioms (intersection_of in OBO)
- **Synonyms** - Standard synonym patterns
- **Relationships** - Which relationships to use

## Why Design Patterns Matter

1. **Consistency**: All terms following the same pattern have the same structure
2. **Quality**: Patterns encode domain expertise and best practices
3. **Automation**: Pattern-based terms can be generated or validated automatically
4. **Reasoning**: Logical definitions enable automated classification
5. **Maintenance**: Updates to patterns can be applied systematically

## Pattern File Structure

DOSDP patterns are defined in YAML files with this structure:

```yaml
pattern_name: pattern_name_here

description: 'Human-readable description with examples'

classes:
  # Upper-level classes used in the pattern
  disease: MONDO:0000001

relations:
  # Relations used in logical definitions
  disease has location: RO:0004026

vars:
  # Variables that will be filled in
  disease: "'disease'"
  location: "'anatomical entity'"

name:
  # Template for term name
  text: '%s of %s'
  vars: [disease, location]

def:
  # Template for definition
  text: 'A %s that involves the %s.'
  vars: [disease, location]

equivalentTo:
  # Logical definition template (OWL equivalence)
  text: "%s and 'disease has location' some %s"
  vars: [disease, location]
```

## Common Pattern Types

### Location-Based Patterns

**Pattern**: `location.yaml`

Used when a disease/phenotype affects a specific anatomical location.

**Structure**:
- Name: `{disease} of {location}` or `{location} {disease}`
- Definition: `A {disease} that involves the {location}.`
- Logic: `{disease} and 'disease has location' some {location}`

**Examples**:
- lymph node adenoid cystic carcinoma
- articular cartilage disease
- urethral disease

**When to use**: Creating terms for diseases in specific anatomical locations

### Gene-Based Disease Patterns

**Pattern**: `disease_series_by_gene.yaml`

Used for diseases caused by mutations in a specific gene.

**Structure**:
- Name: `{disease} caused by variation in {gene}` or `{gene}-related {disease}`
- Definition: `Any {disease} in which the cause of the disease is a variation in the {gene} gene.`
- Logic: `{disease} and 'has material basis in germline mutation in' some {gene}`
- Relationship: `has_material_basis_in_germline_mutation_in {gene_id}`

**Examples**:
- MED12-related intellectual disability syndrome
- TTN-related myopathy
- MYCBP2-related developmental delay with corpus callosum defects

**When to use**: Creating terms for monogenic diseases with gene-based names

**Important notes**:
- Always verify gene identifiers (HGNC for human, NCBI Gene for non-human)
- Use the pattern's naming convention even if users request different formats
- Include proper source attribution in relationships

### Age of Onset Patterns

**Patterns**: `childhood.yaml`, `adult.yaml`, `infantile.yaml`

Used for diseases characterized by onset at specific life stages.

**Structure**:
- Name: `{age_stage} {disease}`
- Definition: `A {disease} that occurs during {age_stage}.`
- Logic: `{disease} and 'has characteristic' some {age_characteristic}`

**Examples**:
- childhood astrocytic tumor
- adult neuronal ceroid lipofuscinosis
- infantile epilepsy

**When to use**: Creating age-specific variants of diseases

### Inheritance Pattern Terms

**Patterns**: `autosomal_dominant.yaml`, `autosomal_recessive.yaml`, `x_linked.yaml`, `y_linked.yaml`

Used for diseases with specific inheritance patterns.

**Examples**:
- autosomal dominant polycystic kidney disease
- autosomal recessive intellectual disability

**When to use**: Creating terms that emphasize inheritance mode

### Neoplasm/Cancer Patterns

**Patterns**: `cancer.yaml`, `carcinoma.yaml`, `benign.yaml`, `malignant.yaml`, `sarcoma.yaml`

Used for various types of neoplastic diseases.

**Examples**:
- lung cancer
- squamous cell carcinoma of skin
- benign neoplasm of breast

**When to use**: Creating cancer/tumor-related terms

### Process-Based Patterns

**Pattern**: `basis_in_disruption_of_process.yaml`

Used for diseases characterized by disruption of a biological process.

**Structure**:
- Logic includes: `'has basis in disruption of' some {process}`

**When to use**: Diseases with clear mechanistic etiology

### Other Common Patterns

- **Inflammatory diseases**: `inflammatory_disease_by_site.yaml`
- **Infectious diseases**: `infectious_disease_by_agent.yaml`
- **Allergies**: `allergy.yaml`, `allergic_form_of_disease.yaml`
- **Rare diseases**: `rare.yaml`, `rare_genetic.yaml`
- **Clinical forms**: `isolated.yaml`, `syndromic.yaml`, `acute.yaml`, `chronic.yaml`

## Applying Patterns: Step-by-Step Process

### Step 1: Identify the Applicable Pattern

Before creating a new term, ask:

1. What is the primary distinguishing characteristic?
   - Location? → Use location pattern
   - Gene? → Use disease_series_by_gene pattern
   - Age of onset? → Use childhood/adult/infantile pattern
   - Cell/tissue type? → Use neoplasm_by_origin or similar
   - Process disrupted? → Use basis_in_disruption_of_process

2. Check pattern directory:
   - Look in `src/patterns/dosdp-patterns/*.yaml`
   - Read pattern descriptions
   - Review examples in the pattern file

3. Examine similar existing terms:
   - Use obo-grep or search to find similar terms
   - Check their structure for consistency

### Step 2: Verify Pattern Components

Once you've identified a pattern, gather the required information:

1. **Variable values**: What will fill the pattern slots?
   - For gene patterns: Verify gene identifier (HGNC/NCBI Gene)
   - For location patterns: Find UBERON/CL term
   - For agent patterns: Find NCBITaxon or other appropriate ID

2. **Parent class**: What is the upper-level class?
   - Should match the pattern's requirement
   - Verify it's the most specific appropriate parent

3. **References**: What sources support this term?
   - PMIDs for definitions
   - Sources for relationships
   - Attribution for synonyms

### Step 3: Apply the Pattern Structure

Create the term following the pattern's template:

**Name**: Follow the pattern's naming convention exactly
- Don't deviate even if user requests different format
- Pattern ensures consistency across the ontology

**Definition**: Use the pattern's definition template
- Fill in variables appropriately
- Add clinical details if needed
- Include proper citations

**Logical definition**: Create intersection_of axioms
```
intersection_of: {parent_class}
intersection_of: {relation} {filler}
```

**Relationships**: Add appropriate relationship statements
```
relationship: {relation} {target} {source="PMID:xxxxx"}
```

**Synonyms**: Follow pattern's synonym templates
- Add with proper scope (EXACT, RELATED, etc.)
- Include citations

### Step 4: Verify Pattern Compliance

Check that your term follows the pattern:

1. **Name matches template**: Does it follow the `name:` section?
2. **Definition matches template**: Does it follow the `def:` section?
3. **Logic is complete**: Are all `intersection_of` axioms present?
4. **Relationships included**: Are redundant relationships present with attribution?
5. **Synonyms follow patterns**: Do they match `annotations:` section?

## Pattern Compliance Examples

### Good Example: Gene-Based Disease Pattern

```
[Term]
id: MONDO:1060117
name: MYCBP2-related developmental delay with corpus callosum defects
def: "Any neurodevelopmental disorder in which th