Coverage for ibllib/atlas/plots.py: 76%
29 statements
« prev ^ index » next coverage.py v7.5.4, created at 2024-07-08 17:16 +0100
1"""
2Module that has convenience plotting functions for 2D atlas slices and flatmaps.
3"""
5import iblatlas.plots as atlas_plots
6from ibllib.atlas import deprecated_decorator
9@deprecated_decorator
10def prepare_lr_data(acronyms_lh, values_lh, acronyms_rh, values_rh):
11 """
12 Prepare data in format needed for plotting when providing different region values per hemisphere
14 :param acronyms_lh: array of acronyms on left hemisphere
15 :param values_lh: values for each acronym on left hemisphere
16 :param acronyms_rh: array of acronyms on right hemisphere
17 :param values_rh: values for each acronym on left hemisphere
18 :return: combined acronyms and two column array of values
19 """
21 return atlas_plots.prepare_lr_data(acronyms_lh, values_lh, acronyms_rh, values_rh) 1b
24@deprecated_decorator
25def reorder_data(acronyms, values, brain_regions=None):
26 """
27 Reorder list of acronyms and values to match the Allen ordering.
29 TODO Document more
31 Parameters
32 ----------
33 acronyms : array_like of str
34 The acronyms to match the Allen ordering, whatever that means.
35 values : array_like
36 An array of some sort of values I guess...
37 brain_regions : ibllib.atlas.regions.BrainRegions
38 A brain regions object.
40 Returns
41 -------
42 numpy.array of str
43 An ordered array of acronyms
44 numpy.array
45 An ordered array of values. I don't know what those values are, not IDs, so maybe indices?
46 """
48 return atlas_plots.reorder_data(acronyms, values, brain_regions=brain_regions) 1c
51@deprecated_decorator
52def plot_scalar_on_slice(regions, values, coord=-1000, slice='coronal', mapping=None, hemisphere='left',
53 background='image', cmap='viridis', clevels=None, show_cbar=False, empty_color='silver',
54 brain_atlas=None, ax=None, vector=False, slice_files=None, **kwargs):
55 """
56 Function to plot scalar value per region on histology slice.
58 Parameters
59 ----------
60 regions : array_like
61 An array of brain region acronyms.
62 values : numpy.array
63 An array of scalar value per acronym. If hemisphere is 'both' and different values want to
64 be shown on each hemisphere, values should contain 2 columns, 1st column for LH values, 2nd
65 column for RH values.
66 coord : float
67 Coordinate of slice in um (not needed when slice='top').
68 slice : {'coronal', 'sagittal', 'horizontal', 'top'}, default='coronal'
69 Orientation of slice.
70 mapping : str, optional
71 Atlas mapping to use, options are depend on atlas used (see `ibllib.atlas.BrainRegions`).
72 If None, the atlas default mapping is used.
73 hemisphere : {'left', 'right', 'both'}, default='left'
74 The hemisphere to display.
75 background : {image', 'boundary'}, default='image'
76 Background slice to overlay onto, options are 'image' or 'boundary'. If `vector` is false,
77 this argument is ignored.
78 cmap: str, default='viridis'
79 Colormap to use.
80 clevels : array_like
81 The min and max color levels to use.
82 show_cbar: bool, default=False
83 Whether to display a colorbar.
84 empty_color : str, default='silver'
85 Color to use for regions without any values (only used when `vector` is true).
86 brain_atlas : ibllib.atlas.AllenAtlas
87 A brain atlas object.
88 ax : matplotlib.pyplot.Axes
89 An axis object to plot onto.
90 vector : bool, default=False
91 Whether to show as bitmap or vector graphic.
92 slice_files: numpy.array
93 The set of vectorised slices for this slice, obtained using `load_slice_files(slice, mapping)`.
94 **kwargs
95 Set of kwargs passed into matplotlib.patches.Polygon, e.g. linewidth=2, edgecolor='None'
96 (only used when vector = True).
98 Returns
99 -------
100 fig: matplotlib.figure.Figure
101 The plotted figure.
102 ax: matplotlib.pyplot.Axes
103 The plotted axes.
104 cbar: matplotlib.pyplot.colorbar, optional
105 matplotlib colorbar object, only returned if show_cbar=True.
106 """
108 return (atlas_plots.plot_scalar_on_slice(regions, values, coord=coord, slice=slice, mapping=mapping,
109 hemisphere=hemisphere, background=background, cmap=cmap, clevels=clevels,
110 show_cbar=show_cbar, empty_color=empty_color, brain_atlas=brain_atlas,
111 ax=ax, vector=vector, slice_files=slice_files, **kwargs))
114@deprecated_decorator
115def plot_scalar_on_flatmap(regions, values, depth=0, flatmap='dorsal_cortex', mapping='Allen', hemisphere='left',
116 background='boundary', cmap='viridis', clevels=None, show_cbar=False, flmap_atlas=None, ax=None):
117 """
118 Function to plot scalar value per allen region on flatmap slice
120 :param regions: array of acronyms of Allen regions
121 :param values: array of scalar value per acronym. If hemisphere is 'both' and different values want to be shown on each
122 hemispheres, values should contain 2 columns, 1st column for LH values, 2nd column for RH values
123 :param depth: depth in flatmap in um
124 :param flatmap: name of flatmap (currently only option is 'dorsal_cortex')
125 :param mapping: atlas mapping to use, options are 'Allen', 'Beryl' or 'Cosmos'
126 :param hemisphere: hemisphere to display, options are 'left', 'right', 'both'
127 :param background: background slice to overlay onto, options are 'image' or 'boundary'
128 :param cmap: colormap to use
129 :param clevels: min max color levels [cmin, cmax]
130 :param show_cbar: whether to add colorbar to axis
131 :param flmap_atlas: FlatMap object
132 :param ax: optional axis object to plot on
133 :return:
134 """
136 return atlas_plots.plot_scalar_on_slice(regions, values, depth=depth, flatmap=flatmap, mapping=mapping,
137 hemisphere=hemisphere, background=background, cmap=cmap, clevels=clevels,
138 show_cbar=show_cbar, flmap_atlas=flmap_atlas, ax=ax)
141@deprecated_decorator
142def plot_volume_on_slice(volume, coord=-1000, slice='coronal', mapping='Allen', background='boundary', cmap='Reds',
143 clevels=None, show_cbar=False, brain_atlas=None, ax=None):
144 """
145 Plot slice through a volume
147 :param volume: 3D array of volume (must be same shape as brain_atlas object)
148 :param coord: coordinate of slice in um
149 :param slice: orientation of slice, options are 'coronal', 'sagittal', 'horizontal'
150 :param mapping: atlas mapping to use, options are 'Allen', 'Beryl' or 'Cosmos'
151 :param background: background slice to overlay onto, options are 'image' or 'boundary'
152 :param cmap: colormap to use
153 :param clevels: min max color levels [cmin, cmax]
154 :param show_cbar: whether to add colorbar to axis
155 :param brain_atlas: AllenAtlas object
156 :param ax: optional axis object to plot on
157 :return:
158 """
160 return atlas_plots.plot_volume_on_slice(volume, coord=coord, slice=slice, mapping=mapping, background=background,
161 cmap=cmap, clevels=clevels, show_cbar=show_cbar, brain_atlas=brain_atlas,
162 ax=ax)
165@deprecated_decorator
166def plot_points_on_slice(xyz, values=None, coord=-1000, slice='coronal', mapping='Allen', background='boundary', cmap='Reds',
167 clevels=None, show_cbar=False, aggr='mean', fwhm=100, brain_atlas=None, ax=None):
168 """
169 Plot xyz points on slice. Points that lie in the same voxel within slice are aggregated according to method specified.
170 A 3D Gaussian smoothing kernel with distance specified by fwhm is applied to images.
172 :param xyz: 3 column array of xyz coordinates of points in metres
173 :param values: array of values per xyz coordinates, if no values are given the sum of xyz points in each voxel is
174 returned
175 :param coord: coordinate of slice in um (not needed when slice='top')
176 :param slice: orientation of slice, options are 'coronal', 'sagittal', 'horizontal', 'top' (top view of brain)
177 :param mapping: atlas mapping to use, options are 'Allen', 'Beryl' or 'Cosmos'
178 :param background: background slice to overlay onto, options are 'image' or 'boundary'
179 :param cmap: colormap to use
180 :param clevels: min max color levels [cmin, cmax]
181 :param show_cbar: whether to add colorbar to axis
182 :param aggr: aggregation method. Options are sum, count, mean, std, median, min and max.
183 Can also give in custom function (https://docs.scipy.org/doc/scipy/reference/generated/scipy.stats.binned_statistic.html)
184 :param fwhm: fwhm distance of gaussian kernel in um
185 :param brain_atlas: AllenAtlas object
186 :param ax: optional axis object to plot on
188 :return:
189 """
191 return atlas_plots.plot_points_on_slice(xyz, values=values, coord=coord, slice=slice, mapping=mapping,
192 background=background, cmap=cmap, clevels=clevels, show_cbar=show_cbar,
193 aggr=aggr, fwhm=fwhm, brain_atlas=brain_atlas, ax=ax)
196@deprecated_decorator
197def plot_scalar_on_barplot(acronyms, values, errors=None, order=True, ax=None, brain_regions=None):
198 """
199 Function to plot scalar value per allen region on a bar plot. If order=True, the acronyms and values are reordered
200 according to the order defined in the Allen structure tree
202 Parameters
203 ----------
204 acronyms: numpy.array
205 A 1D array of acronyms
206 values: numpy.array
207 A 1D array of values corresponding to each acronym in the acronyms array
208 errors: numpy.array
209 A 1D array of error values corresponding to each acronym in the acronyms array
210 order: bool, default=True
211 Whether to order the acronyms according to the order defined by the Allen structure tree
212 ax : matplotlib.pyplot.Axes
213 An axis object to plot onto.
214 brain_regions : ibllib.atlas.regions.BrainRegions
215 A brain regions object
217 Returns
218 -------
219 fig: matplotlib.figure.Figure
220 The plotted figure
221 ax: matplotlib.pyplot.Axes
222 The plotted axes.
224 """
226 return atlas_plots.plot_scalar_on_barplot(acronyms, values, errors=errors, order=order, ax=ax,
227 brain_regions=brain_regions)
230@deprecated_decorator
231def plot_swanson_vector(acronyms=None, values=None, ax=None, hemisphere=None, br=None, orientation='landscape',
232 empty_color='silver', vmin=None, vmax=None, cmap='viridis', annotate=False, annotate_n=10,
233 annotate_order='top', annotate_list=None, mask=None, mask_color='w', fontsize=10, **kwargs):
234 """
235 Function to plot scalar value per allen region on the swanson projection. Plots on a vecortised version of the
236 swanson projection
238 Parameters
239 ----------
240 acronyms: numpy.array
241 A 1D array of acronyms or atlas ids
242 values: numpy.array
243 A 1D array of values corresponding to each acronym in the acronyms array
244 ax : matplotlib.pyplot.Axes
245 An axis object to plot onto.
246 hemisphere : {'left', 'right', 'both', 'mirror'}
247 The hemisphere to display.
248 br : ibllib.atlas.BrainRegions
249 A brain regions object.
250 orientation : {landscape', 'portrait'}, default='landscape'
251 The plot orientation.
252 empty_color : str, tuple of int, default='silver'
253 The greyscale matplotlib color code or an RGBA int8 tuple defining the filling of brain
254 regions not provided.
255 vmin: float
256 Minimum value to restrict the colormap
257 vmax: float
258 Maximum value to restrict the colormap
259 cmap: string
260 matplotlib named colormap to use
261 annotate : bool, default=False
262 If true, labels the regions with acronyms.
263 annotate_n: int
264 The number of regions to annotate
265 annotate_order: {'top', 'bottom'}
266 If annotate_n is specified, whether to annotate the n regions with the highest (top) or lowest (bottom) values
267 annotate_list: numpy.array of list
268 List of regions to annotate, if this is provided, if overwrites annotate_n and annotate_order
269 mask: numpy.array or list
270 List of regions to apply a mask to (fill them with a specific color)
271 mask_color: string, tuple or list
272 Color for the mask
273 fontsize : int
274 The annotation font size in points.
275 **kwargs
276 See plot_polygon and plot_polygon_with_hole.
278 Returns
279 -------
280 matplotlib.pyplot.Axes
281 The plotted axes.
283 """
285 return atlas_plots.plot_swanson_vector(acronyms=acronyms, values=values, ax=ax, hemisphere=hemisphere, br=br,
286 orientation=orientation, empty_color=empty_color, vmin=vmin, vmax=vmax,
287 cmap=cmap, annotate=annotate, annotate_n=annotate_n,
288 annotate_order=annotate_order, annotate_list=annotate_list, mask=mask,
289 mask_color=mask_color, fontsize=fontsize, **kwargs)
292@deprecated_decorator
293def plot_swanson(acronyms=None, values=None, ax=None, hemisphere=None, br=None,
294 orientation='landscape', annotate=False, empty_color='silver', **kwargs):
295 """
296 Displays the 2D image corresponding to the swanson flatmap.
298 This case is different from the others in the sense that only a region maps to another regions,
299 there is no correspondence to the spatial 3D coordinates.
301 Parameters
302 ----------
303 acronyms: numpy.array
304 A 1D array of acronyms or atlas ids
305 values: numpy.array
306 A 1D array of values corresponding to each acronym in the acronyms array
307 ax : matplotlib.pyplot.Axes
308 An axis object to plot onto.
309 hemisphere : {'left', 'right', 'both', 'mirror'}
310 The hemisphere to display.
311 br : ibllib.atlas.BrainRegions
312 A brain regions object.
313 orientation : {landscape', 'portrait'}, default='landscape'
314 The plot orientation.
315 empty_color : str, tuple of int, default='silver'
316 The greyscale matplotlib color code or an RGBA int8 tuple defining the filling of brain
317 regions not provided.
318 vmin: float
319 Minimum value to restrict the colormap
320 vmax: float
321 Maximum value to restrict the colormap
322 cmap: string
323 matplotlib named colormap to use
324 annotate : bool, default=False
325 If true, labels the regions with acronyms.
326 **kwargs
327 See matplotlib.pyplot.imshow.
329 Returns
330 -------
331 matplotlib.pyplot.Axes
332 The plotted axes.
333 """
335 return atlas_plots.plot_swanson(acronyms=acronyms, values=values, ax=ax, hemisphere=hemisphere, br=br,
336 orientation=orientation, annotate=annotate, empty_color=empty_color, **kwargs)