CEA-COSMIC/pysap

Python Sparse data Analysis Package

PySAP

PySAP (Python Sparse data Analysis Package) is a Python module for sparse data analysis that offers:

• A common API for astronomical and neuroimaging datasets.
• Access to Sparse2D executables with both wrappers and bindings.
• Access to application specific plug-ins.
• A graphical user interface to play with the provided functions.

This package is the result of the COSMIC project, which is a collaboration between the CEA Neurospin UNATI and CEA CosmoStat laboratories.

Important links

• Official source code repo: https://github.com/cea-cosmic/pysap
• API documentation (last stable release): https://python-pysap.readthedocs.io/
• PySAP paper: https://arxiv.org/abs/1910.08465

Dependencies

PySAP will automatically install all of the required dependencies, however issues may arise on some operating systems. If you encounter any problems please ensure that you have all of the following dependencies installed before opening a new issue.

1. PySAP requires that the COSMIC package ModOpt be installed.

2. PySAP also requires the installation of the following third party software packages:

• scipy [>=1.5.4]
• numpy [>=1.19.5]
• matplotlib [>=3.3.4]
• astropy [>=4.1]
• nibabel [>=3.2.1]
• pyqtgraph [>=0.11.1]
• progressbar2 [>=3.53.1]
• scikit-learn [>=0.24.1]
• pybind11 [==2.6.2]
• pyqt5 [==5.15.4]
• PyWavelets [>=1.1.1]

Plug-Ins

PySAP currently supports the following plug-ins:

• PySAP-Astro [==0.0.1]
• PySAP-ETomo [==0.0.1]
• PySAP-MRI [==0.4.0]

Installation

The installation of PySAP has been extensively tested on Ubuntu and macOS, however we cannot guarantee it will work on every operating system. A Docker image is available (see below) for those unable to install PySAP directly.

If you encounter any installation issues be sure to go through the following steps before opening a new issue:

1. Check that that all the dependencies listed above have been correctly installed.
2. Read through all of the documentation provided, including the troubleshooting suggestions.
3. Check if your problem has already been addressed in a previous issue.

Further instructions are available here.

From PyPi

To install PySAP simply run:

$ pip install python-pysap

Depending on your Python setup you may need to provide the --user option.

$ pip install --user python-pysap

Locally

To build PySAP locally, clone the repository:

$ git clone https://github.com/CEA-COSMIC/pysap.git

and run:

$ pip install .

or:

$ python setup.py install

As before, use the --user option if needed.

Custom Installation

The following options can be passed when running python setup.py install:

• --noplugins : Install PySAP without any plug-ins
• --only=<PLUG-IN NAME> : Install PySAP with only the specified plug-in names (comma separated)
• --nosparse2d : Install PySAP without building Sparse2D

For example, to install PySAP with only the Etomo plug-in and without Sparse2D you would run the following.

$ python setup.py install --nosparse2d --only=pysap-etomo

Note that these options can also be invoked when installing with pip using the --install-option="<OPTION>" option.

$ pip install . --install-option="--noplugins"

However, this will disable the use of wheels and make take significantly longer to build all of the dependencies. Therefore, when installing PySAP this way it is recommended to pre-install all the required dependencies or use the Conda environment provided.

Conda Environment

A a conda environment.yml file is provided to facilitate the installation of the required PySAP dependencies along with some optional dependencies that provide additional features. To build the environment run:

$ conda env create -f environment.yml

Then to activate the environment run:

$ conda activate pysap

Finally, install PySAP following the instructions above.

Docker Image

A PySAP Docker image is available via DockerHub that includes the latest stable version of PySAP pre-installed. To install the image run:

$ docker pull ceacosmic/pysap

A Jupyter notebook can be launched using the Docker image as a backend and with access to the users current working directory as follows:

$ docker run -p 8888:8888 -v ${PWD}:/home ceacosmic/pysap

macOS

Help with installation on macOS is available here.

Linux

Please refer to the PyQtGraph homepage for issues regarding the installation of pyqtgraph.

Windows

Help with installation on Windows on this Gist.

Contributing

If you want to contribute to pySAP, be sure to review the contribution guidelines and follow to the code of conduct.

Citation

If you use PySAP in a scientific publication, we would appreciate citations to the following paper: PySAP: Python Sparse Data Analysis Package for multidisciplinary image processing, S. Farrens et al., Astronomy and Computing 32, 2020

The bibtex citation is the following: k:

@Article{farrens2020pysap,
  title={{PySAP: Python Sparse Data Analysis Package for multidisciplinary image processing}},
  author={Farrens, S and Grigis, A and El Gueddari, L and Ramzi, Z and Chaithya, GR and Starck, S and Sarthou, B and Cherkaoui, H and Ciuciu, P and Starck, J-L},
  journal={Astronomy and Computing},
  volume={32},
  pages={100402},
  year={2020},
  publisher={Elsevier}
}