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
Create the initial plot object. |
|
Create an aesthetic mapping |
|
Set the boundaries of the plot. |
-
hail.ggplot.
ggplot
(table, mapping={})[source]¶ 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
-
hail.ggplot.
aes
(**kwargs)[source]¶ 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)[source]¶ Set the boundaries of the plot.
- Parameters
- Returns
FigureAttribute
– The coordinate attribute to be applied.
Geoms
Create a scatter plot. |
|
Create a line plot. |
|
Create a scatter plot where each point is text from the |
|
Create a bar chart that counts occurrences of the various values of the |
|
Create a bar chart that uses bar heights specified in y aesthetic. |
|
Creates a histogram. |
|
Creates a smoothed density plot. |
|
Plots a horizontal line at |
|
Plots a vertical line at |
|
Creates a line plot with the area between the line and the x-axis filled in. |
|
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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ Plots a horizontal line at
yintercept
.- Parameters
- Returns
FigureAttribute
– The geom to be applied.
-
hail.ggplot.
geom_vline
(xintercept, *, linetype='solid', color=None)[source]¶ Plots a vertical line at
xintercept
.- Parameters
- Returns
FigureAttribute
– The geom to be applied.
-
hail.ggplot.
geom_area
(mapping={}, fill=None, color=None)[source]¶ 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)[source]¶ 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
|
The default continuous x scale. |
|
The default discrete x scale. |
|
The default genomic x scale. |
|
Transforms x axis to be log base 10 scaled. |
|
Transforms x-axis to be vertically reversed. |
|
The default continuous y scale. |
|
The default discrete y scale. |
|
Transforms y-axis to be log base 10 scaled. |
|
Transforms y-axis to be vertically reversed. |
The default continuous color scale. |
|
The default discrete color scale. |
|
Map discrete colors to evenly placed positions around the color wheel. |
|
|
A color scale that assigns strings to colors using the pool of colors specified as values. |
A color scale that assumes the expression specified in the |
|
The default continuous fill scale. |
|
The default discrete fill scale. |
|
Map discrete fill colors to evenly placed positions around the color wheel. |
|
|
A color scale that assigns strings to fill colors using the pool of colors specified as values. |
A color scale that assumes the expression specified in the |
-
hail.ggplot.
scale_x_continuous
(name=None, breaks=None, labels=None, trans='identity')[source]¶ The default continuous x scale.
- Parameters
- Returns
FigureAttribute
– The scale to be applied.
-
hail.ggplot.
scale_x_discrete
(name=None, breaks=None, labels=None)[source]¶ The default discrete x scale.
-
hail.ggplot.
scale_x_genomic
(reference_genome, name=None)[source]¶ The default genomic x scale. This is used when the
x
aesthetic corresponds to aLocusExpression
.- 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)[source]¶ 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)[source]¶ 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')[source]¶ The default continuous y scale.
- Parameters
- Returns
FigureAttribute
– The scale to be applied.
-
hail.ggplot.
scale_y_discrete
(name=None, breaks=None, labels=None)[source]¶ The default discrete y scale.
-
hail.ggplot.
scale_y_log10
(name=None)[source]¶ 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)[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ Map discrete colors to evenly placed positions around the color wheel.
- Returns
FigureAttribute
– The scale to be applied.
-
hail.ggplot.
scale_color_manual
(*, values)[source]¶ A color scale that assigns strings to colors using the pool of colors specified as values.
- Parameters
values (
list
ofstr
) – The colors to choose when assigning values to colors.- Returns
FigureAttribute
– The scale to be applied.
-
hail.ggplot.
scale_color_identity
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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
()[source]¶ 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)[source]¶ A color scale that assigns strings to fill colors using the pool of colors specified as values.
- Parameters
values (
list
ofstr
) – The colors to choose when assigning values to colors.- Returns
FigureAttribute
– The scale to be applied.
-
hail.ggplot.
scale_fill_identity
()[source]¶ 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
|
Sets the x-axis label of a plot. |
|
Sets the y-axis label of a plot. |
|
Sets the title of a plot. |
-
hail.ggplot.
xlab
(label)[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ The class representing a figure created using the
hail.ggplot
module.Create one by using
ggplot()
.