Documentation

The hmap.plot plot subpackage

The hmap.plot.basic module

This class offers basic plot Functions for generating nice heatmaps.

hmap.plot.basic.Annotation(ids_sorted, annotation_df, annotation_col_id, axis=1, color_list=['#812b9c', '#d0a6fd', '#00ad1f', '#c27ef6', '#8cf67d', '#004fdf', '#29f9a2', '#6bbefd', '#ff84bf', '#0020aa', '#8d89fe', '#683600', '#d4b06f', '#ffd2df', '#b08050', '#ed0400', '#ff7200', '#c81477', '#690220', '#fffb19', '#d1b003', '#000000'], is_categorial=True, cmap=<matplotlib.colors.LinearSegmentedColormap object>, color_dict=None, ax=None)

Function that plots annotations.

Parameters

  • ids_sorted (list) – List of ids in the order in which the annotation shall be plotted.

  • annotation_df (pandas.DataFrame) – DataFrame containing grouping informatation for the ids for which the annotation shall be plotted. Columns: groups, rows: ids.

  • annotation_col_id (str) – Column id of the group in annotation_df, for which the annotation mshall be plotted.

  • axis (int, optional) – If 0, then the annotation is plotted vertically, i.e. for rows of a DataFrame. If 1, then the annotation is plotted horizontally, i.e. for columns of a DataFrame, defaults to 1

  • color_list (list, optional) – List of colors used to plot annotations, defaults to colors[“xkcd”].

  • is_categorial (bool, optional) – Boolean parameter that defines if the colorscale shall be categorial, or continuous (e.g. age), defaults to True

  • cmap (matplotlib.colors.LinearSegmentedColormap, optional) – ColorMap object, that defines the colormap used for plotting continuous variables, defaults to plt.cm.GnBu_r.

  • color_dict (dict, optional) – If is_categorial is True you can define colors for each category. These colors have to be given as a dict, where the key is the category and the value is the color code, defaults to None.

  • ax (class:matplotlib.axes._subplots.AxesSubplot, optional) – Axes on which to plot the annotation, defaults to None.

Returns

tuple containing the following two elements: 1. True, if the annotation was categorial, False otherwise. 2. If the first element is True, then it is a list containing one representative patch per group, along with the group name and the color representation of the group. If the first element is False, then it is a list, containing the matplotlib.colors.LinearSegmentedColormap object, the min, and the max value from the floating value annotations.

Return type

tuple

hmap.plot.basic.ColorScale(table, cmap='Reds', symmetric_color_scale=True, symmetry_point=0.0, vmin=None, vmax=None, ax=None)

Function that plots the color scale of values inside a dataframe.

Parameters

  • table (pandas.DataFrame) – Table containing numerical values.

  • cmap (str, optional) – Colormap used to produce color scale, defaults to “Reds”.

  • symmetric_color_scale (bool, optional) – If true, vmin, and vmax will be set to have equal distance from symmetry point, defaults to True.

  • symmetry_point (float, optional) – Only used, when symmetric_color_scale is true. If symmetric_color_scale is true, and symmetry_point is not set, defaults to zero.

  • vmin (float, optional) – Minimal value of data_table, that has a color representation, defaults to None.

  • vmax (float, optional) – Maximal value of data_table, that has a color representation, defaults to None.

  • ax (class:matplotlib.axes._subplots.AxesSubplot, optional) – Axes instance on which to plot the color scale, defaults to None.

Returns

Min. and max value displayed on color scale

Return type

tuple

hmap.plot.basic.Dendrogram(table, distance_metric='correlation', linkage_method='complete', axis=1, lw=1.0, n_clust=None, optimal_row_ordering=True, optimal_col_ordering=True, ax=None)

Function that plots a dendrogram on axis 0 (rows), or axis 1 (columns) of a pandas.DataFrame.

Parameters

  • table (pandas.DataFrame) – Data matrix used to calculate dendrograms.

  • distance_metric (str, optional) – Distance metric used to determine distance between two vectors. The distance function can be either of ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’, defaults to ‘correlation’.

  • linkage_method (str, optional) – Methods for calculating the distance between the newly formed cluster u and each v. Possible methods are, ‘single’, ‘complete’, ‘average’, ‘weighted’, and ‘centroid’, defaults to ‘complete’.

  • axis (int, optional) – Axis of table used for plotting dendrogram (0 = rows, 1 = columns), defaults to 1.

  • lw (float, optional) – Width of the lines (in points) defining the dengrogram, defaults to 1.

  • n_clust (int, optional) – Number of clusters in which the dendrogram should be cut. Note: Dendrogram cutting makes use of scipy.cluster.hierarchy.cut_tree function, defaults to None.

  • optimal_row_ordering (bool, optional) – If True, the rows will be ordered optimally with regards to the cluster separation. Be careuful: Can take a long time, depending on the number of rows, defaults to True.

  • optimal_col_ordering (bool, optional) – If True, the columns will be ordered optimally with regards to the cluster separation. Be careuful: Can take a long time, depending on the number of columns, defaults to True.

  • ax (matplotlib.axes._subplots.AxesSubplot) – Axes n which to plot the dendrogram, defaults to None.

Returns

Tuple containing the following entries: 1. Resulting dictionary from scipy.cluster.hierarchy.dendrogram function. 2. linkage matrix, that is returned from scipy.cluster.hierarchy.linkage function 3. dictionary containing the row_ids, (in case of axis = 0), or column_ids (in case of axis = 1) that are assigned to different clusters. Only makes sense if n_clust is not None.

Return type

dict

hmap.plot.basic.Heatmap(table, cmap='Reds', distance_metric='correlation', linkage_method='complete', show_column_labels=False, show_row_labels=False, row_clustering=True, column_clustering=True, custom_row_clustering=None, custom_column_clustering=None, vmin=None, vmax=None, symmetric_color_scale=False, symmetry_point=0, show_plot=True, optimal_row_ordering=True, optimal_col_ordering=True, ax=None)

Function that plots a two dimensional matrix as clustered heatmap. Sorting of rows and columns is done by hierarchical clustering.

Parameters

  • table (Object of type pandas.DataFrame) – Two dimensional array containing numerical values to be clustered.

  • cmap (str, optional) – Colormap used to produce color scale, defaults to “Reds”.

  • distance_metric (str, optional) – Distance metric used to determine distance between two vectors.The distance function can be either of ‘braycurtis’, ‘canberra’, ‘chebyshev’, ‘cityblock’, ‘correlation’, ‘cosine’, ‘dice’, ‘euclidean’, ‘hamming’, ‘jaccard’, ‘jensenshannon’, ‘kulsinski’, ‘mahalanobis’, ‘matching’, ‘minkowski’, ‘rogerstanimoto’, ‘russellrao’, ‘seuclidean’, ‘sokalmichener’, ‘sokalsneath’, ‘sqeuclidean’, ‘yule’, defaults to ‘correlation’.

  • linkage_method (str, optional) – methods for calculating the distance between the newly formed cluster u and each v. Possible methods are, ‘single’, ‘complete’, ‘average’, ‘weighted’, and ‘centroid’, defaults to ‘complete’.

  • show_column_labels (bool, optional) – If true, show labels of columns, as defined in table, defaults to False.

  • show_row_labels (bool, optional) – If true, show labels of rows, as defined in table, defaults to False.

  • row_clustering (bool, optional) – If true, the rows a clustered according to distance_metric, and linkage_method, defaults to True.

  • column_clustering (bool, optional) – If true, the columns are clustered according to distance_metric, and linkage_method, defaults to True.

  • custom_row_clustering (list, optional) – List of Row ids from table in the order they should appear in the heatmap. Only applies if row_clustering is False, defaults to None.

  • custom_column_clustering (list, optional) – List of column ids from table in the order they should appear in the heatmap. Only applies if column_clustering is False, defaults to None.

  • vmin (float, optional) – Minimal value of data_table, that has a color representation, defaults to None.

  • vmax (float, optional) – Maximal value of data_table, that has a color representation, defaults to None.

  • symmetric_color_scale (bool, optional) – If true, vmin, and vmax will be set to have equal distance from symmetry point, defaults to False.

  • symmetry_point (float, optional) – Only used, when symmetric_color_scale is true. If symmetric_color_scale is true, and symmetry_point is not set, defaults to zero.

  • show_plot (bool, optional) – If True, the heatmap will be shown on the given axis, else the function only returns the return values, defaults to True.

  • optimal_row_ordering (bool, optional) – If True, the rows will be ordered optimally with regards to the cluster separation. Be careuful: Can take a long time, depending on the number of rows, defaults to True.

  • optimal_col_ordering (bool, optional) – If True, the columns will be ordered optimally with regards to the cluster separation. Be careuful: Can take a long time, depending on the number of columns, defaults to True.

  • ax (matplotlib.axes._subplots.AxesSubplot, optional) – Axes instance on which to plot heatmap, defaults to None.

Returns

Tuple containing: 1. column_names_reordered: List of column names after reordering as given as column names of table. 2. row_names_reordered: List of row names after reordering as given as index names of table. 3. vmin: Minimal value of table, that gets a color representation in heatmap. 4. vmax: Maximal value of table, that gets a color representation in heatmap.

Return type

tuple

hmap.plot.basic.Legends(patch_list_dict, annotation_ids=None, ax=None)

Function that plots Legends based on pathc lists from Annotation function.

Parameters

  • patch_list_dict (dict) – A dictionary, storing patches used for legend plotting. The key is the name of the Annotation, and the value is a list of 2 elements. The first element is a boolean value, defining if the annotation was catgorial (True) or non-categorial (False). The second element is in the case of categorial annotations the patch list, and in the case of non categorial annotations the cmap used, as well as the min and the max values.

  • annotation_ids (list, optional) – List of annotation ids, for which the Legend shall be plotted. Legends will be plotted in the same order as given in annotation_ids list, defaults to None.

  • ax (class:matplotlib.axes._subplots.AxesSubplot, optional) – Axes instance on which to plot the legends, defaults to None.

Returns

Nothing to be returned.

Return type

None

The hmap.layout subpackage

The hmap.layout.layout module

This module offers functions for creating nice and clean figure layouts.

hmap.layout.layout.layoutGrid(nrows, ncols, row_widths, col_heights, hspace, wspace, bottom, top, left, right)

Function, that makes a grid layout using extensions given in mm.

Parameters

  • nrows (int) – Number of rows in the grid.

  • ncols (int) – Number of columns in the grid.

  • row_widths (list :param col_heights: list of column heights in mm, as type floar) – list of row widths in mm, as type float.

  • hspace (float) – Height space between cells in mm.

  • wspace (float) – Width space between cells in mm.

  • bottom (float) – Bottom space of grid in mm.

  • top (float) – Top space of grid in mm.

  • left (float) – Left space of grid in mm.

  • right (float) – Right space of grid in mm.

Returns

A tuple of type matplotlib.figure.Figure, defining the figure on which the grid is defined, and matplotlib.gridspec.GridSpec, defining the grid.

Return type

tuple