Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@epnev
epnev authored Aug 16, 2019
1 parent 779f614 commit 35c8726
Showing 1 changed file with 22 additions and 93 deletions.
115 changes: 22 additions & 93 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,12 +34,13 @@ A paper explaining most of the implementation details and benchmarking can be fo

All the results and figures of the paper can be regenerated using this package. For more information visit this [page](https://github.com/flatironinstitute/CaImAn/tree/master/use_cases/eLife_scripts).

## Other docs in this repo
* [Running CaImAn on a Cluster](docs/CLUSTER.md)
* [More detailed install instructions for Windows](docs/INSTALL-windows.md)
* [Install quirks on some Linux Distributions](docs/README-Distros.md)
* [How CaImAn can use your GPUs](docs/README-GPU.md)
* [The CaImAn GUI](docs/GUI.md)
## New: Installation through conda-forge (August 2019)

Beginning in August 2019 we have an experimental binary release of the software in the conda-forge package repos. This is intended for people who can use CaImAn as a library, interacting with it as the demos do. It also does not need a compiler. It is not suitable for people intending to change the CaImAn codebase. Comfort with conda is still required. If you wish to use the binary package, you do not need the sources (including this repo) at all. With a functional install of conda, you can do (on any platform):
```bash
conda create -n caiman -c conda-forge caiman
```
You will still need to use caimanmanager.py afterwards to create a data directory. If you install this way, do not follow any of the other install instructions below.

## New: Exporting results, GUI and NWB support (July 2019)

Expand Down Expand Up @@ -68,80 +69,7 @@ To see examples of how these methods are used, please consult the demos. While t

## Installation for calcium imaging data analysis

### Installing the binary package

Beginning in August 2019 we have an experimental binary release of the software in the conda-forge package repos. This is intended for people who can use CaImAn as a library, interacting with it as the demos do. It also does not need a compiler. It is not suitable for people intending to change the CaImAn codebase. Comfort with conda is still required. If you wish to use the binary package, you do not need the sources (including this repo) at all. With a functional install of conda, you can do (on any platform):
```bash
conda create -c conda-forge caiman
```
You will still need to use caimanmanager.py afterwards to create a data directory. If you install this way, do not follow any of the other install instructions below.

### Upgrading CaImAn

If you want to upgrade CaImAn (and have already used the pip installer to install it) follow the instructions given in the [wiki](https://github.com/flatironinstitute/CaImAn/wiki/Updating-CaImAn).

Also, if you want to install new packages into your conda environment for CaImAn, it is important that you not mix conda-forge and the defaults channel; we recommend only using conda-forge. To ensure you're not mixing channels, perform the install (inside your environment) as follows:
```bash
conda install -c conda-forge --override-channels NEW_PACKAGE_NAME
```
You will notice that any packages installed this way will mention, in their listing, that they're from conda-forge, with none of them having a blank origin. If you fail to do this, differences between how packages are built in conda-forge versus the default conda channels may mean that some packages (e.g. OpenCV) stop working despite showing as installed.

### Installation on Windows
On Windows, please follow the install instructions [here](docs/INSTALL-windows.md) .

### Installation on Mac or Linux

* Download and install Anaconda or Miniconda (Python 3.x version) <http://docs.continuum.io/anaconda/install>

```bash
git clone https://github.com/flatironinstitute/CaImAn
cd CaImAn/
conda env create -f environment.yml -n caiman
source activate caiman
pip install .
```
If you want to develop code then replace the last command with
```
pip install -e .
```
If any of these steps gives you errors do not proceed to the following step without resolving it

#### known issues

With OSX Mojave you will need to perform the following steps before your first install:

```
xcode-select --install
open /Library/Developer/CommandLineTools/Packages/
```

(install the package file you will find in the folder that pops up)

### Setting up environment variables

To make the package work *efficiently* and eliminate "crosstalk" between different processes, run these commands before launching Python (this is for Linux and OSX):

```bash
export MKL_NUM_THREADS=1
export OPENBLAS_NUM_THREADS=1
```
The commands should be run every time before launching python. It is recommended that you save these values inside your environment so you don't have to repeat this process every time. You can do this by following the instructions [here](https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#saving-environment-variables).

### Setting up caimanmanager

Once CaImAn is installed, you may want to get a working directory with code samples and datasets; pip installed a caimanmanager.py command that manages this. If you have not installed Caiman before, you can do
```
caimanmanager.py install
```
or
```
python caimanmanager.py install --inplace
```
if you used "pip install -e ."

This will place that directory under your home directory in a directory called caiman_data. If you have, some of the demos or datafiles may have changed since your last install, to follow API changes. You can check to see if they have by doing `caimanmanager.py check`. If they have not, you may keep using them. If they have, we recommend moving your old caiman data directory out of the way (or just remove them if you have no precious data) and doing a new data install as per above.

If you prefer to manage this information somewhere else, the `CAIMAN_DATA` environment variable can be set to customise it. The caimanmanager tool and other libraries will respect that.
Installation and updating instructions can be found [here](./docs/source/Installation.rst).

### Known Issues

Expand Down Expand Up @@ -169,26 +97,21 @@ They are located in the `demos/notebooks`. To launch one of the jupyter notebook
and select the notebook from within Jupyter's browser. The argument `--NotebookApp.iopub_data_rate_limit=1.0e10` will prevent any memory issues while plotting on a notebook.

* demo files are also found in the demos/general subfolder. We suggest trying demo_pipeline.py first as it contains most of the tasks required by calcium imaging. For behavior use demo_behavior.py

* If you want to directly launch the python files, your python console still must be in the CaImAn directory.

* If you modify the demos to use them for your own data it is recommended that you save them in a different file to avoid file conflicts during updating.

* If you want to directly launch the python files, your python console still must be in the CaImAn directory.

## Testing

* All diffs must be tested before asking for a pull request. Call ```python caimanmanager.py test``` from outside of your CaImAn folder to look for errors (you need to pass the path to the caimanmanager.py file).

# Contributors:
# Main developers:

* Andrea Giovannucci, **Flatiron Institute, Simons Foundation**
* Eftychios A. Pnevmatikakis, **Flatiron Institute, Simons Foundation**
* Andrea Giovannucci, **University of North Carolina, Chapel Hill**
* Johannes Friedrich, **Flatiron Institute, Simons Foundation**
* Pat Gunn, **Flatiron Institute, Simons Foundation**
* Erick, Cobos, **Baylor College of Medicine**
* Valentina Staneva, **University of Washington**
* Ben Deverett, **Princeton University**
* Jérémie Kalfon, **University of Kent, ECE paris**
* Mike Schachter, **Inscopix**
* Brandon Brown, **UCSF**

A complete list of contributors can be found [here](https://github.com/flatironinstitute/CaImAn/graphs/contributors).

Expand Down Expand Up @@ -229,21 +152,27 @@ If you use this code please cite the corresponding papers where original methods
<a name="vst"></a>[9] Tepper, M., Giovannucci, A., and Pnevmatikakis, E (2018). Anscombe meets Hough: Noise variance stabilization via parametric model estimation. In ICASSP, 2018. [[paper]](https://marianotepper.github.io/papers/anscombe-meets-hough.pdf). [[Github repository]](https://github.com/marianotepper/hough-anscombe)


## Other docs in this repo
* [Running CaImAn on a Cluster](docs/CLUSTER.md)
* [More detailed install instructions for Windows](docs/INSTALL-windows.md)
* [Install quirks on some Linux Distributions](docs/README-Distros.md)
* [How CaImAn can use your GPUs](docs/README-GPU.md)
* [The CaImAn GUI](docs/GUI.md)


## Related packages

The implementation of this package is developed in parallel with a MATLAB toobox, which can be found [here](https://github.com/epnev/ca_source_extraction).

Some tools that are currently available in Matlab but have been ported to CaImAn are
Some tools that are currently available in Matlab but have not been ported to CaImAn are

- [MCMC spike inference](https://github.com/epnev/continuous_time_ca_sampler)
- [Group LASSO initialization and spatial CNMF](https://github.com/danielso/ROI_detect)

## Dependencies

A list of dependencies can be found in the [environment file](https://github.com/flatironinstitute/CaImAn/blob/master/environment.yml).



## Questions, comments, issues

Please use the [gitter chat room](https://gitter.im/agiovann/Constrained_NMF) for questions and comments and create an issue for any bugs you might encounter.
Expand Down

0 comments on commit 35c8726

Please sign in to comment.