The plotting module

This is a module contains scripts for generating plots from compact and full matrices of interaction data.

Concepts

These functions take either compact, upper-triangle, or full 3d data matrices.

Data can either be arranged in compact, upper-triangle, or complete (rectangular) arrays. With HiC data, compact arrays are N x M x 2, where N is the number of fends or bins, and M is the maximum distance between fends or bins. This is useful for working with sets of short interactions. When using 5C data, the compact format is an N x M x 2 array where N is the number of forward primers and M is the number of reverse primers. Data can be raw, fend-corrected, distance-dependence removed, or enrichment values. Arrays are 3-dimensional with observed values in the first layer of d3, expected values in the second layer of d3.

API Documentation

hifive.plotting.plot_compact_array(data, maxscore=None, minscore=None, symmetricscaling=True, logged=True, min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, diagonal_included=False, **kwargs)

Fill in and rescale bitmap from a HiC compact array.

Parameters:
  • data (numpy array) – A three-dimensional compact array of HiC interaction data.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
  • diagonal_included (bool.) – If true, adjust output shape as necessary.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_diagonal_from_compact_array(data, maxscore=None, minscore=None, symmetricscaling=True, logged=True, min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, diagonal_included=False, **kwargs)

Fill in and rescale bitmap from a HiC compact array, plotting only the upper triangle rotated 45 degrees counter-clockwise.

Parameters:
  • data (numpy array) – A three-dimensional compact array of HiC interaction data.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
  • diagonal_included (bool.) – If true, adjust output shape as necessary.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_diagonal_from_upper_array(data, maxscore=None, minscore=None, symmetricscaling=True, logged=True, min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, diagonal_included=False, **kwargs)

Fill in and rescale bitmap from a HiC upper array, plotting only the upper triangle rotated 45 degrees counter-clockwise.

Parameters:
  • data (numpy array) – A three-dimensional upper array of HiC interaction data.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
  • diagonal_included (bool.) – If true, adjust output shape as necessary.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_fivec_compact_heatmap_dict(filename, maxscore=None, minscore=None, symmetricscaling=True, logged=True, regions=[], min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, **kwargs)

Fill in and rescale bitmap in a compact format from a 5C heatmap h5dict file.

This plots the data in a 5C compact format such that the rows correspond to positive-strand primers and columns correspond to negative-strand primers.

Parameters:
  • filename – Location of a heatmap h5dict containing 5C data arrays.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • regions (list) – If specified, only the indicated regions are plotted. Otherwise all regions present in the h5dict are plotted.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_fivec_dict(array_dict, maxscore=None, minscore=None, symmetricscaling=True, logged=True, regions=[], min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, **kwargs)

Fill in and bitmap ifrom a 5C heatmap dictionary.

Parameters:
  • array_dict – Dictionary containing 5C data arrays and either 1 or two 2D mapping arrays (full or compact, respectively) with tuples are region name or pairs as keys.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • regions (list) – If specified, only the indicated regions are plotted. Otherwise all regions present in the h5dict are plotted.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_fivec_heatmap(filename, maxscore=None, minscore=None, symmetricscaling=True, logged=True, regions=[], min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, **kwargs)

Fill in and rescale bitmap in a full format from a 5C heatmap h5dict file.

Parameters:
  • filename – Location of a heatmap h5dict containing 5C data arrays.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • regions (list) – If specified, only the indicated regions are plotted. Otherwise all regions present in the h5dict are plotted.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_full_array(data, maxscore=None, minscore=None, symmetricscaling=True, logged=True, min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, **kwargs)

Fill in and rescale bitmap from a 5C or HiC full array.

Parameters:
  • data (numpy array) – A three-dimensional compact array of interaction data.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_hic_heatmap(filename, maxscore=None, minscore=None, symmetricscaling=True, logged=True, chroms=[], min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, format='hdf5', **kwargs)

Fill in and rescale bitmap from a HiC heatmap h5dict file.

Parameters:
  • filename (str.) – File name of heatmap h5dict containing binned data arrays.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • chroms (list) – A list of chromosome names to include in the plot. If left empty, all chromosomes present in the heatmap file will be plotted.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
  • format (str.) – Format of the heatmap.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.

hifive.plotting.plot_key(min_score, max_score, height, width, labelformat='%0.2f', orientation='left', num_ticks=5, min_color='0000ff', mid_color='ffffff', max_color='ff0000', labelattr=None, log_display=True, **kwargs)

Create a key including color gradient and labels indicating associated values, returning a pyx canvas.

Parameters:
  • min_score (float) – The minimum value of the key scale.
  • max_score (float) – The maximum value of the key scale.
  • height (float) – The height of the gradient bar in whatever units pyx is using.
  • width (float) – The width of the gradient bar in whatever units pyx is using.
  • labelformat (str.) – A string denoting the format for displaying number labels using the string formatting style from Python <= 2.6.
  • orientation – Indicates where labels are placed relative to gradient bar. This parameter will accept ‘left’, ‘right’, ‘top’, and ‘bottom’.
  • num_ticks (int.) – Indicates how many evenly-spaced tick marks and associated labels to insert. This can be zero for no labels or greater than one. Labels are inserted at the minimum and maximum values first with remaining ticks occuring evenly distributed between the extremes.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • labelattr (str.) – A list of pyx attributes to be passed to the text function.
  • log_display (bool.) – If True, min_score and max_score are taken to be logged values and so labels are evenly spaced in log space but converted to normal space for display.
Returns:

Pxy canvas object.

hifive.plotting.plot_upper_array(data, maxscore=None, minscore=None, symmetricscaling=True, logged=True, min_color='0000ff', mid_color='ffffff', max_color='ff0000', returnscale=False, diagonal_included=False, **kwargs)

Fill in and rescale bitmap from a 5C or HiC upper array.

Parameters:
  • data (numpy array) – A two-dimensional compact array of interaction data.
  • maxscore (float) – A ceiling value to cutoff scores at for plot color.
  • minscore (float) – A floor value to cutoff scores at for plot color.
  • symmetricscaling (bool.) – Indicates whether to recenter data for scaling or maintain scores about zero.
  • logged (bool.) – Indicates whether to use log2 values of scores for color values.
  • min_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This variable is used to create a color gradient for plotting along with max_color and mid_color.
  • mid_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the minimum plot value. This can be set to None to create a gradient ranging from min_color to max_color or to a hex color to create a divergent gradient.
  • max_color (str.) – This is a hex color code (“rrggbb” where each pair ranges from 00-ff) specifying the color associated with the maximum plot value. This variable is used to create a color gradient for plotting along with min_color and mid_color.
  • returnscale (bool.) – Indicates whether to return a list containing the bitmap, minimum score, and maximum score, or just the bitmap.
  • diagonal_included (bool.) – If true, adjust output shape as necessary.
Returns:

PIL bitmap object and if requested, minimum and maximum scores.