View Source GGity.Plot (GGity v0.5.0)

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. Text elements (e.g. the plot title, axis labels, legend labels) are escaped using the logic from Plug.HTML, but other values are not, so users still need to be mindful of the risks of generating plots using user-supplied data or parameters.

Link to this section Summary

Functions

Adds geoms to a plot from raw data.

Adds a ribbon geom to the plot with the position: :stack option set.

Adds a bar geom to the plot.

Adds a boxplot 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 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.

Convenience method that returns an IO List with an XML declaration, in order to support output to a standalone .svg file. Plot.to_xml/2 takes a second argument specifying a fixed height for the SVG element. A fixed width is also added, equal to the height multiplied by the plot's aspect ration.

Updates the plot x axis label.

Updates the plot y axis label.

Link to this section Types

@type column() :: list()
@type mapping() :: map()
@type name() :: binary() | atom()
@type options() :: keyword()
@type record() :: map()
@type t() :: %GGity.Plot{
  area_padding: term(),
  aspect_ratio: term(),
  breaks: term(),
  combined_layers: term(),
  data: term(),
  labels: term(),
  layers: term(),
  limits: term(),
  mapping: term(),
  margins: term(),
  scales: term(),
  theme: term(),
  title_margin: term(),
  width: term(),
  y_label_padding: term()
}

Link to this section Functions

Link to this function

annotate(plot, geom_type, data)

View Source
@spec annotate(t(), atom(), keyword()) :: t()

Adds geoms to a plot from raw data.

annotate/3 can be used to add annotations to a plot. The function takes a plot, a type of geom and a keyword list of values and options. The keyword list must include values for the aesthetics required to draw the geom, and can also include any other options that could be passed to constructor for that geom.

Supported geoms and required aesthetics include:

  • :text - :x, :y, :label
Link to this function

geom_area(plot, mapping \\ [], options \\ [])

View Source
@spec geom_area(t(), map() | keyword(), keyword()) :: t()

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.

Link to this function

geom_bar(plot, mapping \\ [], options \\ [])

View Source
@spec geom_bar(t(), map() | keyword(), keyword()) :: t()

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 additional 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:

  • :custom_attributes - a function that takes two arguments: first, the Plot struct, and second, the data record (a map - note that this is the data AFTER the statistical transformation has been supplied) to be mapped to the bar geom. The function must return a keyword list of property-value pairs, which are added to the point element drawn in the generated SVG. This can be used to add Phoenix event handlers or any other attributes based on characteristic of the plot and the data being mapped to the geom. See geom_point/3 for a more explanation of the :custom_attributes option.

  • :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 the GGity.Stat module that is to be applied to the data. Defaults to :count (see above).

Link to this function

geom_boxplot(plot, mapping \\ [], options \\ [])

View Source
@spec geom_boxplot(t(), map() | keyword(), keyword()) :: t()

Adds a boxplot 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 additional 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, for example.

Boxplot geoms support mapping data to the following aesthetics, which use the noted scales:

  • :x (required - should be a discrete variable)
  • :y (required - the value for which percentile statistics are calculated)
  • :alpha
  • :color
  • :fill

geom_boxplot/3 uses the :boxplot stat, which calculates the following for the variable mapped to the :y aesthetic:

  • 25th and 75th percentiles (the y-coordinates of the top and bottom of the box)
  • median (the y-coordinate of the line in the middle of the box)
  • "ymin" and "ymax" (the outlying y-coordinates of the vertical lines extending from the top and bottom of each box.

"ymin" and "ymax" represent the range of values between the 25th/75th percentiles minus/plus 1.58 multiplied by the interquartile range, respectively. The interquartile range is the difference between the 75th and 25th percentile values.

Values mapped to :y that are less than "ymin" or greater than "ymax" ("outiers") are plotted as individual points.

Other supported options:

  • :custom_attributes - a function that takes two arguments: first, the Plot struct, and second, the data record (a map - note that this is the data AFTER the statistical transformation has been supplied) to be mapped to the boxplot geom. The function must return a keyword list of property-value pairs, which are added to the point element drawn in the generated SVG. This can be used to add Phoenix event handlers or any other attributes based on characteristic of the plot and the data being mapped to the geom. See geom_point/3 for a more explanation of the :custom_attributes option.

  • :outlier_color - color of outlier points. Defaults to "black".

  • :outlier_shape - shape of outlier points (:circle, :triangle, :square, :diamond) Defaults to :circle. Setting this value to :na omits the outliers from the plot entirely.

  • :outlier_size - size of outlier points. Defaults to 2.

GGity uses method "Type 7" to calculate percentiles, in conformance with the default used by R.

Link to this function

geom_col(plot, mapping \\ [], options \\ [])

View Source
@spec geom_col(t(), map() | keyword(), keyword()) :: t()

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.

Link to this function

geom_line(plot, mapping \\ [], options \\ [])

View Source
@spec geom_line(t(), map() | keyword(), keyword()) :: t()

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 additional 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.
Link to this function

geom_point(plot, mapping \\ [], options \\ [])

View Source
@spec geom_point(t(), map() | keyword(), keyword()) :: t()

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 additional 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:

  • :custom_attributes - a function that takes two arguments: first, the Plot struct, and second, the data record (a map) to be mapped to the point geom. The function must return a keyword list of property-value pairs, which are added to the point element drawn in the generated SVG. This can be used to add Phoenix event handlers or any other attributes based on characteristic of the plot and the data being mapped to the geom.

  • :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 the GGity.Stat module that is to be applied to the data. Defaults to :identity (i.e., no transformation).

custom-attributes

Custom Attributes

Custom attributes are a powerful hook for interactivity. For example, to add a simple javascript alert based tooltip:

Plot.new(data, %{x: "x", y: "y"})
|> Plot.geom_point(
  custom_attributes: fn plot, row ->
    [onclick: "alert('#{plot.labels.x}: #{row["x"]}')"]
  end
)
# I hope the plot x-axis label is trusted data...

or a Phoenix LiveView event handler:

Plot.new(data, %{x: "x", y: "y"})
|> Plot.geom_point(
  custom_attributes: fn _plot, row ->
    [phx_click: "filter_by_y", phx_value_y: row["y"]]
  end
)

The values (but not the keys) generated are HTML-escaped but otherwise not sanitized; users should be mindful of the risks of using untrusted data to generate custom attribute values.

Link to this function

geom_ribbon(plot, mapping \\ [], options \\ [])

View Source
@spec geom_ribbon(t(), map() | keyword(), keyword()) :: t()

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 additional 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 :position is set to :stack.

Link to this function

geom_text(plot, mapping \\ [], options \\ [])

View Source
@spec geom_text(t(), map() | keyword(), keyword()) :: t()

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 position adjustment for the text geom as that specified for the bar chart.

Accepts a mapping and/or additional 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:

  • :custom_attributes - a function that takes two arguments: first, the Plot struct, and second, the data record (a map) to be mapped to the text geom. The function must return a keyword list of property-value pairs, which are added to the point element drawn in the generated SVG. This can be used to add Phoenix event handlers or any other attributes based on characteristic of the plot and the data being mapped to the geom. See geom_point/3 for a more explanation of the :custom_attributes option.

  • :family - The font family used to display the text; equivalent to the SVG font-family attribute. Defaults to "Helvetica, Arial, sans-serif".

  • :fontface - Equivalent to SVG font-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 to 0.

  • :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 to 1.

  • :stat - an atom referring to a statistical transformation function in the GGity.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.

@spec guides(
  t(),
  keyword()
) :: t()

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

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
@spec labs(
  t(),
  keyword()
) :: t()

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.

Link to this function

new(data, mapping \\ %{}, options \\ [])

View Source
@spec new([record()] | Explorer.DataFrame.t(), mapping(), keyword()) :: t()

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 to 10.

  • :aspect_ratio - the ratio of the plot area height to :width. Defaults to 1.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 to 5.

  • :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). A nil 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 to 20.

@spec plot(t()) :: iolist()

Generates an iolist of SVG markup representing a Plot.

SVG text elements (e.g. the plot title, axis labels, legend labels) are escaped using the logic from Plug.HTML, but other values are not, so users need to be mindful of the risks of generating plots using user-supplied data or parameters.

The SVG's viewBox is set by the plot's :width and :aspect_ratio values.

Link to this function

scale_alpha_continuous(plot, options \\ [])

View Source
@spec scale_alpha_continuous(
  t(),
  keyword()
) :: t()

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
Link to this function

scale_alpha_discrete(plot, options \\ [])

View Source
@spec scale_alpha_discrete(
  t(),
  keyword()
) :: t()

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. See GGity.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

Link to this function

scale_alpha_identity(plot)

View Source
@spec scale_alpha_identity(t()) :: t()

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.

Link to this function

scale_color_identity(plot)

View Source
@spec scale_color_identity(t()) :: t()

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
Link to this function

scale_color_viridis(plot, options \\ [])

View Source
@spec scale_color_viridis(
  t(),
  keyword()
) :: t()

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. See GGity.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.

Link to this function

scale_fill_viridis(plot, options \\ [])

View Source
@spec scale_fill_viridis(
  t(),
  keyword()
) :: t()

Sets fill color for fillable shapes (e.g., bars).

Accepts the same options as scale_color_viridis/2.

Link to this function

scale_label_identity(plot)

View Source
@spec scale_label_identity(t()) :: t()
Link to this function

scale_linetype_discrete(plot, options \\ [])

View Source
@spec scale_linetype_discrete(
  t(),
  keyword()
) :: t()

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. See GGity.Labels for valid values for this option.
Link to this function

scale_shape(plot, options \\ [])

View Source
@spec scale_shape(
  t(),
  keyword()
) :: t()

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. See GGity.Labels for valid values for this option.
Link to this function

scale_shape_manual(plot, options \\ [])

View Source
@spec scale_shape_manual(
  t(),
  keyword()
) :: t()

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. See GGity.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()
Link to this function

scale_size(plot, options \\ [])

View Source
@spec scale_size(
  t(),
  keyword()
) :: t()

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
Link to this function

scale_size_identity(plot)

View Source
@spec scale_size_identity(t()) :: t()

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.

Link to this function

scale_x_continuous(plot, options \\ [])

View Source
@spec scale_x_continuous(
  t(),
  keyword()
) :: t()

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. See GGity.Labels for valid values for this option.
Link to this function

scale_x_date(plot, options \\ [])

View Source
@spec scale_x_date(
  t(),
  keyword()
) :: t()

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. See GGity.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
Link to this function

scale_x_datetime(plot, options \\ [])

View Source
@spec scale_x_datetime(
  t(),
  keyword()
) :: t()

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. See GGity.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"
Link to this function

scale_x_discrete(plot, options \\ [])

View Source
@spec scale_x_discrete(
  t(),
  keyword()
) :: t()

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. See GGity.Labels for valid values for this option.
Link to this function

scale_y_continuous(plot, options \\ [])

View Source
@spec scale_y_continuous(
  t(),
  keyword()
) :: t()

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. See GGity.Labels for valid values for this option.
@spec theme(
  t(),
  keyword()
) :: t()

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.

@spec to_xml(t()) :: iolist()

Convenience method that returns an IO List with an XML declaration, in order to support output to a standalone .svg file. Plot.to_xml/2 takes a second argument specifying a fixed height for the SVG element. A fixed width is also added, equal to the height multiplied by the plot's aspect ration.

@spec to_xml(t(), number()) :: iolist()
@spec xlab(t(), binary()) :: t()

Updates the plot x axis label.

@spec ylab(t(), binary()) :: t()

Updates the plot y axis label.