fluent-plots 0.1.0

A declarative data visualization library with a fluent API, built on Polars and Charming.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# fluent-plots

[![Crates.io](https://img.shields.io/crates/v/fluent-plots.svg)](https://crates.io/crates/fluent-plots)
[![License](https://img.shields.io/badge/license-MIT%2FApache--2.0-blue.svg)](LICENSE-MIT)

A declarative and easy-to-use Rust data visualization library for creating static and interactive charts from Polars DataFrames. `fluent-plots` provides a simple, chainable API for quickly building common plot types.

## Features

- **Fluent API**: Chain methods together to build your chart declaratively.
- **Polars `DataFrame` Integration**: Designed to work directly with the powerful Polars `DataFrame`.
- **Dual Backends**:
  - **(Default)** Static chart rendering using `plotters` (drawing logic still in development).
  - **(Optional)** Interactive HTML charts powered by `charming` and ECharts.js.
- **Lightweight**: The interactive backend is an optional feature to keep your dependency tree small if you only need static plots.

## Installation

Add `fluent-plots` to your `Cargo.toml` file.

For interactive charts, enable the `interactive` feature:

```toml
[dependencies]
fluent-plots = { version = "0.1.0", features = ["interactive"] }
polars = { version = "0.41", features = ["csv"] } # Needed for the examples
```

If you only need the static plotting capabilities (once implemented), you can omit the feature flag.

## Usage

Here's how to create an interactive bar chart from a Polars `DataFrame`.

```rust
use fluent_plots::barchart;
use polars::prelude::*;
use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create a DataFrame
    let df = df!(
        "category" => &["A", "B", "C", "D"],
        "value" => &[10, 25, 5, 42],
    )?;

    // 2. Build the chart and generate the HTML
    let html_content = barchart(df)
        .x("category")
        .y("value")
        .to_interactive_html()?;

    // 3. Save the HTML to a file
    fs::write("my_interactive_chart.html", html_content)?;

    Ok(())
}
```

### Creating Different Chart Types

You can easily create other chart types by calling `linechart()` or `scatterplot()`.

```rust
use fluent_plots::linechart;
use polars::prelude::*;
use std::fs;

// ... create your DataFrame `df` ...

let html_content = linechart(df)
    .x("category")
    .y("value")
    .to_interactive_html()?;

fs::write("my_line_chart.html", html_content)?;
```

## Running with the Example Binary

This repository includes a test application in the `plot-tester` directory (if you choose to include it) that can be run from the command line to generate charts from a CSV file.

First, create a `sample_data.csv` file:
```csv
category,value
A,10
B,25
C,5
D,42
E,18
```

Then, run the application:

```bash
# Generate a bar chart (default)
cargo run -- sample_data.csv

# Generate a line chart
cargo run -- sample_data.csv line

# Generate a scatter plot
cargo run -- sample_data.csv scatter
```

## License

This project is licensed under either of

- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)

at your option.

## Contributing

Contributions are welcome! Feel free to open an issue or submit a pull request.