Vocabulary Domains: /Documentation/Archive/22.3

Vocabulary Domains

Premium Feature — Available with all Premium Editions of LabKey Server. Learn more or contact LabKey.

Vocabulary properties can be used to define a dictionary of terms for use in annotating experiment and sample data. These "ad-hoc" terms can capture metadata of interest not known at the time of assay or sample type definition and not present in the data file. Example use cases:

Attaching provenance information to assay data, such as "Instrument type" or "Original data source".
Attaching provenance information to sample data such as "Clinic of origin", etc.
Attaching any information that is not already part of the result data or samples.

Vocabulary properties are defined and stored in a Vocabulary Domain. This topic shows how to create a Vocabulary Domain and attach its properties to assay and sample data.

Available Actions and Data Objects
Create Vocabulary Domains
Attaching Vocabulary Properties to Data
SQL Queries for Vocabulary Properties
Surface in Custom Grid Views
Reference Documents

Available Actions and Eligible Data Objects

There are three APIs for defining Vocabulary properties:

API to list property set domains
API to get and update properties of an existing domain
API to find usages of a specific property or any property from a specific domain

Vocabulary properties can be attached to the following data objects in LabKey Server:

Individual samples (rows in a sample type)
Individual rows in the exp.Data schema (for example, Files and DataClass rows)
Experiment Runs (for example, Sample Derivation or Assay Runs)

Create Vocabulary Domains

Reference Documentation:

LABKEY.Domain.create - Create a new domain of type "Vocabulary" to store ad-hoc properties.
LABKEY.Domain.listDomains - Get a list of current, available domains.

Creating a vocabulary domain:

LABKEY.Domain.create({
  kind: "Vocabulary",
  domainDesign: {
    name: "MyVocab",
    fields: [{
      name: "pH", rangeURI: "int"
    },{
      name: "instrument",
      rangeURI: "int",
      lookupSchema: "lists",
      lookupQuery: "Instruments"
    }]
  }
});

Listing vocabulary domains (to find the property URI of one of the fields):

LABKEY.Domain.listDomains({
  domainKinds: [ "Vocabulary" ],
  includeProjectAndShared: false,
  includeFields: true
});

Selecting a property and all properties attached to the row:

LABKEY.Query.selectRows({
  requiredVersion: 17.1,
  schemaName: "samples",
  queryName: "Samples",
  columns: ["name", "urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#pH", "Properties"]
})

The response will include a nested JSON object containing all of the property values. For example,

{
  "rows": [
    {
      "data": {
        "Name": {
          "url": "/labkey/VocabularyTest/experiment-showMaterial.view?rowId=1104302",
          "value": "testing"
        },
        "Properties": {
          "urn:lsid:labkey$Pcom:Vocabulary$PFolder-3234:MyVocab2#pH": {
            "value": 7.2
          }
        }
      }
    },
    {
      "data": {
        "Name": {
          "url": "/labkey/VocabularyTest/experiment-showMaterial.view?rowId=1093855",
          "value": "other"
        },
        "Properties": {
          "urn:lsid:labkey$Pcom:Vocabulary$PFolder-3234:MyVocab2#pH": {
            "value": 6.7
          },
          "urn:lsid:labkey$Pcom:Vocabulary$PFolder-3234:MyVocab2#instrument": {
            "url": "/labkey/VocabularyTest/list-details.view?listId=1&pk=1",
            "displayValue": "HPLC",
            "value": 1
          }
        }
      }
    }
  ]
}

Attaching Vocabulary Properties to Data

Reference Documentation:

Inserting samples with vocabulary properties:

LABKEY.Query.insertRows({
  schemaName: "samples",
  queryName: "Samples",
  rows: [{
    Name: "testing",
    "urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#pH": 7.2
  }]
});

Updating property values:

LABKEY.Query.updateRows({
  schemaName: "samples",
  queryName: "test",
  rows: [{
    rowId: 319524,
    "urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#pH": 7.6
  }]
});

Using saveRuns to create a new assay run with properties:

LABKEY.Experiment.saveRuns({
  assayId: 8753,
  runs: [{
    name: 'testing',
    properties: {
      'urn:lsid:labkey.com:Vocabulary.Folder-3234:ProcessParameters#flowRate': 3.2
    },
    materialOutputs: [{
      id: 1092216
    },{
      // a new sample will be created when the run is saved
      name: 'S-123',
      sampleSet: {
        name: 'Samples'
      },
      properties: {
        'urn:lsid:labkey.com:Vocabulary.Folder-3234:ProcessParameters#flowRate': 3.2
      }
    }],
    dataRows: []
  }]
});

Another saveRuns example:

LABKEY.Experiment.saveRuns({
    protocolName: LABKEY.Experiment.SAMPLE_DERIVATION_PROTOCOL,
    runs: [{
        name: 'two',
        properties: {
            // property URI from a Vocabulary
            'urn:lsid:labkey.com:VocabularyDomain.Folder-123:MyVocab#SoftwareTool': 'hello'
        },
        materialInputs: [{
            name: ‘ParentSampleA’,
            sampleSet: {name: 'test'},
            properties: {
                // property name from the Sample Type
                bar: 3,


                // property URI from a Vocabulary
                'urn:lsid:labkey.com:VocabularyDomain.Folder-123:MyVocab#SoftwareTool': 'hello',
            }
        }],
    }]
});

SQL Queries for Vocabulary Properties

LabKey SQL Example:

SELECT
Samples.Name,
Samples."urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#pH",
Samples."urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#instrument",
Properties,
FROM Samples

Surface in Custom Grid Views

You can surface vocabulary properties in custom grid views as follows:

Go to (Grid Views) > Customize Grid.
Select Show Hidden Fields.
Select Properties to show a nested grid of all properties, or select individual fields to see individual properties. See the screenshot below for examples. Note that rendering the nested Properties column may have performance impacts, as it is backed by a broad query.

Reference Documents

LABKEY.Domain.html.create - Create a new domain of type "Vocabulary" to store ad-hoc properties.
LABKEY.Domain.html.listDomains - Get a list of current, available domains.
LABKEY.Experiment.saveBatch/saveRuns - Save data to the ad-hoc properties.
LABKEY.Query.insertRows/updateRows

LabKey Support

LabKey Support