Plotlars

<p align="center"> <a href="https://crates.io/crates/plotlars"> <img alt="Crates.io" src="https://img.shields.io/crates/v/plotlars.svg"></a> <a href="https://docs.rs/plotlars"> <img alt="docs.rs" src="https://img.shields.io/docsrs/plotlars"> </a> <a href="https://crates.io/crates/plotlars"> <img alt="Downloads" src="https://img.shields.io/crates/d/plotlars"> </a> <a href="https://github.com/your-repo/plotlars/blob/main/LICENSE"> <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"> </a> </p>

Plotlars is a versatile Rust library that acts as a wrapper around the Plotly crate, bridging the gap between the powerful Polars data analysis library and Plotly. It simplifies the process of creating visualizations from data frames, allowing developers to focus on data insights rather than the intricacies of plot creation.

Implemented Plots Overview

<table> <tr> <td align="center"> <img src="https://imgur.com/LMrqAaT.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Array2dPlot.html">Array 2D</a> </td> <td align="center"> <img src="https://imgur.com/HQQvQey.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.BarPlot.html">Bar Plot</a> </td> <td align="center"> <img src="https://imgur.com/jdA3g9r.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.BoxPlot.html">Box Plot</a> </td> <td align="center"> <img src="https://imgur.com/91y2Kis.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.CandlestickPlot.html">Candlestick</a> </td> </tr> <tr> <td align="center"> <img src="https://imgur.com/VWgxHC8.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.ContourPlot.html">Contour Plot</a> </td> <td align="center"> <img src="https://imgur.com/82eLyBm.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.DensityMapbox.html">Density Mapbox</a> </td> <td align="center"> <img src="https://imgur.com/5uFih4M.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.HeatMap.html">Heat Map</a> </td> <td align="center"> <img src="https://imgur.com/w2oiuIo.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Histogram.html">Histogram</a> </td> </tr> <tr> <td align="center"> <img src="https://imgur.com/PAtdaHj.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Image.html">Image</a> </td> <td align="center"> <img src="https://imgur.com/PaXG300.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.LinePlot.html">Line Plot</a> </td> <td align="center"> <img src="https://imgur.com/bljzmw5.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Mesh3D.html">Mesh3D</a> </td> <td align="center"> <img src="https://imgur.com/Sv8r9VN.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.OhlcPlot.html">OHLC</a> </td> </tr> <tr> <td align="center"> <img src="https://imgur.com/q44HDwT.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.PieChart.html">Pie Chart</a> </td> <td align="center"> <img src="https://imgur.com/jvAew8u.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.SankeyDiagram.html">Sankey Diagram</a> </td> <td align="center"> <img src="https://imgur.com/WYTQxHA.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Scatter3dPlot.html">Scatter 3D Plot</a> </td> <td align="center"> <img src="https://imgur.com/8PCEbhN.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.ScatterGeo.html">Scatter Geo</a> </td> </tr> <tr> <td align="center"> <img src="https://imgur.com/8MCjVOd.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.ScatterMap.html">Scatter Map</a> </td> <td align="center"> <img src="https://imgur.com/9jfO8RU.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.ScatterPlot.html">Scatter Plot</a> </td> <td align="center"> <img src="https://imgur.com/kl1pY9c.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.ScatterPolar.html">Scatter Polar</a> </td> <td align="center"> <img src="https://imgur.com/RvZwv3O.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.SubplotGrid.html">Subplot Grid Irregular</a> </td> </tr> <tr> <td align="center"> <img src="https://imgur.com/q0K7cyP.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.SubplotGrid.html">Subplot Grid Regular</a> </td> <td align="center"> <img src="https://imgur.com/tdVte4l.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.SurfacePlot.html">Surface Plot</a> </td> <td align="center"> <img src="https://imgur.com/QDKTeFX.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.Table.html">Table</a> </td> <td align="center"> <img src="https://imgur.com/hL27Xcn.png" width="120" height="120"><br> <a href="https://docs.rs/plotlars/latest/plotlars/struct.TimeSeriesPlot.html">Time Series</a> </td> </tr> </table>

Plot Types Reference

| Plot Type | Required Params | Facet | Group | |---|---|---|---| | Array2dPlot | data | -- | -- | | BarPlot | data, labels, values | Yes | Yes | | BoxPlot | data, labels, values | Yes | Yes | | CandlestickPlot | data, dates, open, high, low, close | -- | -- | | ContourPlot | data, x, y, z | Yes | -- | | DensityMapbox | data, lat, lon, z | -- | -- | | HeatMap | data, x, y, z | Yes | -- | | Histogram | data, x | Yes | Yes | | Image | path | -- | -- | | LinePlot | data, x, y | Yes | -- | | Mesh3D | data, x, y, z | Yes | -- | | OhlcPlot | data, dates, open, high, low, close | -- | -- | | PieChart | data, labels | Yes | -- | | SankeyDiagram | data, sources, targets, values | Yes | -- | | Scatter3dPlot | data, x, y, z | Yes | Yes | | ScatterGeo | data, lat, lon | -- | Yes | | ScatterMap | data, latitude, longitude | -- | Yes | | ScatterPlot | data, x, y | Yes | Yes | | ScatterPolar | data, theta, r | Yes | Yes | | SubplotGrid | plots | -- | -- | | SurfacePlot | data, x, y, z | Yes | -- | | Table | data, columns | -- | -- | | TimeSeriesPlot | data, x, y | Yes | -- |

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 (Plotly) 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:

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

use polars::prelude::*;

fn main() {
    let dataset = LazyCsvReader::new(PlRefPath::new("data/penguins.csv"))
        .finish().unwrap()
        .select([
            col("species"),
            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::with_text("Penguin Flipper Length vs Body Mass"))
        .x_axis(Axis::