/XNAT-PIC-pipelines

XNAT-PIC Pipelines for analysing single or multiple subjects within the same project in XNAT.

Primary LanguageMATLABGNU General Public License v3.0GPL-3.0

Contributors Forks Stargazers Issues License


Logo

XNAT-PIC

Extending XNAT to Preclinical Imaging Centers
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents
  1. About
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Citation
  8. Media
  9. Contact
  10. Funding
  11. Acknowledgements

About

XNAT-PIC XNAT for Preclinical Imaging Centers (XNAT-PIC) has been developed to expand XNAT's basic functionalities to preclinical imaging and consists of:

  1. MRI2DICOM, a Magnetic Resonance Imaging (MRI) converter from ParaVision® (Bruker, Inc. Billerica, MA) file format to DICOM standard
  2. XNAT-PIC Uploader to import multimodal DICOM image datasets to XNAT
  3. XNAT-PIC Pipelines for analysing single or multiple subjects within the same project in XNAT.

Built With

XNAT-PIC has been built by using the following major frameworks:

Getting Started

This section contains instructions on setting up XNAT-PIC on your computer, in both Linux and Windows OS.
Make sure you have the following softwares and packages in place:

Prerequisites

XNAT-PIC requires an XNAT instance to work with, therefore you first need to install XNAT on a local desktop or server. XNAT-PIC has been designed and tested for XNAT 1.7.6: we recommend to install this version. You can find the XNAT installation guide at the following link https://wiki.xnat.org/documentation/getting-started-with-xnat/xnat-installation-guide. If you need help with the XNAT installation, please get in touch with us!

Installation

MRI2DICOM and XNAT-PIC Uploader

  1. Clone the repo

    git clone https://github.com/szullino/XNAT-PIC

  2. Install Python 3.7.6 or, alternatively, Anaconda

Once you have Python up and running, you can install the following libraries. Again, we recommend to install the indicated versions as XNAT-PIC has not been tested to work with the latest releases. For any issue, please contact us.

  1. Install Numpy 1.15.4

    pip install numpy==1.15.4

  2. Install pydicom 1.2.1

    pip install pydicom==1.2.1

  3. Install xnatpy 0.3.22

    pip install xnatpy==0.3.22

  4. Install pyAesCrypt 0.4.3

    pip install pyAesCrypt==0.4.3

XNAT-PIC Pipelines

  1. Clone the repo 
    git clone https://github.com/szullino/XNAT-PIC-pipelines

Follow these instructions to set up the XNAT-PIC Pipelines:

  1. Create a Python 2.7 virtual environment

  2. Install Requests 2.23.0

    pip install requests==2.23.0

  3. Install pyxnat 1.2.1.0.post3

    pip install pyxnat==1.2.1.0.post3

  4. Install the MATLAB Engine API for Python

In particular, for the Mask_Average XNAT-PIC Pipeline you need to install Python 3.8.3 and the following libraries:

  1. Install numpy 1.18.5

    pip install numpy==1.18.5

  2. Install opencv-python 4.4.0.40

    pip install opencv-python==4.4.0.40

  3. Install nibabel 3.1.1

    pip install nibabel==3.1.1

  4. Install dcmrtstruct2nii 1.0.19

    pip install dcmrtstruct2nii==1.0.19

Usage

MRI2DICOM and XNAT-PIC Uploader

You can launch MRI2DICOM and the XNAT-PIC Uploader by running launcher.py in your Python IDE or via operating system command-line or terminal:

$ python launcher.py

Users can then click on MRI2DICOM to convert the ParaVision® (Bruker, Inc. Billerica, MA) raw data to DICOM standard or on the XNAT-PIC Uploader to import the MR image sessions to XNAT, if your images are already in DICOM. In the first case, the converter needs to know the directory of the project in ParaVision® format. Once the process is over, a new folder with the DICOM images will be created in the same directory.

The DICOM image dataset can be then uploaded to XNAT. XNAT-PIC Uploader can upload a single subject or multiple subjects. You need to provide the XNAT webpage address and the login details. Then users can create a new project or select a pre-existing one in the drop-down menu, browse to the directory and type the number of custom variables. A pop-up window notifies the user once the process is complete.

When uploading DICOM images to XNAT the user can also adopt a more complex structure that automatically sets custom variables (up to 3) and their values. For example, this data tree structure corresponds to the following custom variables and values:

cim-custom-variables

For more information about custom variables in XNAT, please visit: https://wiki.xnat.org/documentation/how-to-use-xnat/creating-and-managing-projects/adding-custom-variables-to-xnat-projects

XNAT-PIC Pipelines

If you wish to use the pipelines developed in XNAT-PIC, you have two options accordingly to your profile:

  1. generic XNAT users can sign up to our CIM-XNAT instance at http://cim-xnat.unito.it, upload the MR image datasets to be analyzed and add the pipelines to their own projects.
    More information can be found here: Adding Pipelines to your Project

  2. XNAT admins can download the XNAT-PIC pipelines from https://github.com/szullino/XNAT-PIC-Pipelines, install and register them in their own XNAT instance.
    More information can be found here: Installing Pipelines in XNAT

In this second case, you need to create the following XNAT format config file, named .central.cfg, to be placed at a default location.

{"server": "your_xnat_url", "user": "user", "password": "your_xnat_password"}

The path of your .central.cfg file must be replaced in the following scripts REST_XNAT_Getscans_bytype.py, download_project_scans_of_type.py, and upload_XNAT_files.py.

To run a pipeline in XNAT, please follow this guide: https://wiki.xnat.org/documentation/how-to-use-xnat/running-pipelines-in-xnat

This table shows a list of the XNAT-PIC Pipelines currently available:

Name Description
Process_DWI Pipeline processes DWI map
Process_DWI project Pipeline processes all DWI maps in a project
Process_T1w_SR Pipeline processes T1 Saturation Recovery map
Process_T1w_SR_project Pipeline processes all T1 Saturation Recovery maps in a project
Process_T2w Pipeline processes T2 map
Process_T2w_project Pipeline processes T2 maps in a project
Mask_Average Pipeline computes a mean value in a Region of Interest of a parametric map

Roadmap

Please visit open issues for a list of proposed features (and known issues).

Contributing

Contributions are greatly appreciated.
If you wish to help us in improving the XNAT-PIC project, please follow these instructions.

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/XNAT-PIC-new-feature)
  3. Commit your Changes (git commit -m 'Add some XNAT-PIC-new-feature')
  4. Push to the Branch (git push origin feature/XNAT-PIC-new-feature)
  5. Open a Pull Request

Thank you!

License

XNAT-PIC is distributed under the terms of the GNU General Public License (GPL) v3 or any later version as stated by the Free Software Foundation. See LICENSE for more information.

Citation

Please, cite these repositories by using:

  • S. Zullino, A. Paglialonga, W. Dastrù, D. L. Longo, S. Aime. XNAT-PIC: Extending XNAT to Preclinical Imaging Centers, 2021. DOI: https://arxiv.org/abs/2103.02044

News & Media

  • "Demonstrator 5: XNAT-PIC: expanding XNAT for image archiving and processing to Preclinical Imaging Centers". EOSC-Life website, https://www.eosc-life.eu/d5/

  • "Towards sharing and reusing of preclinical image data". Euro-Bioimaging website, https://www.eurobioimaging.eu/news/towards-sharing-and-reusing-of-preclinical-image-data/

  • "Data Management: Biological and Preclinical Imaging Perspective". Euro-Bioimaging Virtual Pub, February 12th, 2021.

  • "XNAT-PIC: expanding XNAT for image archiving and processing to Preclinical Imaging Centers". Demonstrator 5 from Populating EOSC-Life: Success stories for the Demonstrators – Session 1 from January 13, 2021.

Contact

Sara Zullino, PhD
LinkedIn Publons Twitter
Molecular Imaging Center
Department of Molecular Biotechnology and Health Sciences
Logo
Via Nizza 52 | 10126 Torino, Italy
sara.zullino@unito.it | T +39 011 670 9539

Funding

Logo     Logo    Logo     Logo

Acknowledgments