Skip to content

plot

group 

group(group, selected_regions, *markers, colors=[], orientation='h', check_regions=True)

Scatter plot of AnimalGroup data in the selected brain regions.

Parameters:

  • group : AnimalGroup

    The data of a cohort to plot.

  • selected_regions : list[str] | np.ndarray[str]

    A list of the brain regions picked to plot.

  • *markers : str, default= ()

    The marker(s) to plot the data of. If not specified, it plots all markers in group.

  • colors : Iterable, default= []

    The list of colours used to identify each marker.

  • orientation : str, default= 'h'

    'h' for horizontal scatter plots; 'v' for vertical scatter plots.

  • check_regions : bool, default= True

    If False, it does not check whether group contains all selected_regions. If data for a region is missing, it will display an empty scatter.

Returns:

Raises:

  • ValueError –

    If group has data split between left and right hemisphere.

  • ValueError –

    If you didn't specify a colour for one of the markers chosen to display.

  • KeyError –

    If at least one region in selected_regions is missing from group.

pie_ontology 

pie_ontology(brain_ontology, selected_regions, use_acronyms=True, hole=0.3, line_width=2, text_size=12)

Pie plot of the major divisions weighted on the number of corresponding selected subregions.

Parameters:

  • brain_ontology : AllenBrainOntology

    The brain region ontology used to gather the major divisions of each brain area.

  • selected_regions : Collection[str]

    The selected subregions counted by major division.

  • use_acronyms : bool, default= True

    If True, it displays brain region names as acronyms. If False, it uses their full name.

  • hole : float, default= 0.3

    The size of the hole in the pie chart. Must be between 0 and 1.

  • line_width : float, default= 2

    The thickness of pie's slices.

  • text_size : float, default= 12

    The size of the brain region names.

Returns:

See also

braian.AllenBrainOntology.get_corresponding_md

above_threshold 

above_threshold(brains, threshold, regions, width=700, height=500)

Scatter plot of the regions above a threshold. Usually used together with SliceMetrics.CVAR.

Parameters:

  • brains : Experiment | AnimalGroup | Sequence[AnimalBrain]

    The brains from where to get the data.

  • threshold : float

    The threshold above which a brain region is displayed.

  • regions : Sequence[str]

    The names of the brain regions to filter from.

  • width : int, default= 700

    The width of the plot.

  • height : int, default= 500

    The height of the plot.

Returns:

slice_density 

slice_density(brains, regions, width=700, height=500)

Scatter plot of the sections' density.

Parameters:

  • brains : SlicedExperiment | SlicedGroup | Sequence[SlicedBrain]

    The brains from where to get the data.

  • regions : Collection

    The regions to plot. If the data of brains is split between left and right hemisphere, you can pass, for example, both "Left: Isocortex" and "Right: Isocortex".

  • width : int, default= 700

    The width of the plot.

  • height : int, default= 500

    The height of the plot.

Returns:

region_scores 

region_scores(scores, brain_ontology, title=None, title_size=20, regions_size=15, use_acronyms=True, use_acronyms_in_mjd=True, mjd_opacity=0.5, thresholds=None, width=800, barheight=30, bargap=0.3, bargroupgap=0.0)

Bar plot of the given regions' scores, visually grouped by the major divisions of the given brain_ontology.

Parameters:

  • scores : pd.Series

    A series of scores for each brain region, where each brain region is represented by its acronym and it is the index of the scores.

  • brain_ontology : AllenBrainOntology

    The brain region ontology used to gather the major divisions of each brain area.

  • title : str, default= None

    The title of the plot.

  • title_size : int, default= 20

    The size of the title.

  • regions_size : int, default= 15

    The size of each brain region name.

  • use_acronyms : bool, default= True

    If True, it uses the acronym of the brain regions instead of their full name.

  • use_acronyms_in_mjd : bool, default= True

    If True, it uses the acronym of the major divisions instead of their full name.

  • mjd_opacity : float, default= 0.5

    The amount of opacity used for the background of bar plot, delimiting each major division.

  • thresholds : float | Collection[float], default= None

    If specified, it plots a vertical dotted line at the given value.

  • width : int, default= 800

    The width of the plot.

Returns:

  • –

    A Plotly figure.

See also

braian.AllenBrainOntology.get_corresponding_md

heatmap 

heatmap(bd1, brain_regions, bd2=None, orientation='frontal', depth=None, n=10, highlighted_regions=None, cmin=None, cmax=None, cmap='magma_r', centered_cmap=False, ccenter=0, show_acronyms=False, title=None, ticks=None, ticks_labels=None, output_path=None, filename=None)

Plots the heatmaps of the given BrainData onto a 2D representation of the brain delimited by the desired regions.

Parameters:

  • bd1 : BrainData

    The brain data to plot.

  • brain_regions : list[str]

    The brain regions to be displayed in the 2D.

  • bd2 : BrainData, default= None

    If specified, it splits the heatmap in two hemispheres and plots bd1 on the left hemishpere, and bd2 on the right hemisphere.

  • orientation : str, default= 'frontal'

    The orientation at which the 3D brain is cut into 2D sections. It can be either "frontal", "sagittal" or "horizontal".

  • depth : int | Sequence[int], default= None

    The depth, in µm along the orientation, at which to cut the brain and produce the corresponding heatmap. If a sequence of depths is given, it produces multiple heatmaps.

  • n : int, default= 10

    If depth is not specified, it defines the number of equidistant heatmaps to plot by sectioning the brain along orientation.

  • highlighted_regions : Sequence[str] | tuple[Sequence[str]], default= None

    If specified, it draws a thicker outlines on the regions correspoding to the given acronyms. If bd2 is also specified, it can also be a tuple of two lists, one for each hemisphere.

  • cmin : float, default= None

    The lowerbound value for the heatmap.

  • cmax : float, default= None

    The upperbound value for the heatmap.

  • cmap : str | mpl.colors.Colormap, default= 'magma_r'

    The colormap used for the heatmap.

  • centered_cmap : bool, default= False

    If True, it uses a linear colormap that spans from red to blue, with white being the neutral/middle color.

  • ccenter : float, default= 0

    If centered_cmap=True, it sets the white color to the specified value, even if the distance from ccenter of cmin and cmax differs.

  • show_acronyms : bool, default= False

    If True, it overlays the acronym over each brain region in the heatmap.

  • title : str, default= None

    The title of the figure.

  • ticks : Sequence[float], default= None

    If specified, it adds additional ticks to the colormap in the legend of the figure.
    This option may be useful to show to which values specific colors correspond to.

  • ticks_labels : Sequence[str], default= None

    If specified, it set a name to the corresponding ticks.

  • output_path : Path | str, default= None

    If specified, it saves all the resulting heatmaps in the given location. It no folder exists at the given location, it creates it.

  • filename : str, default= None

    The name used as prefix for each heatmap SVG file saved into output_path.

Returns:

  • mpl.figure.Figure | dict[int, mpl.figure.Figure] –

    A matplotlib figure.
    If n>1 or depth is a collection of depths, it returns a dictionary where the key is the depth and the value the corresponding matplotlib figure.

hierarchy 

hierarchy(brain_ontology)

Plots the ontology as a tree.

Returns:

draw_edges 

draw_edges(G, layout, width)

Draws a plotly Line plot of the given graph G, based on the given layout. If G is a directed graph, it the drawn edges are arrows

Parameters:

  • G : ig.Graph

    A graph

  • layout : ig.Layout

    The layout used to position the nodes of the graph G

  • width : int

    The width of the edges' lines

Returns:

draw_nodes 

draw_nodes(G, layout, brain_ontology, node_size, outline_size=0.5, use_centrality=False, centrality_metric=None, use_clustering=False, metrics={'degree': ig.VertexSeq.degree})

Draws a plotly Scatter plot of the given graph G, based on the given layout.

Parameters:

  • G : ig.Graph

    A graph

  • layout : ig.Layout

    The layout used to position the nodes of the graph G

  • brain_ontology : braian.AllenBrainOntology

    TODO: missing

  • node_size : int

    The size of the region nodes

  • outline_size : float, default= 0.5

    the size of the region nodes' outlines

  • use_centrality : bool, default= False

    If true, it colors the regions nodes based on the attribute defined in centrality_metric of each G vertex If false, it uses the corresponding brain region color.

  • centrality_metric : str, default= None

    The name of the attribute used if use_centrality=True

  • use_clustering : bool, default= False

    If true, it colors the regions nodes outlines based on the cluster attribute of each G vertex If false, it uses the corresponding brain region color.

  • metrics : dict[str, Callable[[ig.VertexSeq], Iterable[float]]], default= {'degree': ig.VertexSeq.degree}

    A dictionary that defines M additional information for the vertices of graph G. The keys are title of an additional metric, while the values are functions that take a igraph.VertexSeq and spits a value for each vertex.

Returns:

Raises:

  • ValueError –

    If use_centrality=True, but the vertices of G have no attribute as defined in centrality_metric

  • ValueError –

    If use_clustering=True, but the vertices of G have no cluster attribute

permutation 

permutation(pls, component=1)

Plots the result of PLS.random_permutation(). It shows how much the product of the given partial least square analysis is a result of pure chance.

Parameters:

  • pls : bas.PLS

    An instance of a mean-centered task partial least square analysis.

  • component : int, default= 1

    The component of the PLS for which to plot the permutation.

Returns:

See also

PLS.n_components

groups_salience 

groups_salience(pls, component=1)

Bar plot of the salience scores of each group in the PLS.

Parameters:

  • pls : bas.PLS

    An instance of a mean-centered task partial least square analysis.

  • component : int, default= 1

    The component of the PLS for which to plot the permutation.

Returns:

See also

PLS.n_components

latent_variable 

latent_variable(pls, of='X', width=800, height=800)

PCA-like plot of brain scores or group scores of a PLS. This might help see how animals or groups are discernable from each other.

It always plots the first component on the x-axis and the second component on the y-axis.

Parameters:

  • pls : bas.PLS

    An instance of a mean-centered task partial least square analysis.

  • of : str, default= 'X'

    If "X", it plots the brain scores. If "Y", it plots the group scores.

  • width : int, default= 800

    The width of the plot.

  • height : int, default= 800

    The height of the plot.

Returns:

xmas_tree 

xmas_tree(groups, selected_regions, marker1, marker2=None, brain_ontology=None, pls_n_permutation=None, pls_n_bootstrap=None, pls_threshold=None, pls_seed=None, markers_salience_scores=None, plot_scatter=True, scatter_width=0.7, space_between_markers=0.02, groups_marker1_colours=['LightCoral', 'SandyBrown'], groups_marker2_colours=['IndianRed', 'Orange'], max_value=None, color_heatmap='deep_r', width=None, height=None)

Plots the XMasTree of the given data. This is a visualisation of whole-brain data from multiple groups in a way that is comprehensive and complete.

The data is divided in two main plots: a heatmap (the trunk) and a scatter plot (the leaves and the xmas baubles). Both are aligned on the y-axis so that each row represents the data of a brain region across animals, groups and markers.

If pls_n_permutation and pls_n_bootstrap—or, alternatively, markers_salience_scores—are specified, it dims out the brain regions that are not salient in a partial least squared analysis between the given groups. it is only supported when there are only two groups.

Parameters:

  • groups : Experiment | Collection[AnimalGroup]

    The groups to display in the plot.

  • selected_regions : Collection[str]

    The acronyms of the brain regions shown in the plot.
    If brain_ontology is not given, selecting any missing region from the groups data will result in an error.

  • marker1 : str

    The name of the marker's data to plot.

  • marker2 : str, default= None

    If specified, the name of the second marker's data to plot.

  • brain_ontology : AllenBrainOntology, default= None

    If specified, the selected_regions are checked against the ontology and sorted by major divisions. If a brain region is missing from groups but present in selected_regions, it is shown with all-NA values.

  • pls_n_permutation : int, default= None

    If specified, it corresponds to the parameter used for defining how generizable the salience scores are.

  • pls_n_bootstrap : int, default= None

    If specified, it corresponds to the parameter used for finding the stable regions.

  • pls_threshold : float, default= None

    The threshold used on the salience scores to define which regions are salient and which ones are not.
    If not specified, it applies a threshold of \(~1.96\).

  • pls_seed : int, default= None

    The random seed used for PLS's permutation and bootstrap operations. If specified, the salient regions are always deterministic.

  • markers_salience_scores : dict[str, BrainData], default= None

    The salience scores computed on marker1 and, eventually, marker2.
    If specified, it does not use pls_n_permutation and pls_bootstrap parmeters and select the brain regions to dim out based on this dictonary.

  • plot_scatter : bool, default= True

    If False, it does not plot the scatter plot of the brain regions' values for each animal. It only plots the mean of the whole group.

  • scatter_width : float, default= 0.7

    The ratio of the whole plot's width dedicated to the scatter plot. The remaining 1-scatter_width is occupied by the heatmap.

  • space_between_markers : float, default= 0.02

    The retio of the whole plot's width dedicated to the gap between markers and used to specify the major divisions.
    If marker2 and brain_ontology are not specified, it is not used.

  • groups_marker1_colours : Sequence, default= ['LightCoral', 'SandyBrown']

    The list of colours used to identify marker1 scatter data of each group.

  • groups_marker2_colours : Sequence, default= ['IndianRed', 'Orange']

    The list of colours used to identify marker2 scatter data of each group.

  • max_value : int, default= None

    If specified, it caps the visualization of the brain data to this value.

  • color_heatmap : str, default= 'deep_r'

    The colormap used to display the data in the heatmap.

  • width : int, default= None

    The width of the plot.

  • height : int, default= None

    The height of the plot.

Returns: