Using DQR: Bulk Querying and Importing via CSV File

Let's say that you already have a list of the studies you want to import and don't want to have to individually search for each of them. In cases like these, the Import CSV option can be very helpful. Like with a normal import, you start by going to a project that you want to import PACS data into and then clicking "Import from PACS" in the Actions box. After you have made sure the correct "Source PACS" is selected in the dropdown, simply click the "Import CSV" link. The modal shown below will then come up:

Then you just need to click "Browse..." select the CSV file you want to use and click upload. From there the table will be populated (much like how it is when you search the PACS without using a CSV) and you can proceed with an import. However, knowing this doesn't do you any good until you know how the CSV needs to be formatted.

Writing a CSV for DQR Import

The structure of the CSV is fairly simple. It should be a text file (not necessarily ending in .csv, though this is recommended) where every cell in every row is comma separated.

CSV Headers

There should first be a header row with the names of the columns you want to use. These columns can be one of two types:

  1. Search columns to use to find studies on the PACS to import
  2. Relabeling columns to use to describe how the data should be relabeled by XNAT when received

The search column headers are similar to the search criteria available through the UI, though with some additional options. Unlike in the UI, you can search by date of birth (DOB) and modality, and first name and last name are broken up into separate columns. So the allowable search column headers are:

  1. "Accession Number"
  2. "Study Date"
  3. "Patient ID"
  4. "Last Name"
  5. "First Name"
  6. "DOB"
  7. "Modality"

The double quotes contain the exact strings that should be included, but the double quotes themselves should not be included in the CSV. These columns, as well as the relabeling ones, can appear in any order and you only need to include the columns that you want to use.

While there are a variety of relabeling columns that are supported by the import REST calls, only the "Subject" and "Session" ones are supported by the XNAT user interface (UI). If you upload through the UI, other requested relabeling will be ignored, so if you want to do any other relabeling, you should read the "Import with REST" section of this documentation. The relabeling columns that the CSV REST call supports are the following (though only "Subject" and "Session" are supported when importing through the UI and, as before, the double quotes should not be included in the actual CSV files) :

  1. "Subject"
  2. "Session"
  3. "Relabel Accession Number"
  4. "Relabel Study Date"
  5. "Relabel Study ID"
  6. "Relabel Patient ID"
  7. "Relabel Patient Name"
  8. "Relabel Patient Birth Date"

CSV Rows

Let's say that I want to import a single study whose Accession Number I know, 25175352, and have that study appear in XNAT as a session under a subject named "Subj001". To do this, I could upload the following file:

Accession Number,Subject

After uploading that CSV, my import page looks like this:

If I then check the box for this study and begin the import (leaving all series descriptions selected in the next modal), that study will be imported into XNAT. The same rules as in the earlier relabeling section still apply:

  1. Patient's Name = value entered for Subject
  2. Patient ID = value entered for Subject
  3. Study ID = value entered for Session
  4. Accession Number = value entered for Session

So when the study's DICOM files are received by XNAT, the Patient's Name and Patient ID values in the DICOM are changed to "Subj001", leading to it showing up in the prearchive with Subject listed as Subj001. No session relabeling was requested, so the normal dqrObjectIdentifier rules are followed (as described in the DICOM Object Identifiers section), which means that whatever the Study ID was in the DICOM is what will be used for the session label.

CSV files are able to contain as many lines as you want (with the warning that selecting too many studies to import at a time in the table you see after uploading the CSV, even as few as 20 or so, can fail for reasons described in the Importing from a PACS section).

Each line can also match as many studies in the PACS as you want. Note that you must include at least one non-blank search criteria for every row in the table, though search criteria can be left blank and the non-blank criteria for one row can be different than the non-blank criteria for another row). However, you should be particularly careful about the possibility that one CSV row will return multiple studies from the PACS when relabeling.

Consider the case where I know the study date for a study and want to import it, giving it the generic name of Subj001 and the session label of Sess_001. To do this, I upload the following CSV:

Study Date,Subject,Session

However, the result is a little different than I was expecting. I assumed there would only have been a single study on the PACS for this date, but there were actually three. I probably don't want all three to be assigned to the same subject in XNAT, and almost certainly don't want them to all be given identical session labels (perhaps sess_001, sess_002, and sess_003 would be acceptable though). Here is what I see after uploading that CSV file:

I then have the opportunity to either modify my CSV file and upload it again, or work with the results it gave me, changing subject and session labels as needed and only selecting the studies that I want to import.

Details on allowable values in the CSV

The format that should be used for the search criteria strings when doing a CSV import are a little different than the format used when importing through the UI. For example, when you select the date range in the UI, both dates are formatted like 2020-01-01. However, this is not the format in which study dates are stored within most/all PACS and the PACS format is what should be used in the CSVs. When importing through a CSV, XNAT pretty much passes the values you give it to the PACS exactly as you provided them (though first and last name are combined). So since the study dates on my PACS have the date format yyyymmdd (e.g. 20200101), this is the format I should use in my CSV.

While you should generally avoid using double quotes in your CSV, the one exception is if you want to have a DICOM field set to the empty string. For example, if I uploaded this CSV:

Patient ID,Subject,Session

I would see the following table:

If I then completed the import, I would see a session show up in the prearchive with whatever the default values are for Subject and Session when they're empty in the DICOM. In the case of dqrObjectIdentifier, the session would show up in the prearchive with Subject equal to the empty string and Session equal to dicom_upload.

Date ranges are supported, for both Study Date and DOB, and should be formatted like yyyymmdd-yyyymmdd. So if you wanted a range from February 1st 2017 to February 1st 2019, you would do 20170201-20190201.

If you're very familiar with the DICOM standard, you can probably figure out some more advanced search criteria tricks you can do. One of the most useful is the character for multiple values: '\'. For example, there is cat data on my PACS for cats named "Nacho" and "Taylor" and I know that their Patient IDs are "Nacho_CT" and "Taylor_CT" and so I can upload this CSV:

Patient ID

When I do, I get the following table of results:

Instead of the PACS returning studies with Patient ID = "Nacho_CT\Taylor_CT", it returned all studies with Patient ID = "Nacho_CT" OR Patient ID = "Taylor_CT".

Completing the CSV Import Process

Once you have your CSV returning the rows you want, you simply proceed like for any other import. The next steps are as follows:

  1. Check the box for the rows that have the studies you want to import.
  2. Make sure the Subject/Session relabeling is set up the way you want it.
  3. Select the XNAT SCP Receiver that you want to use for the import.
  4. Click the "Begin Import" button.
  5. Uncheck the series descriptions whose series you don't want to have imported.
  6. Click the "Import Selected" button.