Metadata-Version: 2.1
Name: neurocollage
Version: 0.3.7
Summary: A tool to create 2D morphology collage plots based on matplotlib.
Home-page: https://neurocollage.readthedocs.io
Author: Blue Brain Project, EPFL
License: Apache License 2.0
Project-URL: Tracker, https://github.com/BlueBrain/neurocollage/issues
Project-URL: Source, https://github.com/BlueBrain/neurocollage
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
License-File: AUTHORS.md
Requires-Dist: bluepysnap >=3.0.1
Requires-Dist: brainbuilder >=0.20.1
Requires-Dist: click >=8
Requires-Dist: geomdl >=5.2.8
Requires-Dist: joblib >=1.1
Requires-Dist: mapbox-earcut >=1
Requires-Dist: matplotlib >=3.6
Requires-Dist: morph-tool >=2.9
Requires-Dist: networkx >=2.5
Requires-Dist: neurom >=3.2
Requires-Dist: numpy >=1.26
Requires-Dist: pandas >=2.1
Requires-Dist: pyglet <2,>=1.5.20
Requires-Dist: pyquaternion >=0.9.5
Requires-Dist: region-grower >=1.5.1
Requires-Dist: scikit-learn >=1.1
Requires-Dist: scipy >=1.13
Requires-Dist: tqdm >=4.60
Requires-Dist: trimesh >=3.23
Requires-Dist: voxcell >=3.1.5
Requires-Dist: vtk >=9.0.2
Provides-Extra: docs
Requires-Dist: docutils <0.21 ; extra == 'docs'
Requires-Dist: m2r2 ; extra == 'docs'
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: sphinx-bluebrain-theme ; extra == 'docs'
Requires-Dist: sphinx-click ; extra == 'docs'
Provides-Extra: test
Requires-Dist: mock >=3 ; extra == 'test'
Requires-Dist: coverage <7,>=6.5 ; extra == 'test'
Requires-Dist: pytest >=6.1 ; extra == 'test'
Requires-Dist: pytest-click >=1.1 ; extra == 'test'
Requires-Dist: pytest-console-scripts >=1.4 ; extra == 'test'
Requires-Dist: pytest-cov >=4.1 ; extra == 'test'
Requires-Dist: pytest-html >=3.2 ; extra == 'test'

# NeuroCollage

A tool to create 2D morphology collage plots based on matplotlib.


## Installation

It is recommended to install ``NeuroCollage`` using [pip](https://pip.pypa.io/en/stable/):

```bash
pip install neurocollage
```

## Usage

This package provides only one command that aims at building figures of morphologies in atlas
planes (i.e. collage plots).

### Inputs

The collage requires the following inputs:

* the path to a standard `CircuitConfig`, or the path to a sonata `circuit_config.json` file of
  a [SONATA circuit](https://sonata-extension.readthedocs.io/en/latest/sonata_overview.html)
  and the path to an Atlas directory that can be read by
  [Voxcell](https://voxcell.readthedocs.io/en/latest/index.html).
* [optional] a configuration file containing the default values used for the CLI arguments (all
  these values are overridden by the ones passed to the CLI). The config file is a `INI` file
  divided in sections. These sections correspond to the first part of the CLI parameter names. For
  example, the `atlas-path` parameter of the CLI corresponds to the `path` parameter of the `atlas`
  section in the configuration file.

### Outputs

This package contains three main functions:
* `get_layer_annotation`: can generate annotation of layers for plotting or other uses
* `create_planes`: defines a set of planes to create collage plots, with various algorithms.
  Planes are sampled along a centerline, which can be straight aligned or not with world
  coordinates or curved using an algorithm from former `atlas_analysis` package. The first and last point
  of the centerline can be defined manually, or estimated internally to span the given region best.
* `plot_collage`: make the collage plot, see API for possible arguments.

### Command

This package provides a CLI whose parameters are described in the Command Line Interface page of
this documentation. It is also possible to get help from the command:

```bash
neuro-collage --help
```

If all the arguments are provided in the configuration file, the command is just:

```bash
neuro-collage -c <config-file>
```

Any argument from the configuration file can be overridden through the CLI:

```bash
neuro-collage -c <config-file> --cells-sample 20 --collage-pdf-filename custom_collage_name.pdf
```

Note that the parameter names of the CLI use the section in the configuration file as prefix. In the
previous example, the `--cells-sample` overrides the `sample` parameter of the `cells` section of
the configuration file.


## Examples

The `examples` folder contains a simple example on `S1` region of `SSCx` with `L5_TPC:A` morphologies. It
also provides examples of programmatic use of the `NeuroCollage` API with both types of circuit formats.

![](doc/source/images/collage.png)


## Funding & Acknowledgment

The development of this software was supported by funding to the Blue Brain Project,
a research center of the École polytechnique fédérale de Lausanne (EPFL),
from the Swiss government's ETH Board of the Swiss Federal Institutes of Technology.

Copyright (c) 2022-2024 Blue Brain Project/EPFL
