subcortex-visualization 1.1.0__tar.gz → 1.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (91) hide show
  1. {subcortex_visualization-1.1.0/subcortex_visualization.egg-info → subcortex_visualization-1.2.0}/PKG-INFO +27 -13
  2. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/README.md +26 -12
  3. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/pyproject.toml +1 -1
  4. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/setup.py +2 -2
  5. subcortex_visualization-1.2.0/subcortex_visualization/atlases/AICHA_subcortex.nii.gz +0 -0
  6. subcortex_visualization-1.2.0/subcortex_visualization/atlases/AICHA_subcortex_lookup.csv +40 -0
  7. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Brainnetome_subcortex.nii.gz +0 -0
  8. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Brainnetome_subcortex_lookup.csv +36 -0
  9. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S1_subcortex.nii.gz +0 -0
  10. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S1_subcortex_lookup.csv +16 -0
  11. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S2_subcortex.nii.gz +0 -0
  12. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S2_subcortex_lookup.csv +32 -0
  13. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S3_subcortex.nii.gz +0 -0
  14. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S3_subcortex_lookup.csv +50 -0
  15. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S4_subcortex.nii.gz +0 -0
  16. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Melbourne_S4_subcortex_lookup.csv +54 -0
  17. subcortex_visualization-1.2.0/subcortex_visualization/atlases/SUIT_cerebellar_lobule.nii.gz +0 -0
  18. subcortex_visualization-1.2.0/subcortex_visualization/atlases/SUIT_cerebellar_lobule_lookup.csv +28 -0
  19. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Thalamus_Nuclei_HCP.nii.gz +0 -0
  20. subcortex_visualization-1.2.0/subcortex_visualization/atlases/Thalamus_Nuclei_HCP_lookup.csv +14 -0
  21. subcortex_visualization-1.2.0/subcortex_visualization/atlases/aseg_subcortex.nii.gz +0 -0
  22. subcortex_visualization-1.2.0/subcortex_visualization/atlases/aseg_subcortex_lookup.csv +14 -0
  23. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_L_ordering.csv +21 -21
  24. subcortex_visualization-1.2.0/subcortex_visualization/data/Melbourne_S4_L_ordering.csv +45 -0
  25. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S4_R.svg +7 -7
  26. subcortex_visualization-1.2.0/subcortex_visualization/data/Melbourne_S4_R_ordering.csv +45 -0
  27. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S4_both_ordering.csv +43 -45
  28. subcortex_visualization-1.1.0/subcortex_visualization/data/SUIT_both.svg → subcortex_visualization-1.2.0/subcortex_visualization/data/SUIT_cerebellar_lobule_both.svg +17 -17
  29. subcortex_visualization-1.1.0/subcortex_visualization/data/SUIT_both_ordering.csv → subcortex_visualization-1.2.0/subcortex_visualization/data/SUIT_cerebellar_lobule_both_ordering.csv +9 -9
  30. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Thalamus_Nuclei_HCP_L.svg +31 -31
  31. subcortex_visualization-1.2.0/subcortex_visualization/data/Thalamus_Nuclei_HCP_R.svg +316 -0
  32. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Thalamus_Nuclei_HCP_both.svg +59 -59
  33. subcortex_visualization-1.2.0/subcortex_visualization/data/__init__.py +0 -0
  34. subcortex_visualization-1.2.0/subcortex_visualization/data/aseg_L_ordering.csv +14 -0
  35. subcortex_visualization-1.2.0/subcortex_visualization/data/aseg_R_ordering.csv +14 -0
  36. subcortex_visualization-1.2.0/subcortex_visualization/data/aseg_both_ordering.csv +27 -0
  37. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/plotting.py +31 -15
  38. subcortex_visualization-1.2.0/subcortex_visualization/segmentation.py +80 -0
  39. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0/subcortex_visualization.egg-info}/PKG-INFO +27 -13
  40. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization.egg-info/SOURCES.txt +22 -2
  41. subcortex_visualization-1.1.0/subcortex_visualization/data/Melbourne_S4_L_ordering.csv +0 -47
  42. subcortex_visualization-1.1.0/subcortex_visualization/data/Melbourne_S4_R_ordering.csv +0 -47
  43. subcortex_visualization-1.1.0/subcortex_visualization/data/Thalamus_Nuclei_HCP_R.svg +0 -316
  44. subcortex_visualization-1.1.0/subcortex_visualization/data/aseg_L_ordering.csv +0 -14
  45. subcortex_visualization-1.1.0/subcortex_visualization/data/aseg_R_ordering.csv +0 -14
  46. subcortex_visualization-1.1.0/subcortex_visualization/data/aseg_both_ordering.csv +0 -27
  47. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/LICENSE.txt +0 -0
  48. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/MANIFEST.in +0 -0
  49. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/setup.cfg +0 -0
  50. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/__init__.py +0 -0
  51. {subcortex_visualization-1.1.0/subcortex_visualization/data → subcortex_visualization-1.2.0/subcortex_visualization/atlases}/__init__.py +0 -0
  52. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_L.svg +0 -0
  53. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_L_ordering.csv +0 -0
  54. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_R.svg +0 -0
  55. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_R_ordering.csv +0 -0
  56. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_both.svg +0 -0
  57. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/AICHA_both_ordering.csv +0 -0
  58. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_L.svg +0 -0
  59. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_L_ordering.csv +0 -0
  60. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_R.svg +0 -0
  61. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_R_ordering.csv +0 -0
  62. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_both.svg +0 -0
  63. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Brainnetome_both_ordering.csv +0 -0
  64. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_L.svg +0 -0
  65. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_L_ordering.csv +0 -0
  66. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_R.svg +0 -0
  67. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_R_ordering.csv +0 -0
  68. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_both.svg +0 -0
  69. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S1_both_ordering.csv +0 -0
  70. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_L.svg +0 -0
  71. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_R.svg +0 -0
  72. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_R_ordering.csv +0 -0
  73. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_both.svg +0 -0
  74. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S2_both_ordering.csv +0 -0
  75. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_L.svg +0 -0
  76. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_L_ordering.csv +0 -0
  77. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_R.svg +0 -0
  78. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_R_ordering.csv +0 -0
  79. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_both.svg +0 -0
  80. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S3_both_ordering.csv +0 -0
  81. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S4_L.svg +0 -0
  82. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Melbourne_S4_both.svg +0 -0
  83. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Thalamus_Nuclei_HCP_L_ordering.csv +0 -0
  84. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Thalamus_Nuclei_HCP_R_ordering.csv +0 -0
  85. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/Thalamus_Nuclei_HCP_both_ordering.csv +0 -0
  86. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/aseg_L.svg +0 -0
  87. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/aseg_R.svg +0 -0
  88. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/data/aseg_both.svg +0 -0
  89. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization/utils.py +0 -0
  90. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization.egg-info/dependency_links.txt +0 -0
  91. {subcortex_visualization-1.1.0 → subcortex_visualization-1.2.0}/subcortex_visualization.egg-info/top_level.txt +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: subcortex_visualization
3
- Version: 1.1.0
3
+ Version: 1.2.0
4
4
  Summary: A package to visualize subcortical and cerebellar brain data in two dimensions.
5
5
  Author: Annie G. Bryant
6
6
  Author-email: "Annie G. Bryant" <anniegbryant@gmail.com>
@@ -27,7 +27,7 @@ Dynamic: license-file
27
27
 
28
28
  [![DOI](https://zenodo.org/badge/965897997.svg)](https://doi.org/10.5281/zenodo.15385315)
29
29
 
30
- This python package currently includes the following nine subcortical and cerebellar atlases for data visualization in two-dimensional vector graphics:
30
+ This package (implemented in Python and R) currently includes the following nine subcortical and cerebellar atlases for data visualization in two-dimensional vector graphics:
31
31
 
32
32
  <img src="docs-site/docs/images/all_atlas_showcase.png" width="100%">
33
33
 
@@ -35,19 +35,21 @@ More information about these atlases, including the process of rendering the sur
35
35
 
36
36
  ## 🙋‍♀️ Motivation
37
37
 
38
- This Python package was created to generate two-dimensional subcortex images in the style of the popular [`ggseg` package](https://github.com/ggseg/ggseg) in R.
38
+ This visualization package was created to generate two-dimensional subcortex images in the style of the popular [`ggseg` package](https://github.com/ggseg/ggseg) in R.
39
39
  We based our vector graphic outlines on the three-dimensional subcortical meshes either (1) provided as part of the [ENIGMA toolbox](https://github.com/MICA-MNI/ENIGMA) for the aseg atlas or (2) meshes generated in-house using rendering software from [Chris Rorden's lab](https://github.com/neurolabusc) ([Surf Ice](https://github.com/neurolabusc/surf-ice); check out [`custom_segmentation_pipeline/`](https://github.com/anniegbryant/subcortex_visualization/tree/main/custom_segmentation_pipeline) for more information).
40
40
 
41
- The below graphic summarizes the transformation from 3D volumetric meshes to 2D surfaces, starting from the ENIGMA toolbox ('aseg' atlas, left) or a custom-rendered mesh from the [Melbourne Subcortex Atlas](https://github.com/yetianmed/subcortex/tree/master) as published in [Tian et al. (2020)]()https://www.nature.com/articles/s41593-020-00711-6 -- ('S1' granularity level, right).
41
+ The below graphic summarizes the transformation from 3D volumetric meshes to 2D surfaces, starting from the [Melbourne Subcortex Atlas](https://github.com/yetianmed/subcortex/tree/master) as published in [Tian et al. (2020)](https://www.nature.com/articles/s41593-020-00711-6) at the 'S1' resolution.
42
42
 
43
- <img src="docs-site/docs/images/aseg_and_Melbourne_S1_3D_to_2D_schematic.png" width="90%">
43
+ <img src="docs-site/docs/images/Melbourne_S1_subcortical_atlas_info.png" width="90%">
44
44
 
45
- While `ggseg` offers subcortical plotting with the `aseg` atlas, it is [not currently possible](https://github.com/ggseg/ggseg/issues/104) to show data from all seven subcortical regions (accumbens, amygdala, caudate, hippocampus, pallidum, putamen, thalamus) in the same figure.
46
- Moreover, there is currently no other software available to visualize any of the other above subcortical, thalamic, or cerebellar atlases in two dimensions with real data, hence development here.
45
+ While [`ggseg`](https://github.com/ggseg/ggseg) offers subcortical plotting with the `aseg` atlas, it is [not currently possible](https://github.com/ggseg/ggseg/issues/104) to show data from all seven subcortical regions (accumbens, amygdala, caudate, hippocampus, pallidum, putamen, thalamus) in the same figure.
46
+ Moreover, there is currently no other software available to visualize any of the other above subcortical, thalamic, or cerebellar atlases in two dimensions with real data, motivating the development of this package.
47
47
 
48
48
  ## 🖥️ Installation
49
49
 
50
- The package can be installed from GitHub in two ways.
50
+ ### Python
51
+
52
+ The Python version of this package can be installed in two ways.
51
53
  First, you can install directly with pip from the [PyPI repository](https://pypi.org/project/subcortex-visualization/):
52
54
 
53
55
  ```bash
@@ -64,11 +66,23 @@ pip install .
64
66
 
65
67
  This will install the `subcortex_visualization` package so you have access to the `plot_subcortical_data` function and associated data.
66
68
 
69
+ ### R
70
+
71
+ The R version of this package can be installed from GitHub within R using the `remotes` package as follows:
72
+
73
+ ```R
74
+ # if not already installed
75
+ install.packages("remotes")
76
+
77
+ # then install subcortexVisualizationR
78
+ remotes::install_github("anniegbryant/subcortex_visualization", subdir = "subcortexVisualizationR"
79
+ ```
80
+
67
81
  ## 👨‍💻 Usage
68
82
 
69
83
  ### ❗️ Quick start
70
84
 
71
- Running the code below will produce an image of the left subcortex in the aseg atlas (the default), each region colored by its index, with the plasma color scheme:
85
+ Running the code below (in either python or R) will produce an image of the left subcortex in the aseg atlas (the default), each region colored by its index, with the plasma color scheme:
72
86
 
73
87
  ```python
74
88
  plot_subcortical_data(hemisphere='L', cmap='plasma',
@@ -81,7 +95,7 @@ plot_subcortical_data(hemisphere='L', cmap='plasma',
81
95
  ### 📚 Tutorial
82
96
 
83
97
  For a guide that goes through all the functionality and atlases available in this package, we compiled a simple walkthrough tutorial in [tutorial.ipynb](https://github.com/anniegbryant/subcortex_visualization/blob/main/tutorial.ipynb).
84
- To plot real data in the subcortex, your `subcortex_data` should be a `pandas.DataFrame` structured as follows (here we've just assigned an integer index to each region):
98
+ To plot real data in the subcortex, your `subcortex_data` should be a Python `pandas.DataFrame` or an R `data.frame` structured as follows (here we've just assigned an integer index to each region):
85
99
 
86
100
  | region | value | Hemisphere |
87
101
  | :--- | :---: | :---: |
@@ -97,16 +111,16 @@ Briefly, all functionality is contained within the `plot_subcortical_data` funct
97
111
  * `subcortex_data`: The three-column dataframe in a format as shown above; this is optional, if left out the plot will just color each region by its index
98
112
  * `atlas`: The name of the subcortical, thalamic, or cerebellar segmentation atlas (default is 'aseg', all options listed below)
99
113
  * `value_column`: The name of the column in your `subcortex_data` to plot, defaults to 'value'
100
- * `line_thickness`: How thick the lines around each subcortical region should be drawn, in mm (default is 1.5)
114
+ * `line_thickness`: How thick the lines around each subcortical region should be drawn
101
115
  * `line_color`: What color the lines around each subcortical region should be (default is 'black')
102
116
  * `hemisphere`: Which hemisphere ('L' or 'R') the `subcortex_data` is from; can also be 'both' (default is 'L')
103
117
  * `fill_title`: Name to add to legend (default is 'values')
104
- * `cmap`: name of colormap (e.g., 'plasma' or 'viridis') or a `matplotlib.colors.Colormap` (default is 'viridis')
118
+ * `cmap`: name of colormap (e.g., 'plasma' or 'viridis') or a `matplotlib.colors.Colormap` (default is 'viridis'); for R, this could be a vector of discrete colors or a color palette generating function
105
119
  * `vmin`: Min fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure
106
120
  * `vmax`: Max fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure
107
121
  * `midpoint`: Midpoint value to enforce for fill range; this is optional
108
122
 
109
- Here's an example plotting both hemispheres, with data randomly sampled from a normal distribution, setting a color range from blue (low) to red (high) with white at the center (midpoint=0):
123
+ Here's an example in Python for plotting both hemispheres, with data randomly sampled from a normal distribution, setting a color range from blue (low) to red (high) with white at the center (midpoint=0):
110
124
 
111
125
  ```python
112
126
  import matplotlib.colors as mcolors
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![DOI](https://zenodo.org/badge/965897997.svg)](https://doi.org/10.5281/zenodo.15385315)
4
4
 
5
- This python package currently includes the following nine subcortical and cerebellar atlases for data visualization in two-dimensional vector graphics:
5
+ This package (implemented in Python and R) currently includes the following nine subcortical and cerebellar atlases for data visualization in two-dimensional vector graphics:
6
6
 
7
7
  <img src="docs-site/docs/images/all_atlas_showcase.png" width="100%">
8
8
 
@@ -10,19 +10,21 @@ More information about these atlases, including the process of rendering the sur
10
10
 
11
11
  ## 🙋‍♀️ Motivation
12
12
 
13
- This Python package was created to generate two-dimensional subcortex images in the style of the popular [`ggseg` package](https://github.com/ggseg/ggseg) in R.
13
+ This visualization package was created to generate two-dimensional subcortex images in the style of the popular [`ggseg` package](https://github.com/ggseg/ggseg) in R.
14
14
  We based our vector graphic outlines on the three-dimensional subcortical meshes either (1) provided as part of the [ENIGMA toolbox](https://github.com/MICA-MNI/ENIGMA) for the aseg atlas or (2) meshes generated in-house using rendering software from [Chris Rorden's lab](https://github.com/neurolabusc) ([Surf Ice](https://github.com/neurolabusc/surf-ice); check out [`custom_segmentation_pipeline/`](https://github.com/anniegbryant/subcortex_visualization/tree/main/custom_segmentation_pipeline) for more information).
15
15
 
16
- The below graphic summarizes the transformation from 3D volumetric meshes to 2D surfaces, starting from the ENIGMA toolbox ('aseg' atlas, left) or a custom-rendered mesh from the [Melbourne Subcortex Atlas](https://github.com/yetianmed/subcortex/tree/master) as published in [Tian et al. (2020)]()https://www.nature.com/articles/s41593-020-00711-6 -- ('S1' granularity level, right).
16
+ The below graphic summarizes the transformation from 3D volumetric meshes to 2D surfaces, starting from the [Melbourne Subcortex Atlas](https://github.com/yetianmed/subcortex/tree/master) as published in [Tian et al. (2020)](https://www.nature.com/articles/s41593-020-00711-6) at the 'S1' resolution.
17
17
 
18
- <img src="docs-site/docs/images/aseg_and_Melbourne_S1_3D_to_2D_schematic.png" width="90%">
18
+ <img src="docs-site/docs/images/Melbourne_S1_subcortical_atlas_info.png" width="90%">
19
19
 
20
- While `ggseg` offers subcortical plotting with the `aseg` atlas, it is [not currently possible](https://github.com/ggseg/ggseg/issues/104) to show data from all seven subcortical regions (accumbens, amygdala, caudate, hippocampus, pallidum, putamen, thalamus) in the same figure.
21
- Moreover, there is currently no other software available to visualize any of the other above subcortical, thalamic, or cerebellar atlases in two dimensions with real data, hence development here.
20
+ While [`ggseg`](https://github.com/ggseg/ggseg) offers subcortical plotting with the `aseg` atlas, it is [not currently possible](https://github.com/ggseg/ggseg/issues/104) to show data from all seven subcortical regions (accumbens, amygdala, caudate, hippocampus, pallidum, putamen, thalamus) in the same figure.
21
+ Moreover, there is currently no other software available to visualize any of the other above subcortical, thalamic, or cerebellar atlases in two dimensions with real data, motivating the development of this package.
22
22
 
23
23
  ## 🖥️ Installation
24
24
 
25
- The package can be installed from GitHub in two ways.
25
+ ### Python
26
+
27
+ The Python version of this package can be installed in two ways.
26
28
  First, you can install directly with pip from the [PyPI repository](https://pypi.org/project/subcortex-visualization/):
27
29
 
28
30
  ```bash
@@ -39,11 +41,23 @@ pip install .
39
41
 
40
42
  This will install the `subcortex_visualization` package so you have access to the `plot_subcortical_data` function and associated data.
41
43
 
44
+ ### R
45
+
46
+ The R version of this package can be installed from GitHub within R using the `remotes` package as follows:
47
+
48
+ ```R
49
+ # if not already installed
50
+ install.packages("remotes")
51
+
52
+ # then install subcortexVisualizationR
53
+ remotes::install_github("anniegbryant/subcortex_visualization", subdir = "subcortexVisualizationR"
54
+ ```
55
+
42
56
  ## 👨‍💻 Usage
43
57
 
44
58
  ### ❗️ Quick start
45
59
 
46
- Running the code below will produce an image of the left subcortex in the aseg atlas (the default), each region colored by its index, with the plasma color scheme:
60
+ Running the code below (in either python or R) will produce an image of the left subcortex in the aseg atlas (the default), each region colored by its index, with the plasma color scheme:
47
61
 
48
62
  ```python
49
63
  plot_subcortical_data(hemisphere='L', cmap='plasma',
@@ -56,7 +70,7 @@ plot_subcortical_data(hemisphere='L', cmap='plasma',
56
70
  ### 📚 Tutorial
57
71
 
58
72
  For a guide that goes through all the functionality and atlases available in this package, we compiled a simple walkthrough tutorial in [tutorial.ipynb](https://github.com/anniegbryant/subcortex_visualization/blob/main/tutorial.ipynb).
59
- To plot real data in the subcortex, your `subcortex_data` should be a `pandas.DataFrame` structured as follows (here we've just assigned an integer index to each region):
73
+ To plot real data in the subcortex, your `subcortex_data` should be a Python `pandas.DataFrame` or an R `data.frame` structured as follows (here we've just assigned an integer index to each region):
60
74
 
61
75
  | region | value | Hemisphere |
62
76
  | :--- | :---: | :---: |
@@ -72,16 +86,16 @@ Briefly, all functionality is contained within the `plot_subcortical_data` funct
72
86
  * `subcortex_data`: The three-column dataframe in a format as shown above; this is optional, if left out the plot will just color each region by its index
73
87
  * `atlas`: The name of the subcortical, thalamic, or cerebellar segmentation atlas (default is 'aseg', all options listed below)
74
88
  * `value_column`: The name of the column in your `subcortex_data` to plot, defaults to 'value'
75
- * `line_thickness`: How thick the lines around each subcortical region should be drawn, in mm (default is 1.5)
89
+ * `line_thickness`: How thick the lines around each subcortical region should be drawn
76
90
  * `line_color`: What color the lines around each subcortical region should be (default is 'black')
77
91
  * `hemisphere`: Which hemisphere ('L' or 'R') the `subcortex_data` is from; can also be 'both' (default is 'L')
78
92
  * `fill_title`: Name to add to legend (default is 'values')
79
- * `cmap`: name of colormap (e.g., 'plasma' or 'viridis') or a `matplotlib.colors.Colormap` (default is 'viridis')
93
+ * `cmap`: name of colormap (e.g., 'plasma' or 'viridis') or a `matplotlib.colors.Colormap` (default is 'viridis'); for R, this could be a vector of discrete colors or a color palette generating function
80
94
  * `vmin`: Min fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure
81
95
  * `vmax`: Max fill value; this is optional, and you would only want to use this to manually constrain the fill range to match another figure
82
96
  * `midpoint`: Midpoint value to enforce for fill range; this is optional
83
97
 
84
- Here's an example plotting both hemispheres, with data randomly sampled from a normal distribution, setting a color range from blue (low) to red (high) with white at the center (midpoint=0):
98
+ Here's an example in Python for plotting both hemispheres, with data randomly sampled from a normal distribution, setting a color range from blue (low) to red (high) with white at the center (midpoint=0):
85
99
 
86
100
  ```python
87
101
  import matplotlib.colors as mcolors
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "subcortex_visualization"
7
- version = "1.1.0"
7
+ version = "1.2.0"
8
8
  authors = [
9
9
  { name="Annie G. Bryant", email="anniegbryant@gmail.com" },
10
10
  ]
@@ -10,13 +10,13 @@ install_requires = [
10
10
 
11
11
  setup(
12
12
  name='subcortex_visualization',
13
- version='0.1.12',
13
+ version='1.2.0',
14
14
  description='Visualize subcortical brain data from SVG templates',
15
15
  author='Annie G. Bryant',
16
16
  packages=find_packages(),
17
17
  include_package_data=True, # ← IMPORTANT
18
18
  package_data={
19
- 'subcortex_visualization': ['data/*.svg', 'data/*.csv'],
19
+ 'subcortex_visualization': ['data/*.svg', 'data/*.csv', 'atlases/*.nii.gz', 'atlases/*.csv'],
20
20
  },
21
21
  install_requires=[
22
22
  'numpy',
@@ -0,0 +1,40 @@
1
+ 345,Amygdala-1-lh
2
+ 346,Amygdala-1-rh
3
+ 347,Caudate-1-lh
4
+ 348,Caudate-1-rh
5
+ 349,Caudate-2-lh
6
+ 350,Caudate-2-rh
7
+ 351,Caudate-3-lh
8
+ 352,Caudate-3-rh
9
+ 353,Caudate-4-lh
10
+ 354,Caudate-4-rh
11
+ 355,Caudate-5-lh
12
+ 356,Caudate-5-rh
13
+ 357,Caudate-6-lh
14
+ 358,Caudate-6-rh
15
+ 359,Caudate-7-lh
16
+ 360,Caudate-7-rh
17
+ 361,Pallidum-1-lh
18
+ 362,Pallidum-1-rh
19
+ 363,Putamen-2-lh
20
+ 364,Putamen-2-rh
21
+ 365,Putamen-3-lh
22
+ 366,Putamen-3-rh
23
+ 367,Thalamus-1-lh
24
+ 368,Thalamus-1-rh
25
+ 369,Thalamus-2-lh
26
+ 370,Thalamus-2-rh
27
+ 371,Thalamus-3-lh
28
+ 372,Thalamus-3-rh
29
+ 373,Thalamus-4-lh
30
+ 374,Thalamus-4-rh
31
+ 375,Thalamus-5-lh
32
+ 376,Thalamus-5-rh
33
+ 377,Thalamus-6-lh
34
+ 378,Thalamus-6-rh
35
+ 379,Thalamus-7-lh
36
+ 380,Thalamus-7-rh
37
+ 381,Thalamus-8-lh
38
+ 382,Thalamus-8-rh
39
+ 383,Thalamus-9-lh
40
+ 384,Thalamus-9-rh
@@ -0,0 +1,36 @@
1
+ 211,mAmyg-lh
2
+ 212,mAmyg-rh
3
+ 213,lAmyg-lh
4
+ 214,lAmyg-rh
5
+ 215,rHipp-lh
6
+ 216,rHipp-rh
7
+ 217,cHipp-lh
8
+ 218,cHipp-rh
9
+ 219,vCa-lh
10
+ 220,vCa-rh
11
+ 221,GP-lh
12
+ 222,GP-rh
13
+ 223,NAC-lh
14
+ 224,NAC-rh
15
+ 225,vmPu-lh
16
+ 226,vmPu-rh
17
+ 227,dCa-lh
18
+ 228,dCa-rh
19
+ 229,dlPu-lh
20
+ 230,dlPu-rh
21
+ 231,mPFtha-lh
22
+ 232,mPFtha-rh
23
+ 233,mPMtha-lh
24
+ 234,mPMtha-rh
25
+ 235,Stha-lh
26
+ 236,Stha-rh
27
+ 237,rTtha-lh
28
+ 238,rTtha-rh
29
+ 239,PPtha-lh
30
+ 240,PPtha-rh
31
+ 241,Otha-lh
32
+ 242,Otha-rh
33
+ 243,cTtha-lh
34
+ 244,cTtha-rh
35
+ 245,lPFtha-lh
36
+ 246,lPFtha-rh
@@ -0,0 +1,16 @@
1
+ 1,hippocampus-rh
2
+ 2,amygdala-rh
3
+ 3,thalamus_posterior-rh
4
+ 4,thalamus_anterior-rh
5
+ 5,pallidum-rh
6
+ 6,accumbens-rh
7
+ 7,putamen-rh
8
+ 8,caudate-rh
9
+ 9,hippocampus-lh
10
+ 10,amygdala-lh
11
+ 11,thalamus_posterior-lh
12
+ 12,thalamus_anterior-lh
13
+ 13,pallidum-lh
14
+ 14,accumbens-lh
15
+ 15,putamen-lh
16
+ 16,caudate-lh
@@ -0,0 +1,32 @@
1
+ 1,hippocampus_anterior-rh
2
+ 2,hippocampus_posterior-rh
3
+ 3,amygdala_lateral-rh
4
+ 4,amygdala_medial-rh
5
+ 5,thalamus_DP-rh
6
+ 6,thalamus_VP-rh
7
+ 7,thalamus_VA-rh
8
+ 8,thalamus_DA-rh
9
+ 9,accumbens_shell-rh
10
+ 10,accumbens_core-rh
11
+ 11,pallidum_posterior-rh
12
+ 12,pallidum_anterior-rh
13
+ 13,putamen_anterior-rh
14
+ 14,putamen_posterior-rh
15
+ 15,caudate_anterior-rh
16
+ 16,caudate_posterior-rh
17
+ 17,hippocampus_anterior-lh
18
+ 18,hippocampus_posterior-lh
19
+ 19,amygdala_lateral-lh
20
+ 20,amygdala_medial-lh
21
+ 21,thalamus_DP-lh
22
+ 22,thalamus_VP-lh
23
+ 23,thalamus_VA-lh
24
+ 24,thalamus_DA-lh
25
+ 25,accumbens_shell-lh
26
+ 26,accumbens_core-lh
27
+ 27,pallidum_posterior-lh
28
+ 28,pallidum_anterior-lh
29
+ 29,putamen_anterior-lh
30
+ 30,putamen_posterior-lh
31
+ 31,caudate_anterior-lh
32
+ 32,caudate_posterior-lh
@@ -0,0 +1,50 @@
1
+ 1,hippocampus_head_med-rh
2
+ 2,hippocampus_head_lat-rh
3
+ 3,hippocampus_body-rh
4
+ 4,hippocampus_tail-rh
5
+ 5,thalamus_VP_med-rh
6
+ 6,thalamus_VP_lat-rh
7
+ 7,thalamus_VA_inf-rh
8
+ 8,thalamus_VA_sup-rh
9
+ 9,thalamus_DA_med-rh
10
+ 10,thalamus_DA_lat-rh
11
+ 11,putamen_VA-rh
12
+ 12,putamen_DA-rh
13
+ 13,putamen_VP-rh
14
+ 14,putamen_DP-rh
15
+ 15,caudate_VA-rh
16
+ 16,caudate_DA-rh
17
+ 17,caudate_body-rh
18
+ 18,caudate_tail-rh
19
+ 19,amygdala_lat-rh
20
+ 20,amygdala_med-rh
21
+ 21,thalamus_DP-rh
22
+ 22,accumbens_shell-rh
23
+ 23,accumbens_core-rh
24
+ 24,GP_post-rh
25
+ 25,GP_ant-rh
26
+ 26,hippocampus_head_med-lh
27
+ 27,hippocampus_head_lat-lh
28
+ 28,hippocampus_body-lh
29
+ 29,hippocampus_tail-lh
30
+ 30,thalamus_VP_med-lh
31
+ 31,thalamus_VP_lat-lh
32
+ 32,thalamus_VA_inf-lh
33
+ 33,thalamus_VA_sup-lh
34
+ 34,thalamus_DA_med-lh
35
+ 35,thalamus_DA_lat-lh
36
+ 36,putamen_VA-lh
37
+ 37,putamen_DA-lh
38
+ 38,putamen_VP-lh
39
+ 39,putamen_DP-lh
40
+ 40,caudate_VA-lh
41
+ 41,caudate_DA-lh
42
+ 42,caudate_body-lh
43
+ 43,caudate_tail-lh
44
+ 44,amygdala_lat-lh
45
+ 45,amygdala_med-lh
46
+ 46,thalamus_DP-lh
47
+ 47,accumbens_shell-lh
48
+ 48,accumbens_core-lh
49
+ 49,GP_post-lh
50
+ 50,GP_ant-lh
@@ -0,0 +1,54 @@
1
+ 1,hippocampus_head_med_1-rh
2
+ 2,hippocampus_head_med_2-rh
3
+ 3,thalamus_VA_inf_post-rh
4
+ 4,thalamus_VA_inf_ant-rh
5
+ 5,hippocampus_head_lat-rh
6
+ 6,hippocampus_body-rh
7
+ 7,hippocampus_tail-rh
8
+ 8,thalamus_VP_med-rh
9
+ 9,thalamus_VP_lat-rh
10
+ 10,thalamus_VA_sup-rh
11
+ 11,thalamus_DA_med-rh
12
+ 12,thalamus_DA_lat-rh
13
+ 13,putamen_VA-rh
14
+ 14,putamen_DA-rh
15
+ 15,putamen_VP-rh
16
+ 16,putamen_DP-rh
17
+ 17,caudate_VA-rh
18
+ 18,caudate_DA-rh
19
+ 19,caudate_body-rh
20
+ 20,caudate_tail-rh
21
+ 21,amygdala_lat-rh
22
+ 22,amygdala_med-rh
23
+ 23,thalamus_DP-rh
24
+ 24,accumbens_shell-rh
25
+ 25,accumbens_core-rh
26
+ 26,GP_post-rh
27
+ 27,GP_ant-rh
28
+ 28,hippocampus_head_med_1-lh
29
+ 29,hippocampus_head_med_2-lh
30
+ 30,thalamus_VA_inf_post-lh
31
+ 31,thalamus_VA_inf_ant-lh
32
+ 32,hippocampus_head_lat-lh
33
+ 33,hippocampus_body-lh
34
+ 34,hippocampus_tail-lh
35
+ 35,thalamus_VP_med-lh
36
+ 36,thalamus_VP_lat-lh
37
+ 37,thalamus_VA_sup-lh
38
+ 38,thalamus_DA_med-lh
39
+ 39,thalamus_DA_lat-lh
40
+ 40,putamen_VA-lh
41
+ 41,putamen_DA-lh
42
+ 42,putamen_VP-lh
43
+ 43,putamen_DP-lh
44
+ 44,caudate_VA-lh
45
+ 45,caudate_DA-lh
46
+ 46,caudate_body-lh
47
+ 47,caudate_tail-lh
48
+ 48,amygdala_lat-lh
49
+ 49,amygdala_med-lh
50
+ 50,thalamus_DP-lh
51
+ 51,accumbens_shell-lh
52
+ 52,accumbens_core-lh
53
+ 53,GP_post-lh
54
+ 54,GP_ant-lh
@@ -0,0 +1,28 @@
1
+ 1,IV-lh
2
+ 2,IV-rh
3
+ 3,V-lh
4
+ 4,V-rh
5
+ 5,VI-lh
6
+ 6,VI-vermis
7
+ 7,VI-rh
8
+ 8,Crus_I-lh
9
+ 9,Crus_I-vermis
10
+ 10,Crus_I-rh
11
+ 11,Crus_II-lh
12
+ 12,Crus_II-vermis
13
+ 13,Crus_II-rh
14
+ 14,VIIb-lh
15
+ 15,VIIb-vermis
16
+ 16,VIIb-rh
17
+ 17,VIIIa-lh
18
+ 18,VIIIa-vermis
19
+ 19,VIIIa-rh
20
+ 20,VIIIb-lh
21
+ 21,VIIIb-vermis
22
+ 22,VIIIb-rh
23
+ 23,IX-lh
24
+ 24,IX-vermis
25
+ 25,IX-rh
26
+ 26,X-lh
27
+ 27,X-vermis
28
+ 28,X-rh
@@ -0,0 +1,14 @@
1
+ 1,Pulvinar-lh
2
+ 2,Anterior-lh
3
+ 3,Medio_Dorsal-lh
4
+ 4,Ventral_Latero_Dorsal-lh
5
+ 5,Central_Lateral-Lateral_Posterior-Medial_Pulvinar-lh
6
+ 6,Ventral_Anterior-lh
7
+ 7,Ventral_Latero_Ventral-lh
8
+ 8,Pulvinar-rh
9
+ 9,Anterior-rh
10
+ 10,Medio_Dorsal-rh
11
+ 11,Ventral_Latero_Dorsal-rh
12
+ 12,Central_Lateral-Lateral_Posterior-Medial_Pulvinar-rh
13
+ 13,Ventral_Anterior-rh
14
+ 14,Ventral_Latero_Ventral-rh
@@ -0,0 +1,14 @@
1
+ 10,thalamus-lh
2
+ 11,caudate-lh
3
+ 12,putamen-lh
4
+ 13,pallidum-lh
5
+ 17,hippocampus-lh
6
+ 18,amygdala-lh
7
+ 26,accumbens-lh
8
+ 49,thalamus-rh
9
+ 50,caudate-rh
10
+ 51,putamen-rh
11
+ 52,pallidum-rh
12
+ 53,hippocampus-rh
13
+ 54,amygdala-rh
14
+ 58,accumbens-rh
@@ -1,30 +1,30 @@
1
1
  region,Hemisphere,seg_index,face,plot_order
2
- putamen_posterior,L,30,medial,1
3
- putamen_anterior,L,29,medial,2
4
- accumbens_core,L,26,medial,3
5
- accumbens_shell,L,25,medial,4
6
- caudate_anterior,L,31,medial,5
7
- caudate_posterior,L,32,medial,6
8
- pallidum_posterior,L,27,medial,7
9
- pallidum_anterior,L,28,medial,8
2
+ hippocampus_anterior,L,17,medial,12
3
+ hippocampus_anterior,L,17,lateral,22
4
+ hippocampus_posterior,L,18,medial,11
5
+ hippocampus_posterior,L,18,lateral,21
10
6
  amygdala_lateral,L,19,medial,9
7
+ amygdala_lateral,L,19,lateral,24
11
8
  amygdala_medial,L,20,medial,10
12
- hippocampus_posterior,L,18,medial,11
13
- hippocampus_anterior,L,17,medial,12
9
+ amygdala_medial,L,20,lateral,23
14
10
  thalamus_DP,L,21,medial,13
11
+ thalamus_DP,L,21,lateral,19
15
12
  thalamus_VP,L,22,medial,14
16
- thalamus_DA,L,24,medial,15
13
+ thalamus_VP,L,22,lateral,20
17
14
  thalamus_VA,L,23,medial,16
18
15
  thalamus_VA,L,23,lateral,17
16
+ thalamus_DA,L,24,medial,15
19
17
  thalamus_DA,L,24,lateral,18
20
- thalamus_DP,L,21,lateral,19
21
- thalamus_VP,L,22,lateral,20
22
- hippocampus_posterior,L,18,lateral,21
23
- hippocampus_anterior,L,17,lateral,22
24
- amygdala_medial,L,20,lateral,23
25
- amygdala_lateral,L,19,lateral,24
26
- caudate_posterior,L,32,lateral,25
27
- caudate_anterior,L,31,lateral,26
18
+ accumbens_shell,L,25,medial,4
19
+ accumbens_core,L,26,medial,3
28
20
  accumbens_core,L,26,lateral,27
29
- putamen_anterior,L,47,lateral,28
30
- putamen_posterior,L,30,lateral,29
21
+ pallidum_posterior,L,27,medial,7
22
+ pallidum_anterior,L,28,medial,8
23
+ putamen_anterior,L,29,medial,2
24
+ putamen_anterior,L,29,lateral,28
25
+ putamen_posterior,L,30,medial,1
26
+ putamen_posterior,L,30,lateral,29
27
+ caudate_anterior,L,31,medial,5
28
+ caudate_anterior,L,31,lateral,26
29
+ caudate_posterior,L,32,medial,6
30
+ caudate_posterior,L,32,lateral,25
@@ -0,0 +1,45 @@
1
+ region,Hemisphere,seg_index,face,plot_order
2
+ thalamus_DA_med,L,38,lateral,1
3
+ thalamus_VA_sup,L,37,lateral,2
4
+ thalamus_VP_lat,L,36,lateral,3
5
+ thalamus_DA_lat,L,39,lateral,4
6
+ thalamus_DP,L,50,lateral,5
7
+ hippocampus_tail,L,34,lateral,6
8
+ hippocampus_body,L,33,lateral,7
9
+ amygdala_med,L,49,lateral,8
10
+ hippocampus_head_lat,L,32,lateral,9
11
+ amygdala_lat,L,48,lateral,10
12
+ accumbens_core,L,52,lateral,11
13
+ caudate_DA,L,45,lateral,12
14
+ caudate_body,L,46,lateral,13
15
+ caudate_tail,L,47,lateral,14
16
+ putamen_VA,L,40,lateral,15
17
+ putamen_DA,L,41,lateral,16
18
+ putamen_DP,L,43,lateral,17
19
+ putamen_VP,L,42,lateral,18
20
+ putamen_DA,L,41,medial,19
21
+ putamen_VP,L,42,medial,20
22
+ putamen_DP,L,43,medial,21
23
+ putamen_VA,L,40,medial,22
24
+ accumbens_core,L,52,medial,23
25
+ accumbens_shell,L,51,medial,24
26
+ caudate_DA,L,45,medial,25
27
+ caudate_VA,L,44,medial,26
28
+ caudate_body,L,46,medial,27
29
+ caudate_tail,L,47,medial,28
30
+ amygdala_lat,L,48,medial,29
31
+ hippocampus_head_lat,L,32,medial,30
32
+ hippocampus_body,L,33,medial,31
33
+ hippocampus_head_med_1,L,28,medial,32
34
+ hippocampus_head_med_2,L,29,medial,33
35
+ amygdala_med,L,49,medial,34
36
+ hippocampus_tail,L,34,medial,35
37
+ GP_post,L,53,medial,36
38
+ GP_ant,L,54,medial,37
39
+ thalamus_DA_lat,L,39,medial,38
40
+ thalamus_DP,L,50,medial,39
41
+ thalamus_VP_med,L,35,medial,40
42
+ thalamus_VA_inf_post,L,30,medial,41
43
+ thalamus_VA_inf_ant,L,31,medial,42
44
+ thalamus_DA_med,L,38,medial,43
45
+ thalamus_VA_sup,L,37,medial,44