Upload Experiment Data via Spreadsheet

If your project data is stored in a spreadsheet, using the XNAT CSV Uploader is the most expedient way of getting that data into your XNAT project. To use the CSV Uploader from anywhere in the application, go to Upload > Spreadsheet in the top navigation.

In this demo, we are uploading subject demographic data from the mBIRN_calib project on XNAT Central. You can download the example CSV spreadsheet file here: csv-upload-raw-data.csv

Configure Your Upload Template

1. Name your new upload template. Or, you can select a previously loaded template, if you have used the uploader before.

2. Select the root data type you will be uploading to. In this case, since we are uploading subject data, your root data type will be xnat:subjectData. In our CSV file, each new line will correspond to a single subject record. If we were uploading experiment data, each new line would correspond to a single experiment record.

You can click the "Show All" link to reveal every known data type in XNAT, if you need to upload data of a type that hasn't been uploaded to XNAT before.

3. Click Submit.

In the next step, we will configure the fields that the data in your CSV file will map to. Here is the raw export data we are starting with: 

Subject,M/F,Hand,YOB
50782592,M,R,1964
58259524,M,R,1968
73213384,M,R,1964
79363080,F,R,1959
99657608,M,R,1968

4. Select Your Related Fields. Browse through the list of attributes associated with your root data type, and select the appropriate fields. The gender, handedness and year of birth attributes in our CSV file can be found in xnat:subjectData/demographics/xnat:demographicData. 

An ID field for your subject data is automatically generated in the first column of the template file, and does not have to be selected.

5. Click Submit. This will create and save a CSV upload template in your user cache in the XNAT file system.

Fit Your Data to the CSV Upload Template

Now that you have a CSV upload template generated in XNAT, you need to ensure that your spreadsheet of data fits the format that XNAT is looking for. The best way to do this is to download the CSV template file, open it in Excel (or your spreadsheet handling application of choice), and compare its structure with your own data. In our case, the template file looks like this:

ID,yob,gender,handedness

As you can see, the columns are in a different order than our source data, and the headers are named differently. We must adapt our source data to fit the format that XNAT expects.

After doing so, here is what our source data now looks like:

ID,yob,gender,handedness
50782592,1964,M,R
58259524,1968,M,R
73213384,1964,M,R
79363080,1959,F,R
99657608,1968,M,R

Now we are ready to continue the upload process.

Upload Your Data

6. Click "Browse" and select your CSV-formatted spreadsheet file.

7. Click "Upload."  The page will refresh and display the data you have selected.

Assuming your column names are properly formatted, the header row of your CSV spreadsheet file will be automatically skipped. If not, your header row will appear as the first row of data. You can remove it by clicking the "Remove" button next to that row.

8. Select a Project to upload to.

9. Click "Save." The page will process your data and reload, displaying the values it finds.

Validate and Recode Your Data As Needed

XNAT can only upload data that is valid for the data attributes you have selected. Any invalid data will be ignored during the upload process. Invalid data is highlighted in red in this review screen. In our case, the value "R" is not an accepted value for the "handedness" attribute. Handedness expects data to be coded as "LEFT" or "RIGHT," so we will have to recode our data and try again.

After recoding, our data now looks like this:

ID,yob,gender,handedness
50782592,1964,M,RIGHT
58259524,1968,M,RIGHT
73213384,1964,M,RIGHT
79363080,1959,F,RIGHT
99657608,1968,M,RIGHT

And upon uploading this data into XNAT, the red fields have now disappeared in the review screen:

Finalize Your Upload

10. Click "Save" on the review screen to finalize your upload.  The page will reload and display a success message. You can ensure that your data got properly uploaded and coded by navigating to your project page. In our demo, this page now looks like so:

There is a known bug with handling of gender data in the Spreadsheet uploader. The individual subject attributes are correctly noted as "Male" and "Female", but the XSD table display shows "U". See here for issue updates:

XNAT-1827

Reupload Data to Modify or Correct Entries

11. Resave modified data in our CSV template. We can resolve the gender coding issue in our data file that results from the unresolved XNAT-1827 issue and reupload our spreadsheet to modify the subject listings we just created. This is a useful process for uploading modified data of any kind. First, we need to recode our subjects' gender values using full words in lowercase, rather than uppercase initials. Do this and resave your CSV document. 

ID,yob,gender,handedness
50782592,1964,male,RIGHT
58259524,1968,male,RIGHT
73213384,1964,male,RIGHT
79363080,1959,female,RIGHT
99657608,1968,male,RIGHT

12. Reupload your modified CSV file 

Return to the "Upload > Spreadsheet" page and select the saved CSV upload template that we defined earlier: 

After uploading your new CSV file and selecting the same project to upload to, your confirmation screen should look like this: 

Upon saving this modified data and returning to your project home page, your subject listing will now have corrected values for the gender column.