pyLAR

pyLAR features Python implementations of a low-rank atlas-to-imageregistration(LAR) framework and its applications in medical image analysisand computer vision. The core machine learning technique is Robust PCA.

Subdirectory content:

• core --- two implementations of RPCA
• examples -- a couple of ipython notebook examples of running RPCA
• tests -- testing scripts of the core functionalities
• low_rank_atlas -- the study of using RPCA in a low-rank atlas buildling framework
• eval_utils -- the utilitiy scripts to evaluate the results on the low rank atlas building framework

pyLAR contains implementation of the following paper:

@article{Liu14,    author = {X.~Liu and M.~Niethammer and R.~Kwitt and M.~McCormick and S.~Aylward},    title = {Low-Rank to the Rescue – Atlas-based Analyses in the Presence of Pathologies},    year = 2014,    journal = {MICCAI},

The implementations of two recent proposals for robust PCA can be found in the "core" subdirectory:

@article{Candes11a,    author = {E.J.~Cand\'es and X.~Li and Y.~Ma and J.~Wright},    title = {Robust Principal Component Analysis?},    year = 2011,    volume = 58,    number = 3,    journal = {J. ACM},    pages = {1-37}}

and

@article{Xu12a,    author = {H.~Xu and C.~Caramanis and S.~Sanghavi},    title = {Robust {PCA} via Outlier Pursuit},    journal = {IEEE Trans. Inf. Theory},    volume = 59,    number = 5,    pages = {3047-3064},    year = 2012}

Please cite these articles in case you use the code in "core". Note that the originalauthors of those articles also provide MATLAB code. Further, the objectivesof the two works are different: Candes et al.'s approach assumes randomlydistributed corruptions throughout the dataset, while Xu et al.'s approachassumes that full observations (i.e., column vectors of the data matrix) andnot just single entries are corrupted.

Requirements

• numpy
• SimpleITK [Optional]

Problem Statement(s)

See references (above) for the exact problem formulations of Candeset al. and Xu et al.

Example

An illustrative example for Candes et al.'s RPCA approach is to use acheckerboard image (provided under the examples directory) which is,by definition, low-rank and corrupt that image with randomly distributedoutliers. The task is then to recover the low-rank part and thus obtaina clean version of the checkerboard image (as well as the sparsitypattern).

The examples directory contains an example (ex1.py) that demonstratesexactly this scenario. (Note: The example requiresSimpleITK's python wrapping for image loading andimage writing; it should be easy to replace these parts with your favoriteimage handling library, though).

Run the code with

python ex1.py checkerboard.png 0.3 /tmp/outlierImage.png /tmp/lowRank.png

Two images will be written: /tmp/outlierImage.png (i.e., the image withoutliers) and /tmp/lowRank.png (i.e., the low-rank recovered part).

Using the IPython Notebook

We provide an IPython notebook, pyrpca-Tutorial.ipynb which can be foundin the top-level directory of pyrpca. It basically walks a new user throughthe example implemented in ex1.py.

The following instructions were tested on a Linux machine runningUbuntu 12.04. We assume that you have virtualenv installed,e.g., using apt-get install python-virtualenv. Basically, wecreate a virtual environment, install all the required packagesand eventually run the IPython notebook.

To vizualize the matplolib plots without using IPython Notebook, youneed to make sure that matplotlib is built with a backend that allowsplotting. By default, it is usually set to use 'Agg' as a backend,which only allows to save the plot, not to visualize it.

On Ubuntu 15.10, To build matplotlib with 'tkAgg', which allowsinteractive plotting, you need to install the following packages:

sudo apt-get install tcl-dev tk-dev python-tk python3-tk

Install matplotlib with pip only after installing these packages.

cd ~mkdir tutorial-envvirtualenv ~/tutorial-env --no-site-packages~/tutorial-env/bin/pip install ipython~/tutorial-env/bin/pip install ipython[zmq]~/tutorial-env/bin/pip install tornado~/tutorial-env/bin/pip install numpy~/tutorial-env/bin/pip install matplotlib~/tutorial-env/bin/easy_install SimpleITK

Next, launch the IPython notebook:

~/tutorial-env/bin/ipython notebook --pylab=inline

If you get the following error message, just follow the instructions andwrite %pylab inline at the top of your notebook.

[E 15:41:01.741 NotebookApp] Support for specifying --pylab on the command line has been removed.[E 15:41:01.741 NotebookApp] Please use `%pylab inline` or `%matplotlib inline` in the notebook itself.

License

pyLAR is distributed under the Apache License Version 2.0 (see LICENSE.md)