Plotting With hail.ggplot Overview

Warning

Plotting functionality is in early stages and is experimental.

The hl.ggplot module is designed based on R’s tidyverse ggplot2 library. This module provides a subset of ggplot2’s functionality to allow users to generate plots in much the same way they would in ggplot2.

This module is intended to be a new, more flexible way of plotting compared to the hl.plot module. This module currently uses plotly to generate plots, as opposed to hl.plot, which uses bokeh.

Core functions

ggplot	Create the initial plot object.
aes	Create an aesthetic mapping
coord_cartesian	Set the boundaries of the plot.

hail.ggplot.ggplot(table, mapping={})

Create the initial plot object.

This function is the beginning of all plots using the hail.ggplot interface. Plots are constructed by calling this function, then adding attributes to the plot to get the desired result.

Examples

Create a y = x^2 scatter plot

>>> ht = hl.utils.range_table(10)
>>> ht = ht.annotate(squared = ht.idx**2)
>>> my_plot = hl.ggplot.ggplot(ht, hl.ggplot.aes(x=ht.idx, y=ht.squared)) + hl.ggplot.geom_point()

Parameters

• table – The table containing the data to plot.

• mapping – Default list of aesthetic mappings from table data to plot attributes.

Returns

GGPlot

hail.ggplot.aes(**kwargs)

Create an aesthetic mapping

Parameters

kwargs – Map aesthetic names to hail expressions based on table’s plot.

Returns

Aesthetic – The aesthetic mapping to be applied.

hail.ggplot.coord_cartesian(xlim=None, ylim=None)

Set the boundaries of the plot.

Parameters

• xlim (tuple with two int) – The minimum and maximum x value to show on the plot.

• ylim (tuple with two int) – The minimum and maximum y value to show on the plot.

Returns

FigureAttribute – The coordinate attribute to be applied.

Geoms

geom_point	Create a scatter plot.
geom_line	Create a line plot.
geom_text	Create a scatter plot where each point is text from the text aesthetic.
geom_bar	Create a bar chart that counts occurrences of the various values of the x aesthetic.
geom_col	Create a bar chart that uses bar heights specified in y aesthetic.
geom_histogram	Creates a histogram.
geom_density	Creates a smoothed density plot.
geom_hline	Plots a horizontal line at yintercept.
geom_vline	Plots a vertical line at xintercept.
geom_area	Creates a line plot with the area between the line and the x-axis filled in.
geom_ribbon	Creates filled in area between two lines specified by x, ymin, and ymax

hail.ggplot.geom_point(mapping={}, *, color=None, size=None, alpha=None, shape=None)

Create a scatter plot.

Supported aesthetics: x, y, color, alpha, tooltip, shape

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_line(mapping={}, *, color=None, size=None, alpha=None)

Create a line plot.

Supported aesthetics: x, y, color, tooltip

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_text(mapping={}, *, color=None, size=None, alpha=None)

Create a scatter plot where each point is text from the text aesthetic.

Supported aesthetics: x, y, label, color, tooltip

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_bar(mapping={}, *, fill=None, color=None, alpha=None, position='stack', size=None)

Create a bar chart that counts occurrences of the various values of the x aesthetic.

Supported aesthetics: x, color, fill, weight

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_col(mapping={}, *, fill=None, color=None, alpha=None, position='stack', size=None)

Create a bar chart that uses bar heights specified in y aesthetic.

Supported aesthetics: x, y, color, fill

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_histogram(mapping={}, *, min_val=None, max_val=None, bins=None, fill=None, color=None, alpha=None, position='stack', size=None)

Creates a histogram.

Note: this function currently does not support same interface as R’s ggplot.

Supported aesthetics: x, color, fill

Parameters

• mapping (Aesthetic) – Any aesthetics specific to this geom.

• min_val (int or float) – Minimum value to include in histogram

• max_val (int or float) – Maximum value to include in histogram

• bins (int) – Number of bins to plot. 30 by default.

• fill – A single fill color for all bars of histogram, overrides fill aesthetic.

• color – A single outline color for all bars of histogram, overrides color aesthetic.

• alpha (float) – A measure of transparency between 0 and 1.

• position (str) – Tells how to deal with different groups of data at same point. Options are “stack” and “dodge”.

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_density(mapping={}, *, k=1000, smoothing=0.5, fill=None, color=None, alpha=None)

Creates a smoothed density plot.

This method uses the hl.agg.approx_cdf aggregator to compute a sketch of the distribution of the values of x. It then uses an ad hoc method to estimate a smoothed pdf consistent with that cdf.

Note: this function currently does not support same interface as R’s ggplot.

Supported aesthetics: x, color, fill

Parameters

• mapping (Aesthetic) – Any aesthetics specific to this geom.

• k (int) – Passed to the approx_cdf aggregator. The size of the aggregator scales linearly with k. The default value of 1000 is likely sufficient for most uses.

• smoothing (float) – Controls the amount of smoothing applied.

• fill – A single fill color for all density plots, overrides fill aesthetic.

• color – A single line color for all density plots, overrides color aesthetic.

• alpha (float) – A measure of transparency between 0 and 1.

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_hline(yintercept, *, linetype='solid', color=None)

Plots a horizontal line at yintercept.

Parameters

• yintercept (float) – Location to draw line.

• linetype (str) – Type of line to draw. Choose from “solid”, “dashed”, “dotted”, “longdash”, “dotdash”.

• color (str) – Color of line to draw, black by default.

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_vline(xintercept, *, linetype='solid', color=None)

Plots a vertical line at xintercept.

Parameters

• xintercept (float) – Location to draw line.

• linetype (str) – Type of line to draw. Choose from “solid”, “dashed”, “dotted”, “longdash”, “dotdash”.

• color (str) – Color of line to draw, black by default.

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_area(mapping={}, fill=None, color=None)

Creates a line plot with the area between the line and the x-axis filled in.

Supported aesthetics: x, y, fill, color, tooltip

Parameters

• mapping (Aesthetic) – Any aesthetics specific to this geom.

• fill – Color of fill to draw, black by default. Overrides fill aesthetic.

• color – Color of line to draw outlining non x-axis facing side, none by default. Overrides color aesthetic.

Returns

FigureAttribute – The geom to be applied.

hail.ggplot.geom_ribbon(mapping={}, fill=None, color=None)

Creates filled in area between two lines specified by x, ymin, and ymax

Supported aesthetics: x, ymin, ymax, color, fill, tooltip

Parameters

• mapping (Aesthetic) – Any aesthetics specific to this geom.

• fill – Color of fill to draw, black by default. Overrides fill aesthetic.

• color – Color of line to draw outlining both side, none by default. Overrides color aesthetic.

• return:

• :class:`FigureAttribute` – The geom to be applied.

Scales

scale_x_continuous([name, breaks, labels, trans])	The default continuous x scale.
scale_x_discrete([name, breaks, labels])	The default discrete x scale.
scale_x_genomic(reference_genome[, name])	The default genomic x scale.
scale_x_log10([name])	Transforms x axis to be log base 10 scaled.
scale_x_reverse([name])	Transforms x-axis to be vertically reversed.
scale_y_continuous([name, breaks, labels, trans])	The default continuous y scale.
scale_y_discrete([name, breaks, labels])	The default discrete y scale.
scale_y_log10([name])	Transforms y-axis to be log base 10 scaled.
scale_y_reverse([name])	Transforms y-axis to be vertically reversed.
scale_color_continuous()	The default continuous color scale.
scale_color_discrete()	The default discrete color scale.
scale_color_hue()	Map discrete colors to evenly placed positions around the color wheel.
scale_color_manual(*, values)	A color scale that assigns strings to colors using the pool of colors specified as values.
scale_color_identity()	A color scale that assumes the expression specified in the color aesthetic can be used as a color.
scale_fill_continuous()	The default continuous fill scale.
scale_fill_discrete()	The default discrete fill scale.
scale_fill_hue()	Map discrete fill colors to evenly placed positions around the color wheel.
scale_fill_manual(*, values)	A color scale that assigns strings to fill colors using the pool of colors specified as values.
scale_fill_identity()	A color scale that assumes the expression specified in the fill aesthetic can be used as a fill color.

hail.ggplot.scale_x_continuous(name=None, breaks=None, labels=None, trans='identity')

The default continuous x scale.

Parameters

• name (str) – The label to show on x-axis

• breaks (list of float) – The locations to draw ticks on the x-axis.

• labels (list of str) – The labels of the ticks on the axis.

• trans (str) – The transformation to apply to the x-axis. Supports “identity”, “reverse”, “log10”.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_x_discrete(name=None, breaks=None, labels=None)

The default discrete x scale.

Parameters

• name (str) – The label to show on x-axis

• breaks (list of str) – The locations to draw ticks on the x-axis.

• labels (list of str) – The labels of the ticks on the axis.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_x_genomic(reference_genome, name=None)

The default genomic x scale. This is used when the x aesthetic corresponds to a LocusExpression.

Parameters

• reference_genome – The reference genome being used.

• name (str) – The label to show on y-axis

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_x_log10(name=None)

Transforms x axis to be log base 10 scaled.

Parameters

name (str) – The label to show on x-axis

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_x_reverse(name=None)

Transforms x-axis to be vertically reversed.

Parameters

name (str) – The label to show on x-axis

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_y_continuous(name=None, breaks=None, labels=None, trans='identity')

The default continuous y scale.

Parameters

• name (str) – The label to show on y-axis

• breaks (list of float) – The locations to draw ticks on the y-axis.

• labels (list of str) – The labels of the ticks on the axis.

• trans (str) – The transformation to apply to the y-axis. Supports “identity”, “reverse”, “log10”.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_y_discrete(name=None, breaks=None, labels=None)

The default discrete y scale.

Parameters

• name (str) – The label to show on y-axis

• breaks (list of str) – The locations to draw ticks on the y-axis.

• labels (list of str) – The labels of the ticks on the axis.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_y_log10(name=None)

Transforms y-axis to be log base 10 scaled.

Parameters

name (str) – The label to show on y-axis

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_y_reverse(name=None)

Transforms y-axis to be vertically reversed.

Parameters

name (str) – The label to show on y-axis

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_color_continuous()

The default continuous color scale. This linearly interpolates colors between the min and max observed values.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_color_discrete()

The default discrete color scale. This maps each discrete value to a color. Equivalent to scale_color_hue.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_color_hue()

Map discrete colors to evenly placed positions around the color wheel.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_color_manual(*, values)

A color scale that assigns strings to colors using the pool of colors specified as values.

Parameters

values (list of str) – The colors to choose when assigning values to colors.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_color_identity()

A color scale that assumes the expression specified in the color aesthetic can be used as a color.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_fill_continuous()

The default continuous fill scale. This linearly interpolates colors between the min and max observed values.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_fill_discrete()

The default discrete fill scale. This maps each discrete value to a fill color.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_fill_hue()

Map discrete fill colors to evenly placed positions around the color wheel.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_fill_manual(*, values)

A color scale that assigns strings to fill colors using the pool of colors specified as values.

Parameters

values (list of str) – The colors to choose when assigning values to colors.

Returns

FigureAttribute – The scale to be applied.

hail.ggplot.scale_fill_identity()

A color scale that assumes the expression specified in the fill aesthetic can be used as a fill color.

Returns

FigureAttribute – The scale to be applied.

Labels

xlab(label)	Sets the x-axis label of a plot.
ylab(label)	Sets the y-axis label of a plot.
ggtitle(label)	Sets the title of a plot.

hail.ggplot.xlab(label)

Sets the x-axis label of a plot.

Parameters

label (str) – The desired x-axis label of the plot.

Returns

FigureAttribute – Label object to change the x-axis label.

hail.ggplot.ylab(label)

Sets the y-axis label of a plot.

Parameters

label (str) – The desired y-axis label of the plot.

Returns

FigureAttribute – Label object to change the y-axis label.

hail.ggplot.ggtitle(label)

Sets the title of a plot.

Parameters

label (str) – The desired title of the plot.

Returns

FigureAttribute – Label object to change the title.

Classes

class hail.ggplot.GGPlot(ht, aes, geoms=[], labels=<hail.ggplot.labels.Labels object>, coord_cartesian=None, scales=None, facet=None)

The class representing a figure created using the hail.ggplot module.

Create one by using ggplot().

to_plotly()

Turn the hail plot into a Plotly plot.

Returns

A Plotly figure that can be updated with plotly methods.

show()

Render and show the plot, either in a browser or notebook.

write_image(path)

Write out this plot as an image.

This requires you to have installed the python package kaleido from pypi.

Parameters

path (str) – The path to write the file to.

class hail.ggplot.Aesthetic(properties)

class hail.ggplot.FigureAttribute