Struct Histogram 

pub struct Histogram { /* private fields */ }

A structure representing a histogram.

The Histogram struct facilitates the creation and customization of histograms with various options for data selection, layout configuration, and aesthetic adjustments. It supports grouping of data, opacity settings, and customizable markers and colors.

Arguments

• data - A reference to the DataFrame containing the data to be plotted.
• x - A string slice specifying the column name to be used for the x-axis (independent variable).
• group - An optional string slice specifying the column name to be used for grouping data points.
• sort_groups_by - Optional comparator fn(&str, &str) -> std::cmp::Ordering to control group ordering. Groups are sorted lexically by default.
• facet - An optional string slice specifying the column name to be used for faceting (creating multiple subplots).
• facet_config - An optional reference to a FacetConfig struct for customizing facet behavior (grid dimensions, scales, gaps, etc.).
• opacity - An optional f64 value specifying the opacity of the plot markers (range: 0.0 to 1.0).
• color - An optional Rgb value specifying the color of the markers to be used for the plot. This is used when group is not specified.
• colors - An optional vector of Rgb values specifying the colors to be used for the plot. This is used when group is specified to differentiate between groups.
• plot_title - An optional Text struct specifying the title of the plot.
• x_title - An optional Text struct specifying the title of the x-axis.
• y_title - An optional Text struct specifying the title of the y-axis.
• legend_title - An optional Text struct specifying the title of the legend.
• x_axis - An optional reference to an Axis struct for customizing the x-axis.
• y_axis - An optional reference to an Axis struct for customizing the y-axis.
• legend - An optional reference to a Legend struct for customizing the legend of the plot (e.g., positioning, font, etc.).

Example

use plotlars::{Axis, Histogram, Legend, Plot, Rgb, Text, TickDirection};
use polars::prelude::*;

let dataset = LazyCsvReader::new(PlRefPath::new("data/penguins.csv"))
    .finish()
    .unwrap()
    .select([
        col("species"),
        col("sex").alias("gender"),
        col("flipper_length_mm").cast(DataType::Int16),
        col("body_mass_g").cast(DataType::Int16),
    ])
    .collect()
    .unwrap();

let axis = Axis::new()
    .show_line(true)
    .show_grid(true)
    .value_thousands(true)
    .tick_direction(TickDirection::OutSide);

Histogram::builder()
    .data(&dataset)
    .x("body_mass_g")
    .group("species")
    .opacity(0.5)
    .colors(vec![
        Rgb(255, 165, 0),
        Rgb(147, 112, 219),
        Rgb(46, 139, 87),
    ])
    .plot_title(
        Text::from("Histogram")
            .font("Arial")
            .size(18)
    )
    .x_title(
        Text::from("body mass (g)")
            .font("Arial")
            .size(15)
    )
    .y_title(
        Text::from("count")
            .font("Arial")
            .size(15)
    )
    .legend_title(
        Text::from("species")
            .font("Arial")
            .size(15)
    )
    .x_axis(&axis)
    .y_axis(&axis)
    .legend(
        &Legend::new()
            .x(0.9)
    )
    .build()
    .plot();

Implementations

impl Histogram

pub fn builder<'f1, 'f2, 'f3, 'f4, 'f5, 'f6, 'f7, 'f8>() -> HistogramBuilder<'f1, 'f2, 'f3, 'f4, 'f5, 'f6, 'f7, 'f8>

Examples found in repository

examples/faceting.rs (line 255)

fn histogram_example() {
    let csv_path = "data/temperature_seasonal.csv";

    let df = CsvReadOptions::default()
        .with_has_header(true)
        .try_into_reader_with_file_path(Some(csv_path.into()))
        .unwrap()
        .finish()
        .unwrap();

    let facet_config = FacetConfig::new().rows(2).cols(3);

    Histogram::builder()
        .data(&df)
        .x("temperature")
        .group("season")
        .facet("city")
        .facet_config(&facet_config)
        .opacity(0.5)
        .plot_title("Seasonal Temperature Distribution by City")
        .x_title("Temperature (°C)")
        .y_title("Frequency")
        .build()
        .plot();
}

examples/histogram.rs (line 23)

fn main() {
    let dataset = LazyCsvReader::new(PlRefPath::new("data/penguins.csv"))
        .finish()
        .unwrap()
        .select([
            col("species"),
            col("sex").alias("gender"),
            col("flipper_length_mm").cast(DataType::Int16),
            col("body_mass_g").cast(DataType::Int16),
        ])
        .collect()
        .unwrap();

    let axis = Axis::new()
        .show_line(true)
        .show_grid(true)
        .value_thousands(true)
        .tick_direction(TickDirection::OutSide);

    Histogram::builder()
        .data(&dataset)
        .x("body_mass_g")
        .group("species")
        .opacity(0.5)
        .colors(vec![Rgb(255, 165, 0), Rgb(147, 112, 219), Rgb(46, 139, 87)])
        .plot_title(Text::from("Histogram").font("Arial").size(18))
        .x_title(Text::from("body mass (g)").font("Arial").size(15))
        .y_title(Text::from("count").font("Arial").size(15))
        .legend_title(Text::from("species").font("Arial").size(15))
        .x_axis(&axis)
        .y_axis(&axis)
        .legend(&Legend::new().x(0.9))
        .build()
        .plot();
}

examples/subplot_grid.rs (line 162)

fn irregular_grid_example() {
    let dataset1 = LazyCsvReader::new(PlRefPath::new("data/penguins.csv"))
        .finish()
        .unwrap()
        .select([
            col("species"),
            col("sex").alias("gender"),
            col("flipper_length_mm").cast(DataType::Int16),
            col("body_mass_g").cast(DataType::Int16),
        ])
        .collect()
        .unwrap();

    let axis = Axis::new()
        .show_line(true)
        .show_grid(true)
        .value_thousands(true)
        .tick_direction(TickDirection::OutSide);

    let plot1 = Histogram::builder()
        .data(&dataset1)
        .x("body_mass_g")
        .group("species")
        .opacity(0.5)
        .colors(vec![Rgb(255, 165, 0), Rgb(147, 112, 219), Rgb(46, 139, 87)])
        .plot_title(Text::from("Histogram").x(0.0).y(1.35).size(14))
        .x_title(Text::from("body mass (g)").x(0.94).y(-0.35))
        .y_title(Text::from("count").x(-0.062).y(0.83))
        .x_axis(&axis)
        .y_axis(&axis)
        .legend_title(Text::from("species"))
        .legend(&Legend::new().x(0.87).y(1.2))
        .build();

    let dataset2 = LazyCsvReader::new(PlRefPath::new("data/stock_prices.csv"))
        .finish()
        .unwrap()
        .collect()
        .unwrap();

    let increasing = Direction::new()
        .line_color(Rgb(0, 200, 100))
        .line_width(0.5);

    let decreasing = Direction::new()
        .line_color(Rgb(200, 50, 50))
        .line_width(0.5);

    let plot2 = CandlestickPlot::builder()
        .data(&dataset2)
        .dates("date")
        .open("open")
        .high("high")
        .low("low")
        .close("close")
        .increasing(&increasing)
        .decreasing(&decreasing)
        .whisker_width(0.1)
        .plot_title(Text::from("Candlestick").x(0.0).y(1.35).size(14))
        .y_title(Text::from("price ($)").x(-0.06).y(0.76))
        .y_axis(&Axis::new().show_axis(true).show_grid(true))
        .build();

    let dataset3 = LazyCsvReader::new(PlRefPath::new("data/heatmap.csv"))
        .finish()
        .unwrap()
        .collect()
        .unwrap();

    let plot3 = HeatMap::builder()
        .data(&dataset3)
        .x("x")
        .y("y")
        .z("z")
        .color_bar(
            &ColorBar::new()
                .value_exponent(ValueExponent::None)
                .separate_thousands(true)
                .tick_length(5)
                .tick_step(5000.0),
        )
        .plot_title(Text::from("Heat Map").x(0.0).y(1.35).size(14))
        .color_scale(Palette::Viridis)
        .build();

    SubplotGrid::irregular()
        .plots(vec![
            (&plot1, 0, 0, 1, 1),
            (&plot2, 0, 1, 1, 1),
            (&plot3, 1, 0, 1, 2),
        ])
        .rows(2)
        .cols(2)
        .v_gap(0.35)
        .h_gap(0.05)
        .title(
            Text::from("Irregular Subplot Grid")
                .size(16)
                .font("Arial bold")
                .y(0.95),
        )
        .build()
        .plot();
}

Trait Implementations

impl Clone for Histogram

fn clone(&self) -> Histogram

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Serialize for Histogram

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl PlotHelper for Histogram