Ontology Lookup Data Type
Once an ontology has been loaded and the module enabled in your folder, the
field editor will include an
Ontology Lookup data type for all column types. Any column may be defined to use the standard vocabularies available in a selected ontology source.
There can be up to three related fields in the data structure. The naming does not need to match these conventions, but it can be helpful to clarify which columns contain which elements:
- columnName_code: The ontology standard code, a string which can either be provided or retrieved from the ontology. This column is configured as an Ontology Lookup and may have one or both of the following related columns:
- columnName_import: (Optional) The reported, or locally used term that could be imported with the data. If no code is provided, the ontology lookup mechanism will seek a unique code value (and label) matching this term.
- columnName_label: (Optional) The preferred or standard term retrieved from the ontology. This field is read-only and set by the ontology lookup mechanism as a user-readable supplement to the code value.
Lookup Rules
On data import (or update), the following ontology lookup actions will occur:
- If only an "*_import" value is provided, the "*_label" and "*_code" will be populated automatically if found in the ontology as a concept or synonym.
- Note that a code value can be provided as the "*_import" value and will be a successful lookup, provided it is included in the ontology as a synonym for itself.
- If the provided "*_import" happens to match a concept "*_label", it will be shown in both columns: retained as the "*_import" and populated by the lookup as the "*_label".
- If only a code value is provided directly in the "*_code" column, the label will be populated from the ontology. (No "*_import" value will be populated.)
- Note that when the code value is provided in the "*_code" column, it must be prefixed with the ontology abbreviation. Ex: "NCI:c17113", not just "c17113".
- If both an "*_import" and "*_code" value are provided (even if null), the "*_code" is controlling. Note that this means that if there is a "*_code" column in your data, it must contain a valid code value, otherwise the "null" value of this column will "overrule" the lookup of any "_import" value provided. This means:
- For data insert or bulk update, you should include either the "*_code" column or the "*_import" column, but not both, unless the "*_code" is always populated.
- For data update in the grid, providing an "*_import value will not look up the corresponding code; the "*_code" column is present (and null during the update), so will override the lookup.
Usage Example
For example, if you had a dataset containing a disease diagnosis, and wanted to map to the preferred label and code values from a loaded ontology, you could follow these steps:
- Create three fields for your "columnName", in this case "Disease", with the field suffixes and types as follows:
| Field Name | Data Type | |
|---|
| Disease_import | Text | The term imported for this disease, which might be a synonym or could be the preferred term. |
| Disease_label | Text | The standard term retrieved from the ontology. |
| Disease_code | Ontology Lookup | Will display the standard code from the ontology and provides the interconnection |
- Expand the "columnName_code" field.
- Under Ontology Lookup Options:
- Choose an Ontology: The loaded ontologies are all available here. Select which to use for this field.
- Choose an Import Field: Select the "columnName_import" field you defined, here "Disease_import"
- Choose a Label Field: Select the "columnName_label" field you defined.
When data is imported, it can include either the "*_import" field or the "*_code" field, but not both. When using the "*_import" field, if
different terms for the same disease are imported, the preferred term and code fields will standardize them for you. Control which columns are visible using the
grid customizer.
Shown here, a variety of methods for entering a COVID-19 diagnosis were provided, including the preferred term for patient PT-105 and the code number itself for PT-104. All rows can be easily grouped and aggregated using the label and code columns. The reported "*_import" value is retained for reference.
Concept Picker for Insert/Update with Type-ahead
When an
Ontology Lookup field, i.e. the "*_code" field, is included in the insert or update form, you will see a "Search [Ontology Name]" placeholder. Type ahead (at least three characters, and full words for narrower lists) to quickly browse for codes that match a desired term. You'll see both the terms and codes in a dropdown menu. Click to select the desired concept from the list.
You'll see the code in the entry box and a tooltip with the preferred label on the right.
Alternately, you can use the
Find [column name] By Tree link to browse the full Ontology to find a desired code. Shown below, "Medication Code" is the Ontology Lookup, so the link to click reads
Find Medication Code By Tree.
Use the search bar or scroll to find the concept to insert. As you
browse the ontology concepts you can see the paths and synonyms for a selected concept to help you make the correct selection. If the field has been
initialized to an expected concept, the browser will auto scroll to it.
Click
Apply to make your selection. You'll see the code in the entry box and a tooltip with the preferred label on the right as in the typeahead case above.
Initialize Expected Vocabulary
For the Ontology Lookup field, you choose an Ontology to reference, plus optional Import Field, and Label Field. In addition you can initialize the lookup field with an
Expected Vocabulary making it easier for users to enter the expected value(s).
Related Topics
