# Hierarchical Multiselect

Source: https://www.potatoannotator.com/docs/annotation-types/hierarchical-multiselect

The hierarchical multiselect annotation schema provides an expandable tree interface for selecting categories from a nested taxonomy. This schema is ideal for tasks where labels are organized in a hierarchy, such as topic classification, product categorization, or any multi-level tagging task.

## Overview

The hierarchical multiselect schema presents a collapsible tree view where:
- **Parent nodes** expand to reveal child categories
- **Leaf nodes** can be selected individually
- **Optional auto-selection** propagates selections up or down the tree
- **Search** allows annotators to find categories quickly in large taxonomies

## Quick Start

```yaml
annotation_schemes:
  - annotation_type: hierarchical_multiselect
    name: topic_tags
    description: Select all applicable topic categories.
    taxonomy:
      Science:
        Physics:
          - Quantum Mechanics
          - Thermodynamics
        Biology:
          - Genetics
          - Ecology
      Technology:
        - Software
        - Hardware
```

## Configuration Options

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `annotation_type` | string | Required | Must be `"hierarchical_multiselect"` |
| `name` | string | Required | Unique identifier for this schema |
| `description` | string | Required | Instructions displayed to annotators |
| `taxonomy` | object | Required | Nested object defining the category hierarchy |
| `auto_select_children` | boolean | `false` | When a parent is selected, automatically select all its children |
| `auto_select_parent` | boolean | `false` | When all children are selected, automatically select the parent |
| `show_search` | boolean | `false` | Display a search box to filter the taxonomy tree |
| `max_selections` | integer/null | `null` | Maximum number of categories that can be selected (`null` for unlimited) |
| `expand_depth` | integer | `1` | Number of tree levels to expand by default |
| `label_requirement.required` | boolean | `false` | Whether at least one selection is required before submitting |

## Examples

### Topic Classification

```yaml
annotation_schemes:
  - annotation_type: hierarchical_multiselect
    name: topic_classification
    description: Select all topics that apply to this document.
    show_search: true
    max_selections: 5
    taxonomy:
      Politics:
        Domestic:
          - Elections
          - Legislation
          - Policy
        International:
          - Diplomacy
          - Trade
          - Conflict
      Sports:
        - Football
        - Basketball
        - Tennis
      Entertainment:
        Film:
          - Reviews
          - Industry News
        Music:
          - Reviews
          - Concerts
```

### Product Categorization with Auto-Selection

```yaml
annotation_schemes:
  - annotation_type: hierarchical_multiselect
    name: product_category
    description: Categorize this product listing.
    auto_select_children: true
    auto_select_parent: true
    expand_depth: 2
    taxonomy:
      Electronics:
        Computers:
          - Laptops
          - Desktops
          - Tablets
        Audio:
          - Headphones
          - Speakers
      Clothing:
        Men:
          - Shirts
          - Pants
        Women:
          - Dresses
          - Tops
```

### Medical Coding

```yaml
annotation_schemes:
  - annotation_type: hierarchical_multiselect
    name: diagnosis_codes
    description: Select all applicable diagnosis categories.
    show_search: true
    label_requirement:
      required: true
    taxonomy:
      Cardiovascular:
        Hypertension:
          - Primary
          - Secondary
        Arrhythmia:
          - Atrial Fibrillation
          - Ventricular Tachycardia
      Respiratory:
        Obstructive:
          - Asthma
          - COPD
        Infectious:
          - Pneumonia
          - Bronchitis
```

## Output Format

```json
{
  "topic_tags": {
    "labels": ["Science > Physics > Quantum Mechanics", "Technology > Software"]
  }
}
```

Selected categories are stored as full path strings from root to leaf.

## Best Practices

1. **Keep taxonomies manageable** - avoid more than 4 levels of nesting; deep trees are hard to navigate
2. **Enable search for large taxonomies** - when there are more than 30 categories, `show_search: true` greatly improves usability
3. **Use auto-selection carefully** - auto-selecting children is useful when parent categories imply all children, but can be confusing otherwise
4. **Set appropriate expand depth** - expand enough levels so annotators can see the structure without being overwhelmed
5. **Limit selections when appropriate** - use `max_selections` to prevent annotators from over-tagging

## Further Reading

- [Radio & Multiselect](/docs/annotation-types/radio-multiselect) - Flat label selection
- [Select Dropdown](/docs/annotation-types/select-dropdown) - Single-select dropdown
- [Quality Control](/docs/features/quality-control) - Attention checks and gold standards

For implementation details, see the [source documentation](https://github.com/davidjurgens/potato/blob/main/docs/annotation_schemes.md).