https://github.com/khanlab/hippunfold-plot
Plotting functions for hippocampal surface maps from HippUnfold
https://github.com/khanlab/hippunfold-plot
Last synced: 6 months ago
JSON representation
Plotting functions for hippocampal surface maps from HippUnfold
- Host: GitHub
- URL: https://github.com/khanlab/hippunfold-plot
- Owner: khanlab
- License: mit
- Created: 2024-11-29T19:41:13.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-12-01T18:11:40.000Z (over 1 year ago)
- Last Synced: 2024-12-01T18:29:52.161Z (over 1 year ago)
- Language: Jupyter Notebook
- Homepage:
- Size: 2.61 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 🧠 hippunfold_plot
This package provides plotting functions for hippocampal surface maps from HippUnfold (https://github.com/khanlab/hippunfold),
wrapping the Nilearn (https://nilearn.github.io) plotting functions (matplotlib engine) to achieve this.
Note: these plotting functions are distinct from those in HippoMaps (https://github.com/MICA-MNI/hippomaps), which use
VTK wrappers and have a number of limitations therein.
This package is new and still under active development so suggestions and pull-requests are welcome!
## 📦 Installation
To install the package, simply run:
```sh
pip install hippunfold_plot
```
## 🚀 Usage
Here are some examples of how to use the `plot_hipp_surf` function to visualize hippocampal surface maps.
### Example 1: Plot Both Hemispheres
```python
from hippunfold_plot.plotting import plot_hipp_surf
from hippunfold_plot.utils import get_resource_path
#get subfields for demonstrating plotting
label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
density = '1mm'
# Plot dorsal view
fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=density, view='dorsal')
# Plot ventral view
fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=density, view='ventral')
```
### Example 2: Plot Left and Right Hemispheres Separately
```python
from hippunfold_plot.plotting import plot_hipp_surf
from hippunfold_plot.utils import get_resource_path
#get subfields for demonstrating plotting
label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
density = '1mm'
# Plot left hemisphere
fig = plot_hipp_surf(label_gii.format(density=density), hemi='left', density=density, view='dorsal')
# Plot right hemisphere
fig = plot_hipp_surf(label_gii.format(density=density), hemi='right', density=density, view='dorsal')
```
### Example 3: Plot unfolded and canonical space separately
```python
from hippunfold_plot.plotting import plot_hipp_surf
from hippunfold_plot.utils import get_resource_path
#get subfields for demonstrating plotting
label_gii = get_resource_path('tpl-avg_label-hippdentate_density-{density}_subfields.label.gii')
density = '1mm'
# Plot left hemisphere in unfolded space
fig = plot_hipp_surf(label_gii.format(density=density), space='unfold', density=density, view='dorsal')
# Plot left hemisphere in canonical space
fig = plot_hipp_surf(label_gii.format(density=density), space='canonical', density=density, view='dorsal')
```
## 🛠️ Functions
### `plot_hipp_surf`
Plot hippocampal surface map.
This function plots a surface map of the hippocampus, which can be a label-hippdentate shape.gii, func.gii, or a Vx1 array
(where V is the number of vertices in the hippocampus and dentate). Any arguments that can be supplied to nilearn's plot_surf()
can also be applied here, overriding the defaults set below.
###### Parameters
- **surf_map** (str or array-like):
The surface map to plot. This can be a file path to a .gii file or a Vx1 array.
- **density** (str, optional):
The density of the surface map. Can be 'unfoldiso', '0p5mm', '1mm', or '2mm'. Default is '0p5mm'.
- **hemi** (str, optional):
The hemisphere to plot. Can be 'left', 'right', or None (in which case both are plotted). Default is 'left'.
- **space** (str, optional):
The space of the surface map. Can be 'canonical', 'unfold', or None (in which case both are plotted). Default is None.
- **figsize** (tuple, optional):
The size of the figure. Default is (12, 8).
- **dpi** (int, optional):
The resolution of the figure in dots per inch. Default is 300.
- **vmin** (float, optional):
The minimum value for the color scale. Default is None.
- **vmax** (float, optional):
The maximum value for the color scale. Default is None.
- **colorbar** (bool, optional):
Whether to display a colorbar. Default is False.
- **colorbar_shrink** (float, optional):
The shrink factor for the colorbar. Default is 0.25.
- **cmap** (str or colormap, optional):
The colormap to use. Default is None.
- **view** (str, optional):
The view of the surface plot. Default is 'dorsal'.
- **avg_method** (str, optional):
The method to average the data. Default is 'median'.
- **bg_on_data** (bool, optional):
Whether to display the background on the data. Default is True.
- **alpha** (float, optional):
The alpha transparency level. Default is 0.1.
- **darkness** (float, optional):
The darkness level of the background. Default is 2.
- **axes** (matplotlib.axes.Axes or list of matplotlib.axes.Axes, optional):
Axes to plot on. If None, new axes will be created. If a single axis is provided, it will be used for a single plot.
If multiple plots are to be made, a list of axes should be provided.
- **figure** (matplotlib.figure.Figure, optional):
The figure to plot on. If None, a new figure will be created.
- ****kwargs** (dict):
Additional arguments to pass to nilearn's plot_surf().
###### Returns
- **figure** (matplotlib.figure.Figure):
The figure object.
###### Notes
By default, this function will plot one hemisphere (left by default) in both canonical and unfolded space.
Both surfaces can be plotted with hemi=None, but the same surf_map will be plotted on both.
## 🧪 Testing
To run the tests, including unit tests and docstring tests, use the following command:
```sh
python -m unittest discover -s . -p "test_*.py"
```
## 📄 License
This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
## 🙌 Contributing
We welcome contributions and feedback! Please make a PR or post an issue.
---
Happy plotting! 🎉