This tutorial shows you how to use LabKey Server to import data exported from FCS Express.
Install FCS Express
Set Up Folder and Assay Design
Note this tutorial assumes that your server has the "fcsexpress" module installed. Check by selecting (Admin) > Go To Module
and scanning the list for FCS Express.
Adding an assay folder
provides the basic assay functionality. Enabling FCS Express in that folder provides the FCS Express-specific features. Finally the assay design/protocol provides the fields to receive the data, files, jpegs, etc, coming from the FCS Express client.
- Log in to your server and navigate to your "Tutorials" project. Create it if necessary.
- If you don't already have a server to work on where you can create projects, start here.
- If you don't know how to create projects and folders, review this topic.
- Create a new subfolder named "FCS_Express_Data." Choose the Assay folder type and accept other defaults.
- Enable the FCS Express module in the new folder:
- (Admin) > Folder > Management and click the Folder Type tab.
- Under Modules select FCSExpress.
- Click Update Folder.
- Finally, set up the FCS Express assay design/protocol:
- Select (Admin) > Manage Assays.
- Click New Assay Design. Select FCSExpress, scroll down to select the current folder as the assay location, and click Next.
- Enter a Name. (You may enter any name. For the purposes of this tutorial, we have used "My FCS Express Protocol".)
- Before you save this assay design/protocol, scroll down the page to review the built in data fields. Note that you can add fields or customize existing fields, but for this tutorial, simply use the default.
- Click Save & Close.
LabKey Server is now ready to receive data from FCS Express.
FCS Express Set Up
Prepare the FCS Express Report
To kick off a data export from the FCS Express client, you need the following pieces of information:
- The export URL -- this URL kicks off the import process (and encodes the target folder)
- The protocol id -- this tells LabKey Server which assay design/protocol to target
- The field names -- these are the target database fields
- To get the export URL and protocol id, start from your main tutorial folder page, FCS_Express_Data.
- Click the name of your assay design (My FCS Express Protocol), then click Import Data.
- The message in the UI gives you the export URL and the protocol id to use. The example values are circled here, and show where you will enter them in the FCS UI. Note that the value '58' shown here is an example for the machine generating this screencap. Your protocol ID will likely vary.
- To get the field names, return to the main folder using the Folder_Name link.
- Click your assay design (My FCS Express Protocol).
- Select Manage Assay Design > Edit Assay Design.
- Review the field names available and decide which you want to use to receive data. You can also create new fields to receive data as described below.
With this information in hand, you are ready to start the import process by exporting your data in compatible format from FCS Express.
See the FCS Express documentation for the sample data and export process instructions: Exporting to LabKey Server
Beginning with release 18.3, all POST requests to LabKey must include a CSRF token. If your export from FCS Express fails with an "invalid security context" message (the message will also show the HTML of the attempted post), you can temporarily disable this checking in versions of LabKey prior to 19.1. To do so, select (Admin) > Site > Admin Console > Admin Console Links > Site Settings and set CSRF checking to "Admin requests." Remember to return this setting to "All POST requests" after completing this tutorial.
View the Exported Data
- When export is complete, return to LabKey Server to see your data:
- Navigate to the FCS_Express_Data folder.
- In the Assay List, click My FCS Express Protocol, or an alternate name you gave the tutorial assay design.
- The Assay ID field will show the name you entered in FCS Express, click it to see the data you exported from FCS.
The only fields mapped in the tutorial are the ID and Date. Click (Grid Views) > Customize Grid
to see other fields that can be made available.
What Else Can I Do?
Export More Kinds of Data
Below are listed the fields for a expanded assay design/protocol in order to capture more kinds of data from FCS Express. You can create this expanded design from scratch, or use the XAR shortcut described below. Note that any statistical data in FCS Express can be included in the export.
|ParticipantID||Participant ID||Subject/Participant (String)|
|Events||Gate 1 Events||Integer|
|Percent||M1 Percent||Number (Double)|
|FEY||FCS Express Layout||File|
Shortcut: Assay Design From a XAR File
Use the following XAR file as a starting point: FCSProtocol1.xar
- Download the already prepared assay design/protocol: FCSProtocol1.xar
- Return to the main FCS_Express_Data folder.
- In the Assay List, click New Assay Design.
- Click the link UPLOAD or use the data pipeline link option to import the XAR File directly.
- Complete the wizard.
- You will now see the new "FCSProtocol1 Results" assay design in the Assay List web part. No data has been uploaded yet, but the import protocol was created for you in one step.
Make the Comments Field Visible in LabKey Server
When preparing data for export from FCS Express, you can enter comment data that will be included in the exported data. To see this comment data once it has been exported to LabKey Server, follow the instructions below.
- Return to the main FCS_Express_Data folder.
- Click your assay design name.
- Click some data run to view the exported data directly.
- Select (Grid Views) > Customize Grid.
- Under Available Fields, open the Run node, and place a checkmark next to Comments.
- Save the view. Your exported comment data will appear.