PyComplexHeatmap.annotations module

class PyComplexHeatmap.annotations.AnnotationBase(df=None, cmap='auto', colors=None, height=None, legend=None, legend_kws=None, ylim=None, **plot_kws)[source]

Bases: object

Base class for annotation objects.

Parameters:

  • df (dataframe) – a pandas series or dataframe (only one column).

  • cmap (str) – colormap, such as Set1, Dark2, bwr, Reds, jet, hsv, rainbow and so on. Please see https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html for more information, or run matplotlib.pyplot.colormaps() to see all availabel cmap. default cmap is ‘auto’, it would be determined based on the dtype for each columns of df.

  • colors (dict, list or str) – a dict or list (for boxplot, barplot) or str. If colors is a dict: keys should be exactly the same as df.iloc[:,0].unique(), values for the dict should be colors (color names or HEX color). If colors is a list, then the length of this list should be equal to df.iloc[:,0].nunique() If colors is a string, means all values in df.iloc[:,0].unique() share the same color.

  • height (float) – height (if axis=1) / width (if axis=0) for the annotation size.

  • legend (bool) – whether to plot legend for this annotation when legends are plotted or plot legend with HeatmapAnnotation.plot_legends().

  • legend_kws (dict) – vmax, vmin and other kws passed to plt.legend, such as title, prop, fontsize, labelcolor, markscale, frameon, framealpha, fancybox, shadow, facecolor, edgecolor, mode and so on, for more arguments, pleast type ?plt.legend. There is an additional parameter color_text (default is True), which would set the color of the text to the same color as legend marker. if one set legend_kws={‘color_text’:False}, then, black would be the default color for the text. If the user want to use a custom color instead of black (such as blue), please set legend_kws={‘color_text’:False,’labelcolor’:’blue’}.

  • plot_kws (dict) – other plot kws passed to annotation.plot, such as rotation, rotation_mode, ha, va, annotation_clip, arrowprops and matplotlib.text.Text for anno_label. For example, in anno_simple, there is also kws: vmin and vmax, if one want to change the range, please try: anno_simple(df_box.Gene1,vmin=0,vmax=1,legend_kws={‘vmin’:0,’vmax’:1}).

Return type:

Class AnnotationBase.

get_label_width()[source]
get_max_label_width()[source]
get_ticklabel_width()[source]
reorder(idx)[source]
set_axes_kws(subplot_ax)[source]
set_label(label)[source]
set_legend(legend)[source]
set_orientation(orientation)[source]
update_plot_kws(plot_kws)[source]
class PyComplexHeatmap.annotations.HeatmapAnnotation(df=None, axis=1, cmap='auto', colors=None, label_side=None, label_kws=None, ticklabels_kws=None, plot_kws=None, plot=False, legend=True, legend_side='right', legend_gap=5, legend_width=4.5, legend_hpad=2, legend_vpad=5, orientation=None, wgap=0.1, hgap=0.1, plot_legend=True, legend_order='auto', rasterized=False, verbose=1, **args)[source]

Bases: object

Generate and plot heatmap annotations.

Parameters:

  • self (Class) – HeatmapAnnotation

  • df (dataframe) – a pandas dataframe, each column will be converted to one anno_simple class.

  • axis (int) – 1 for columns annotation, 0 for rows annotations.

  • cmap (str) – colormap, such as Set1, Dark2, bwr, Reds, jet, hsv, rainbow and so on. Please see https://matplotlib.org/3.5.0/tutorials/colors/colormaps.html for more information, or run matplotlib.pyplot.colormaps() to see all availabel cmap. default cmap is ‘auto’, it would be determined based on the dtype for each columns in df. If df is None, then there is no need to specify cmap, cmap and colors will only be used when df is provided. If cmap is a string, then all columns in the df would have the same cmap, cmap can also be a dict, keys are the column names from df, values should be cmap (matplotlib.pyplot.colormaps()).

  • colors (dict) – a dict, keys are the column names of df, values are list, dict or string passed to AnnotationBase.__subclasses__(), including anno_simple, anno_boxplot,anno_label and anno_scatter. colors must have the same length as the df.columns, if colors is not provided (default), else, colors would be calculated based on the given cmap. If colors is given, then the cmap would be invalid.

  • label_side (str) – top or bottom when axis=1 (columns annotation), left or right when axis=0 (rows annotations).

  • label_kws (dict) – kws passed to the labels of the annotation labels (would be df.columns if df is given). such as alpha, color, fontsize, fontstyle, ha (horizontalalignment), va (verticalalignment), rotation, rotation_mode, visible, rasterized and so on. For more information, see plt.gca().yaxis.label.properties() or ax.yaxis.label.properties()

  • ticklabels_kws (dict) – label_kws is for the label of annotation, ticklabels_kws is for the label (text) in anno_label, such as axis, which, direction, length, width, color, pad, labelsize, labelcolor, colors, zorder, bottom, top, left, right, labelbottom, labeltop, labelleft, labelright, labelrotation, grid_color, grid_linestyle and so on. For more information,see ?matplotlib.axes.Axes.tick_params

  • plot_kws (dict) – kws passed to annotation functions, such as anno_simple, anno_label et.al.

  • plot (bool) – whether to plot, when the annotation are included in clustermap, plot would be set to False automotially.

  • legend (bool) – True or False, or dict (when df is no None), when legend is dict, keys are the columns of df.

  • legend_side (str) – right or left

  • legend_gap (float) – the vertical gap between two legends, default is 2 [mm]

  • legend_width (float) – width of the legend, default is 4.5[mm]

  • legend_hpad (float) – Horizonal space between heatmap and legend, default is 2 [mm].

  • legend_vpad (float) – Vertical space between top of ax and legend, default is 2 [mm].

  • orientation (str) – up or down, when axis=1 left or right, when axis=0; When anno_label shows up in annotation, the orientation would be automatically be assigned according to the position of anno_label.

  • wgap (float or int) – optional, the space used to calculate wspace, default is [0.1] (mm), control the vertical gap between two annotations.

  • hgap (float or int) – optional, the space used to calculate hspace, default is [0.1] (mm), control the horizontal gap between two annotations.

  • plot_legend (bool) – whether to plot legends.

  • legend_order (str, bool or list) – control the order of legends, default is ‘auto’, sorted by length of legend. could also be True/False or a list (or tuple), if a list / tuple is provided, values should be the label (title) of each legend.

  • args (name-value pair) – key is the annotation label (name), values can be a pandas dataframe, series, or annotation such as anno_simple, anno_boxplot, anno_scatter, anno_label, or anno_barplot.

Return type:

Class HeatmapAnnotation.

collect_legends()[source]

Collect legends. :rtype: None

get_legend_list()[source]
plot_annotations(ax=None, subplot_spec=None, idxs=None, wspace=None, hspace=None)[source]

Plot annotations

Parameters:

  • ax (ax) – axes to plot the annotations.

  • subplot_spec (ax.figure.add_gridspec) – object from ax.figure.add_gridspec or matplotlib.gridspec.GridSpecFromSubplotSpec.

  • idxs (list) – index to reorder df and df of annotation class.

  • wspace (float) – if wspace not is None, use wspace, else wspace would be calculated based on gap.

  • hspace (float) – if hspace not is None, use hspace, else hspace would be calculated based on gap.

Return type:

self.ax

plot_legends(ax=None)[source]

Plot legends. :param ax: :type ax: axes for the plot, is ax is None, then ax=plt.figure()

Return type:

None

set_axes_kws()[source]
show_ticklabels(labels, **kwargs)[source]
class PyComplexHeatmap.annotations.anno_barplot(df=None, cmap='auto', colors=None, height=None, legend=None, legend_kws=None, ylim=None, **plot_kws)[source]

Bases: anno_boxplot

Annotate barplot, all arguments are included in AnnotationBase,

plot_kws for anno_boxplot include edgecolor, grid,align,zorder, and other arguments passed to plt.barplot.

plot(ax=None, axis=1)[source]
class PyComplexHeatmap.annotations.anno_boxplot(df=None, cmap='auto', colors=None, height=None, legend=None, legend_kws=None, ylim=None, **plot_kws)[source]

Bases: AnnotationBase

annotate boxplots, all arguments are included in AnnotationBase, plot_kws for anno_boxplot include showfliers, edgecolor, grid, medianlinecolor width,zorder and other arguments passed to plt.boxplot.

plot(ax=None, axis=1)[source]
class PyComplexHeatmap.annotations.anno_dendrogram(df=None, cmap='auto', colors=None, add_text=False, majority=True, text_kws=None, height=None, dendrogram_kws=None, **plot_kws)[source]

Bases: AnnotationBase

plot(ax=None, axis=1)[source]
class PyComplexHeatmap.annotations.anno_img(df=None, cmap=None, colors=None, border_width=1, border_color=255, merge=False, merge_width=1, rotate=None, mode='RGBA', **plot_kws)[source]

Bases: AnnotationBase

Annotate images.

Parameters:

  • border_width (int) – width of border lines between images (0-256?). Ignored when merge is True.

  • border_color (int) – color of border lines. black:0, white:255. Ignored when merge is True.

  • merge (bool) – whether to merge the same clusters into one and show image only once.

  • merge_width (float) –

  • True (width of image when merge is) – whether to merge the same clusters into one and show image only once.

  • rotate (int) – Rotate the input images

  • mode (str) – all possible mode to convert, between “L”, “RGB” and “CMYK”, ‘RGBA’, default is RGBA

plot(ax=None, axis=1)[source]
read_img(img_path=None, shape=None)[source]
class PyComplexHeatmap.annotations.anno_label(df=None, cmap='auto', colors=None, merge=False, extend=False, frac=0.2, rad=2, majority=True, adjust_color=True, luminance=0.8, height=None, legend=False, legend_kws=None, relpos=None, **plot_kws)[source]

Bases: AnnotationBase

Add label and text annotations. See example on documentatin website: https://dingwb.github.io/PyComplexHeatmap/build/html/notebooks/single_cell_methylation.html

Parameters:

  • merge (bool) – whether to merge the same clusters into one and label only once.

  • extend (bool) – whether to distribute all the labels extend to the all axis, figure or ax or False.

  • frac (float) – fraction of the armA and armB relative to length of connection label, will be passed to connectionstyle: f”arc,angleA={angleA},angleB={angleB},armA={arm_height},armB={arm_height},rad={self.rad}”, frac will be used to calculate arm_height: arm_height = arrow_height * self.frac

  • rad (int) – rad of the connection arrow.

  • majority (bool) – If there are multiple group for one label, whether to annotate the label in the largest group. [True]

  • adjust_color (bool) – When the luminance of the color is too high, use black color replace the original color. [True]

  • luminance (float) – luminance values [0-1], used together with adjust_color, when the calculated luminance > luminance, the color will be replaced with black. [0.5]

  • relpos (tuple) –

    relpos passed to arrowprops in plt.annotate, tuple (x,y) means the arrow start point position relative to the

    label. default is (0, 0) if self.orientation == ‘top’ else (0, 1) for columns labels, (1, 1) if self.orientation == ‘left’ else (0, 0) for rows labels.

  • plot_kws (dict) –

    passed to plt.annotate, including annotation_clip, arrowprops and matplotlib.text.Text, more information about arrowprops could be found in matplotlib.patches.FancyArrowPatch. For example, to remove arrow, just set arrowprops = dict(visible=False). See: https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.annotate.html for more information. arrowprops:

Return type:

Class AnnotationBase.

get_ticklabel_width()[source]
plot(ax=None, axis=1)[source]
set_plot_kws(axis)[source]
class PyComplexHeatmap.annotations.anno_lineplot(df=None, cmap='auto', colors=None, height=None, legend=None, legend_kws=None, ylim=None, **plot_kws)[source]

Bases: anno_barplot

Annotate lineplot, all arguments are included in AnnotationBase,

parameter grid control whether to show grid (default is True), other arguments passed to plt.plot, including linewidth, marker and so on.

plot(ax=None, axis=1)[source]
class PyComplexHeatmap.annotations.anno_scatterplot(df=None, cmap='auto', colors=None, height=None, legend=None, legend_kws=None, ylim=None, **plot_kws)[source]

Bases: anno_barplot

Annotate scatterplot, all arguments are included in AnnotationBase,

plot_kws for anno_scatterplot include linewidths, grid, edgecolors and other arguments passed to plt.scatter.

plot(ax=None, axis=1)[source]
class PyComplexHeatmap.annotations.anno_simple(df=None, cmap='auto', colors=None, add_text=False, majority=True, text_kws=None, height=None, legend=True, legend_kws=None, **plot_kws)[source]

Bases: AnnotationBase

Annotate simple annotation, categorical or continuous variables.

plot(ax=None, axis=1)[source]