• Ontology Lookup Data Type
• Lookup Rules
• Usage Example
• Concept Picker for Insert/Update with Type-ahead
• Initialize Expected Vocabulary

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

• Click the to 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.

• Save.

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).

• Open the field editor, then expand the Ontology Lookup field.
• Select the Ontology to use (if it is not already selected).
• Click Expected Vocabulary to open the concept picker.

• Search or scroll to find the concept of interest. Shown here "Facial Nerve Palsy" or "NCIT:C26769".

• Click Apply.
• The selected concept is now shown in the expanded field details.

• Save these changes.
• Now when you use the concept picker for insert/update, it will select your concept of choice by default.
• Note that this does not restrict the ultimate selection made by the user, it just starts their browsing in the section of the ontology you chose.

Related Topics

• Ontology Column Filtering
• Ontology Integration
• Field Editor