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, smoothed=False)

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.

• smoothed (boolean) – If true, attempts to fit a smooth kernel density estimator. If false, uses a custom method do generate a variable width histogram directly from the approx_cdf results.

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	The default continuous x scale.
scale_x_discrete	The default discrete x scale.
scale_x_genomic	The default genomic x scale.
scale_x_log10	Transforms x axis to be log base 10 scaled.
scale_x_reverse	Transforms x-axis to be vertically reversed.
scale_y_continuous	The default continuous y scale.
scale_y_discrete	The default discrete y scale.
scale_y_log10	Transforms y-axis to be log base 10 scaled.
scale_y_reverse	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	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	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.

Facets

facet_wrap	Introduce a one dimensional faceting on specified fields.
vars	Parameters: *args (hail.expr.Expression) -- Fields to facet by.

hail.ggplot.facet_wrap(facets, *, nrow=None, ncol=None, scales='fixed')

Introduce a one dimensional faceting on specified fields.

Parameters:

• facets (hail.expr.StructExpression created by hl.ggplot.vars function.) – The fields to facet on.

• nrow (int) – The number of rows into which the facets will be spread. Will be ignored if ncol is set.

• ncol (int) – The number of columns into which the facets will be spread.

• scales (str) – Whether the scales are the same across facets. For more information and a list of supported options, see the ggplot documentation.

Returns:

FigureAttribute – The faceter.

hail.ggplot.vars(*args)

Parameters:

*args (hail.expr.Expression) – Fields to facet by.

Returns:

hail.expr.StructExpression – A struct to pass to a faceter.

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