XTolm is a local bash XNAT-aware bash script wrapper that facilitates the execution of batch analyses.
Useful for:
- developing or running image processing locally in bash shell
- using XNAT as data source and/or remote archive in shell scripts
- automating processing of multiple XNAT sessions and to reporting results in spreadsheets
- focusing on local script development and minimizing programming effort to interact with XNAT
To get started writing scripts in XTolm, check out this XTolm use case tutorial.
64-bit Linux (tested on CentOS 6, 7 and 8)
Bash 4.2+
curl,zip on path
Put the contents in a local directory and add it to PATH environment variable.
Developing with XTolm Refer to use cases for examples of batch scripts written with XTolm: Compute whole brain volume and save statistics in a spreadsheet
Mostly, load/save scans, resources and metadata as resources from/to XNAT.
load_scans [,...] load scan(s) to DICOM by ID to the processing dir
load_type load scan(s) DICOM of a given type to the processing dir
load_dir [,...] load resource dir(s) to the processing dir
load_file [fil2..] load resource file(s) to the processing dir
load_workspace load context variables from XNAT session (stored under unique analysis ID)
save_workspace save context variables to XNAT session (stored under unique analysis ID)
save_dir
The purpose is to enable batch analyses. Each study is loaded into a separate directory and is processed within 'processing context': XNAT subject and experiment label. Each study directory can have DICOM, resource dirs, and some configuration files that store context information. Workspace is defined as all user-defined variables that should be saved as key-value pairs.
set_context set current context of subject and session
This command moves to another processing dir that corresponds to another XNAT session, and loads/inits workspace variables for that session. Previously computed variables are loaded using this command.
set_context set current context when multiple contexts (variable namespaces) per session are allowed.
list_contexts list of subcontexts within current context
del_context delete a subcontext within current context
load_vars [var1] [,..] load one or more variables saved in current context
save_vars [var1] [,..] save one or more variables to current context. Save local vars (name+value) to current context (context is saved in a file within processing dir or online in XNAT experiment).
load_workspace load context variables from designated XNAT session resource
save workspace save context variables to XNAT session resource
load_data load a .csv or .xlsx file columns into bash arrays
xt_for <subject_field> [<session_field> [[start-end]]] iterate over arrays populated by load_data; use start-end to control record range
summary <out_file> [sort_column] generate a comma-separated summary of existing contexts (match order in [column])
summary_mc <out_file> summary when multiple session contexts were recorded
save_profile for fast access, save current server connection credentials in user directory
help list console commands
quit quit interactive console
Script execution mode: the user writes a script which is interpreted by XTolm, converted to a bash script and executed. Command format:
xtolm [options] <script file> [script args]
Interactive mode: Invoked by -i option. Bash-like line-by-line command execution.
Offline mode: Enabled by default. All code that interacts with XNAT is ignored.
Online mode: Invoked by -o option. Loading data to/from XNAT is enabled.
Debug mode: temporary bash script is not deleted upon program exit and can be found in the current dir under name.
Sun Grid Engine (SGE) grid execution mode: Invoked by -sge option. Must be in script execution mode. Submit the code inside xt_for sycle to SGE grid (uses qsub)
SLURM grid execution mode: Invoked by -slrm option. Must be in script execution mode. Submit the script to Slurm (uses sbatch)
xt_server https://my_xnat_server
xt_user xnat_user
xt_pass xnat_password
xt_project xnat_project
xt_subj xnat_subject
xt_sess xnat_experiment