XNAT Spreadsheet Upload


It is common for users to store data in spreadsheet format. As such, XNAT provides the ability to import CSV files to ease the process for acquiring new data.

Step 1: Create/Load Template

The first step to uploading a spreadsheet is to create a template for the column structure of your file. The spreadsheet uploader can only upload one data type per template. If you have subject, session, and scan data to upload, then you will need to create three templates. You can choose any data type defined in your schema to be the data in your spreadsheet. By default, the dialog only shows the most common. Use the 'Show All' link to load the rest. 

Notice that the data types are listed according to the name given them in the schema. This is because you are building a spreadsheet that needs to directly correspond to that schema. In effect, you are building an XML document via spreadsheet format... welcome to XNAT.

Also, notice that you can choose previous templates. This can be be helpful if you will be repeatedly uploading the same spreadsheet format. 

Step 2: Configure your template columns

Next, you need to choose which columns will be in your spreadsheet. You can choose any field in the schema. You can even identify child elements (like demographicData) to access their fields. You CANNOT add fields from unbounded elements. This would result in multiple rows per root data type. The XNAT back end can support this, but the user interface here cannot.

Step 3: Enter data

We recommend that you download the template to verify what XNAT expects the columns to look like. Your upload csv must exactly match the column structure (no more, no less). You can use the Upload button to upload your spreadsheet. Or, you can manually enter your data using the form.

Once you have loaded some data (via upload or manual entry), your rows will show up at the bottom of the user interface. From here you can remove invalid rows and re-add them using the manual interface.

Make sure you select a project in the dropdown box. This is the project which your data will be assigned to.


After you've completed step 3, your data will be reviewed. It will be validated according to the XML Schema (XSD). It will also be compared to the values in the database.

  • If your values are new, then the rows will show up as NEW and any invalid fields will be highlighted in RED.
  • If your values match preexisting records in the database (if you are restoring existing data), the rows will show up as MODIFIED. The fields which are unmodified will be grey. Modified fields will be black. Invalid fields will be RED.

You cannot save the data if there are RED (invalid) fields present. Use the back button to return to the previous screen and fix the erroneous rows.

Once your data has been validated and reviewed, you can submit the form and your data will be saved. You will be presented with a list of the rows and whether or not they were successful.

Uploading custom variables

Due to limitations in the current user interface, it is difficult to upload values for custom defined variables via the spreadsheet interface. Luckily, David Gutman of Emory University contributed this PDF, walking through the process of adding these values.

Related: Google Group Discussion Thread