# siibra-jugex
## A toolbox for atlas-based differential analysis of gene expressions
*Authors: Big Data Analytics Group and S. Bludau, Institute of Neuroscience and Medicine (INM-1), Forschungszentrum Jülich GmbH*
Copyright 2020-2021, Forschungszentrum Jülich GmbH
> :warning: **`siibra-jugex` is at an experimental stage.** The software is not yet fully tested. Be aware that you will likely encounter bugs.
JuGEx (Julich-Brain Gene Expression) is an integrated framework developed to combined the AllenBrain and Julich-Brain atlases for statistical analysis of differential gene expression in the adult human brain.
The framework has been developed by S. Bludau et al. and is described in
> Sebastian Bludau, Thomas W. Mühleisen, Simon B. Eickhoff, Michael J. Hawrylycz, Sven Cichon, Katrin Amunts. Integration of transcriptomic and cytoarchitectonic data implicates a role for MAOA and TAC1 in the limbic-cortical network. 2018, Brain Structure and Function. [https://doi.org/10.1007/s00429-018-1620-6](https://doi.org/10.1007/s00429-018-1620-6)*.
The original implementation in Matlab can be found [here](https://www.fz-juelich.de/SharedDocs/Downloads/INM/INM-1/DE/jugex.html?nn=2163780).
The basic idea of JuGExis to supplement different levels of information on brain architecture, e.g. structural and functional connectivity, brain activations, and neurotransmitter receptor density by transcriptional information to enlight biological aspects of brain organization and its diseases, spatially referring to the cytoarchitectonic Julich-Brain atlas. This allows analysis beyond approaches which rely on the traditional segregation of the brain into sulci and gyri, thereby combining functionally different microstructural areas. JuGex is publicly available to empower research from basic, cognitive and clinical neuroscience in further brain regions and disease models with regard to gene expression.
`siibra` is a Python client for interacting with "multilevel" brain atlases, which combine multiple brain parcellations, reference coordinate spaces and modalities. See [here](https://siibra.eu) for more details.
This siibra toolbox implements the JuGEx algorithm with siibra, to provide a simple and intuitive implementation in python, as well as an interactive plugin of the 3D atlas viewer of [EBRAINS](https://ebrains.eu/service/human-brain-atlas/).
The analysis is initialized with a siibra atlas object. It will check if the parcellation selected in the atlas is suitable for performing the analysis, which includes to verify that the given atlas object provides maps in the MNI ICBM 152 space. The analysis is configured by specifying some candidate genes of interest, and two regions of interest (ROI) specified by brain area names that the atlas object can resolve. Note that the siibra atlas class does fuzzy string matching to resolve region names, so you can try with a simple name of the regions to see if siibra interprets them. Also, gene names can easily be looked up and autocompleted in siibra.gene_names.
For the gene expression data, `siibra-jugex` accesses the Allen Brain Atlas API (© 2015 Allen Institute for Brain Science. Allen Brain Atlas API. Available from: brain-map.org/api/index.html).
## Installation
`siibra-python` is available on pypi. To install the latest version, simply run `pip install siibra-jugex`.
## Quick walkthrough
To get familiar with `siibra-jugex`, we recommend to checkout the notebook in the `examples/` subfolder of this repository, which walks you throught the basic idea. You can run it live if you like by visiting mybinder: [](https://mybinder.org/v2/gh/FZJ-INM1-BDA/siibra-jugex/master?filepath=examples%2Fsiibra-jugex.ipynb)
#### Initialize the analysis
The analysis is initialized with a `siibra` atlas object. It will check if the parcellation selected in the atlas is suitable for performing the analysis, which includes to verify that the given atlas object provides maps in the MNI ICBM 152 space. We explicitely select the Julich-Brain probabilistic cytoarchitectonic maps, and tell the atlas to threshold the probability maps for filtering gene expressions instead of using the simplified labelled volume.
```python
import siibra, siibra_jugex
```
> [siibra:INFO] Version: 0.1a1 \
[siibra:INFO] Configuration: siibra-0.1a1 \
[siibra_jugex:INFO] Version: 0.1a1
```python
atlas = siibra.atlases.MULTILEVEL_HUMAN_ATLAS
atlas.select_parcellation(siibra.parcellations.JULICH_BRAIN_CYTOARCHITECTONIC_MAPS_2_5)
atlas.threshold_continuous_maps(0.2)
jugex = siibra_jugex.DifferentialGeneExpression(atlas)
```
> [siibra:INFO] Multilevel Human Atlas | select "Julich-Brain Cytoarchitectonic Maps 2.5"
#### Configure the experiment with brain regions and candidate genes
The analysis is configured by specifying some candidate genes of interest, and two regions of interest (ROI) specified by brain area names that the atlas object can resolve. Note that the siibra atlas class does fuzzy string matching to resolve region names, so you can try with a simple name of the regions to see if siibra interprets them. Also, gene names can easily be looked up and autocompleted in siibra.gene_names.
```python
candidate_regions = ["v1 right","v2 right"]
candidate_genes = ["MAOA","TAC1"]
jugex.add_candidate_genes(candidate_genes)
jugex.define_roi1(candidate_regions[0])
jugex.define_roi2(candidate_regions[1])
```
> [siibra:INFO] Multilevel Human Atlas | select "Area hOc1 (V1, 17, CalcS) - right hemisphere" \
[siibra:INFO] Retrieving probe ids for gene MAOA
For retrieving microarray data, siibra connects to the web API of
the Allen Brain Atlas (© 2015 Allen Institute for Brain Science), available
from https://brain-map.org/api/index.html. Any use of the microarray data needs
to be in accordance with their terms of use, as specified at
https://alleninstitute.org/legal/terms-use/.
> [siibra:INFO] Area hOc1 (V1, 17, CalcS) - right hemisphere: Computing mask by thresholding continuous map at 0.2. \
[siibra:INFO] Retrieving probe ids for gene TAC1 \
[siibra_jugex:INFO] 12 samples found for region v1 right. \
[siibra:INFO] Multilevel Human Atlas | select "Area hOc2 (V2, 18) - right hemisphere" \
[siibra:INFO] Retrieving probe ids for gene MAOA \
[siibra:INFO] Area hOc2 (V2, 18) - right hemisphere: Computing mask by thresholding continuous map at 0.2. \
[siibra:INFO] Retrieving probe ids for gene TAC1 \
[siibra_jugex:INFO] 11 samples found for region v2 right.
#### Run the analysis
```python
result = jugex.run(permutations=1000)
print(result['p-values'])
```
> {'MAOA': 0.96, 'TAC1': 0.441}
The aggregated input parameters can be stored to disk.
```python
jugex.save('jugex_{}_{}.json'.format(
"_".join(candidate_regions),
"_".join(candidate_genes) ))
```
> [siibra_jugex:INFO] Exported p-values and factors to file jugex_v1 right_v2 right_MAOA_TAC1.json.
#### Look at filtered positions of microarray samples in MNI space
Let's have a look at the sample positions that have been found in the Allen atlas. Since we configured brainscapes to prefer thresholded continuous maps for region filtering over the simplified parcellation map, we also plot the probability maps here.
```python
from nilearn import plotting
for regionname in candidate_regions:
samples = jugex.get_samples(regionname)
region = atlas.select_region(regionname)
pmap = atlas.selected_region.get_regional_map(
siibra.spaces.MNI152_2009C_NONL_ASYM,
siibra.MapType.CONTINUOUS)
# we could have also used the simple parcellation map mask as follows:
# mask = atlas.get_mask(bs.spaces.MNI_152_ICBM_2009C_NONLINEAR_ASYMMETRIC)
display = plotting.plot_roi(pmap,cmap="jet",title=region.name)
display.add_markers([s['mnicoord'] for s in samples.values()])
```
## Acknowledgements
This software code is funded from the European Union’s Horizon 2020 Framework
Programme for Research and Innovation under the Specific Grant Agreement No.
945539 (Human Brain Project SGA3).
Raw data
{
"_id": null,
"home_page": "https://github.com/FZJ-INM1-BDA/siibra-jugex",
"name": "siibra-jugex",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "",
"author": "Big Data Analytics Group and S. Bludau, Forschungszentrum Juelich, Institute of Neuroscience and Medicine (INM-1)",
"author_email": "inm1-bda@fz-juelich.de",
"download_url": "https://files.pythonhosted.org/packages/5b/d9/3da0d9c5894f5fec30c52e3d1630f35b1af616918d10e3e514168dc967cc/siibra_jugex-1.22.tar.gz",
"platform": null,
"description": "# siibra-jugex\n\n## A toolbox for atlas-based differential analysis of gene expressions\n\n*Authors: Big Data Analytics Group and S. Bludau, Institute of Neuroscience and Medicine (INM-1), Forschungszentrum J\u00fclich GmbH*\n\nCopyright 2020-2021, Forschungszentrum J\u00fclich GmbH \n\n> :warning: **`siibra-jugex` is at an experimental stage.** The software is not yet fully tested. Be aware that you will likely encounter bugs.\n\nJuGEx (Julich-Brain Gene Expression) is an integrated framework developed to combined the AllenBrain and Julich-Brain atlases for statistical analysis of differential gene expression in the adult human brain.\nThe framework has been developed by S. Bludau et al. and is described in \n\n> Sebastian Bludau, Thomas W. M\u00fchleisen, Simon B. Eickhoff, Michael J. Hawrylycz, Sven Cichon, Katrin Amunts. Integration of transcriptomic and cytoarchitectonic data implicates a role for MAOA and TAC1 in the limbic-cortical network. 2018, Brain Structure and Function. [https://doi.org/10.1007/s00429-018-1620-6](https://doi.org/10.1007/s00429-018-1620-6)*.\n\nThe original implementation in Matlab can be found [here](https://www.fz-juelich.de/SharedDocs/Downloads/INM/INM-1/DE/jugex.html?nn=2163780).\n\nThe basic idea of JuGExis to supplement different levels of information on brain architecture, e.g. structural and functional connectivity, brain activations, and neurotransmitter receptor density by transcriptional information to enlight biological aspects of brain organization and its diseases, spatially referring to the cytoarchitectonic Julich-Brain atlas. This allows analysis beyond approaches which rely on the traditional segregation of the brain into sulci and gyri, thereby combining functionally different microstructural areas. JuGex is publicly available to empower research from basic, cognitive and clinical neuroscience in further brain regions and disease models with regard to gene expression.\n\n`siibra` is a Python client for interacting with \"multilevel\" brain atlases, which combine multiple brain parcellations, reference coordinate spaces and modalities. See [here](https://siibra.eu) for more details.\nThis siibra toolbox implements the JuGEx algorithm with siibra, to provide a simple and intuitive implementation in python, as well as an interactive plugin of the 3D atlas viewer of [EBRAINS](https://ebrains.eu/service/human-brain-atlas/).\nThe analysis is initialized with a siibra atlas object. It will check if the parcellation selected in the atlas is suitable for performing the analysis, which includes to verify that the given atlas object provides maps in the MNI ICBM 152 space. The analysis is configured by specifying some candidate genes of interest, and two regions of interest (ROI) specified by brain area names that the atlas object can resolve. Note that the siibra atlas class does fuzzy string matching to resolve region names, so you can try with a simple name of the regions to see if siibra interprets them. Also, gene names can easily be looked up and autocompleted in siibra.gene_names.\n\nFor the gene expression data, `siibra-jugex` accesses the Allen Brain Atlas API (\u00a9 2015 Allen Institute for Brain Science. Allen Brain Atlas API. Available from: brain-map.org/api/index.html).\n\n## Installation\n\n`siibra-python` is available on pypi. To install the latest version, simply run `pip install siibra-jugex`.\n\n## Quick walkthrough\n\nTo get familiar with `siibra-jugex`, we recommend to checkout the notebook in the `examples/` subfolder of this repository, which walks you throught the basic idea. You can run it live if you like by visiting mybinder: [](https://mybinder.org/v2/gh/FZJ-INM1-BDA/siibra-jugex/master?filepath=examples%2Fsiibra-jugex.ipynb)\n\n\n#### Initialize the analysis\n\nThe analysis is initialized with a `siibra` atlas object. It will check if the parcellation selected in the atlas is suitable for performing the analysis, which includes to verify that the given atlas object provides maps in the MNI ICBM 152 space. We explicitely select the Julich-Brain probabilistic cytoarchitectonic maps, and tell the atlas to threshold the probability maps for filtering gene expressions instead of using the simplified labelled volume. \n\n\n```python\nimport siibra, siibra_jugex\n```\n\n> [siibra:INFO] Version: 0.1a1 \\\n [siibra:INFO] Configuration: siibra-0.1a1 \\\n [siibra_jugex:INFO] Version: 0.1a1\n\n\n```python\natlas = siibra.atlases.MULTILEVEL_HUMAN_ATLAS\natlas.select_parcellation(siibra.parcellations.JULICH_BRAIN_CYTOARCHITECTONIC_MAPS_2_5)\natlas.threshold_continuous_maps(0.2)\n\njugex = siibra_jugex.DifferentialGeneExpression(atlas)\n```\n\n> [siibra:INFO] Multilevel Human Atlas | select \"Julich-Brain Cytoarchitectonic Maps 2.5\"\n\n\n#### Configure the experiment with brain regions and candidate genes\n\nThe analysis is configured by specifying some candidate genes of interest, and two regions of interest (ROI) specified by brain area names that the atlas object can resolve. Note that the siibra atlas class does fuzzy string matching to resolve region names, so you can try with a simple name of the regions to see if siibra interprets them. Also, gene names can easily be looked up and autocompleted in siibra.gene_names. \n\n\n\n```python\ncandidate_regions = [\"v1 right\",\"v2 right\"]\ncandidate_genes = [\"MAOA\",\"TAC1\"]\njugex.add_candidate_genes(candidate_genes)\njugex.define_roi1(candidate_regions[0])\njugex.define_roi2(candidate_regions[1])\n```\n\n> [siibra:INFO] Multilevel Human Atlas | select \"Area hOc1 (V1, 17, CalcS) - right hemisphere\" \\\n [siibra:INFO] Retrieving probe ids for gene MAOA\n\n\n For retrieving microarray data, siibra connects to the web API of\n the Allen Brain Atlas (\u00a9 2015 Allen Institute for Brain Science), available\n from https://brain-map.org/api/index.html. Any use of the microarray data needs\n to be in accordance with their terms of use, as specified at\n https://alleninstitute.org/legal/terms-use/.\n\n\n> [siibra:INFO] Area hOc1 (V1, 17, CalcS) - right hemisphere: Computing mask by thresholding continuous map at 0.2. \\\n [siibra:INFO] Retrieving probe ids for gene TAC1 \\\n [siibra_jugex:INFO] 12 samples found for region v1 right. \\\n [siibra:INFO] Multilevel Human Atlas | select \"Area hOc2 (V2, 18) - right hemisphere\" \\\n [siibra:INFO] Retrieving probe ids for gene MAOA \\\n [siibra:INFO] Area hOc2 (V2, 18) - right hemisphere: Computing mask by thresholding continuous map at 0.2. \\\n [siibra:INFO] Retrieving probe ids for gene TAC1 \\\n [siibra_jugex:INFO] 11 samples found for region v2 right.\n\n\n#### Run the analysis\n\n\n```python\nresult = jugex.run(permutations=1000)\nprint(result['p-values'])\n```\n\n> {'MAOA': 0.96, 'TAC1': 0.441}\n\n\nThe aggregated input parameters can be stored to disk.\n\n\n```python\njugex.save('jugex_{}_{}.json'.format(\n \"_\".join(candidate_regions),\n \"_\".join(candidate_genes) ))\n```\n\n> [siibra_jugex:INFO] Exported p-values and factors to file jugex_v1 right_v2 right_MAOA_TAC1.json.\n\n\n#### Look at filtered positions of microarray samples in MNI space\n\nLet's have a look at the sample positions that have been found in the Allen atlas. Since we configured brainscapes to prefer thresholded continuous maps for region filtering over the simplified parcellation map, we also plot the probability maps here.\n\n\n```python\nfrom nilearn import plotting\n\nfor regionname in candidate_regions:\n samples = jugex.get_samples(regionname)\n region = atlas.select_region(regionname)\n pmap = atlas.selected_region.get_regional_map(\n siibra.spaces.MNI152_2009C_NONL_ASYM, \n siibra.MapType.CONTINUOUS) \n # we could have also used the simple parcellation map mask as follows:\n # mask = atlas.get_mask(bs.spaces.MNI_152_ICBM_2009C_NONLINEAR_ASYMMETRIC)\n display = plotting.plot_roi(pmap,cmap=\"jet\",title=region.name)\n display.add_markers([s['mnicoord'] for s in samples.values()])\n```\n\n \n\n \n\n\n \n\n \n\n\n## Acknowledgements\n\nThis software code is funded from the European Union\u2019s Horizon 2020 Framework\nProgramme for Research and Innovation under the Specific Grant Agreement No.\n945539 (Human Brain Project SGA3).\n",
"bugtrack_url": null,
"license": "",
"summary": "siibra-jugex - Differential analysis of gene expression in brain regions using the siibra framework",
"version": "1.22",
"project_urls": {
"Homepage": "https://github.com/FZJ-INM1-BDA/siibra-jugex"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a6d2ad262e06428b99396ba5b62ffb5a1069b0146f5f71d3114e8b97cf3c1ee5",
"md5": "d85cbc907691702f3aff28996351f39b",
"sha256": "65f8f0e915ec787c3c07d7bc98ed8807efae46f1cd46b69769b665b2efbc9bda"
},
"downloads": -1,
"filename": "siibra_jugex-1.22-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d85cbc907691702f3aff28996351f39b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 13914,
"upload_time": "2023-09-13T08:57:03",
"upload_time_iso_8601": "2023-09-13T08:57:03.533840Z",
"url": "https://files.pythonhosted.org/packages/a6/d2/ad262e06428b99396ba5b62ffb5a1069b0146f5f71d3114e8b97cf3c1ee5/siibra_jugex-1.22-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5bd93da0d9c5894f5fec30c52e3d1630f35b1af616918d10e3e514168dc967cc",
"md5": "f063d7d997c45c301aab8d4ac63162ca",
"sha256": "679a7eff3c00230c71bab9a5f28e3f266d29ef61f39bbe128a3690ed122550b6"
},
"downloads": -1,
"filename": "siibra_jugex-1.22.tar.gz",
"has_sig": false,
"md5_digest": "f063d7d997c45c301aab8d4ac63162ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 15889,
"upload_time": "2023-09-13T08:57:06",
"upload_time_iso_8601": "2023-09-13T08:57:06.460448Z",
"url": "https://files.pythonhosted.org/packages/5b/d9/3da0d9c5894f5fec30c52e3d1630f35b1af616918d10e3e514168dc967cc/siibra_jugex-1.22.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-13 08:57:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "FZJ-INM1-BDA",
"github_project": "siibra-jugex",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "siibra",
"specs": [
[
">=",
"0.2a0"
]
]
},
{
"name": "statsmodels",
"specs": []
},
{
"name": "scipy",
"specs": []
}
],
"lcname": "siibra-jugex"
}
JSON
