This tutorial shows you how to work with one type of microarray experiment data uploaded from sample MAGE-ML data files generated by an Agilent instrument.
When you are finished with this tutorial, you will have created a Microarray dashboard. See an interactive example by clicking here.Tutorial Steps:
In this tutorial, you set up a separate subfolder within a LabKey demo study for the microarray experiment. You must be an administrator in that study folder to complete this tutorial.
- Log in to LabKey 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.
- If you do not already have a subfolder named "HIV Study" in which you installed our demo study, use the instructions in this topic to create it.
- Within the "Tutorials/HIV Study" folder, create a new subfolder named "Microarray Staging". Choose the folder type "Microarray" and accept other defaults in the folder creation wizard.
You will now see the home page of your new folder, the Microarray dashboard. You can return to this dashboard from other pages within the folder by clicking the Microarray Staging
link near the top of the page.
Upload Sample Microarray Data
- In the Data Pipeline web part, click Process and Import Data.
- Drag and drop the unzipped sample file folder [LabKeyDemoFiles]\Assays\Microarray into the pipeline file panel to upload it.
Create a Microarray Assay Design
- Select (Admin) > Manage Assays.
- Click New Assay Design.
- Select Microarray, choose "Current Folder (Microarray Staging)" as the Assay Location and click Next.
- Enter the name "Microarray Test" and leave all other Assay Properties with their default values.
- Scroll down to the Run Fields section, and for each row below, click Add Field and enter the values given.
: these XPaths are specific to the uploaded demo files. We add run fields both with and without XPaths in order to show how such properties are treated differently in the upload process.
- If you select the Producer field again, the section will look like this:
- When finished, scroll up and click Save & Close.
Set up a Sample Set
- Click the Microarray Staging link.
- Add a Sample Sets web part on the left.
- In the new Sample Sets web part at the bottom of the page, click (Create New Sample Set)
- Enter the Name: "Microarray Sample Set".
- Leave the Name Expression blank.
- Click Create.
- On the next page, click Save without adding any more fields.
- In the Sample Sets web part, click the new set: Microarray Sample Set.
- Click Import More Samples.
- Paste the following three lines into the Data text box:
- Leave other options at their defaults.
- Click Submit at the bottom of the page to finish.
Import Microarray Runs
- Click the Microarray Staging link to return to the dashboard.
- In the Assay List web part, click the assay design you created above: Microarray Test.
- Click Import Data. You will now see the Microarray folder that you uploaded to your server. This folder contains MAGE-ML files. Double click to open it.
- Place check marks next to the files test1_MAGEML.xml and test2_MAGEML.xml.
- Click Import Data.
- In the popup dialog, confirm that Use Microarray Test is selected and click Import. This will start to import the selected files into the "Microarray Test" design that you created earlier.
You will now see the "Data Import: Batch Properties" page.
Properties that contain XPaths in the descriptions for their fields will be populated automatically from your files. Additional bulk, run or data properties can be populated using one of two methods by selecting one of the two radio buttons:
- Option 1: Enter run properties for each run separately by entering values into a form.
- Option 2: Specify run properties for all runs at once with tab-separated values (TSV).
In this tutorial, we show you both methods.Option 1: Enter values into a form
Option 2: Populate properties in bulk
- Confirm that "Enter run properties for each run separately by entering values into a form" is selected.
- Click Next to advance to the "Data Import: Run Properties and Data File" page.
- Enter "1" for the RunPropWithoutXPath.
- In the Samples section, select "Microarray Sample Set" for both rows of the Sample Set column.
- For "Sample 1" select "Microarray 1" in the Sample Name column, and for "Sample 2" select "Microarray 2" as shown:
- Click Save and Import Another Run.
- Enter "2" for the RunPropWithoutXPath.
- Leave "Microarray 1" selected for "Sample 1" and "Microarray 2" for "Sample 2."
- Click Save and Finish.
You will now see the run results:
Notice the values you entered in the RunPropWithoutXPath column.
This option allows you to populate properties in bulk by using a spreadsheet instead of filling in the form for each file. You will use a set of TSV (tab-separated values) to specify run metadata. The barcode column in the TSV is matched with the barcode value in the MageML file. The sample name columns, configured in the assay design, will be used to look for matching samples by name in all visible sample sets. Any additional run level properties may be specified as separate columns.
- First delete previously imported runs by selecting both checkboxes and clicking (Delete) and confirming.
- Repeat the steps described in the "Import Microarray Runs" section above.
- This time, select "Specify run properties for all runs at once with tab-separated values (TSV)" on the Data Import: Batch Properties page.
- If we were not providing the values to paste, you could click Download Excel Template and open it in Excel. This spreadsheet shows the barcodes associated with the two files we have chosen to upload. It allows you to specify the sample set for each file, plus the RunPropWithoutXPath. The other run properties (Producer, Version, Protocol_Name) are still populated automatically using the XPaths you provided in the assay design.
- Copy the following table, then paste the contents (including headers) into the Run Properties textbox.
|251379110131_A01||Microarray 1||Microarray 2||1|
|251379110137_A01||Microarray 1||Microarray 2||2|
You will now bypass entering any more information and see the "Microarray Test Runs" grid view as you did after importing using the other method.
Review Run Data
The following items are numbered in the picture of the runs grid shown above:
- QC Flag icon: click to activate - flagging for review can be used to indicate a possible problem with the run.
- Experiment run graph icon: click to see more information about the source sample.
- Name (Assay ID): click for details about all files related to the MAGEML.
- Additional columns: additional metadata for the runs.
- Batch: displays the batch name. Click to see all of the MAGEMLs that were uploaded together as part of one batch.
Integrate Data into a Study (Optional Step)
You can integrate your microarray assay into a study and align it with other data for the particular participant and data collection date. To show you how, we integrate the tutorial data into the HIV Study
- Click the Microarray Staging link to return to the dashboard.
- Click Microarray Test in the Assay List web part.
- Select the runs you would like to copy to a study using the checkboxes on the left side of the grid view. For this demo, we select both runs.
- Click Copy to Study.
- Choose your demo study (ie. the parent folder "HIV Study") as the target study and click Next.
- You will notice icons in the Specimen Match column. This does not block the copy process, but to match these runs to specimens present in the demo study, enter participant IDs and visit dates for each run you have selected. Enter these values for both runs:
- ParticipantID: 249320489
- Date: 2008-12-03
- Click Re-validate to confirm that the given participant/visit pairs already exist in the study. You will see (checkmark) validation markers in the specimen match column, indicating successful matches to Participant/Visit pairs in the demo study:
- To finalize the copy, click Copy to Study.
When the copy is complete, you will see the dataset within your demo study. You can also see a similar dataset in our interactive example
As a finishing touch, you can place this new dataset into the "Assays" category of datasets in your study. In addition, change the dataset label so that the name of this dataset is consistent with the other assay datasets in your study.
- Click the Manage tab.
- Click Manage Datasets.
- Click your assay (Microarray Test). Note that if this is not the first assay by that name copied to the study, a "1" will be appended to the name of the newly copied assay dataset.
- Click Edit Definition.
- Category: Type “Assays” for the category.
- Label: Edit the label to read "Microarray Assay"
- Show in Overview: Confirm this box is checked.
- Click Save.
- Click the Clinical and Assay Data tab.
- Notice that your renamed assay dataset has been added to the Assays section.
You can view the finished list of datasets in our interactive example study's "Clinical and Assay Data" tab, as shown here