# Axon Projection
A code that analyses long-range axons provided as input, and classifies them based on the brain regions they project to.
## Installation
First, create a virtual environment with at least python 3.10, and activate it:
```bash
python -m venv venvAP
source venvAP/bin/activate
```
The preferred way is to install directly from pypi:
```bash
pip install axon-projection
```
Otherwise, you can still clone this repository and install the package:
```bash
git clone https://github.com/BlueBrain/axon-projection.git
cd axon-projection
pip install .
```
## Running
```bash
python run.py <config_file>
```
or
```bash
axon-projection -c <config_file>
```
## Workflow
The workflow can either be run entirely, from clustering to the sampling, by running the `run.py` script. Each step can also be run separately, by running modules individually.
Parameters for each step can be configured in a `.cfg` file, called at execution, *i.e.*:
```bash
python axonal_projections.py config.cfg
```
|<p align="center"><img src="./docs/APWorkflow.png" alt="Axonal projection workflow" width="100%" height="auto"></p>|
|:---:|
| *Overview of the workflow. LRA : Long-range axon.* |
These steps are executed in the following order:
- **axonal_projections.py**: creates a table that contains source region and number of terminals or axonal length in each terminal region, for every provided morphology. Hierarchy level of source and target regions can be controlled in the configuration file (the higher the level, the deeper into regions).
<!-- - **check_atlas.py** (optional): compares source regions found for the morphologies in the provided atlas, with source regions found elsewhere, typically from another atlas or manually assigned. Also checks the discrepancies between targeted regions for each morphology (*n.b.*: morphologies files tested should be the same and at the same disk location). -->
- **classify_axons.py**: runs the clustering on the axonal projections table. Each morphology is grouped by source region, and feature vectors are defined by the number of terminals in each target region. Clustering is unsupervised, and done by Gaussian Mixture Models (GMMs). The number of mixture components (*i.e.* number of clusters) for each source is selected to minimize the Bayesian Information Criterion, which balances the likelihood of the dataset by the number of parameters used in the model.
The output of this step, is the creation of clusters for each source region, defined by :
- a probability to belong to this cluster;
- the mean number of terminals or axonal length in each target region;
- the variances of this feature (terminals or lengths);
and the assignment to each cluster for every morphology in the dataset.
- **visualize_connections.py** (optional): for each cluster, creates a graph of connectivity to other regions. Connectivity strengths are also shown, computed as $s = \frac{N_r}{N_T}$, with $N_r$ is the total number of terminals in the target region in the entire cluster, divided by $N_T$, the total number of terminals of all the axons in this cluster.
|<p align="center"><img src="./docs/graph_example.png" alt="Example graph" width="60%" height="auto"></p>|
|:---:|
| *Orange nodes are for source region, purple for target regions, and blue for intermediary hierarchy to traverse (*i.e.*: DG-mo is in DG, which is in HIP, etc...).* |
- **separate_tufts.py**: clusters and saves the tufts of each morphology by region, with their topological barcodes. Also computes how each tuft is representative of its group, defined by GMM cluster and target region, by comparing the difference of the tuft with all the others tufts of its group, based on a set of morphometrics (defined in the configuration file). This representativity score ranges from 0 (not representative) to 1 (representative). Finally, this step also computes *trunk_morphometric* morphometrics on the trunks of these morphologies (data needed for axon-synthesis).
- **sample_axon.py**: uses the previously defined GMMs to sample an axon from a specified source region. This draws a cluster assignment, and a number of terminals or axon length in each target region.
<!-- Appropriate tufts are then selected, based on this number of terminals and the tufts' representativity score. The output is a tuft tuple, which, among others, contains the tuft topological barcode, which can be used for topological synthesis. -->
## Examples
The example folder contains some files to run an example usage of the code.
### Clustering of axons
First, brain atlas files (`brain_atlas.zip`) need to be downloaded from https://doi.org/10.5281/zenodo.13790069 and uncompressed (for instance with `unzip brain_atlas.zip`) in the example/data folder.
The example/config_clustering_example.cfg configuration file provides the parameters for each step of the workflow. The workflow can be run by executing the script example/run_clustering_example.sh (with the venv activated, source venvAP/bin/activate), which basically runs the complete workflow:
```bash
python ../axon_projection/run.py config_clustering_example.cfg
```
The example should run in a few minutes, depending on the computing configuration (4 minutes with 20 processes). The output is generated in the example/out_clustering_example folder.
### Axon synthesis example
This second example shows how to use the output of the projections clustering from the previous example, as input for the axon synthesis algorithm presented in https://doi.org/10.1101/2024.10.16.618695. Namely, the target locations of the axons, number and selection of tufts is provided by the projection clustering code.
To run the synthesis example, ensure to first run the clustering example.
Then, simply run the run_synthesis_example.sh script with the virtual environment activated. The [example/config_synthesis_example.cfg](example/config_synthesis_example.cfg) configuration file contains the parameters used in the axon synthesis algorithm.
This example synthesizes axons for the set of axon-less morphologies in the folder [example/data/morphologies_for_synthesis](example/data/morphologies_for_synthesis), using the data extracted from axons in the folder [example/data/morphologies](example/data/morphologies).
This example has an initial computation of brain regions masks that takes around 15-20 minutes (and creates the output `boundary.nrrd` in the data directory), and the synthesis runs typically in 5 minutes, without leveraging parallelism.
To use parallelism, one can install the axon-synthesis package with the mpi option
```bash
pip install axon-synthesis[mpi]
```
## Citation
To cite this repository, please cite the accompanying research article:
Petkantchin, R., Berchet, A., Peng, H., Markram, H., Kanari, L., 2024. Generating brain-wide connectome using synthetic axonal morphologies. https://doi.org/10.1101/2024.10.04.616605
## 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.
For license and authors, see `LICENSE.txt` and `AUTHORS.md` respectively.
Copyright © 2023-2024 Blue Brain Project/EPFL
Raw data
{
"_id": null,
"home_page": "https://axon-projection.readthedocs.io",
"name": "axon-projection",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "Blue Brain Project, EPFL",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/87/e9/9190f3a46baf0ba6b7625e74b23e77516a3b09fd1a2e5371bcc14b268d41/axon_projection-0.1.1.tar.gz",
"platform": null,
"description": "# Axon Projection\n\nA code that analyses long-range axons provided as input, and classifies them based on the brain regions they project to.\n\n\n## Installation\n\nFirst, create a virtual environment with at least python 3.10, and activate it:\n```bash\npython -m venv venvAP\nsource venvAP/bin/activate\n```\n\nThe preferred way is to install directly from pypi:\n```bash\npip install axon-projection\n```\n\nOtherwise, you can still clone this repository and install the package:\n```bash\ngit clone https://github.com/BlueBrain/axon-projection.git\ncd axon-projection\npip install .\n```\n\n## Running\n\n```bash\npython run.py <config_file>\n```\nor\n```bash\naxon-projection -c <config_file>\n```\n## Workflow\n\nThe workflow can either be run entirely, from clustering to the sampling, by running the `run.py` script. Each step can also be run separately, by running modules individually.\nParameters for each step can be configured in a `.cfg` file, called at execution, *i.e.*:\n```bash\npython axonal_projections.py config.cfg\n```\n\n|<p align=\"center\"><img src=\"./docs/APWorkflow.png\" alt=\"Axonal projection workflow\" width=\"100%\" height=\"auto\"></p>|\n|:---:|\n| *Overview of the workflow. LRA : Long-range axon.* |\n\nThese steps are executed in the following order:\n- **axonal_projections.py**: creates a table that contains source region and number of terminals or axonal length in each terminal region, for every provided morphology. Hierarchy level of source and target regions can be controlled in the configuration file (the higher the level, the deeper into regions).\n<!-- - **check_atlas.py** (optional): compares source regions found for the morphologies in the provided atlas, with source regions found elsewhere, typically from another atlas or manually assigned. Also checks the discrepancies between targeted regions for each morphology (*n.b.*: morphologies files tested should be the same and at the same disk location). -->\n- **classify_axons.py**: runs the clustering on the axonal projections table. Each morphology is grouped by source region, and feature vectors are defined by the number of terminals in each target region. Clustering is unsupervised, and done by Gaussian Mixture Models (GMMs). The number of mixture components (*i.e.* number of clusters) for each source is selected to minimize the Bayesian Information Criterion, which balances the likelihood of the dataset by the number of parameters used in the model.\nThe output of this step, is the creation of clusters for each source region, defined by :\n - a probability to belong to this cluster;\n - the mean number of terminals or axonal length in each target region;\n - the variances of this feature (terminals or lengths);\n\n and the assignment to each cluster for every morphology in the dataset.\n- **visualize_connections.py** (optional): for each cluster, creates a graph of connectivity to other regions. Connectivity strengths are also shown, computed as $s = \\frac{N_r}{N_T}$, with $N_r$ is the total number of terminals in the target region in the entire cluster, divided by $N_T$, the total number of terminals of all the axons in this cluster.\n\n|<p align=\"center\"><img src=\"./docs/graph_example.png\" alt=\"Example graph\" width=\"60%\" height=\"auto\"></p>|\n|:---:|\n| *Orange nodes are for source region, purple for target regions, and blue for intermediary hierarchy to traverse (*i.e.*: DG-mo is in DG, which is in HIP, etc...).* |\n\n\n- **separate_tufts.py**: clusters and saves the tufts of each morphology by region, with their topological barcodes. Also computes how each tuft is representative of its group, defined by GMM cluster and target region, by comparing the difference of the tuft with all the others tufts of its group, based on a set of morphometrics (defined in the configuration file). This representativity score ranges from 0 (not representative) to 1 (representative). Finally, this step also computes *trunk_morphometric* morphometrics on the trunks of these morphologies (data needed for axon-synthesis).\n- **sample_axon.py**: uses the previously defined GMMs to sample an axon from a specified source region. This draws a cluster assignment, and a number of terminals or axon length in each target region.\n<!-- Appropriate tufts are then selected, based on this number of terminals and the tufts' representativity score. The output is a tuft tuple, which, among others, contains the tuft topological barcode, which can be used for topological synthesis. -->\n\n\n## Examples\nThe example folder contains some files to run an example usage of the code.\n\n### Clustering of axons\nFirst, brain atlas files (`brain_atlas.zip`) need to be downloaded from https://doi.org/10.5281/zenodo.13790069 and uncompressed (for instance with `unzip brain_atlas.zip`) in the example/data folder.\n\nThe example/config_clustering_example.cfg configuration file provides the parameters for each step of the workflow. The workflow can be run by executing the script example/run_clustering_example.sh (with the venv activated, source venvAP/bin/activate), which basically runs the complete workflow:\n\n```bash\npython ../axon_projection/run.py config_clustering_example.cfg\n```\n\nThe example should run in a few minutes, depending on the computing configuration (4 minutes with 20 processes). The output is generated in the example/out_clustering_example folder.\n\n### Axon synthesis example\nThis second example shows how to use the output of the projections clustering from the previous example, as input for the axon synthesis algorithm presented in https://doi.org/10.1101/2024.10.16.618695. Namely, the target locations of the axons, number and selection of tufts is provided by the projection clustering code.\n\nTo run the synthesis example, ensure to first run the clustering example.\n\nThen, simply run the run_synthesis_example.sh script with the virtual environment activated. The [example/config_synthesis_example.cfg](example/config_synthesis_example.cfg) configuration file contains the parameters used in the axon synthesis algorithm.\n\nThis example synthesizes axons for the set of axon-less morphologies in the folder [example/data/morphologies_for_synthesis](example/data/morphologies_for_synthesis), using the data extracted from axons in the folder [example/data/morphologies](example/data/morphologies).\n\nThis example has an initial computation of brain regions masks that takes around 15-20 minutes (and creates the output `boundary.nrrd` in the data directory), and the synthesis runs typically in 5 minutes, without leveraging parallelism.\n\nTo use parallelism, one can install the axon-synthesis package with the mpi option\n```bash\npip install axon-synthesis[mpi]\n```\n\n## Citation\n\nTo cite this repository, please cite the accompanying research article:\n\nPetkantchin, R., Berchet, A., Peng, H., Markram, H., Kanari, L., 2024. Generating brain-wide connectome using synthetic axonal morphologies. https://doi.org/10.1101/2024.10.04.616605\n\n\n## Funding & Acknowledgment\n\nThe development of this software was supported by funding to the Blue Brain Project, a research\ncenter of the \u00c9cole polytechnique f\u00e9d\u00e9rale de Lausanne (EPFL), from the Swiss government\u2019s ETH\nBoard of the Swiss Federal Institutes of Technology.\n\nFor license and authors, see `LICENSE.txt` and `AUTHORS.md` respectively.\n\nCopyright \u00a9 2023-2024 Blue Brain Project/EPFL\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "A code that analyses long-range axons provided as input, and classify them based on the brain regions they project to.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://axon-projection.readthedocs.io",
"Source": "https://github.com/BlueBrain/axon-projection",
"Tracker": "https://github.com/BlueBrain/axon-projection/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b6531c55d5d21b6ebfd20e7b695f70c1d3e63e93668ca31aa4af6842114e4765",
"md5": "25a030440b12afaf53c51dca6a1202c4",
"sha256": "3cd510d42c8297bbe5754c0342f76b6ce98f1c01cc8d8dd2b8e906620119ee5d"
},
"downloads": -1,
"filename": "axon_projection-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "25a030440b12afaf53c51dca6a1202c4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 2443273,
"upload_time": "2024-10-25T09:53:59",
"upload_time_iso_8601": "2024-10-25T09:53:59.838339Z",
"url": "https://files.pythonhosted.org/packages/b6/53/1c55d5d21b6ebfd20e7b695f70c1d3e63e93668ca31aa4af6842114e4765/axon_projection-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "87e99190f3a46baf0ba6b7625e74b23e77516a3b09fd1a2e5371bcc14b268d41",
"md5": "1b9e6c0cea5521bb651332a28baff6e5",
"sha256": "8d7edb06d6bdab3d3978b04ec92fffa79a1bd92ce9b14c91cff3955d336745ba"
},
"downloads": -1,
"filename": "axon_projection-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "1b9e6c0cea5521bb651332a28baff6e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 11419600,
"upload_time": "2024-10-25T09:54:01",
"upload_time_iso_8601": "2024-10-25T09:54:01.830668Z",
"url": "https://files.pythonhosted.org/packages/87/e9/9190f3a46baf0ba6b7625e74b23e77516a3b09fd1a2e5371bcc14b268d41/axon_projection-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 09:54:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "BlueBrain",
"github_project": "axon-projection",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "axon-projection"
}
JSON
