plot_tools

A set of convenience functions used for producing plots in dabest.

add_counts_to_prop_plots

 add_counts_to_prop_plots (plot_data:pandas.core.frame.DataFrame,
                           xvar:str, yvar:str,
                           rawdata_axes:matplotlib.axes._axes.Axes,
                           horizontal:bool, is_paired:bool,
                           prop_sample_counts_kwargs:dict)

Add counts to the proportion plots.

	Type	Details
plot_data	DataFrame	Dataframe of the plot data.
xvar	str	Column name of the x variable.
yvar	str	Column name of the y variable.
rawdata_axes	Axes	Matplotlib axis object to plot on.
horizontal	bool	If the plot is horizontal.
is_paired	bool	Whether the data is paired.
prop_sample_counts_kwargs	dict	Keyword arguments for the sample counts.

source

table_for_horizontal_plots

 table_for_horizontal_plots (effectsize_df:object,
                             ax:matplotlib.axes._axes.Axes,
                             contrast_axes:matplotlib.axes._axes.Axes,
                             ticks_to_plot:list, show_mini_meta:bool,
                             show_delta2:bool, table_kwargs:dict,
                             ticks_to_skip:list)

Add table axes for showing the deltas for horizontal plots.

	Type	Details
effectsize_df	object	Effect size DABEST object.
ax	Axes	Matplotlib axis object to plot the table axes.
contrast_axes	Axes	Matplotlib axis object to plot the contrast axes.
ticks_to_plot	list	List of indices of the contrast objects.
show_mini_meta	bool	Whether to show the mini meta-analysis.
show_delta2	bool	Whether to show the delta-delta.
table_kwargs	dict	Keyword arguments for the table.
ticks_to_skip	list

source

barplotter

 barplotter (xvar:str, yvar:str, all_plot_groups:list,
             rawdata_axes:matplotlib.axes._axes.Axes,
             plot_data:pandas.core.frame.DataFrame, raw_colors:str,
             plot_palette_raw:dict, color_col:str, barplot_kwargs:dict,
             horizontal:bool)

Add bars to the raw data plot.

	Type	Details
xvar	str	Column name of the x variable.
yvar	str	Column name of the y variable.
all_plot_groups	list	List of all plot groups.
rawdata_axes	Axes	Matplotlib axis object to plot on.
plot_data	DataFrame	Dataframe of the plot data.
raw_colors	str	Color of the bar.
plot_palette_raw	dict	Dictionary of colors used in the bar plot.
color_col	str	Column name of the color column.
barplot_kwargs	dict	Keyword arguments for the barplot.
horizontal	bool	If the plot is horizontal.

source

gridkey_plotter

 gridkey_plotter (is_paired:bool, idx:list, all_plot_groups:list,
                  gridkey:list, rawdata_axes:matplotlib.axes._axes.Axes,
                  contrast_axes:matplotlib.axes._axes.Axes,
                  plot_data:pandas.core.frame.DataFrame, xvar:str,
                  yvar:str, results:pandas.core.frame.DataFrame,
                  show_delta2:bool, show_mini_meta:bool, x1_level:list,
                  experiment_label:list, float_contrast:bool,
                  horizontal:bool, delta_delta:object, mini_meta:object,
                  effect_size:str, gridkey_kwargs:dict)

Add gridkey to the contrast plot.

	Type	Details
is_paired	bool	Whether the data is paired.
idx	list	List of indices of the contrast objects.
all_plot_groups	list	List of all plot groups.
gridkey	list	List of gridkey rows.
rawdata_axes	Axes	Matplotlib axis object for the raw data.
contrast_axes	Axes	Matplotlib axis object for the contrast data.
plot_data	DataFrame	Dataframe of the plot data.
xvar	str	Column name of the x variable.
yvar	str	Column name of the y variable.
results	DataFrame	Dataframe of contrast object comparisons.
show_delta2	bool	Whether to show the delta-delta.
show_mini_meta	bool	Whether to show the mini meta-analysis.
x1_level	list	List of x1 levels.
experiment_label	list	List of experiment labels.
float_contrast	bool	Whether the DABEST plot uses Gardner-Altman or Cummings
horizontal	bool	If the plot is horizontal.
delta_delta	object	delta-delta object.
mini_meta	object	Mini meta-analysis object.
effect_size	str	Type of effect size to plot
gridkey_kwargs	dict	Keyword arguments for the gridkey.

source

effect_size_curve_plotter

 effect_size_curve_plotter (ticks_to_plot:list,
                            ticks_for_baseline_ec:list,
                            results:pandas.core.frame.DataFrame,
                            ci_type:str,
                            contrast_axes:matplotlib.axes._axes.Axes,
                            contrast_kwargs:dict,
                            bootstraps_color_by_group:bool,
                            plot_palette_contrast:dict, horizontal:bool,
                            contrast_marker_kwargs:dict,
                            contrast_errorbar_kwargs:dict, idx:list,
                            is_paired:bool, contrast_paired_lines:bool,
                            contrast_paired_lines_kwargs:dict,
                            show_baseline_ec:bool=False)

Add effect size curves to the contrast plot.

	Type	Default	Details
ticks_to_plot	list		List of indices of the contrast objects.
ticks_for_baseline_ec	list		List of indices of the baseline effect curve objects.
results	DataFrame		Dataframe of contrast object comparisons.
ci_type	str		Type of confidence interval to plot.
contrast_axes	Axes		Matplotlib axis object to plot on.
contrast_kwargs	dict		Keyword arguments for the violinplot.
bootstraps_color_by_group	bool		Whether to color the bootstraps by group.
plot_palette_contrast	dict		Dictionary of colors used in the contrast plot.
horizontal	bool		If the plot is horizontal.
contrast_marker_kwargs	dict
contrast_errorbar_kwargs	dict
idx	list		List of indices of the raw groups.
is_paired	bool		Whether the data is paired.
contrast_paired_lines	bool		Whether to add lines for repeated measures data.
contrast_paired_lines_kwargs	dict		Keyword arguments for the repeated measures lines.
show_baseline_ec	bool	False	Whether to show the baseline effect curve.

source

plot_minimeta_or_deltadelta_violins

 plot_minimeta_or_deltadelta_violins (dabest_obj:object, type:str,
                                      ci_type:str, rawdata_axes:matplotlib
                                      .axes._axes.Axes, contrast_axes:matp
                                      lotlib.axes._axes.Axes,
                                      contrast_kwargs:dict,
                                      contrast_xtick_labels:list,
                                      effect_size:str, plot_kwargs:dict,
                                      horizontal:bool, show_pairs:bool,
                                      contrast_marker_kwargs:dict,
                                      contrast_errorbar_kwargs:dict)

Add mini meta-analysis or delta-delta violin plots to the contrast plot.

	Type	Details
dabest_obj	object	DABEST Effectsize object delta-delta or mini_meta
type	str
ci_type	str	Type of confidence interval to plot.
rawdata_axes	Axes	Matplotlib axis object to plot on.
contrast_axes	Axes	Matplotlib axis object to plot on.
contrast_kwargs	dict	Keyword arguments for the violinplot.
contrast_xtick_labels	list	List of xtick labels for the contrast plot.
effect_size	str	Type of effect size to plot.
plot_kwargs	dict	Keyword arguments for the plot.
horizontal	bool	If the plot is horizontal.
show_pairs	bool	Whether the data is paired and shown in pairs.
contrast_marker_kwargs	dict
contrast_errorbar_kwargs	dict

source

slopegraph_plotter

 slopegraph_plotter (dabest_obj:object,
                     plot_data:pandas.core.frame.DataFrame, xvar:str,
                     yvar:str, color_col:str, plot_palette_raw:dict,
                     slopegraph_kwargs:dict,
                     rawdata_axes:matplotlib.axes._axes.Axes,
                     ytick_color:str, temp_idx:list, horizontal:bool,
                     temp_all_plot_groups:list, plot_kwargs:dict)

Add slopegraph to the rawdata axes.

	Type	Details
dabest_obj	object	DABEST object.
plot_data	DataFrame	Dataframe of the plot data.
xvar	str	Column name of the x variable.
yvar	str	Column name of the y variable.
color_col	str	Column name of the color column.
plot_palette_raw	dict	Dictionary of colors used in the plot.
slopegraph_kwargs	dict	Keyword arguments for the slopegraph.
rawdata_axes	Axes	Matplotlib axis object to plot on.
ytick_color	str	Color of the yticks.
temp_idx	list	List of indices of the contrast objects.
horizontal	bool	If the plotting will be in horizontal format.
temp_all_plot_groups	list	List of all plot groups.
plot_kwargs	dict	Keyword arguments for the plot.

source

delta_dots_plotter

 delta_dots_plotter (plot_data:pandas.core.frame.DataFrame,
                     contrast_axes:matplotlib.axes._axes.Axes,
                     delta_id_col:str, idx:list, xvar:str, yvar:str,
                     is_paired:bool, color_col:str, float_contrast:bool,
                     plot_palette_raw:dict, delta_dot_kwargs:dict,
                     horizontal:bool)

	Type	Details
plot_data	DataFrame	Dataframe of the plot data.
contrast_axes	Axes	Matplotlib axis object to plot on.
delta_id_col	str	Column name of the delta id column.
idx	list	List of indices of the contrast objects.
xvar	str	Column name of the x variable.
yvar	str	Column name of the y variable.
is_paired	bool	Whether the data is paired.
color_col	str	Column name of the color column.
float_contrast	bool	Whether the DABEST plot uses Gardner-Altman or Cummings
plot_palette_raw	dict	Dictionary of colors used in the plot.
delta_dot_kwargs	dict	Keyword arguments for the delta dots.
horizontal	bool	If the rawplot is horizontal.

source

delta_text_plotter

 delta_text_plotter (results:pandas.core.frame.DataFrame,
                     ax_to_plot:object, ticks_to_plot:list,
                     delta_text_kwargs:dict, color_col:str,
                     plot_palette_raw:dict, show_pairs:bool,
                     float_contrast:bool, extra_delta:float)

Add delta text to the contrast plot.

	Type	Details
results	DataFrame	Dataframe of contrast object comparisons.
ax_to_plot	object	Matplotlib axis object to plot on.
ticks_to_plot	list	List of indices of the contrast objects.
delta_text_kwargs	dict	Keyword arguments for the delta text.
color_col	str	Column name of the color column.
plot_palette_raw	dict	Dictionary of colors used in the plot.
show_pairs	bool	Whether the data is paired and show pairs.
float_contrast	bool	Whether the DABEST plot uses Gardner-Altman or Cummings.
extra_delta	float	The extra mini-meta or delta-delta value if applicable.

source

add_bars_to_plot

 add_bars_to_plot (bar_dict:dict, ax:matplotlib.axes._axes.Axes,
                   bar_kwargs:dict)

Add bars to the relevant axes.

	Type	Details
bar_dict	dict	Dictionary of bar values.
ax	Axes	Matplotlib axis object to plot on.
bar_kwargs	dict	Keyword arguments for the bars.

source

sankeydiag

 sankeydiag (data:pandas.core.frame.DataFrame, xvar:str, yvar:str,
             temp_all_plot_groups:list, idx:list, temp_idx:list,
             left_labels:list=None, right_labels:list=None,
             palette:str|dict=None, ax=None, flow:bool=True,
             sankey:bool=True, one_sankey:bool=False, width:float=0.4,
             right_color:bool=False, align:str='center', alpha:float=0.65,
             horizontal:bool=False, **kwargs)

Read in melted pd.DataFrame, and draw multiple sankey diagram on a single axes using the value in column yvar according to the value in column xvar left_idx in the column xvar is on the left side of each sankey diagram right_idx in the column xvar is on the right side of each sankey diagram

	Type	Default	Details
data	DataFrame
xvar	str		x column to be plotted.
yvar	str		y column to be plotted.
temp_all_plot_groups	list
idx	list
temp_idx	list
left_labels	list	None	labels for the left side of the diagram. The diagram will be sorted by these labels.
right_labels	list	None	labels for the right side of the diagram. The diagram will be sorted by these labels.
palette	str \| dict	None
ax	NoneType	None	matplotlib axes to be drawn on
flow	bool	True	if True, draw the sankey in a flow, else draw 1 vs 1 Sankey diagram for each group comparison
sankey	bool	True	if True, draw the sankey diagram, else draw barplot
one_sankey	bool	False	determined by the driver function on plotter.py, if True, draw the sankey diagram across the whole raw data axes
width	float	0.4	the width of each sankey diagram
right_color	bool	False	if True, each strip of the diagram will be colored according to the corresponding left labels
align	str	center	the alignment of each sankey diagram, can be ‘center’ or ‘left’
alpha	float	0.65	the transparency of each strip
horizontal	bool	False	if True, the horizontal format for the sankey diagram will be used
kwargs	VAR_KEYWORD

source

single_sankey

 single_sankey (left:<built-infunctionarray>, right:<built-
                infunctionarray>, xpos:float=0, left_weight:<built-
                infunctionarray>=None, right_weight:<built-
                infunctionarray>=None, colorDict:dict=None,
                left_labels:list=None, right_labels:list=None, ax=None,
                flow:bool=True, sankey:bool=True, width=0.5, alpha=0.65,
                bar_width=0.2, error_bar_on:bool=True, strip_on:bool=True,
                one_sankey:bool=False, right_color:bool=False,
                align:str='center', horizontal:bool=False)

*Make a single Sankey diagram showing proportion flow from left to right

Original code from: https://github.com/anazalea/pySankey

Changes are added to normalize each diagram’s height to be 1*

	Type	Default	Details
left	array		data on the left of the diagram
right	array		data on the right of the diagram, len(left) == len(right)
xpos	float	0	the starting point on the x-axis
left_weight	array	None	weights for the left labels, if None, all weights are 1
right_weight	array	None	weights for the right labels, if None, all weights are corresponding left_weight
colorDict	dict	None	input format: {‘label’: ‘color’}
left_labels	list	None	labels for the left side of the diagram. The diagram will be sorted by these labels.
right_labels	list	None	labels for the right side of the diagram. The diagram will be sorted by these labels.
ax	NoneType	None	matplotlib axes to be drawn on
flow	bool	True	if True, draw the sankey in a flow, else draw 1 vs 1 Sankey diagram for each group comparison
sankey	bool	True	if True, draw the sankey diagram, else draw barplot
width	float	0.5
alpha	float	0.65
bar_width	float	0.2
error_bar_on	bool	True	if True, draw error bar for each group comparison
strip_on	bool	True	if True, draw strip for each group comparison
one_sankey	bool	False	if True, only draw one sankey diagram
right_color	bool	False	if True, each strip of the diagram will be colored according to the corresponding left labels
align	str	center	if ‘center’, the diagram will be centered on each xtick, if ‘edge’, the diagram will be aligned with the left edge of each xtick
horizontal	bool	False	if True, the horizontal format for the sankey diagram will be used

source

width_determine

 width_determine (labels, data, pos='left')

*Calculates normalized width positions for a set of labels based on their associated data.

This function is designed to determine width positions for plotting or graphical representation. It takes into account the cumulative weight of each label in the data and adjusts their positions accordingly. The function allows for adjusting the position of labels to either the ‘left’ or ‘right’.

Parameters: labels (list): A list of labels whose width positions are to be calculated. data (DataFrame): A pandas DataFrame containing the data used for calculating width positions. The DataFrame should have columns corresponding to the ‘pos’ and ‘posWeight’. pos (str, optional): The position of labels. It can be either ‘left’ or ‘right’. Defaults to ‘left’.

Returns: defaultdict: A dictionary where each key is a label and the value is another dictionary with keys ‘bottom’, ‘top’, and ‘pos’, representing the calculated width positions.

Note: The function assumes that the data DataFrame contains columns named after the value of ‘pos’ and an additional column named ‘posWeight’ which represents the weight of each label.*

source

normalize_dict

 normalize_dict (nested_dict, target)

*Normalizes the values in a nested dictionary based on a target dictionary.

This function iterates through a nested dictionary, calculates the sum of values for each key across all sub-dictionaries, and then normalizes these values according to a target dictionary. The normalization is performed such that the values in each sub-dictionary are proportionally scaled to match the corresponding ‘right’ values in the target dictionary.

Parameters: nested_dict (dict of dict): A nested dictionary where each key maps to another dictionary. The values in these inner dictionaries are subject to normalization. target (dict): A dictionary with the target values for normalization. Each key in nested_dict should have a corresponding key in target, and each target[key] should be a dictionary with a ‘right’ key containing the target normalization value.

Returns: dict: The normalized nested dictionary. The original nested_dict is modified in place.

Note: - If the sum of values for a particular key in nested_dict is zero, the normalized value is set to 0. - If a key in a sub-dictionary of nested_dict does not exist in the target dictionary, the corresponding ‘right’ value from the target dictionary is directly assigned. - The function modifies the input nested_dict in place and also returns it.*

source

check_data_matches_labels

 check_data_matches_labels (labels, data, side:str)

Function to check that the labels and data match in the sankey diagram. And enforce labels and data to be lists. Raises an exception if the labels and data do not match.

	Type	Details
labels		list of input labels
data		Pandas Series of input data
side	str	‘left’ or ‘right’ on the sankey diagram

source

error_bar

 error_bar (data:pandas.core.frame.DataFrame, x:str, y:str,
            type:str='mean_sd', offset:float=0.2, ax=None,
            line_color='black', gap_width_percent=1, pos:list=[0, 1],
            method:str='gapped_lines', horizontal:bool=False,
            **kwargs:dict)

*Function to plot the standard deviations as vertical errorbars. The mean is a gap defined by negative space.

This function combines the functionality of gapped_lines(), proportional_error_bar(), and sankey_error_bar().*

	Type	Default	Details
data	DataFrame		This DataFrame should be in ‘long’ format.
x	str		x column to be plotted.
y	str		y column to be plotted.
type	str	mean_sd	Choose from [‘mean_sd’, ‘median_quartiles’]. Plots the summary statistics for each group. If ‘mean_sd’, then the mean and standard deviation of each group is plotted as a gapped line. If ‘median_quantiles’, then the median and 25th and 75th percentiles of each group is plotted instead.
offset	float	0.2	Give a single float (that will be used as the x-offset of all gapped lines), or an iterable containing the list of x-offsets.
ax	NoneType	None	If a matplotlib Axes object is specified, the gapped lines will be plotted in order on this axes. If None, the current axes (plt.gca()) is used.
line_color	str	black	The color of the gapped lines.
gap_width_percent	int	1	The width of the gap in the gapped lines, as a percentage of the y-axis span.
pos	list	[0, 1]
method	str	gapped_lines	The method to use for drawing the error bars. Options are: ‘gapped_lines’, ‘proportional_error_bar’, and ‘sankey_error_bar’.
horizontal	bool	False	If True, the error bars will be horizontal. If False, the error bars will be vertical.
kwargs	dict

source

get_swarm_spans

 get_swarm_spans (coll)

Given a matplotlib Collection, will obtain the x and y spans for the collection. Will return None if this fails.

source

halfviolin

 halfviolin (v, half='right', fill_color='k', alpha=1, line_color='k',
             line_width=0)

source

SwarmPlot

 SwarmPlot (data:pandas.core.frame.DataFrame, x:str, y:str,
            ax:matplotlib.axes._axes.Axes, order:List=None, hue:str=None,
            palette:Union[Iterable,str]='black', zorder:float=1,
            size:float=5, side:str='center', jitter:float=1,
            horizontal:bool=False)

Initialize a SwarmPlot instance.

	Type	Default	Details
data	DataFrame		The input data as a pandas DataFrame.
x	str		The column in the DataFrame to be used as the x-axis.
y	str		The column in the DataFrame to be used as the y-axis.
ax	Axes		Matplotlib axes.Axes object for which the plot would be drawn on.
order	List	None	The order in which x-axis categories should be displayed. Default is None.
hue	str	None	The column in the DataFrame that determines the grouping for color. If None (by default), it assumes that it is being grouped by x.
palette	Union	black	The color palette to be used for plotting. Default is “black”.
zorder	float	1	The z-order for drawing the swarm plot wrt other matplotlib drawings. Default is 1.
size	float	5
side	str	center	The side on which points are swarmed (“center”, “left”, or “right”). Default is “center”.
jitter	float	1	Determines the distance between points. Default is 1.
horizontal	bool	False	If True, the swarm plot is drawn horizontally. Default is False.
Returns	None

source

swarmplot

 swarmplot (data:pandas.core.frame.DataFrame, x:str, y:str,
            ax:matplotlib.axes._axes.Axes, order:List=None, hue:str=None,
            palette:Union[Iterable,str]='black', zorder:float=1,
            size:float=5, side:str='center', jitter:float=1,
            filled:Union[bool,List,Tuple]=True, is_drop_gutter:bool=True,
            gutter_limit:float=0.5, horizontal:bool=False, **kwargs)

API to plot a swarm plot.

	Type	Default	Details
data	DataFrame		The input data as a pandas DataFrame.
x	str		The column in the DataFrame to be used as the x-axis.
y	str		The column in the DataFrame to be used as the y-axis.
ax	Axes		Matplotlib axes.Axes object for which the plot would be drawn on. Default is None.
order	List	None	The order in which x-axis categories should be displayed. Default is None.
hue	str	None	The column in the DataFrame that determines the grouping for color. If None (by default), it assumes that it is being grouped by x.
palette	Union	black	The color palette to be used for plotting. Default is “black”.
zorder	float	1	The z-order for drawing the swarm plot wrt other matplotlib drawings. Default is 1.
size	float	5
side	str	center	The side on which points are swarmed (“center”, “left”, or “right”). Default is “center”.
jitter	float	1	Determines the distance between points. Default is 1.
filled	Union	True	Determines whether the dots in the swarmplot are filled or not. If set to False, dots are not filled. If provided as a List or Tuple, it should contain boolean values, each corresponding to a swarm group in order, indicating whether the dot should be filled or not.
is_drop_gutter	bool	True	If True, drop points that hit the gutters; otherwise, readjust them.
gutter_limit	float	0.5	The limit for points hitting the gutters.
horizontal	bool	False	If True, the swarm plot is drawn horizontally. Default is False.
kwargs	VAR_KEYWORD
Returns	axes.Axes		Matplotlib axes.Axes object for which the swarm plot has been drawn on.