Struct Axes 

pub struct Axes { /* private fields */ }

A single set of axes within a figure, containing chart artists and configuration.

Users do not construct Axes directly; they are created by [Figure::add_subplot] or the convenience function [Figure::subplots]. Once an Axes handle is obtained, chart methods such as plot, scatter, and bar add data, and configuration methods like set_title control labels, limits, and styling.

Implementations

impl Axes

pub fn is_twin(&self) -> bool

Returns true if this axes is a twin of another axes.

pub fn twin_side(&self) -> Option<TwinSide>

Returns the twin side, if this axes is a twin.

impl Axes

pub fn plot<X, Y>(&mut self, x: X, y: Y) -> Result<&mut LineArtist>

where X: IntoSeries, Y: IntoSeries,

Plots a line connecting (x, y) data points.

Returns a mutable reference to the newly created LineArtist so that the caller can chain builder methods (.color(), .width(), .label(), etc.).

Errors

Returns PlotError::SeriesLengthMismatch if x and y have different lengths, or PlotError::EmptyData if either is empty.

pub fn scatter<X, Y>(&mut self, x: X, y: Y) -> Result<&mut ScatterArtist>

where X: IntoSeries, Y: IntoSeries,

Creates a scatter plot of (x, y) data points.

Returns a mutable reference to the ScatterArtist for chaining.

Errors

Returns PlotError::SeriesLengthMismatch or PlotError::EmptyData on invalid input.

pub fn bar<C, H>(&mut self, categories: C, heights: H) -> Result<&mut BarArtist>

where C: IntoCategories, H: IntoSeries,

Creates a vertical bar chart from categorical data and heights.

Each category label maps to one bar whose height is the corresponding value in heights.

Errors

Returns PlotError::SeriesLengthMismatch if categories and heights have different lengths, or PlotError::EmptyData if empty.

pub fn barh<C, W>(&mut self, categories: C, widths: W) -> Result<&mut BarArtist>

where C: IntoCategories, W: IntoSeries,

Creates a horizontal bar chart from categorical data and widths.

Behaves like bar but draws horizontal bars from the y-axis.

Errors

Same as bar.

pub fn hist<D>(&mut self, data: D, bins: usize) -> Result<&mut HistArtist>

where D: IntoSeries,

Creates a histogram from raw data.

The data is partitioned into bins equal-width bins spanning the data range, and each bin is drawn as a vertical bar whose height equals the count of values falling in that bin.

Errors

Returns PlotError::EmptyData if data is empty.

pub fn fill_between<X, Y1, Y2>( &mut self, x: X, y1: Y1, y2: Y2, ) -> Result<&mut FillBetweenArtist>

where X: IntoSeries, Y1: IntoSeries, Y2: IntoSeries,

Fills the area between two y-series that share the same x values.

Useful for confidence intervals, envelopes, and area charts.

Errors

Returns PlotError::SeriesLengthMismatch if any of the three series differ in length, or PlotError::EmptyData if empty.

pub fn step<X: IntoSeries, Y: IntoSeries>( &mut self, x: X, y: Y, ) -> Result<&mut StepArtist>

Plots a step (staircase) chart connecting (x, y) data points.

Returns a mutable reference to the StepArtist for chaining.

Errors

Returns PlotError::SeriesLengthMismatch or PlotError::EmptyData on invalid input.

pub fn stem<X: IntoSeries, Y: IntoSeries>( &mut self, x: X, y: Y, ) -> Result<&mut StemArtist>

Plots a stem (lollipop) chart from (x, y) data points.

Returns a mutable reference to the StemArtist for chaining.

Errors

Returns PlotError::SeriesLengthMismatch or PlotError::EmptyData on invalid input.

pub fn boxplot(&mut self, datasets: Vec<Vec<f64>>) -> Result<&mut BoxPlotArtist>

Creates a box-and-whisker plot from one or more data groups.

Each inner Vec<f64> produces one box. Groups are placed at integer x-positions starting from 0.

Errors

Returns PlotError::EmptyData if datasets is empty.

pub fn errorbar<X: IntoSeries, Y: IntoSeries>( &mut self, x: X, y: Y, ) -> Result<ErrorBarArtist>

Creates an error bar plot from (x, y) data points.

Returns an owned ErrorBarArtist that can be configured with builder methods (.yerr_symmetric(), .cap_size(), etc.) and then added to the axes via add_errorbar.

Errors

Returns PlotError::SeriesLengthMismatch or PlotError::EmptyData on invalid input.

pub fn add_errorbar(&mut self, artist: ErrorBarArtist)

Adds a finalized ErrorBarArtist to the axes.

Use this after configuring the artist returned by errorbar.

pub fn heatmap(&mut self, data: Vec<Vec<f64>>) -> Result<&mut HeatmapArtist>

Creates a heatmap from a 2D grid of values.

Returns a mutable reference to the HeatmapArtist for chaining builder methods (.colormap(), .vmin(), .show_values(), etc.).

Errors

Returns PlotError::EmptyData if data is empty.

pub fn pie<S: IntoSeries>(&mut self, sizes: S) -> Result<&mut PieArtist>

Creates a pie chart from wedge sizes.

The sizes are automatically normalised so that all wedges sum to a full circle. Returns a mutable reference to the PieArtist for chaining builder methods (.labels(), .autopct(), .explode(), etc.).

Errors

Returns PlotError::EmptyData if sizes is empty.

impl Axes

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

Sets the title displayed above the axes area.

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

Sets the x-axis label.

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

Sets the y-axis label.

pub fn set_xlim(&mut self, min: f64, max: f64) -> &mut Self

Sets explicit x-axis limits. Pass (min, max).

pub fn set_ylim(&mut self, min: f64, max: f64) -> &mut Self

Sets explicit y-axis limits. Pass (min, max).

pub fn set_xscale(&mut self, scale: Scale) -> &mut Self

Sets the x-axis scale (linear, log10, symlog).

pub fn set_yscale(&mut self, scale: Scale) -> &mut Self

Sets the y-axis scale (linear, log10, symlog).

pub fn grid(&mut self, show: bool) -> &mut Self

Enables or disables grid lines on this axes.

pub fn legend(&mut self) -> &mut Self

Enables the legend on this axes.

pub fn set_legend_loc(&mut self, loc: Loc) -> &mut Self

Sets the legend location.

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

Overrides the figure theme for this axes only.

pub fn grid_axis(&mut self, axis: &str) -> &mut Self

Sets which axes display grid lines.

Accepts "x", "y", or "both" (the default). Unrecognised values are silently treated as "both".

pub fn grid_alpha(&mut self, alpha: f64) -> &mut Self

Sets the grid line opacity (0.0 = fully transparent, 1.0 = fully opaque).

pub fn grid_style(&mut self, style: LineStyle) -> &mut Self

Sets the grid line style.

pub fn invert_xaxis(&mut self) -> &mut Self

Inverts the x-axis so that larger values appear on the left.

pub fn invert_yaxis(&mut self) -> &mut Self

Inverts the y-axis so that larger values appear at the bottom.

pub fn set_xticks(&mut self, ticks: &[f64]) -> &mut Self

Sets custom tick positions on the x-axis.

When set, the auto-generated ticks are replaced by these positions.

pub fn set_yticks(&mut self, ticks: &[f64]) -> &mut Self

Sets custom tick positions on the y-axis.

When set, the auto-generated ticks are replaced by these positions.

pub fn set_xticklabels(&mut self, labels: &[&str]) -> &mut Self

Sets custom tick labels for the x-axis.

The number of labels should match the number of custom tick positions set via set_xticks. Extra labels are ignored; missing labels default to the formatted tick value.

pub fn set_yticklabels(&mut self, labels: &[&str]) -> &mut Self

Sets custom tick labels for the y-axis.

The number of labels should match the number of custom tick positions set via set_yticks. Extra labels are ignored; missing labels default to the formatted tick value.

pub fn tick_params_x_rotation(&mut self, degrees: f64) -> &mut Self

Sets the rotation angle (in degrees) for x-axis tick labels.

pub fn tick_params_y_rotation(&mut self, degrees: f64) -> &mut Self

Sets the rotation angle (in degrees) for y-axis tick labels.

pub fn text(&mut self, x: f64, y: f64, text: &str) -> &mut TextAnnotation

Places a text label at data coordinates (x, y).

Returns a mutable reference to the TextAnnotation for builder-style configuration (.fontsize(), .color(), .ha(), .va(), .rotation()).

Text annotations do not affect autoscale; they annotate existing data without expanding the axis limits.

pub fn annotate( &mut self, text: &str, xy: (f64, f64), xytext: (f64, f64), ) -> &mut Annotation

Annotates the data point xy with text placed at xytext.

Returns a mutable reference to the Annotation for builder-style configuration (.fontsize(), .color(), .ha(), .va(), .arrowstyle(), .arrow_color()).

When an ArrowStyle other than ArrowStyle::None is set, an arrow is drawn from xytext to xy. Annotations do not affect autoscale.

impl Axes

pub fn colorbar( &mut self, cmap: Colormap, vmin: f64, vmax: f64, ) -> &mut Colorbar

Adds a colorbar to this axes.

impl Axes

pub fn contour( &mut self, x: &[f64], y: &[f64], z: Vec<Vec<f64>>, ) -> Result<&mut ContourArtist>

Creates a contour plot (iso-lines) from a 2D grid of z values.

pub fn contourf( &mut self, x: &[f64], y: &[f64], z: Vec<Vec<f64>>, ) -> Result<&mut ContourArtist>

Creates a filled contour plot from a 2D grid of z values.

pub fn violin(&mut self, datasets: Vec<Vec<f64>>) -> Result<&mut ViolinArtist>

Creates a violin plot from one or more datasets.

pub fn bar_group<C: IntoCategories>( &mut self, categories: C, series: &[(&str, Vec<f64>)], ) -> Result<()>

Creates grouped (side-by-side) bars for multiple series.

series is a slice of (label, heights) pairs. Each series gets bars placed side-by-side within each category.

pub fn hexbin<X, Y>(&mut self, x: X, y: Y) -> Result<&mut HexbinArtist>

where X: IntoSeries, Y: IntoSeries,

Creates a hexagonal binning plot from (x, y) data points.

Returns a mutable reference to the HexbinArtist for chaining builder methods (.gridsize(), .colormap(), .mincnt(), etc.).

Errors

Returns PlotError::EmptyData if x or y is empty. Returns PlotError::SeriesLengthMismatch if x and y differ in length.

pub fn polar_plot<T, R>(&mut self, theta: T, r: R) -> Result<&mut PolarArtist>

where T: IntoSeries, R: IntoSeries,

Creates a polar line plot from (theta, r) data in polar coordinates.

theta contains angles in radians, r contains the corresponding radial distances. The data is drawn as a connected polyline in polar space.

Returns a mutable reference to the PolarArtist for chaining.

Errors

Returns PlotError::SeriesLengthMismatch if theta and r have different lengths, or PlotError::EmptyData if either is empty.

pub fn polar_fill<T, R>(&mut self, theta: T, r: R) -> Result<&mut PolarArtist>

where T: IntoSeries, R: IntoSeries,

Creates a filled polar (radar/area) chart from (theta, r) data.

Like polar_plot, but the path is automatically closed and filled, producing a radar or area chart.

Errors

Returns PlotError::SeriesLengthMismatch if theta and r have different lengths, or PlotError::EmptyData if either is empty.

pub fn waterfall<C, V>( &mut self, categories: C, values: V, ) -> Result<&mut WaterfallArtist>

where C: IntoCategories, V: IntoSeries,

Creates a waterfall chart from categorical data and change values.

Each bar represents an incremental change (positive or negative) from the previous running total. Positive changes are colored green, negative changes red, and bars marked as totals are colored blue-gray.

The method also sets the x-axis tick positions and labels to match the category labels so they render on the axis automatically.

Errors

Returns PlotError::SeriesLengthMismatch if categories and values have different lengths, or PlotError::EmptyData if empty.

impl Axes

pub fn collect_legend_entries(&self) -> Vec<LegendEntry>

Collects legend entries from this axes’ artists.

Trait Implementations

impl Debug for Axes

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.