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 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
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
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.
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. Seegeom_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 theGGity.Stat
module that is to be applied to the data. Defaults to:count
(see above).
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. Seegeom_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 to2
.
GGity uses method "Type 7" to calculate percentiles, in conformance with the default used by R.
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.
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.
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 theGGity.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.
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
.
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. Seegeom_point/3
for a more explanation of the:custom_attributes
option.: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
.
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
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.
@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 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
.
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.
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
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
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.
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
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
.
Sets fill color for fillable shapes (e.g., bars).
Accepts the same options as scale_color_viridis/2
.
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.
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.
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()
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
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.
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.
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
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"
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.
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.
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
.
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.