XNAT

1.9.0

• Operating System:

• Terminal:

• Shell:

• Editor:

• Package Manager:

• Programming Language:

• Database:

• Utility:

• Extension:

XNAT is an open source imaging informatics platform developed by the Neuroinformatics Research Group at Washington University.

More information can be found here.

Setting Up an XNAT Job

When starting an XNAT job, the user must specify two parameters:

• Database directory: A folder containing a PostgreSQL database for XNAT. If an empty folder is mounted, a new database will be created inside that folder.

• XNAT root directory: The root folder of the XNAT file system structure (see below). If an empty folder is mounted, a file tree rooted in the mounted folder will be created.

The XNAT file system stucture is the following:

xnat_root_dir/
├── archive/
├── build/
├── cache/
├── fileStore/
├── ftp/
├── home/
│   ├── config/
│   │   └──xnat-conf.properties
│   │   └──prefs-init.ini
│   └── logs/
│   └── plugins/
│   └── work/
├── inbox/
├── prearchive/
└── pipeline/

By adding a public link to the XNAT job, the interface will be accessible to anyone who has the link.

Initialization

For information on how to use the Initialization parameter, please refer to the Initialization - Bash script section of the documentation.

User Management

The admin user

When starting a new XNAT instance, the admin user has username admin and password admin.

This password can be changed from the interface by going to Administer > Users, clicking the admin row, and then Change User Password.

Important

For security reasons, the admin user should change the admin password immediately after starting a new XNAT instance.

User creation

The admin user can register a new user account by going to the interface and clicking Register from the login screen and entering the required information.

The admin user must enable new users before it becomes active. This is done from the interface by clicking Administer > Users, clicking the row with the new user and clicking Enabled in the pop-up window:

Once enabled by an admin, the new user can login to the interface.

Note

SMTP servers are not set up, which means that it is not possible to send emails to/from the XNAT job. This means that user email verification, email notifications, etc. are not possible.

Database Dumps

It is possible to back up the XNAT database backend which is mounted to Database directory. This functionality is controlled with two optional parameters:

• Database dump frequency: The backup feature is enabled by setting this parameter (disabled by default). The parameter value sets the number of minutes between consecutive dumps (and between the job start and the first dump).

• Database dump directory: Folder where the database dumps should be saved. If no folder is mounted, database dumps are saved in /work/db_dumps.

Note

Database dump files are named using the timestamp of the dump as <yyyymmdd>_<hhmmss>_dump.out.

Restoring a database dump

The database can be restored from a dump using a PostgreSQL Server job.

Start a PostgreSQL Server job with an empty folder mounted to Database path, and the folder containing the database dump file mounted using the Add folder parameter.

When the job starts, open the job's terminal window and run:

$ psql -f /path/to/dumpfile postgres

Note

Replace /path/to/dumpfile with the path to the actual .out that the database should be restored from.

Depending on the size of the database, restoring can take a while to finish.

The restored database will be saved in the mounted Database path and can be used with XNAT.

Important

When restoring a database from a dump file, be sure to use the same version of PostgreSQL Server as in the XNAT version where the restored database will be used.

Site Settings

The first time an XNAT instance is started in a UCloud job, the admin user must set a number of settings regarding the file system structure etc. Many of these are set automatically to correspond with e.g., the mounted XNAT root folder.

If the user wants to change these settings, or update any of the other available settings, this can be done from the Adminster tab inside the XNAT interface.

If an XNAT instance is restarted in a new job (i.e., by mounting an existing database path and the corresponding XNAT root folder during job submission), the settings of that instance are automatically loaded.

Plugins

XNAT's core functionality can be extended using using plugins. Plugins must be saved as .jar files.

To attach plugins to an XNAT job, the user must mount a folder containing all the plugin files using the Plugin directory optional parameter. All .jar files from the mounted folder will be copied into <xnat_root_folder>/home/plugins.

If a populated XNAT root folder is mounted during job submission, the plugins in <xnat_root_folder>/home/plugins will also be available. Hence, it is not necessary to mount a folder with these plugins.

If a folder is mounted to Plugin directory, the plugins in this folder will replace plugins in <xnat_root_folder>/home/plugins in case of name clashes.

Pipelines

In XNAT it is possible to deploy XML-based pipelines for semi-automatized or fully automatized workflows.

Using pipelines requires both the XNAT Pipeline Engine Plugin and the XNAT Pipeline Engine. The plugin should be added using the Plugin directory optional parameter (see above) while the pipeline engine is vailable in /opt/xnat-pipeline-engine inside the job.

Setting up the pipeline engine

The following steps are required to make the pipeline engine functional:

1. Run the Pipeline Engine's installation script called setup.sh with [destination] set as /work/<xnat_root_dir>/pipeline and xnatUrl set as localhost:8080.

2. From the XNAT interface, set Administer > Site Administration > Pipeline Settings > Processing Url to http://localhost:8080.

3. Add the Build functionality to the Data type to which the pipeline should apply. See this guide.

4. Once everything is saved, restart XNAT.

Note

It is not possible to run container-based pipelines.

Restarting XNAT

To restart XNAT, run the following command from the XNAT job's terminal:

$ restart_xnat

Important

When executing restart_xnat all unsaved sessions will be immediately and irretrievably deleted and the interface will be unavailable to all users for a few minutes.