GGity v0.3.0 GGity.Plot View Source
Configures and generates an iolist representing an SVG plot.
The Plot module is GGity's public interface. A Plot struct is created
with new/3
, specifying the data and aesthetic mappings to be used,
along with options associated with the plot's general appearance.
Data must be provided as a list of maps, where each map in the list represents an observation, and the map's keys represent variable names. GGity does not perform any validation of the data; data is assumed to be clean and not to have missing values.
Examples.mtcars()
|> Plot.new(%{x: :wt, y: :mpg})
Mappings are specified using maps, where the map's keys are the names of supported aesthetics, and the values are the names of variables in the data.
Examples.mtcars()
|> Plot.new(%{x: :wt, y: :mpg})
|> Plot.geom_point()
A plot layer (represented as a struct that implements the GGity.Geom
protocol)
is added to the plot using functions such as geom_point/3
or geom_line/3
.
As layers are assembled into a plot, the scales for each aesthetic are calculated using the data assigned to each aesthetic in each layer. Scales generate functions that transform data into an aesthetic value (e.g, an x coordinate or a color) and functions that transform an aesthetic value back into an observation (for the purpose of drawing axes or legends).
The plot will assign default scales based on the type of data assigned to each
aesthetic in each layer (by examining the value in the first row of the data),
typically mapping numerical data to a continuous scale (if available) and binary
data to a discrete scale. These assignments can be overridden by passing the Plot
struct to a scale-setting function, e.g. scale_[scale_type]/2
. For x
values
only, GGity will assign at date/datetime scale if the data mapped to the :x
aesthetic is a Date
, DateTime
or NaiveDateTime
struct.
Examples.mtcars()
|> Plot.new(%{x: :wt, y: :mpg})
|> Plot.geom_point()
|> Plot.plot()
plot/1
generates an iolist that represents the plot. None of the data
is sanitized, so users will need to be mindful of the risks of generating
plots using user-supplied data or parameters.
Link to this section Summary
Functions
Adds a ribbon geom to the plot with the position: :stack
option set.
Adds a bar geom to the plot.
Shorthand for geom_bar(plot, stat: :identity)
.
Adds a line geom to the plot.
Adds a layer with a point geom to the plot.
Adds a ribbon geom to the plot.
Adds a layer with a text geom to the plot.
Manually sets the type of guide used for specified scales.
Updates plot title, axis and legend labels.
Generates a Plot struct with provided data and aesthetic mappings.
Generates an iolist of SVG markup representing a Plot
.
Sets geom point opacity for continuous data.
Sets geom point opacity for categorical data.
Sets geom point opacity using the value of the data mapped to the :alpha
aesthetic.
Can be used to manually assign opacity to individual data points by including an
value with each observation.
Sets geom point color using the value of the data mapped to the color aesthetic. Can be used to manually assign colors to individual data points by including a color value with each observation. Such color values must be provided as a hex value or CSS color name.
Sets geom point colour using the Viridis color palettes. Viridis is used by ggplot2 and other libraries in part because it is optimized to maintain contrast when viewed by those with various types of color blindess.
Sets fill color for fillable shapes (e.g., bars).
Sets type of line for categorical data in line charts.
Sets geom point marker shape for categorical data.
Sets geom point marker shape for categorical data using a custom palette.
Sets geom point size for continuous data.
Sets geom point size for categorical data.
Sets geom point size using the value of the data mapped to the size aesthetic. Can be used to manually assign size to individual data points by including an value with each observation.
Sets geom x coordinate for continuous numerical data.
Sets geom x coordinate for continuous Date
data.
Sets geom x coordinate for continuous DateTime
data.
Sets geom x coordinate for discrete (categorical) data.
Sets geom y coordinate for continuous numerical data.
Updates the plot theme.
Saves the plot to a file at the given path.
Updates the plot x axis label.
Updates the plot y axis label.
Link to this section Types
Link to this section Functions
Specs
Adds a ribbon geom to the plot with the position: :stack
option set.
geom_area/3
is a convenience alias for geom_ribbon/3
that sets the
:position
option to :stack
in order to create stacked area chart.
See geom_ribbon/3
for available aesthetics and options.
Note that stacked ribbon charts are not yet supported - mappings to the
:y_min
aesthetic will be ignored.
Specs
Adds a bar geom to the plot.
Accepts an alternative dataset to be used; if one is not provided defaults to the plot dataset.
Accepts a mapping and/or additonal options to be used. The provided mapping
is merged with the plot mapping for purposes of the geom - there is no need
to re-specify the :x
mapping.
Bar geoms support mapping data to the following aesthetics, which use the noted default scales:
:x
(required):y
(required to draw the geom, but not typically specified for bar geoms - see below):alpha
:fill
Bar geoms also support providing fixed values (specified as options, e.g. color: "blue"
)
for the optional aesthetics above. A fixed value is assigned to the aesthetic
for all observations.
geom_bar/3
uses the :count
stat, which counts the number of
observations in the data for each combination of mapped aesthetics and assigns
that value to the :y
aesthetic. To create a bar chart with bars tied values of
a specific variable use specify stat: :identity
or use geom_col/3
,
which is identical to calling geom_bar/3
with the stat: :identity
option. In either case, if stat: :identity
is called, a variable in the data
must be mapped to the :y
aesthetic.
Other supported options:
:key_glyph
- Type of glyph to use in the legend key. Available values are:a
,:point
,:path
,:rect
and:timeseries
. Defaults to:rect
.:position
- Available values are::identity
(bars sit on top of each other; not recommended),:stack
(one bar per:x
value):dodge
(one bar per unique:x
/:fill
value pair). Defaults to:stack
.
:stat
- an atom referring to a statistical transformation function in theGGity.Stat
module that is to be applied to the data. Defaults to:count
(see above).
Specs
Shorthand for geom_bar(plot, stat: :identity)
.
Produces a bar chart similar to geom_bar/3
, but uses the values of
observations mapped to the :y
aesthetic (instead of observation counts) to
calculate the height of the bars. See geom_bar/3
for supported options.
Specs
Adds a line geom to the plot.
Accepts an alternative dataset to be used; if one is not provided defaults to the plot dataset.
Accepts a mapping and/or additonal options to be used. The provided mapping
is merged with the plot mapping for purposes of the geom - there is no need
to re-specify the :x
or :y
mappings.
Note that the line geom sorts the data by the values for the variable mapped
to the :x
aesthetic using Erlang default term ordering.
Line geoms support mapping data to the following aesthetics, which use the noted default scales:
:x
(required):y
(required):alpha
:color
:linetype
:size
Line geoms also support providing fixed values (specified as options, e.g. color: "blue"
)
for the optional aesthetics above. A fixed value is assigned to the aesthetic
for all observations.
Other supported options:
:key_glyph
- Type of glyph to use in the legend key. Available values are:path
and:timeseries
. By default this value is assigned based on the type of the value in the first row of the data for the variable mapped to the:x
aesthetic.
Specs
Adds a layer with a point geom to the plot.
Accepts an alternative dataset to be used; if one is not provided defaults to the plot dataset.
Accepts a mapping and/or additonal options to be used. The provided mapping
is merged with the plot mapping for purposes of the geom - there is no need
to re-specify the :x
or :y
mappings.
Point geoms support mapping data to the following aesthetics, which use the noted default scales:
:x
(required):y
(required):alpha
:color
:shape
:size
Point geoms also support providing fixed values (specified as options, e.g. color: "blue"
)
for the optional aesthetics above. A fixed value is assigned to the aesthetic for
all observations.
Other supported options:
:key_glyph
- Type of glyph to use in the legend key. Available values are:point
,:path
and:timeseries
; defaults to:point
.:stat
- an atom referring to a statistical transformation function in theGGity.Stat
module that is to be applied to the data. Defaults to:identity
(i.e., no transformation).
Specs
Adds a ribbon geom to the plot.
Accepts an alternative dataset to be used; if one is not provided defaults to the plot dataset.
Accepts a mapping and/or additonal options to be used. The provided mapping
is merged with the plot mapping for purposes of the geom - there is no need
to re-specify the :x
mapping.
Ribbon geoms support mapping data to the following aesthetics, which use the noted default scales:
:x
(required):y_max
(required) - defines the top boundary of the ribbon:y_min
- defines the bottom boundary of the ribbon; defaults to zero:alpha
:fill
A ribbon geom with no :y_min
specified is essentially an area chart. To draw
a stacked area chart, set the :position
option to :stack
, or use the geom_area/3
convenience function.
Ribbon geoms also support providing fixed values (specified as options, e.g. fill: "blue"
)
for the :alpha
and :fill
aesthetics above. A fixed value is assigned to the aesthetic
for all observations. Fixed values can also be specified for:
:color
- ribbon border color:size
- ribbon border color width
Other supported options:
:key_glyph
- Type of glyph to use in the legend key. Available values are:a
,:point
,:path
,:rect
and:timeseries
. Defaults to:rect
.:position
- Available values are::identity
(ribbons overlay one another),:stack
(ribbons stacked on the y-axis; note ) Defaults to:identity
.
Note that stacked ribbon charts are not yet supported - mappings to the
:y_min
aesthetic will be ignored is :positon
is set to :stack
.
Specs
Adds a layer with a text geom to the plot.
Accepts an alternative dataset to be used; if one is not provided defaults to the plot dataset.
A common use for text geoms is labelling of bar or point geoms. For bar chart labels in particular, it is important to specify the same stat and postion adjustment for the text geom as that specified for the bar chart.
Accepts a mapping and/or additonal options to be used. The provided mapping
is merged with the plot mapping for purposes of the geom - there is no need
to re-specify the :x
or :y
mappings.
Text geoms support mapping data to the following aesthetics, which use the noted default scales:
:x
(required):y
(required):label
(required - the text to be displayed):group
:alpha
:color
:size
The :group
aesthetic is generally needed for bar chart labelling, where the
:fill
or :alpha
aesthetic is mapped to a value in the data, in those scenarios,
the text geom position adjustment must match the bar, and the :group
aesthetic for
the text geom should be mapped to the variable mapped to :fill
or :alpha
on the
bar chart layer. See the visual examples code for examples.
Text geoms also support providing fixed values (specified as options, e.g. color: "blue"
)
for the optional aesthetics above. A fixed value is assigned to the aesthetic for
all observations.
Other supported options:
:family
- The font family used to display the text; equivalent to the SVGfont-family
attribute. Defaults to"Helvetica, Arial, sans-serif"
.:fontface
- Equivalent to SVGfont-weight
attribute. Defaults to:normal
.:hjust
- Horizontal alignment of the text relevant to element's:x
value. Valid values are:left
,:center
and:right
. Defaults to:center
.:key_glyph
- Type of glyph to use in the legend key. Available values are:a
,:point
,:path
and:timeseries
. Defaults to:a
.nudge_x
,:nudge_y
- Adjust the x- or y-position value by the specified number of pixels. Both default to0
.:position
- Available values are:identity
(no adjustment),:stack
(:y
value represents cumulative value for a given:x
value) or:dodge
(one text element per unique pair of:x
and other non-:y
mapped aesthetics). Defaults to:identity
.position_vjust
- Adjust:y
position vertically; expressed as a percentage of the calculated:y
value after taking into account the specified position adjustment. Defaults to1
.:stat
- an atom referring to a statistical transformation function in theGGity.Stat
module that is to be applied to the data. Defaults to:identity
(i.e., no transformation). Supported values are:count
and:identity
. Where text geom is intended to serve as a label for another layer with the:count
stat, the state for the text layer should:vjust
- Baseline of the text relevant to element's:y
value. Valid values are:top
,:middle
and:bottom
. Defaults to:center
.
Specs
Manually sets the type of guide used for specified scales.
Accepts a keyword list of aesthetics and values for the :guide
options
for the associated scales.
Currently this is only used to turn legends on or off. Valid values are
:legend
(draw a legend) and :none
(do not draw a legend).
Example
Plot.new(%{x: "x", y: "y"})
|> Plot.geom_point(color: "color", shape: "shape", size: "size")
# By default all three legends will be drawn
|> Plot.guides(shape: :none, size: :none) # Plot will only draw a legend for the color scale
Specs
Updates plot title, axis and legend labels.
Accepts a keyword list where the keys are :title
and/or the aesthetic(s)
tied to the axes/legends to be labelled.
Specs
Generates a Plot struct with provided data and aesthetic mappings.
data
must be passed in the form of a list of maps, where each map represents
an observation or record, the map keys are variable names, and the map values
represent the measurement of that variable for that observation.integer()
Mappings tie variables to aesthetics, i.e. visual characteristics of the plot.
A mapping is specified using a map, with key-value pairs representing the assignment of
variables to available aesthetics. Mappings passed to new/3
must include key-value
pairs for the :x
aesthetic and the :y
aesthetic.
new/3
also supports several options that shortcut plot creation or alter the
appearance of the plot. All graphical size units are in pixels.
:area_padding
- amount of blank space before the first tick and after the last tick on each axis (same value applied to both axes) defaults to10
.:aspect_ratio
- the ratio of the plot area height to:width
. Defaults to1.5.
:breaks
- the number of tick intervals on the x- and y axis (same value applied to both axes). This may be adjusted by the scale function based on the data. Defaults to5
.:labels
- a map specifying the titles of the plot (:title
), x and y-axes (:x
and:y
) or legend title for another aesthetic (e.g.:color
). Anil
value indicates no label. Defaults to%{title: :nil, x: nil, y: nil}
.:margins
- a map with keys:left
,:top
,:right
and:bottom
, specifying the plot margins. Default is%{left: 30, top: 10, right: 0, bottom: 0}
.:panel_background_color
- a string value (hex or CSS color name) for the panel background. Defaults to grey (#eeeeee
):y_label_padding
- vertical distance between the y axis and its label. Defaults to20
.
Specs
Generates an iolist of SVG markup representing a Plot
.
The data is not sanitized; users should be mindful of the risks of generating a plot with user-defined data and parameters.
The Plot
struct's :plot_width
and :aspect_ratio
values are used to set the height
and width properties of the SVG. The viewBox property is set by the plot's :width
and
:aspect_ratio
values.
Specs
Sets geom point opacity for continuous data.
This scale defines a mapping function that assigns an opacity to be mapped to a given value of the mapped variable.
This function takes the following options:
:range
- a tuple with minimum (default -0.1
) and maximum (default -1
) values to be bound to the data
Specs
Sets geom point opacity for categorical data.
For categorical data for which a linear mapping of values to opacity is not appropriate, this scale generates a palette of evenly spaced opacity values mapped to each unique value of the data. The palette is generated such that the difference between each opacity value is maximized. The set of unique data values are sorted for the purpose of assigning them to an opacity and ordering the legend.
This function also takes the following options:
:labels
- specifies how legend item names (levels of the scale) should be formatted. SeeGGity.Labels
for valid values for this option.:range
- a tuple with minimum (default -0.1
) and maximum (default -1
) values to be bound to the data
Specs
Sets geom point opacity using the value of the data mapped to the :alpha
aesthetic.
Can be used to manually assign opacity to individual data points by including an
value with each observation.
See scale_color_identity/1
for an example of identity scale use.
Specs
Sets geom point color using the value of the data mapped to the color aesthetic. Can be used to manually assign colors to individual data points by including a color value with each observation. Such color values must be provided as a hex value or CSS color name.
For example, with the dataset below, one could render points for
:weight
values as "blue"
for low weights and "red"
for high weights
by assigning a value to the :point_color
variable accordingly.
[
%{weight: 6, age: 4, point_color: "blue"},
%{weight: 5, age: 3, point_color: "blue"},
%{weight: 8, age: 4, point_color: "red"},
%{weight: 7, age: 4, point_color: "red"},
]
|> Plot.new(%{x: :weight, y: :age})
|> Plot.geom_point(%{color: :point_color})
|> Plot.scale_color_identity()
|> Plot.plot
Specs
Sets geom point colour using the Viridis color palettes. Viridis is used by ggplot2 and other libraries in part because it is optimized to maintain contrast when viewed by those with various types of color blindess.
The scale is discrete - it is intended to map colors to categorical data. The scale generates a palette of evenly spaced values from the Viridis color palette and these are mapped to each unique value of the data. The palette is generated such that the visual difference between each color value is maximized. The set of unique data values are sorted for the purpose of assigning them to a color and ordering the legend.
This function also takes the following options:
:labels
- specifies how legend item names (levels of the data mapped to the scale) should be formatted. SeeGGity.Labels
for valid values for this option.:option
- specifies which palette to use. Available palettes are:magma
,:inferno
,:plasma
,:viridis
(the default) and:cividis
. These palettes can also be specified via their letter codes -:a
,:b
,:c
,:d
and:e
, respectively.
Examples of each color palette option can be generated using mix ggity.visual.scale_color_viridis
.
Specs
Sets fill color for fillable shapes (e.g., bars).
Accepts the same options as scale_color_viridis/2
.
Specs
Specs
Sets type of line for categorical data in line charts.
This scale uses a palette of six line types (:solid
, :dashed
, :dotted
, :longdash
,
:dotdash
and :twodash
) that are mapped to each unique value of the data. The
set of unique data values are sorted for the purpose of assigning them to a line type
(in the same order as listed above) and ordering the legend.
If there are more than six unique values in the data, the line types are recycled per the order above.
This function also takes the following options:
:labels
- specifies how legend item names (levels of the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
Specs
Sets geom point marker shape for categorical data.
This scale uses a palette of four marker types (:circle
, :square
, :diamond
and :triangle
) that are mapped to each unique value of the data. The set of unique
data values are sorted for the purpose of assigning them to a size (using the shape
order above) and ordering the legend.
If there are greater than four unique values in the data, the shapes are recycled per the order above.
This function also takes the following options:
:labels
- specifies how legend item names (levels of the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
Specs
Sets geom point marker shape for categorical data using a custom palette.
This scale requires a :values
option be passed, which must contain a list
of characters or valid shape names (:circle
, :square
, :diamond
or :triangle
)
to be used as markers. These values are mapped to the unique values of the mapped variable
in term order. The list must have as many values as there are unique values in the data.
This function also takes the following (optional) options:
:labels
- specifies how legend item names (levels of the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
[
%{x: 6, y: 4, mood: "happy"},
%{x: 5, y: 3, mood: "ok"},
%{x: 8, y: 4, mood: "sad"},
%{x: 7, y: 4, mood: "sad"},
]
|> Plot.new(%{x: :x, y: :y})
|> Plot.geom_point(%{shape: :mood}, size: 7)
|> Plot.scale_shape_manual(values: ["đ", "đ", "âšī¸"])
|> Plot.plot()
Specs
Sets geom point size for continuous data.
This scale defines a mapping function that assigns a shape area based on the given value of the mapped variable.
This function takes the following options:
:range
- a tuple with minimum (default -9
) and maximum (default -100
) values to be bound to the data
Specs
Sets geom point size for categorical data.
For categorical data for which a linear mapping of values to marker size is not
appropriate, this scale generates a palette of evenly spaced area values
between 9
and 100
that are mapped to each unique value of the data. The
palette is generated such that the difference between each size value is
maximized. The set of unique data values are sorted for the purpose of assigning
them to a size and ordering the legend.
This function also takes the following options:
:labels
- specifies how legend item names (levels of the scale) should be formatted. SeeGGity.Labels
for valid values for this option.:range
- a tuple with minimum (default -9
) and maximum (default -100
) values to be bound to the data
Specs
Sets geom point size using the value of the data mapped to the size aesthetic. Can be used to manually assign size to individual data points by including an value with each observation.
Note that "size" is the marker diameter, not marker area (which is generally preferable but not yet implemented).
See scale_color_identity/1
for an example of identity scale use.
Specs
Sets geom x coordinate for continuous numerical data.
This scale defines a mapping function that assigns a coordinate on the x axis to the value of the mapped variable. The scale also defines an inverse of this function that is used to generate axis tick labels.
This function also takes the following options:
:labels
- specifies how break names (tick labels calculated by the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
Specs
Sets geom x coordinate for continuous Date
data.
This scale defines a mapping function that assigns a coordinate on the x axis to the value of the mapped variable. The scale also defines an inverse of this function that is used to generate axis tick labels.
This function also takes the following options:
:labels
- specifies how break names (tick labels calculated by the scale) should be formatted. SeeGGity.Labels
for valid values for this option. -:date_labels
- special formatting patterns for dates. If:date_labels
is specified, the value of the:labels
option will be overridden.
:date_labels
can be either a format string pattern that is accepted by NimbleStrftime
:
data
|> Plot.new(%{x: :date_variable, y: :other_variable})
|> Plot.geom_line()
|> Plot.scale_x_date(date_labels: "%b %d %Y") # Label format "Jan 01 2001"
or a tuple {format, options}
where format
is the pattern and options
is a keyword
list of options accepted by NimbleStrftime.format/3
:
rename_weekdays = fn day_of_week ->
{
"Monday",
"Tuesday",
"Hump Day",
"Thursday",
"Friday",
"Saturday",
"Sunday"
}
|> elem(day_of_week - 1)
end
data
|> Plot.new(%{x: :date_variable, y: :other_variable})
|> Plot.geom_line()
|> Plot.scale_x_date(date_labels: {"%A", day_of_week_names: rename_weekdays})
# Ticks are just weekday names, Wednesday is Hump Day
Specs
Sets geom x coordinate for continuous DateTime
data.
This scale defines a mapping function that assigns a coordinate on the x axis to the value of the mapped variable. The scale also defines an inverse of this function that is used to generate axis tick labels.
This function also takes the following options:
:labels
- specifies how break names (tick labels calculated by the scale) should be formatted. SeeGGity.Labels
for valid values for this option. -:date_labels
- special formatting patterns for dates. If:date_labels
is specified, the value of the:labels
option will be overridden.
:date_labels
can be either a format string pattern that is accepted by NimbleStrftime
:
See scale_x_date/2
for more usage examples.
data
|> Plot.new(%{x: :datetime_variable, y: :other_variable})
|> Plot.geom_line()
|> Plot.scale_x_datetime(date_labels: "%b %d H%H") # Label format "Jan 01 H01"
Specs
Sets geom x coordinate for discrete (categorical) data.
This scale defines a mapping function that assigns a coordinate on the x axis to the value of the mapped variable. In the discrete case, this is equivalent to evenly distributing geoms across the x axis.
This function also takes the following options:
:labels
- specifies how break names (tick labels calculated by the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
Specs
Sets geom y coordinate for continuous numerical data.
This scale defines a mapping function that assigns a coordinate on the y axis to the value of the mapped variable. The scale also defines an inverse of this function that is used to generate axis tick labels.
This function also takes the following options:
:labels
- specifies how break names (tick labels calculated by the scale) should be formatted. SeeGGity.Labels
for valid values for this option.
Specs
Updates the plot theme.
GGity uses themes to style non-data plot elements. The default theme is similar to ggplot2's signature gray background/white gridline theme.
theme/2
is used to update on or more elements of the plot theme by passing
a keyword list of new elements and values, which are merged with those of the
current theme.
For supported elements and values, see GGity.Theme
.
Specs
Saves the plot to a file at the given path.
Specs
Updates the plot x axis label.
Specs
Updates the plot y axis label.