Running xnat2bids with a custom configuration

Open a new file in your favorite text editor, and save it as something ending in .toml like x2b_my_first_config.toml.

To open VSCode in an interactive desktop, open a terminal with a right click followed by selecting 'Open Terminal Here". Next, run the command: module load vscode

To launch VSCode, run code on the command line.

1. Configure slurm parameters

First, let's configure a couple of slurm arguments; paste the following into your .toml file:

[slurm-args]
mail-user = "[email protected]"
mail-type = "ALL"

Update the value of example-user to be your e-mail. This will allow you to receive notifications on the status of your jobs!

For further details on all available slurm parameter options, see Slurm's documentation here: https://slurm.schedmd.com/sbatch.html

NOTE: By default, SBATCH output logs will be located at: ~/scratch/logs/

If you would like your logs to live somewhere else, update your configuration as follows:

[slurm-args]
output="/path/to/logs/dir/%x-%J.txt"

2. Configure xnat2bids parameters

Next, you'll need to configure what arguments to pass to xnat2bids, such as the session (or comma-separated list of sessions) you would like to process, as well as any other arguments.

💡Click here for a comprehensive list of all available options
project TEXT: Project ID from XNAT

subjects LIST[TEXT]: List of one or more subjects. Corresponds with the "last name" provided when registering the participant on the scanner, which becomes the "subject" ID on XNAT. If subjects parameter is specified, project must also be specified.

sessions LIST[TEXT]: List of one or more Accession #s found on XNAT

bids_root TEXT: Root output directory for exporting the files [default: ~/bids-export/]

version TEXT: Version of xnat-tools [default: latest]

host TEXT: XNAT's URL [default: https://xnat.bnc.brown.edu]

bidsmap-file TEXT: Bidsmap JSON file to correct sequence names

dicomfix-config TEXT: JSON file listing DICOM fields to correct for each specified sequence. USE WITH CAUTION

includeseq LIST[INTEGERS or STRINGS]: Include this sequence(s) only

skipseq LIST[INTEGERS or STRINGS]: Exclude this sequence(s) from processing

log-id TEXT: ID or suffix to append to logfile. If empty, current date is used [default: current date - MM-DD-YYYY-HH-MM-SS]

verbose INTEGER: Verbose level, from 0 (quiet) to 2 (most verbose) [default: 0]

overwrite BOOLEAN: Remove directories where prior results for this session/participant [default: false]

export-only BOOLEAN: Export DICOM data from XNAT without BIDS conversion [default: false]

skip-export BOOLEAN: Skip DICOM export and initiate BIDS conversion [default: false]

validate_frames BOOLEAN: Use if you manually terminate your fMRI runs. If the final volume does not contain the expected number of slices, the associated DICOM file(s) will be deleted. [default: false]

For this demo, paste the following text into your config file:

Here, we are setting the sessions to be processed as XNAT_E00080, XNAT_E00114, and XNAT_E00152 , which are the XNAT Accession numbers for subject 004 and subject 005 (sessions 1 and 2) in our BNC demo dataset. Notice that by defining skipseq, we are choosing to process everything except the scan with a "series description" on XNAT of "anat-t1w_acq-memprage". You can skip or include particular scans either by their series description like this, or by their scan number on XNAT (i.e. includeseq = [7,10]).

2.1 (Optional) Specify sessions to process with Project ID and Subject IDs rather than Accession numbers

To process all sessions from a given project, you only need to add the Project ID to your config file's project field. If you only would like to process sessions from a subset of a project's subjects, add the subjects field with a list of one or more Subject IDs. If you specify a project and subject(s) this way, you do not need to include a "sessions" list of Accession numbers.

NOTE: If exporting sessions by Subject IDs, the subjects field must be accompanied by a valid Project ID in the project field.

NOTE: Here, overwrite=true will tell xnat2bids to reprocess any existing session exports specified in your config file. Enabling the verbose=1 flag will turn on DEBUG logging for your script and signal xnat2bids to output more detailed printing to your logs.

2.2 (Optional) Define Custom Parameters for Each Session

There may be the case in which you would like to add new arguments or override default parameters for processing a given session—for instance, defining logging verbosity levels or including or excluding certain sequences.

Add the following to the bottom of your config file:

NOTE: The section name must match an entry in your sessions list. Each session will inherit all default parameters and those specified under [xnat2bids-args], overriding when necessary. At the moment, you need to provide a sessions list of Accession numbers (rather than Project/Subject IDs) if you want to define custom parameters for each session.

2.3 (Optional) Executing Pipeline Components Separately: Export Only or Skip Export Flags

If you're only interested in exporting your data from XNAT without converting your DICOM data into BIDS, you can add the following entry to your user config:

Similarly, if you would like to BIDS-convert data already exported to Oscar, you can add the following entry to your user config:

NOTE: When working with multi-value parameters like includeseq and skipseq, you also have the option to specify a range of values instead of individually listing them. To achieve this, utilize a string format rather than a list format, as demonstrated in the example below:

includeseq="1-4,6,10"

NOTE: By default, the root output directory for DICOM exports and converted BIDS files will be /users/<your-user-name>/bids-export/. If you prefer a different path to your data, you can define BIDS_ROOT in your [xnat2bids-args]list as following: bids_root="/path/to/bids-export"

NOTE: By default, run_xnat2bids uses the latest version of xnat-tools xnat2bids, unless specified under [xnat2bids-args] with the following format: version="vX.X.X"

3. Running XNAT2BIDS

Now that you have a complete configuration file like this, you are ready to run the pipeline!

First, we need to load a module that will give us access to python and a few basic packages. From the command line, run the following:

Then we can launch the script, using --config to specify your custom configuration file.

In your terminal, you should immediately see the following print statements:

Check /oscar/scratch/<your-username>/logs/ for four new log files

  • xnat2bids-XNAT_E00114-<JOB-ID>.txt

  • xnat2bids-XNAT_E00080-<JOB-ID>.txt

  • xnat2bids-XNAT_E00152-<JOB-ID>.txt

  • bids-validator-<JOB-ID>.txt

Click here for an example xnat2bids output log

Click here for an example bids-validator output log

Finally, go to your ~/bids-export directory to check your exported DICOM data and processed BIDS directory structure! 🎉

Click here to see how it should look

PreviousRunning xnat2bids using default configurationNextSyncing your XNAT project & Oscar data directory

Last updated

Was this helpful?