Struct GGPlot 

pub struct GGPlot { /* private fields */ }

The top-level plot specification — builder pattern.

Implementations

impl GGPlot

pub fn new(data: impl GGData) -> Self

Create a new plot with the given data source.

Never panics on malformed input: e.g. column-oriented data whose columns have different lengths is padded with NA and reported as a GGError::ValidationError by try_build and the render_*/save* methods.

pub fn aes(self, mapping: Aes) -> Self

Set the plot-level aesthetic mapping.

pub fn geom_point(self) -> Self

pub fn geom_point_with(self, geom: GeomPoint) -> Self

pub fn geom_line(self) -> Self

pub fn geom_line_with(self, geom: GeomLine) -> Self

pub fn geom_bar(self) -> Self

pub fn geom_bar_with(self, geom: GeomBar) -> Self

pub fn geom_histogram(self) -> Self

pub fn geom_histogram_with(self, geom: GeomHistogram) -> Self

pub fn geom_boxplot(self) -> Self

pub fn geom_boxplot_with(self, geom: GeomBoxplot) -> Self

pub fn geom_smooth(self) -> Self

pub fn geom_smooth_with(self, geom: GeomSmooth) -> Self

pub fn geom_col(self) -> Self

pub fn geom_col_with(self, geom: GeomCol) -> Self

pub fn geom_hline(self, yintercept: f64) -> Self

pub fn geom_hline_with(self, geom: GeomHline) -> Self

Add a horizontal reference line with custom styling (color/linetype/width).

pub fn geom_vline(self, xintercept: f64) -> Self

pub fn geom_vline_with(self, geom: GeomVline) -> Self

Add a vertical reference line with custom styling (color/linetype/width).

pub fn geom_abline(self, slope: f64, intercept: f64) -> Self

pub fn geom_abline_with(self, geom: GeomAbline) -> Self

Add a slope/intercept reference line with custom styling.

pub fn geom_text(self) -> Self

pub fn geom_text_with(self, geom: GeomText) -> Self

pub fn geom_bracket(self, xmin: &str, xmax: &str, y: f64, label: &str) -> Self

Draw a significance bracket over the plot (ggpubr::geom_bracket): a bar spanning the categorical positions xmin..xmax at height y, captioned with label (e.g. a p-value or significance stars). Pairs with a boxplot and stat_compare_means.

pub fn geom_bracket_many( self, geom: GeomBracket, brackets: &[(&str, &str, f64, &str)], ) -> Self

Draw several significance brackets at once with a configured GeomBracket. Each tuple is (xmin, xmax, y, label).

pub fn geom_label(self) -> Self

pub fn geom_label_with(self, geom: GeomLabel) -> Self

pub fn geom_area(self) -> Self

pub fn geom_area_with(self, geom: GeomArea) -> Self

pub fn geom_ribbon(self) -> Self

pub fn geom_ribbon_with(self, geom: GeomRibbon) -> Self

pub fn geom_errorbar(self) -> Self

pub fn geom_errorbar_with(self, geom: GeomErrorbar) -> Self

pub fn geom_segment(self) -> Self

pub fn geom_segment_with(self, geom: GeomSegment) -> Self

pub fn geom_density(self) -> Self

pub fn geom_density_with(self, geom: GeomDensity) -> Self

pub fn geom_rug(self) -> Self

pub fn geom_rug_with(self, geom: GeomRug) -> Self

pub fn geom_jitter(self) -> Self

pub fn geom_jitter_with(self, geom: GeomJitter) -> Self

pub fn geom_path(self) -> Self

pub fn geom_path_with(self, geom: GeomPath) -> Self

pub fn stat_ellipse(self) -> Self

Add a confidence-ellipse layer (default 95%) as a path per group.

pub fn stat_ellipse_level(self, level: f64) -> Self

Add a confidence-ellipse layer at the given level (0, 1).

pub fn geom_step(self) -> Self

pub fn geom_step_with(self, geom: GeomStep) -> Self

pub fn geom_freqpoly(self) -> Self

pub fn geom_freqpoly_with(self, geom: GeomFreqpoly) -> Self

pub fn geom_linerange(self) -> Self

pub fn geom_linerange_with(self, geom: GeomLinerange) -> Self

pub fn geom_pointrange(self) -> Self

pub fn geom_pointrange_with(self, geom: GeomPointrange) -> Self

pub fn geom_crossbar(self) -> Self

pub fn geom_crossbar_with(self, geom: GeomCrossbar) -> Self

pub fn geom_spoke(self) -> Self

pub fn geom_spoke_with(self, geom: GeomSpoke) -> Self

pub fn geom_rect(self) -> Self

pub fn geom_rect_with(self, geom: GeomRect) -> Self

pub fn geom_tile(self) -> Self

pub fn geom_tile_with(self, geom: GeomTile) -> Self

pub fn geom_raster(self) -> Self

Dense regular grid of filled cells (heatmap/raster) from x, y, fill.

pub fn geom_raster_with(self, geom: GeomRaster) -> Self

pub fn geom_polygon(self) -> Self

pub fn geom_polygon_with(self, geom: GeomPolygon) -> Self

pub fn geom_curve(self) -> Self

pub fn geom_curve_with(self, geom: GeomCurve) -> Self

pub fn geom_violin(self) -> Self

pub fn geom_violin_with(self, geom: GeomViolin) -> Self

pub fn geom_dotplot(self) -> Self

pub fn geom_dotplot_with(self, geom: GeomDotplot) -> Self

pub fn geom_qq(self) -> Self

pub fn geom_qq_with(self, geom: GeomQQ) -> Self

pub fn geom_qq_line(self) -> Self

pub fn geom_qq_line_with(self, geom: GeomQQLine) -> Self

pub fn geom_bin2d(self) -> Self

pub fn geom_bin2d_with(self, geom: GeomBin2d) -> Self

pub fn geom_hex(self) -> Self

pub fn geom_hex_with(self, geom: GeomHex) -> Self

pub fn geom_count(self) -> Self

pub fn geom_count_with(self, geom: GeomCount) -> Self

pub fn geom_contour(self) -> Self

pub fn geom_contour_with(self, geom: GeomContour) -> Self

pub fn geom_contour_filled(self) -> Self

Filled contour bands from gridded (x, y, z) data — draws polygons filled by band level. Pair with a continuous fill scale (e.g. scale_fill_viridis_c).

pub fn geom_density2d(self) -> Self

pub fn geom_density2d_with(self, geom: GeomDensity2d) -> Self

pub fn geom_candlestick(self) -> Self

Candlestick chart: map x and open/high/low/close (Aes::new().x("date").open("o").high("h").low("l").close("c")).

pub fn geom_candlestick_with(self, geom: GeomCandlestick) -> Self

pub fn geom_ohlc(self) -> Self

OHLC bar chart (high–low bar with open/close ticks); same aesthetics as geom_candlestick.

pub fn geom_ohlc_with(self, geom: GeomOhlc) -> Self

pub fn geom_calendar(self) -> Self

Calendar heatmap (GitHub/ECharts style): the plot’s x (a date — DateTime, epoch seconds or "YYYY-MM-DD") is laid out as week columns × weekday rows (Sunday on top) via StatCalendar, coloured by fill, with month labels along x, Mon/Wed/Fri along y, month boundary outlines and square cells. Spans over MAX_CALENDAR_YEARS are clipped to the most recent years (with a build warning). Uses the plot-level data and x mapping.

pub fn geom_calendar_with(self, tile: GeomTile, monday_first: bool) -> Self

geom_calendar with a custom cell style and optionally Monday-first weeks.

pub fn geom_blank(self) -> Self

pub fn stat(self, stat: impl Stat + 'static) -> Self

Override the stat for the most recently added layer.

pub fn position(self, pos: impl Position + 'static) -> Self

Override the position for the most recently added layer.

pub fn layer_data(self, data: impl GGData) -> Self

Override the data for the most recently added layer.

pub fn layer_aes(self, mapping: Aes) -> Self

Override the aesthetic mapping for the most recently added layer.

pub fn show_legend(self, show: bool) -> Self

Control whether the most recently added layer contributes to the legend. true = always show, false = always hide, default (None) = auto.

pub fn scale_x_continuous(self, s: ScaleContinuous) -> Self

pub fn scale_y_continuous(self, s: ScaleContinuous) -> Self

pub fn scale_x_discrete(self, s: ScaleDiscrete) -> Self

pub fn scale_y_discrete(self, s: ScaleDiscrete) -> Self

pub fn scale_color(self, s: impl Scale + 'static) -> Self

pub fn scale_fill(self, s: impl Scale + 'static) -> Self

pub fn scale_color_manual(self, values: Vec<(&str, RGBAColor)>) -> Self

pub fn scale_fill_manual(self, values: Vec<(&str, RGBAColor)>) -> Self

pub fn scale_color_viridis(self) -> Self

pub fn scale_color_brewer(self, name: PaletteName) -> Self

pub fn scale_color_gradient(self, low: RGBAColor, high: RGBAColor) -> Self

pub fn scale_fill_gradient(self, low: RGBAColor, high: RGBAColor) -> Self

pub fn scale_color_gradient2( self, low: RGBAColor, mid: RGBAColor, high: RGBAColor, ) -> Self

pub fn scale_fill_gradient2( self, low: RGBAColor, mid: RGBAColor, high: RGBAColor, ) -> Self

pub fn scale_fill_viridis(self) -> Self

pub fn scale_color_viridis_c(self) -> Self

Continuous viridis color scale (for numeric data).

pub fn scale_fill_viridis_c(self) -> Self

Continuous viridis fill scale (for numeric data).

pub fn scale_color_gradientn(self, stops: Vec<(f64, RGBAColor)>) -> Self

N-stop continuous color gradient.

pub fn scale_fill_gradientn(self, stops: Vec<(f64, RGBAColor)>) -> Self

N-stop continuous fill gradient.

pub fn scale_color_steps( self, low: RGBAColor, high: RGBAColor, n_bins: usize, ) -> Self

Binned (stepped) two-colour continuous colour scale — buckets the mapped variable into n_bins bins, each a discrete colour, with a stepped legend.

pub fn scale_color_stepsn(self, stops: Vec<RGBAColor>, n_bins: usize) -> Self

Binned N-stop continuous colour scale.

pub fn scale_color_fermenter(self, name: PaletteName, n_bins: usize) -> Self

Binned ColorBrewer colour scale (R’s scale_color_fermenter).

pub fn scale_fill_steps( self, low: RGBAColor, high: RGBAColor, n_bins: usize, ) -> Self

Binned (stepped) two-colour continuous fill scale.

pub fn scale_fill_fermenter(self, name: PaletteName, n_bins: usize) -> Self

Binned ColorBrewer fill scale.

pub fn scale_fill_discrete_sorted(self) -> Self

Default discrete fill palette with levels in sorted order, so a level keeps its colour across charts regardless of data order. For a custom palette: scale_fill(ScaleColorDiscrete::new(Aesthetic::Fill) .with_palette(p).sorted()).

pub fn scale_color_discrete_sorted(self) -> Self

Default discrete colour palette with levels in sorted order (see scale_fill_discrete_sorted).

pub fn scale_fill_brewer(self, name: PaletteName) -> Self

pub fn scale_linetype_manual(self, values: Vec<(&str, Linetype)>) -> Self

pub fn scale_shape_manual(self, values: Vec<(&str, PointShape)>) -> Self

pub fn scale_color_grey(self) -> Self

pub fn scale_fill_grey(self) -> Self

pub fn scale_color_grey_with(self, s: ScaleColorGrey) -> Self

pub fn scale_fill_grey_with(self, s: ScaleColorGrey) -> Self

pub fn scale_x_reverse(self) -> Self

pub fn scale_y_reverse(self) -> Self

pub fn scale_x_datetime(self, s: ScaleDateTime) -> Self

pub fn scale_y_datetime(self, s: ScaleDateTime) -> Self

pub fn scale_size(self, s: ScaleSizeContinuous) -> Self

pub fn scale_alpha(self, s: ScaleAlphaContinuous) -> Self

pub fn xlim(self, min: f64, max: f64) -> Self

pub fn ylim(self, min: f64, max: f64) -> Self

pub fn scale_x_log10(self) -> Self

pub fn scale_y_log10(self) -> Self

pub fn scale_x_sqrt(self) -> Self

pub fn scale_y_sqrt(self) -> Self

pub fn scale_x_log2(self) -> Self

pub fn scale_y_log2(self) -> Self

pub fn scale_x_ln(self) -> Self

pub fn scale_y_ln(self) -> Self

pub fn scale_x_logit(self) -> Self

Logit-transformed x axis (for proportions in (0, 1)).

pub fn scale_y_logit(self) -> Self

pub fn scale_x_probit(self) -> Self

Probit-transformed x axis (inverse normal CDF, for proportions in (0, 1)).

pub fn scale_y_probit(self) -> Self

pub fn scale_x_pseudo_log(self) -> Self

Sign-preserving pseudo-log x axis (handles zero and negative values).

pub fn scale_y_pseudo_log(self) -> Self

pub fn scale_x_reciprocal(self) -> Self

Reciprocal (1/x) x axis.

pub fn scale_y_reciprocal(self) -> Self

pub fn scale_x_exp(self) -> Self

Exponential x axis (labels spaced logarithmically).

pub fn scale_y_exp(self) -> Self

pub fn scale_x_boxcox(self, lambda: f64) -> Self

Box–Cox x axis with the given lambda (x > 0).

pub fn scale_y_boxcox(self, lambda: f64) -> Self

pub fn facet_wrap(self, var: &str, ncol: Option<usize>) -> Self

pub fn facet_wrap_free( self, var: &str, ncol: Option<usize>, scales: FacetScales, ) -> Self

pub fn facet_wrap_labeller( self, var: &str, ncol: Option<usize>, labeller: FacetLabeller, ) -> Self

pub fn facet_grid(self, row: Option<&str>, col: Option<&str>) -> Self

pub fn facet_grid_free( self, row: Option<&str>, col: Option<&str>, scales: FacetScales, ) -> Self

pub fn facet_grid_multi( self, row: Option<&str>, cols: &[&str], scales: FacetScales, space: FacetSpace, ) -> Self

facet_grid over multiple column variables (R’s rows ~ b + c): the columns become the combination of the given variables’ values. Also accepts free scales + proportional space for full parity.

pub fn facet_grid_space( self, row: Option<&str>, col: Option<&str>, scales: FacetScales, space: FacetSpace, ) -> Self

facet_grid with proportional panel sizing (R’s space =): panels are sized to their data range. Typically paired with free scales.

pub fn facet_grid_labeller( self, row: Option<&str>, col: Option<&str>, labeller: FacetLabeller, ) -> Self

pub fn coord_flip(self) -> Self

pub fn coord_fixed(self, ratio: f64) -> Self

pub fn coord_trans( self, x: Option<ScaleTransform>, y: Option<ScaleTransform>, ) -> Self

Transform the coordinate space at draw time (R’s coord_trans) — stats are computed on raw data but drawn on non-linear axes. Pass a per-axis ScaleTransform (e.g. Some(ScaleTransform::Log10)), None to leave an axis linear.

pub fn coord_trans_y(self, y: ScaleTransform) -> Self

coord_trans on the y-axis only.

pub fn coord_trans_x(self, x: ScaleTransform) -> Self

coord_trans on the x-axis only.

pub fn coord_cartesian_zoom( self, xlim: Option<(f64, f64)>, ylim: Option<(f64, f64)>, ) -> Self

Zoom into a region without filtering data (unlike xlim/ylim which filter).

pub fn coord_polar(self) -> Self

pub fn coord_radar(self) -> Self

Radar / spider chart coordinates: discrete x → spokes, y → distance from the centre, straight segments, ring/spoke guides. Pair with geom_polygon (closed series) and geom_point.

pub fn coord_radar_with(self, coord: CoordRadar) -> Self

pub fn coord_polar_with(self, coord: CoordPolar) -> Self

pub fn theme(self, theme: Theme) -> Self

Replace the theme. A primary_color set earlier is kept unless the new theme sets its own, so preset/primary_color call order doesn’t matter.

pub fn axis_text_x_angle(self, degrees: f64) -> Self

Rotate the x-axis tick labels by degrees (R’s guides(x = guide_axis(angle = ...)) / axis.text.x = element_text(angle)). Useful for long category labels. Call after any theme_*() preset.

pub fn axis_text_y_angle(self, degrees: f64) -> Self

Rotate the y-axis tick labels by degrees.

pub fn axis_text_x_dodge(self, n: usize) -> Self

Stagger x-axis tick labels across n rows to avoid overlap (R’s guides(x = guide_axis(n.dodge = n))). 1 = no dodging.

pub fn aspect_ratio(self, ratio: f64) -> Self

Fix the panel’s height:width ratio (R’s aspect.ratio). Call after any theme_*() preset.

pub fn panel_ontop(self) -> Self

Draw gridlines on top of the data layers (R’s panel.ontop).

pub fn axis_minor_ticks(self) -> Self

Draw minor tick marks between major ticks (R’s axis.minor.ticks).

pub fn title_position(self, pos: TitlePosition) -> Self

Align title/subtitle/caption to the panel or the whole plot width (R’s plot.title.position).

pub fn tag_position(self, pos: TagPosition) -> Self

Corner for the tag() label (R’s plot.tag.position).

pub fn legend_direction(self, dir: LegendDirection) -> Self

Force the legend key layout direction (R’s legend.direction).

pub fn legend_position_inside(self, x: f64, y: f64) -> Self

Set the brand/primary color used as the default for single-series geoms that have no color/fill aesthetic mapped. Composes with any theme — one render process can serve different tenants’ brands at render time. Place the legend inside the panel at panel-relative coordinates (0..1, 0..1) — (0,0) bottom-left, (1,1) top-right (R’s legend.position = c(x, y)).

pub fn legend_position(self, pos: LegendPosition) -> Self

Set the legend position (R’s legend.position, e.g. Top/Bottom).

pub fn primary_color(self, color: (u8, u8, u8)) -> Self

pub fn theme_minimal(self) -> Self

pub fn theme_bw(self) -> Self

pub fn theme_gray(self) -> Self

pub fn theme_classic(self) -> Self

pub fn theme_pubr(self) -> Self

Apply the publication-ready theme_pubr() (ggpubr style).

pub fn theme_linedraw(self) -> Self

pub fn theme_light(self) -> Self

pub fn theme_dark(self) -> Self

pub fn theme_void(self) -> Self

pub fn theme_update(self, update: ThemeUpdate) -> Self

Apply incremental theme modifications on top of the current theme. Like R’s + theme(axis.text.x = element_text(...)).

pub fn guides(self, guide: GuideLegend) -> Self

Configure legend guide (title, ncol, reverse).

pub fn labs(self, labels: Labels) -> Self

pub fn title(self, title: &str) -> Self

pub fn tag(self, tag: &str) -> Self

Corner tag label (R’s labs(tag = ...)), drawn at the top-left — handy for labelling figure panels (“A”, “B”, …).

pub fn subtitle(self, subtitle: &str) -> Self

pub fn xlab(self, label: &str) -> Self

pub fn ylab(self, label: &str) -> Self

pub fn caption(self, caption: &str) -> Self

pub fn annotate(self, annotation: Annotation) -> Self

Add an annotation to the plot.

pub fn annotate_text(self, label: &str, x: f64, y: f64) -> Self

Add a text annotation at data coordinates.

pub fn annotate_rect(self, xmin: f64, xmax: f64, ymin: f64, ymax: f64) -> Self

Add a rectangle annotation at data coordinates.

pub fn annotate_segment(self, x: f64, y: f64, xend: f64, yend: f64) -> Self

Add a segment annotation between data coordinates.

pub fn try_build(self) -> Result<BuiltPlot, GGError>

Build the plot without rendering, returning errors on validation failure.

pub fn build(self) -> BuiltPlot

Build the plot without rendering (analogous to R’s ggplot_build()). Returns the fully computed BuiltPlot with layer data ready for inspection. Panics on validation errors — use try_build() for error handling.

pub fn save(self, path: &str) -> Result<(), GGError>

Build and save the plot to a file. Format determined by extension. (Requires the plotters feature, on by default; native only — wasm has no filesystem/plotters backend.)

pub fn save_with_size(self, path: &str, w: u32, h: u32) -> Result<(), GGError>

Build and save with custom dimensions. (Feature plotters; native only.)

pub fn render_svg(self) -> Result<String, GGError>

Render the plot to an in-memory SVG document (default 800x600).

Unlike save, this writes nothing to disk — handy for serving charts from a web/MCP service. Requires the plotters feature (on by default); without it use render_svg_native.

pub fn render_svg_with_size(self, w: u32, h: u32) -> Result<String, GGError>

Render the plot to an in-memory SVG document with custom dimensions. (Feature plotters; native only — on wasm or without plotters use render_svg_native_with_size.)

pub fn render_svg_native(self) -> Result<String, GGError>

Render to SVG through the self-contained SvgBackend — a plotters-free path that drives the same PlotRenderer, proving the DrawBackend abstraction (and needing no glyph rasterization).

pub fn render_svg_native_with_size( self, w: u32, h: u32, ) -> Result<String, GGError>

render_svg_native with an explicit size.

The root <svg> carries data-plot="x y w h" (the panel rect) and the trained position domains (data-domain, data-xdomain, data-ydomain, data-xlevels, data-ylevels — see root_data_attrs). Hoverable marks carry data-x, data-series and data-value.

pub fn render_svg_native_with_warnings( self, w: u32, h: u32, ) -> Result<(String, Vec<String>), GGError>

Like render_svg_native_with_size, but also returns the build warnings (rows dropped for non-finite positions, layers whose stat produced no data, …) — see BuiltPlot::warnings.

pub fn render_svg_native_at( self, x: f64, y: f64, w: u32, h: u32, ) -> Result<String, GGError>

Render a w×h chart as a nested <svg x=.. y=.. width=.. height=.. viewBox="0 0 w h"> fragment for composition into a larger SVG (a dashboard): no xmlns (inherited from the parent), positioned at (x, y) in the parent’s user space. No string surgery needed:

let mut page = String::from(r#"<svg xmlns="http://www.w3.org/2000/svg" width="900" height="400">"#);
page += &plot_a.render_svg_native_at(0.0, 0.0, 450, 400)?;
page += &plot_b.render_svg_native_at(450.0, 0.0, 450, 400)?;
page += "</svg>";

pub fn render_svg_area_with_size( self, w: u32, h: u32, ) -> Result<(String, [f64; 4]), GGError>

Like render_svg_native_with_size, but also returns the panel rect in pixels [x, y, w, h] — enough to overlay a WebGL/canvas layer that draws marks in data coordinates.

pub fn render_png(self) -> Result<Vec<u8>, GGError>

Render the plot to in-memory PNG bytes (default 800x600).

Returns a fully-encoded PNG, ready to write to an HTTP response or embed as a data URI — no temp files involved. Requires the plotters feature (on by default); see also render_png_raster_with_size (feature canvas).

pub fn render_png_with_size(self, w: u32, h: u32) -> Result<Vec<u8>, GGError>

Render the plot to in-memory PNG bytes with custom dimensions. (Feature plotters; native only — PNG needs the plotters bitmap backend.)

pub fn ggsave( self, path: &str, width_inches: f64, height_inches: f64, dpi: f64, ) -> Result<(), GGError>

Save with physical dimensions (inches) and DPI. (Feature plotters; native only.)