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:
- 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:
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
Related Topics
