Linking Assays with Images and Other Files: /Documentation

Linking Assays with Images and Other Files

The following topic explains how to automatically link together assay data with images and other file types in the File repository. When imported assay data contains file names and/or paths, the system can associate these file names with actual files residing on the server. Files are resolved for both assay results and assay run properties. Assay results file can be either TSV or Excel formats.

For Standard (previously known as "GPAT") assays, files will be automatically associated with assay result runs provided that:

The files have been uploaded to a location on the LabKey Server file repository.
The assay design is of type Standard
The file names and paths are captured in a field of type File.
The file names resolve to a single file
Paths are either full or relative paths to the pipeline or file repository root.

File names will be associated with the actual images in the following scenarios:

On import:

When assay data is imported from the file browser.
When assay data is uploaded via the assay upload wizard (in this case, we use the pipeline root).
When an assay run is created via experiment-saveBatch.api.
When an assay run is created via assay-importRun.api.

On update:

When updating assay data via query-updateRows.api.
When updating assay data via experiment-saveBatch.api.
When updating assay data via the build-in browser-based update form.

Note that image files are exported with assay results as follows:

when exported as Excel files, images appear inline.
when exported as .tsv files, the file name is shown.

Example

Assume that the following image files exist in the server's file repository at the path scans/patient1/CT/

When the following assay result file is imported...

ParticipantId	Date	ScanFile
100	12/12/2017	scans/patient1/CT/ct_scan1.png
100	12/12/2017	scans/patient1/CT/ct_scan2.png
100	12/12/2017	scans/patient1/CT/ct_scan3.png

...the imported assay results will resolve and link to the files in the repository. Note the automatically generated thumbnail in the assay results:

API Example

File association also works when importing using the assay API, for example:

LABKEY.Experiment.saveBatch({
 
   assayId : 444,
   batch : {
       runs : [{
           properties : {
               sop : 'filebrowser.png'
           },
           dataRows : [{
               specimenId : '22',
               participantId : '33',
               filePath : 'cat.png'
           }]
       }]
   },
   success : function(){console.log('success');},
   failure : function(){console.log('failure');}
 
});
 
LABKEY.Assay.importRun({
   assayId: 444,
   name: "new run",
   properties: {
       "sop": "assayData/dog.png"
   },
   batchProperties: {
       "Batch Field": "value"
   },
   dataRows : [{
       specimenId : '22',
       participantId : '33',
       filePath : 'cat.png'
   },{
       specimenId : '22',
       participantId : '33',
       filePath : 'filebrowser.png'
   },{
       specimenId : '22',
       participantId : '33',
       filePath : 'assayData/dog.png'
   }],
   success : function(){console.log('success');},
   failure : function(){console.log('failure');}
});

LabKey Support

LabKey Support