qipipe - Quantitative Imaging pipeline

Feature List

  1. Recognizes new study images.
  2. Stages images for submission to The Cancer Imaging Archive (TCIA) QIN collection.
  3. Masks images to subtract extraneous image content.
  4. Corrects motion artifacts.
  5. Performs pharmokinetic modeling.
  6. Imports the input scans and processing results into the XNAT image database.

Installation

The following instructions assume that you start in your home directory. We recommend the Anaconda environment for scientific packages and pip for the remaining Python packages. Install qipipe using the following procedure:

  1. Install and activate a qixnat Anaconda environment as described in the qixnat Installation Instructions.

  2. Install the qipipe dependencies hosted by Anaconda:

    wget -q --no-check-certificate -O \
      - https://www.github.com/ohsu-qin/qipipe/raw/master/requirements_conda.txt \
      | xargs conda install --yes
    
  3. Download the qipipe constraints file:

    wget -q --no-check-certificate -O \
      - https://www.github.com/ohsu-qin/qipipe/raw/master/constraints.txt \
      > /tmp/constraints.txt
    
  4. Install the qipipe package using pip:

    pip install qipipe --constraint /tmp/constraints.txt && rm /tmp/constraints.txt
    
  5. For ANTS registration, build the ants package from source using the ANTS Compile Instructions:

    pushd ~/workspace
    git clone git://github.com/stnava/ANTs.git
    mkdir $HOME/ants
    cd $HOME/ants
    ccmake ../workspace/ANTs
    cmake
    #=> Enter “c"
    #=> Enter “g”
    #=> Exit back to the terminal
    make -j 4
    popd
    

    Then, prepend ANTS to your shell login script. E.g., for Linux or Mac OS X, open an editor on $HOME/.bashrc or $HOME/.bash_profile and add the following lines:

    # Prepend ANTS to the path.
    ANTS_HOME=$HOME/ants
    export PATH=$ANTS_HOME/bin
    

and refresh your environment:

. $HOME/.bash_profile

Usage

Run the following command for the pipeline options:

qipipe --help

Development

Download

Download the source by cloning the source repository, e.g.:

cd ~/workspace
git clone https://github.com/ohsu-qin/qipipe.git
cd qipipe

Installing from a local qipipe clone requires the constraints option:

pip install -c constraints.txt -e .

Testing

Testing is performed with the nose package, which can be installed separately as follows:

conda install nose

The unit tests are then run as follows:

nosetests test/unit/

Documentation

API documentation is built automatically by ReadTheDocs when the project is pushed to GitHub. The modules documented are defined in doc/api. If you add a new Python file to a package directory pkg, then include it in the doc/apipkg ``.rst`` file.

Documentation can be generated locally as follows:

  • Install Sphinx and docutils, if necessary:

    conda install Sphinx docutils
    
  • Run the following in the doc subdirectory:

    make html
    

Read The Docs builds occur in a limited context that sometimes fails on dependencies, e.g. when an install a requires C extension. In that case, the project has a requirements_read_the_doc.txt that eliminates the problematic dependency and specify the requirements file in the Read The Docs project Advance Settings.

Release

Building a release requires a PyPI account and the twine package, which can be installed separately as follows:

pip install twine

The release is then published as follows:

  • Confirm that the unit tests run without failure.

  • Add a one-line summary release theme to History.rst.

  • Update the __init__.py version.

  • Commit these changes:

    git add --message 'Bump version.' History.rst qipipe/__init__.py
    
  • Merge changes on a branch to the current master branch, e.g.:

    git checkout master
    git pull
    git merge --no-ff <branch>
    
  • Reconfirm that the unit tests run without failure.

  • Build the release:

    python setup.py sdist
    
  • Upload the release:

    twine upload dist/qipipe-<version>.tar.gz
    
  • Tag the release:

    git tag v<n.n.n>
    
  • Update the remote master branch:

    git push
    git push --tags