Skip to content

Latest commit

 

History

History
404 lines (293 loc) · 19 KB

README.rst

File metadata and controls

404 lines (293 loc) · 19 KB
Raw

FISSA

Latest Release Latest PyPI release Python Versions Supported
License GPLv3 License
Documentation Documentation
Build Status Documentation Status GHA Status AppVeyor Build Status Coverage pre-commit.ci status
Code style black pre-commit enabled
Interactive Demo Launch Notebooks in Binder
Support Join the FISSA chat
Citation DOI

FISSA (Fast Image Signal Separation Analysis) is a Python package for decontaminating somatic signals from two-photon calcium imaging data. It can read images in tiff format and ROIs from zip files exported by ImageJ; or operate on numpy arrays, generated by importing files stored in other or as the output of other packages.

For details of the algorithm, please see our companion paper published in Scientific Reports. For the code used to generate the simulated data in the companion paper, see the SimCalc repository.

FISSA is compatible with both Python 2.7 and Python >=3.5, however it is strongly encouraged that you use Python 3, since as Python 2 has reached its end of life. FISSA is continually tested on Ubuntu, Windows, and Mac OSX during its development cycle.

Documentation, including the full API, is available online at readthedocs.

If you encounter a specific problem please open a new issue. For general discussion and help with installation or setup, please see the Gitter chat.

Usage

A concise example of how to use FISSA is as follows.

import fissa

result = fissa.run_fissa("path/to/tiffs", "path/to/rois.zip")

# The decontaminated time series is now available as
# result[roi_index, tiff_index][0, :]

We also have several example notebooks for a basic workflow and more complicated workflows where FISSA needs to interact with the outputs of other two-photon calcium imaging toolboxes which can be used to automatically detect cells.

You can try out each of the example notebooks interactively in your browser on Binder (note that it may take 10 minutes for Binder to boot up). Note that the Suite2p notebook is housed in its own repository, and runs on a separate Binder instance from the other notebooks.

Workflow Jupyter Notebook Script
Function-based (ImageJ) Docs Launch Binder Download Linux/Mac Windows
Object-oriented (ImageJ) Docs Launch Binder Download Linux/Mac Windows
With suite2p Docs Launch Binder Download    
With SIMA Docs Launch Binder Download    
With CNMF (MATLAB) Docs Launch Binder Download    

These notebooks can also be run on your own machine. To do so, you will need to:

  1. If you want to run the Suite2p notebook, you'll have to install everything into a conda environment, as per their installation instructions.
  2. Install fissa with its plotting dependencies pip install fissa[plotting].
  3. If you want to run the sima notebook, you will also have to install sima with pip install sima. Note that sima only supports python<=3.6.
  4. Download a copy of the repository, unzip it and browse to the examples directory.
  5. Start up a Jupyter notebook server to run our notebooks jupyter notebook.

If you're new to Jupyter notebooks, here is an approachable tutorial.

Installation

Quick Guide

FISSA is available on PyPI and the latest version can be installed into your current environment using pip.

pip install fissa

If you need more details or you're stuck with something in the dependency chain, more detailed instructions for both Windows and Ubuntu users are below.

Installation on Windows

We detail two different ways to install Python on your Windows. One is to download the official Python installer, and the other is to use Anaconda.

Official Python distribution

  1. Go to the Python website and download the latest version of Python for Windows.

  1. Run the executable file downloaded, which has a name formatted like python-3.y.z.exe.

  2. In the installation window, tick the checkbox "Add Python 3.y to PATH".

  3. Click "Install Now", and go though the installation process to install Python.

  4. Open the Command Prompt application. We can run Python from the general purpose command prompt because we added its binaries to the global PATH variable in Step 3.

  5. At the Command Prompt command prompt, install fissa and its dependencies by running the command:

    pip install fissa

  6. You can check to see if fissa is installed with:

    python -c "import fissa; print(fissa.__version__)"

    You should see your FISSA version number printed in the terminal.

  7. You can now use FISSA from the Python command prompt. To open a python command prompt, either execute the command python within the Command Prompt, or open Python executable which was installed in Step 4. At the python command prompt, you can run FISSA as described in Usage above.

Anaconda distribution

  1. Download and install the latest version of either Anaconda or Miniconda. Miniconda is a lightweight version of Anaconda, the same thing but without any packages pre-installed.

  1. Open the Anaconda Prompt, which was installed by either Anaconda or Miniconda in Step 1.

  2. In the Anaconda Prompt, run the following command to install some of FISSA's dependencies with conda.

    conda install -c conda-forge numpy scipy shapely tifffile

  3. Run the following command to install FISSA, along with the rest of its dependencies.

    pip install fissa

  4. You can check to see if fissa is installed with:

    python -c "import fissa; print(fissa.__version__)"

    You should see your FISSA version number printed in the terminal.

  5. You can now use FISSA from the Python command prompt. To open a python command prompt, either execute the command python within the Anaconda Prompt. At the python command prompt, you can run FISSA as described in Usage above.

  6. Optionally, if you want use suite2p, it and its dependencies can be installed as follows.

    conda install -c conda-forge mkl mkl_fft numba pyqt
pip install suite2p rastermap

Installation on Linux

Before installing FISSA, you will need to make sure you have all of its dependencies (and the dependencies of its dependencies) installed.

Here we will outline how to do all of these steps, assuming you already have both Python and pip installed. It is highly likely that your Linux distribution ships with these. You can upgrade to a newer version of Python by downloading Python from the official website.

Alternatively, you can use an Anaconda environment (not detailed here).

  1. Dependencies of dependencies

    These packages can be installed on Debian/Ubuntu with the following shell commands.

    sudo apt-get update
sudo apt-get install gfortran libopenblas-dev liblapack-dev libatlas-dev libatlas-base-dev
sudo apt-get install libgeos-dev
sudo apt-get install libjpeg-dev

  2. Install the latest release version of FISSA from PyPI using pip:

    pip install fissa

  3. You can check to see if FISSA is installed by running the command:

    python -c "import fissa; print(fissa.__version__)"

    You will see your FISSA version number printed in the terminal.

  4. You can now use FISSA from the Python command prompt, as described in Usage above.

Citing FISSA

If you use FISSA for your research, we would be grateful if you could cite our paper on FISSA in any resulting publications:

S. W. Keemink, S. C. Lowe, J. M. P. Pakan, E. Dylda, M. C. W. van Rossum, and N. L. Rochefort. FISSA: A neuropil decontamination toolbox for calcium imaging signals, Scientific Reports, 8(1):3493, 2018. doi: 10.1038/s41598-018-21640-2.

For your convenience, we provide a copy of this citation in bibtex and RIS format.

You can browse papers which utilise FISSA here.

License

Unless otherwise stated in individual files, all code is Copyright (c) 2015–2022, Sander Keemink, Scott Lowe, and Nathalie Rochefort. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.