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.
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
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.
For this demo, paste the following text into your config file:
[xnat2bids-args]
sessions = ["XNAT_E00080", "XNAT_E00114", "XNAT_E00152"]
skipseq=["anat-t1w_acq-memprage"]Here, we are setting the sessions to be processed as , 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.
[xnat2bids-args]
project="BNC_DEMODAT"
subjects=["004", "005"]
skipseq=["anat-t1w_acq-memprage"]
overwrite=true
verbose=0NOTE: 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:
[XNAT_E00080]
includeseq=[19, 21]
[XNAT_E00114]
includeseq=[7,8,11,14]
[XNAT_E00152]
verbose=1NOTE: 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:
export-only=trueSimilarly, if you would like to BIDS-convert data already exported to Oscar, you can add the following entry to your user config:
skip-export=true3. Running XNAT2BIDS
Now that you have a complete configuration file like this, you are ready to run the pipeline!
[slurm-args]
mail-user = "[email protected]"
mail-type = "ALL"
[xnat2bids-args]
sessions = ["XNAT_E00080", "XNAT_E00114", "XNAT_E00152"]
skipseq=["anat-t1w_acq-memprage"]
overwrite=true
[XNAT_E00080]
includeseq=[19, 21]
[XNAT_E00114]
includeseq=[7,8,11,14]
[XNAT_E00152]
verbose=1First, 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:
module load anacondaThen we can launch the script, using --config to specify your custom configuration file.
python /oscar/data/bnc/scripts/run_xnat2bids.py --config <example_user_config.toml> In your terminal, you should immediately see the following print statements:
DEBUG: {'message': 'Argument List', 'session': 'XNAT_E00152', 'slurm_param_list': ['--time 04:00:00', '--mem 16000', '--nodes 1', '--cpus-per-task 2', '--job-name xnat2bids', '--mail-user [email protected]', '--mail-type ALL', '--output /gpfs/scratch/elorenc1/logs/%x-XNAT_E00152-%J.txt'], 'x2b_param_list': ['XNAT_E00152', '/users/elorenc1/bids-export/', '--host https://xnat.bnc.brown.edu', '--user elorenc1', '--skipseq anat-t1w_acq-memprage', '--overwrite', '--verbose']}
DEBUG: {'message': 'Executing xnat2bids', 'session': 'XNAT_E00152', 'command': ['sbatch', '--time', '04:00:00', '--mem', '16000', '--nodes', '1', '--cpus-per-task', '2', '--job-name', 'xnat2bids', '--mail-user', '[email protected]', '--mail-type', 'ALL', '--output', '/gpfs/scratch/elorenc1/logs/%x-XNAT_E00152-%J.txt', '--wrap', 'apptainer', 'exec', '--no-home', '-B', '/users/elorenc1/bids-export/', '/gpfs/data/bnc/simgs/brownbnc/xnat-tools-v1.6.0.sif', 'xnat2bids', '[XNAT_E00152,', '/users/elorenc1/bids-export/,', '--host,', 'https://xnat.bnc.brown.edu,', '--user,', 'elorenc1,', '--skipseq,', 'anat-t1w_acq-memprage,', '--overwrite,', '--verbose]']}
INFO: Launched 3 xnat2bids jobs
INFO: Job IDs: 11801791 11801792 11801793
INFO: Launched 1 bids-validator job to check BIDS compliance
INFO: Job ID: 11801794
INFO: Processed Scans Located At: /users/<your-username>/bids-export/Check /oscar/scratch/<your-username>/logs/ for four new log files
xnat2bids-XNAT_E00114-<JOB-ID>.txtxnat2bids-XNAT_E00080-<JOB-ID>.txtxnat2bids-XNAT_E00152-<JOB-ID>.txtbids-validator-<JOB-ID>.txt
Finally, go to your ~/bids-export directory to check your exported DICOM data and processed BIDS directory structure! 🎉
Last updated
Was this helpful?