Crate plotlars

Plotlars

Plotlars is a versatile Rust library that bridges the gap between the powerful Polars data analysis library and various plotting libraries. It simplifies the process of creating visualizations from data frames, allowing developers to focus on data insights rather than the intricacies of plot creation.

Motivation

The creation of Plotlars was driven by the need to simplify the process of creating complex plots in Rust, particularly when working with the powerful Polars data manipulation library. Generating visualizations often requires extensive boilerplate code and deep knowledge of both the plotting library and the data structure. This complexity can be a significant hurdle, especially for users who need to focus on analyzing and interpreting data rather than wrestling with intricate plotting logic.

To illustrate this, consider the following example where a scatter plot is created without Plotlars:

Without Plotlars

use plotly::{
    common::*,
    layout::*,
    Plot,
    Scatter,
};

use polars::prelude::*;

fn main() {
    let dataset = LazyCsvReader::new("penguins.csv")
        .finish().unwrap()
        .select([
            col("species").cast(
                DataType::Categorical(
                    None,
                    CategoricalOrdering::default()
                )
            ),
            col("flipper_length_mm").cast(DataType::Int16),
            col("body_mass_g").cast(DataType::Int16),
        ])
        .collect().unwrap();

    let group_column = "species";
    let x = "body_mass_g";
    let y = "flipper_length_mm";

    let groups = dataset
        .column(group_column).unwrap()
        .unique().unwrap();

    let layout = Layout::new()
        .title(Title::new("Penguin Flipper Length vs Body Mass"))
        .x_axis(Axis::new().title(Title::new("Body Mass (g)")))
        .y_axis(Axis::new().title(Title::new("Flipper Length (mm)")))
        .legend(Legend::new().title(Title::new("Species")));

    let mut plot = Plot::new();
    plot.set_layout(layout);

    for group in groups.iter() {
        let group = group.get_str().unwrap();

        let data = dataset
            .clone()
            .lazy()
            .filter(col(group_column).eq(lit(group)))
            .collect().unwrap();

        let x = data
            .column(x).unwrap()
            .i16().unwrap()
            .to_vec();

        let y = data
            .column(y).unwrap()
            .i16().unwrap()
            .to_vec();

        let trace = Scatter::default()
            .x(x)
            .y(y)
            .name(group)
            .mode(Mode::Markers)
            .marker(Marker::new().size(10).opacity(0.5));

        plot.add_trace(trace);
    }

    plot.show();
}

In this example, creating a scatter plot involves writing substantial code to manually handle the data and configure the plot, including grouping the data by category and setting up the plot layout.

With Plotlars

Now, compare that to the same plot created using Plotlars:

use plotlars::{
    ScatterPlot,
    Plot,
    Text,
};

use polars::prelude::*;

fn main() {
    let dataset = LazyCsvReader::new("notebook/data/penguins.csv")
        .finish().unwrap()
        .select([
            col("species").cast(
                DataType::Categorical(
                    None,
                    CategoricalOrdering::default()
                )
            ),
            col("flipper_length_mm").cast(DataType::Int16),
            col("body_mass_g").cast(DataType::Int16),
        ])
        .collect().unwrap();

    ScatterPlot::builder()
        .data(&dataset)
        .x("body_mass_g")
        .y("flipper_length_mm")
        .group("species")
        .size(10)
        .opacity(0.5)
        .plot_title(Text::from("Penguin Flipper Length vs Body Mass"))
        .x_title(Text::from("Body Mass (g)"))
        .y_title(Text::from("Flipper Length (mm)"))
        .legend_title(Text::from("Species"))
        .build()
        .plot();
}

With Plotlars, the same scatter plot is created with significantly less code. The library abstracts away the complexities of dealing with individual plot components and allows the user to specify high-level plot characteristics. This streamlined approach not only saves time but also reduces the potential for errors and makes the code more readable and maintainable.

Installation

cargo add plotlars

Features

• Seamless Integration with Polars: Leverage the power of Polars for efficient data manipulation and analysis.
• Support for Multiple Plot Types: Easily create bar, line, scatter, and other plot types.
• Customization: Modify plot appearance with an intuitive API.

License

This project is licensed under the MIT License. See the LICENSE.txt file for details.

Acknowledgements

• Polars: For providing a fast and efficient data manipulation library.
• Plotly: For the inspiration and ideas behind visualization libraries.
• Rust Community: For the support and development of an amazing programming language.

Macros

• marker
  Do not use it.

Structs

• Histogram
  A structure representing a histogram.
• HorizontalBarPlot
  A structure representing a horizontal bar plot.
• HorizontalBoxPlot
  A structure representing a horizontal box plot.
• LinePlot
  A structure representing a line plot.
• Rgb
  A structure representing an RGB color with red, green, and blue components.
• ScatterPlot
  A structure representing a scatter plot.
• Text
  A structure representing text with customizable content, font, size, and color.
• TimeSeriesPlot
  A structure representing a time series plot.
• VerticalBarPlot
  A structure representing a vertical bar plot.
• VerticalBoxPlot
  A structure representing a vertical bar plot.

Enums

• LineType
  An enum representing different styles of lines that can be used in plots.

Traits

• Plot
  A trait representing a generic plot that can be displayed or rendered.