Struct FacetConfig 

pub struct FacetConfig {
    pub rows: Option<usize>,
    pub cols: Option<usize>,
    pub scales: FacetScales,
    pub h_gap: Option<f64>,
    pub v_gap: Option<f64>,
    pub title_style: Option<Text>,
    pub sorter: Option<fn(&str, &str) -> Ordering>,
    pub highlight_facet: bool,
    pub unhighlighted_color: Option<Rgb>,
}

A structure representing facet configuration for creating small multiples.

The FacetConfig struct allows customization of faceted plots including grid layout, scale behavior, spacing, title styling, custom ordering, and highlighting options. Faceting splits data by a categorical variable to create multiple subplots arranged in a grid, making it easy to compare patterns across categories.

Example

use plotlars::{SurfacePlot, FacetConfig, Plot, Palette, Text};
use polars::prelude::*;
use ndarray::Array;

let n: usize = 50;
let (x_base, _): (Vec<f64>, Option<usize>) =
    Array::linspace(-5., 5., n).into_raw_vec_and_offset();
let (y_base, _): (Vec<f64>, Option<usize>) =
    Array::linspace(-5., 5., n).into_raw_vec_and_offset();

let mut x_all = Vec::new();
let mut y_all = Vec::new();
let mut z_all = Vec::new();
let mut category_all = Vec::new();

type SurfaceFunction = Box<dyn Fn(f64, f64) -> f64>;
let functions: Vec<(&str, SurfaceFunction)> = vec![
    (
        "Sine Wave",
        Box::new(|xi: f64, yj: f64| (xi * xi + yj * yj).sqrt().sin()),
    ),
    ("Saddle", Box::new(|xi: f64, yj: f64| xi * xi - yj * yj)),
    (
        "Gaussian",
        Box::new(|xi: f64, yj: f64| (-0.5 * (xi * xi + yj * yj)).exp()),
    ),
];

for (name, func) in &functions {
    for &xi in x_base.iter() {
        for &yj in y_base.iter() {
            x_all.push(xi);
            y_all.push(yj);
            z_all.push(func(xi, yj));
            category_all.push(*name);
        }
    }
}

let dataset = df![
    "x" => &x_all,
    "y" => &y_all,
    "z" => &z_all,
    "function" => &category_all,
]
.unwrap();

SurfacePlot::builder()
    .data(&dataset)
    .x("x")
    .y("y")
    .z("z")
    .facet("function")
    .facet_config(&FacetConfig::new().cols(3).rows(1).h_gap(0.08).v_gap(0.12))
    .plot_title(
        Text::from("3D Mathematical Functions")
            .font("Arial")
            .size(20),
    )
    .color_scale(Palette::Viridis)
    .opacity(0.9)
    .build()
    .plot();

Fields

rows: Option<usize>

cols: Option<usize>

scales: FacetScales

h_gap: Option<f64>

v_gap: Option<f64>

title_style: Option<Text>

sorter: Option<fn(&str, &str) -> Ordering>

highlight_facet: bool

unhighlighted_color: Option<Rgb>

Implementations

impl FacetConfig

pub fn new() -> Self

Creates a new FacetConfig instance with default values.

By default, the grid dimensions are automatically calculated, scales are fixed across all facets, and highlighting is disabled.

pub fn rows(self, rows: usize) -> Self

Sets the number of rows in the facet grid.

When specified, the grid will have exactly this many rows, and the number of columns will be calculated automatically based on the number of facets. If not specified, both dimensions are calculated automatically.

Argument

• rows - A usize value specifying the number of rows (must be greater than 0).

Panics

Panics if rows is 0.

pub fn cols(self, cols: usize) -> Self

Sets the number of columns in the facet grid.

When specified, the grid will have exactly this many columns, and the number of rows will be calculated automatically based on the number of facets. If not specified, both dimensions are calculated automatically.

Argument

• cols - A usize value specifying the number of columns (must be greater than 0).

Panics

Panics if cols is 0.

pub fn scales(self, scales: FacetScales) -> Self

Sets the axis scale behavior across facets.

Controls whether facets share the same axis ranges (Fixed) or have independent scales (Free, FreeX, or FreeY). Fixed scales make it easier to compare values across facets, while free scales allow each facet to use its optimal range.

Argument

• scales - A FacetScales enum value specifying the scale behavior.

pub fn h_gap(self, gap: f64) -> Self

Sets the horizontal spacing between columns.

The gap is specified as a proportion of the plot width, with typical values ranging from 0.0 (no gap) to 0.2 (20% gap). If not specified, plotly’s default spacing is used.

Argument

• gap - A f64 value from 0.0 to 1.0 representing the relative gap size.

Panics

Panics if gap is negative, NaN, or infinite.

pub fn v_gap(self, gap: f64) -> Self

Sets the vertical spacing between rows.

The gap is specified as a proportion of the plot height, with typical values ranging from 0.0 (no gap) to 0.2 (20% gap). If not specified, plotly’s default spacing is used.

Argument

• gap - A f64 value from 0.0 to 1.0 representing the relative gap size.

Panics

Panics if gap is negative, NaN, or infinite.

pub fn title_style<T: Into<Text>>(self, style: T) -> Self

Sets the styling for facet labels.

Controls the font, size, and color of the category labels that appear above each facet. If not specified, plotly’s default text styling is used.

Argument

• style - A Text component or any type that can be converted into Text, specifying the styling options for facet titles.

pub fn sorter(self, f: fn(&str, &str) -> Ordering) -> Self

Sets a custom sorting function for facet order.

By default, facets are ordered alphabetically by category name. This method allows you to specify a custom comparison function to control the order in which facets appear in the grid.

Argument

• f - A function that takes two string slices and returns an Ordering, following the same signature as str::cmp.

Example

use plotlars::FacetConfig;
use std::cmp::Ordering;

// Reverse alphabetical order
let config = FacetConfig::new()
    .sorter(|a, b| b.cmp(a));

pub fn highlight_facet(self, highlight: bool) -> Self

Enables or disables facet highlighting mode.

When enabled, each facet shows all data from all categories, but emphasizes the data for the current facet’s category while displaying other categories in a muted color. This provides visual context by showing the full data distribution while focusing attention on the current facet.

Argument

• highlight - A boolean value: true to enable highlighting, false to disable.

pub fn unhighlighted_color(self, color: Rgb) -> Self

Sets the color for unhighlighted data points in highlighting mode.

This setting only takes effect when highlight_facet is enabled. It specifies the color used for data points that belong to other categories (not the current facet’s category). If not specified, a default grey color is used.

Argument

• color - An Rgb value specifying the color for unhighlighted data.

Trait Implementations

impl Clone for FacetConfig

fn clone(&self) -> FacetConfig

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for FacetConfig

fn default() -> FacetConfig

Returns the “default value” for a type.