Metadata-Version: 2.1
Name: region-grower
Version: 1.6.0
Summary: Synthesize cells in a given spatial context.
Home-page: https://region-grower.readthedocs.io
Author: Blue Brain Project, EPFL
License: Apache License 2.0
Project-URL: Tracker, https://github.com/BlueBrain/region-grower/issues
Project-URL: Source, https://github.com/BlueBrain/region-grower
Classifier: Development Status :: 4 - Beta
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: attrs>=19.3.0
Requires-Dist: click>=8.0
Requires-Dist: dask[dataframe,distributed]>=2023.3.2
Requires-Dist: diameter-synthesis<1,>=0.5.4
Requires-Dist: morphio<4,>=3.3.6
Requires-Dist: morph-tool[nrn]<3,>=2.11
Requires-Dist: neuroc<1,>=0.3
Requires-Dist: neurom<4,>=3.2
Requires-Dist: neurots<4,>=3.6
Requires-Dist: numpy>=1.26
Requires-Dist: pandas>=2.1
Requires-Dist: tqdm>=4.60
Requires-Dist: voxcell<4,>=3.1.5
Requires-Dist: pynrrd>=0.4.0
Requires-Dist: trimesh>=3.23
Requires-Dist: rtree>=1.0.1
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-jsonschema; extra == "docs"
Requires-Dist: sphinx-click; extra == "docs"
Provides-Extra: mpi
Requires-Dist: dask_mpi>=2022.4; extra == "mpi"
Requires-Dist: mpi4py>=3.1.1; extra == "mpi"
Provides-Extra: test
Requires-Dist: brainbuilder>=0.20.1; extra == "test"
Requires-Dist: dictdiffer>=0.9; extra == "test"
Requires-Dist: pytest>=6.2.5; extra == "test"
Requires-Dist: pytest-click>=1; extra == "test"
Requires-Dist: pytest-console-scripts>=1.3; extra == "test"
Requires-Dist: pytest-cov>=3; extra == "test"
Requires-Dist: pytest-html>=2; extra == "test"
Requires-Dist: pytest-mock>=3.5; extra == "test"
Requires-Dist: pytest-xdist>=3.0.2; extra == "test"
Requires-Dist: neurocollage>=0.3.6; extra == "test"
Requires-Dist: scikit-image>=0.19; extra == "test"

# Region Grower

Synthesize neuronal morphologies in a given spatial context provided by an atlas. The documentation can be found here: https://region-grower.readthedocs.io/en/latest/


## Introduction

This package provides a general tools to synthesize cells in a given spatial context (a brain Atlas)
with embarrassingly parallel computation (with distributed computing via dask-mpi).
This package is difficult to use on its own, as it requires several specific inputs from atlas and
synthesis. It is advised to use it via [synthesis-workflow](https://github.com/BlueBrain/synthesis-workflow),
which is a workflow generating most of the inputs of region-grower.


## Installation

This package should be installed using pip:

```bash
pip install region-grower
```


## Usage

This package provides one main command which provides several tools.
Two tools to generate input parameters and input distributions and another to synthesize the cells.

### Generate distributions

Generate the TMD distribution file:

```bash
region-grower generate-distributions --help
```

#### Input data

The command ``region-grower generate-distributions`` needs the following inputs:

* a folder containing the cells which are used to generate the parameters (see the ``input_folder`` and ``--ext`` parameters).
* a ``dat`` file (see the ``dat_file`` parameter) with 3 columns:
	* morphology names,
	* any integer value (this column is not used by ``region-grower``)
	* mtypes.
* optionally a ``JSON`` file containing the specific parameters used for diametrization (see the ``--diametrizer-config`` parameter).

#### Output data

The command ``region-grower generate-distributions`` will create the following outputs:

* a ``JSON`` file containing the formatted distributions (see the ``--parameter-filename`` parameter).

### Generate parameters

Generate the TMD parameter file:

```bash
region-grower generate-parameters --help
```

#### Input data

The command ``region-grower generate-parameters`` needs the following inputs:

* a folder containing the cells which are used to generate the parameters (see the ``input_folder`` and ``--ext`` parameters).
* a ``dat`` file (see the ``dat_file`` parameter) with 3 columns:
	* morphology names,
	* any integer value (this column is not used by ``region-grower``)
	* mtypes.
* optionally a ``JSON`` file containing the specific parameters used for diametrization (see the ``--diametrizer-config`` parameter).

#### Output data

The command ``region-grower generate-parameters`` will create the following outputs:

* a ``JSON`` file containing the formatted parameters (see the ``--parameter-filename`` parameter).

### Synthesize cells

Synthesize morphologies into an given atlas according to the given TMD parameters and distributions:

```bash
region-grower synthesize-morphologies --help
```

#### Input data

The command ``region-grower synthesize-morphologies`` needs the following inputs:

* a ``sonata`` file containing the positions of the cells that must be synthesized.
* a ``JSON`` file containing the parameters used to synthesize the cells (see the ``--tmd-parameters`` parameter). This file should follow the schema given in :ref:`Parameters`.
* a ``JSON`` file containing the distributions used to synthesize the cells (see the ``--tmd-distributions`` parameter). This file should follow the schema given in :ref:`Parameters`.
* a ``TSV`` file giving which morphology should be used for axon grafting and the optional scaling factor (see the ``--morph-axon`` parameter). The morphologies referenced in this file should exist in the directory given with the ``--base-morph-dir`` parameter.
* a directory containing an Atlas.

#### Output data

The command ``region-grower synthesize-morphologies`` will create the following outputs:

* a ``sonata`` file containing all the positions and orientations of the synthesized cells (see ``--out-cells`` parameter).
* a directory containing all the synthesized morphologies (see ``--out-morph-dir`` and ``--out-morph-ext`` parameters).
* a ``YAML`` file containing the apical point positions (see ``--out-apical`` parameter).
* a ``YAML`` file containing the Neuron IDs of the sections containing the apical points (see ``--out-apical-nrn-sections`` parameter).

## 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
