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 Eligible Data Objects

There are three APIs for defining Vocabulary properties:

  1. API to list property set domains
  2. API to get and update properties of an existing domain
  3. 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:

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({
schemaName: "samples",
queryName: "Samples",
columns: ["name", "urn:lsid:labkey.com:Vocabulary.Folder-3234:MyVocab2#pH", "Properties"]
})

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

Related Topics

Discussion

Was this content helpful?

Log in or register an account to provide feedback


previousnext
 
expand all collapse all