reasonhub-valueset-properties

ValueSet from Code System Properties

Overview

Every code system loaded in ReasonHub exposes filter properties that let you define ValueSets declaratively — by clinical intent rather than by listing every code. This skill covers all five systems: what properties are available, which are most clinically useful, and how to combine them.

For deep SNOMED semantic queries, complement this skill with snomed-semantic. For starting from a non-SNOMED code, use terminology-crossmap first.

Before You Start

Always call this first to get the exact version string for your target system:

list_available_codesystem_versions()

Every compose.include block must include "version". Omitting it will cause the expand to fail or use an unexpected default.

To see all supported filter properties for a specific system:

codesystem_filter_properties(system="<system_url>")

SNOMED CT — `http://snomed.info/sct`

SNOMED has two complementary filter mechanisms: hierarchy (IS-A traversal) and attribute equality (semantic relationship properties). The most powerful ValueSets combine both.

Hierarchy filters

`property`	`op`	Effect
`concept`	`is-a`	Concept + all descendants
`concept`	`descendent-of`	Strict descendants only (excludes named concept)

Property equality filters (most useful)

`property`	Meaning	Tip
`363698007`	Finding site	Body structure concept ID as value
`246075003`	Causative agent	Organism or substance concept ID
`116676008`	Associated morphology	Morphologic abnormality concept ID
`363704007`	Procedure site - Direct	Body structure concept ID
`inactive`	Inactive concept flag	Use `"false"` to exclude retired codes
`semanticTag`	Semantic tag from FSN	`"disorder"`, `"finding"`, `"procedure"`
`moduleId`	SNOMED module	`731000124108` = US Edition

Combining filters (AND logic within one include)

{
  "system": "http://snomed.info/sct",
  "version": "<version>",
  "filter": [
    { "property": "concept",   "op": "is-a", "value": "64572001" },
    { "property": "363698007", "op": "=",    "value": "80891009" },
    { "property": "inactive",  "op": "=",    "value": "false"    }
  ]
}

→ Active disorders whose finding site is the heart.

Multiple include blocks (OR logic between includes)

{
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct",
        "version": "<version>",
        "filter": [{ "property": "363698007", "op": "=", "value": "80891009" }]
      },
      {
        "system": "http://snomed.info/sct",
        "version": "<version>",
        "filter": [{ "property": "363698007", "op": "=", "value": "59652004" }]
      }
    ]
  }
}

→ Disorders of the heart OR atrium.

Exclude blocks

{
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct",
        "version": "<version>",
        "filter": [{ "property": "concept", "op": "is-a", "value": "64572001" }]
      }
    ],
    "exclude": [
      {
        "system": "http://snomed.info/sct",
        "version": "<version>",
        "filter": [{ "property": "concept", "op": "is-a", "value": "128139000" }]
      }
    ]
  }
}

→ All disorders EXCEPT musculoskeletal disorders.

LOINC — `http://loinc.org`

LOINC's most useful filters are flat property equalities on CLASS, CLASSTYPE, STATUS, and ORDER_OBS. Hierarchy (parent, panel-parent) is available but less commonly needed.

Most useful property filters

`property`	`op`	Key values	Use for
`CLASS`	`=` or `in`	`CHEM`, `HEM/BC`, `MICRO`, `RAD`, `CARD`, `UA`, `COAG`	Discipline/panel type
`CLASSTYPE`	`=`	`1`=Lab, `2`=Clinical, `3`=Claims, `4`=Survey	Broad category
`STATUS`	`=`	`ACTIVE`, `DEPRECATED`, `DISCOURAGED`, `TRIAL`	Lifecycle
`ORDER_OBS`	`=` or `in`	`Order`, `Observation`, `Both`	Ordering vs reporting
`SCALE_TYP`	`=`	`LP7753-9`=Qn (quantitative), `LP7751-3`=Ord (ordinal)	Numeric vs categorical

Hierarchy filters

`property`	`op`	`value`	Effect
`parent`	`is-a`	LOINC or LP code	Code + all descendants in component hierarchy
`panel-parent`	`is-a`	LOINC code	Code + all panel/form descendants

Common patterns

All active quantitative lab chemistry tests (orderable):

{
  "system": "http://loinc.org",
  "version": "<version>",
  "filter": [
    { "property": "CLASS",     "op": "=", "value": "CHEM" },
    { "property": "CLASSTYPE", "op": "=", "value": "1" },
    { "property": "STATUS",    "op": "=", "value": "ACTIVE" },
    { "property": "ORDER_OBS", "op": "in","value": "Order,Both" },
    { "property": "SCALE_TYP", "op": "=", "value": "LP7753-9" }
  ]
}

All active hematology and chemistry tests:

{
  "filter": [
    { "property": "CLASS",  "op": "in", "value": "CHEM,HEM/BC" },
    { "property": "STATUS", "op": "=",  "value": "ACTIVE" }
  ]
}

All radiology observation codes:

{
  "filter": [
    { "property": "CLASS",     "op": "=", "value": "RAD" },
    { "property": "ORDER_OBS", "op": "=", "value": "Observation" }
  ]
}

Finding UCUM units: After expanding a LOINC ValueSet, call codesystem_lookup on any result code to get its EXAMPLE_UCUM_UNITS property for the recommended observation unit.

RxNorm — `http://www.nlm.nih.gov/research/umls/rxnorm`

RxNorm's most powerful filter is TTY (term type). It defines what level of drug granularity you want. Relationship filters (has_ingredient, tradename_of, etc.) let you build ingredient-centric sets.

TTY filter — choose your granularity

TTY	Meaning	When to use
`IN`	Ingredient	Drug class ValueSets, formulary by active substance
`SCD`	Semantic Clinical Drug (generic)	Prescribing, order entry (no brand)
`SBD`	Semantic Branded Drug	Brand-specific formulary
`SCDF`	Semantic Clinical Drug Form	Dose-form-level grouping
`BN`	Brand Name	Brand lookups
`GPCK` / `BPCK`	Generic/Branded Pack	Package-level

Relationship filters (combine with TTY)

`property`	Meaning	Value type
`has_ingredient`	Drug contains this ingredient	RxCUI of ingredient
`tradename_of`	Brand of this generic	RxCUI of generic SCD
`has_dose_form`	Drug has this dose form	RxCUI of dose form
`has_doseformgroup`	Drug has this dose form group	RxCUI of DFG

Common patterns

All generic oral solid clinical drugs:

{
  "filter": [
    { "property": "TTY",           "op": "=",  "value": "SCD" },
    { "property": "has_doseformgroup", "op": "=", "value": "316945" },
    { "property": "inactive",      "op": "=",  "value": "false" }
  ]
}

(316945 = Oral Solid Dosage Form Group)

All clinical drugs containing metformin (RxCUI 6809):

{
  "filter": [
    { "property": "TTY",           "op": "in", "value": "SCD,SCDF,SBD" },
    { "property": "has_ingredient", "op": "=", "value": "6809" }
  ]
}

All ingredients only (for drug class ValueSet):

{
  "filter": [
    { "property": "TTY",      "op": "=",   "value": "IN" },
    { "property": "inactive", "op": "=",   "value": "false" }
  ]
}

Tip: RxNorm hierarchy (via parent is-a) is sparse — IS-A traversal rarely returns what you want. Prefer TTY + relationship filters.

ICD-10-CM — `http://hl7.org/fhir/sid/icd-10-cm`

ICD-10-CM's primary filter mechanism is its tabular hierarchy via parent. Property equality filters exist but are mostly free-text and not useful for filtering.

Hierarchy filters

`property`	`op`	Effect
`parent`	`is-a`	Code + all child codes in the tabular classification
`parent`	`descendent-of`	Strict children only

Common patterns

All diabetes codes:

{ "property": "parent", "op": "is-a", "value": "E11" }

All respiratory disease codes:

{ "property": "parent", "op": "is-a", "value": "J00-J99" }

Multiple chapters (OR, two includes):

{
  "compose": {
    "include": [
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "version": "<version>",
        "filter": [{ "property": "parent", "op": "is-a", "value": "I00-I99" }]
      },
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "version": "<version>",
        "filter": [{ "property": "parent", "op": "is-a", "value": "J00-J99" }]
      }
    ]
  }
}

→ All cardiovascular OR respiratory codes.

Tip: ICD-10-CM hierarchy is very shallow compared to SNOMED. For richer subsetting, crossmap to SNOMED first (see terminology-crossmap skill).

UCUM — `http://unitsofmeasure.org`

UCUM is compositional — compound expressions like mg/dL are not indexed. Filters operate only on the ~336 base and derived atom units.

Most useful filters

`property`	`op`	Values	Effect
`property`	`=`	Physical quantity name	All units measuring that quantity
`CLASS`	`=`	`si`, `clinical`, `cgs`, `intcust`, `dimless`	Units by class
`isMetric`	`=`	`yes` / `no`	Metric-prefixable units only

Common patterns

All mass units:

{ "property": "property", "op": "=", "value": "mass" }

All clinical concentration units:

{
  "filter": [
    { "property": "CLASS",    "op": "=", "value": "clinical" },
    { "property": "property", "op": "=", "value": "mass concentration" }
  ]
}

Validating a composed expression (mg/dL, mmol/L, etc.):

codesystem_verify_code(code="mg/dL", system="http://unitsofmeasure.org")

Use this instead of expand for composed expressions — they won't appear in an expansion but are valid UCUM codes.

Cross-System ValueSets

ValueSets can mix multiple code systems in one compose:

{
  "compose": {
    "include": [
      {
        "system": "http://snomed.info/sct",
        "version": "<version>",
        "filter": [{ "property": "concept", "op": "is-a", "value": "64572001" }]
      },
      {
        "system": "http://hl7.org/fhir/sid/icd-10-cm",
        "version": "<version>",
        "filter": [{ "property": "parent", "op": "is-a", "value": "I00-I99" }]
      }
    ]
  }
}

Decision Guide — Which System to Use

Clinical goal	Best system	Key filter
Clinical conditions with rich semantic subsetting	SNOMED CT	Attribute + hierarchy
Administrative diagnosis coding (billing)	ICD-10-CM	`parent is-a`
Lab observation panels and results	LOINC	`CLASS` + `STATUS`
Medication formulary (ordering)	RxNorm	`TTY=SCD` + `has_ingredient`
Medication formulary (ingredient class)	RxNorm	`TTY=IN`
Observation units	UCUM	`property` or verify composed
Rich semantic subsetting from a non-SNOMED starting point	Crossmap to SNOMED	See `terminology-crossmap`

Debugging Expansions

If valueset_expand returns no results or an error:

Check the version — run list_available_codesystem_versions() and confirm the version string matches exactly.
Check the property code — run codesystem_filter_properties(system=...) to verify the property code is spelled correctly.
Verify the value concept — run codesystem_lookup on the filter value to confirm it exists and is active in the right system.
Test a simpler filter first — remove all but one filter condition to isolate which condition is causing empty results.
For SNOMED attribute filters — look up a representative concept you expect to match and confirm it actually has the attribute you're filtering on.

About this skill

Overview

Before You Start

SNOMED CT — http://snomed.info/sct

Hierarchy filters

Property equality filters (most useful)

Combining filters (AND logic within one include)

Multiple include blocks (OR logic between includes)

Exclude blocks

LOINC — http://loinc.org

Most useful property filters

Hierarchy filters

Common patterns

RxNorm — http://www.nlm.nih.gov/research/umls/rxnorm

TTY filter — choose your granularity

Relationship filters (combine with TTY)

Common patterns

ICD-10-CM — http://hl7.org/fhir/sid/icd-10-cm

Hierarchy filters

Common patterns

UCUM — http://unitsofmeasure.org

Most useful filters

Common patterns

Cross-System ValueSets

Decision Guide — Which System to Use

Debugging Expansions

SNOMED CT — `http://snomed.info/sct`

LOINC — `http://loinc.org`

RxNorm — `http://www.nlm.nih.gov/research/umls/rxnorm`

ICD-10-CM — `http://hl7.org/fhir/sid/icd-10-cm`

UCUM — `http://unitsofmeasure.org`