Struct Chart 

pub struct Chart { /* private fields */ }

The fully-rendered output of a .build() call.

A Chart is produced by calling .build() at the end of any builder chain. From it you can retrieve the SVG string, write output files, or inspect warnings emitted during rendering.

Examples

use charcoal::Chart;
let chart = Chart::scatter(&df)
    .x("sepal_length")
    .y("sepal_width")
    .build()?;
chart.save_svg("iris.svg")?;
chart.save_html("iris.html")?;

Implementations

impl Chart

pub fn scatter(df: &DataFrame) -> ScatterBuilder<'_>

Begin building a scatter chart from df.

Required columns: .x() (Numeric or Temporal) and .y() (Numeric).

Examples

use charcoal::Chart;
let chart = Chart::scatter(&df)
    .x("sepal_length")
    .y("sepal_width")
    .color_by("species")
    .build()?;

pub fn line(df: &DataFrame) -> LineBuilder<'_>

Begin building a line chart from df.

Required columns: .x() (Numeric or Temporal) and .y() (Numeric).

Examples

use charcoal::{Chart, NullPolicy};
let chart = Chart::line(&df)
    .x("date")
    .y("value")
    .null_policy(NullPolicy::Skip)
    .build()?;

pub fn bar(df: &DataFrame) -> BarBuilder<'_>

Begin building a bar chart from df.

Required columns: .x() (Categorical) and .y() (Numeric).

Examples

use charcoal::Chart;
let chart = Chart::bar(&df)
    .x("category")
    .y("count")
    .build()?;

pub fn histogram(df: &DataFrame) -> HistogramBuilder<'_>

Begin building a histogram from df.

Required column: .x() (Numeric). Bin counts are computed automatically.

Examples

use charcoal::Chart;
let chart = Chart::histogram(&df)
    .x("value")
    .bins(20)
    .build()?;

pub fn heatmap(df: &DataFrame) -> HeatmapBuilder<'_>

Begin building a heatmap from df.

Required columns: .x() (Categorical), .y() (Categorical), .z() (Numeric).

Examples

use charcoal::{Chart, ColorScale};
let chart = Chart::heatmap(&df)
    .x("col_label")
    .y("row_label")
    .z("value")
    .color_scale(ColorScale::Viridis)
    .build()?;

pub fn box_plot(df: &DataFrame) -> BoxPlotBuilder<'_>

Begin building a box plot from df.

Required columns: .x() (Categorical, group labels) and .y() (Numeric, values to summarise).

Examples

use charcoal::Chart;
let chart = Chart::box_plot(&df)
    .x("group")
    .y("measurement")
    .notched(true)
    .build()?;

pub fn area(df: &DataFrame) -> AreaBuilder<'_>

Begin building an area chart from df.

Required columns: .x() (Numeric or Temporal) and .y() (Numeric).

Examples

use charcoal::{Chart};
use charcoal::FillMode;
let chart = Chart::area(&df)
    .x("week")
    .y("downloads")
    .fill_mode(FillMode::ToZero)
    .build()?;

impl Chart

pub fn svg(&self) -> &str

The rendered SVG string.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
let svg: &str = chart.svg();
assert!(svg.starts_with("<svg"));

pub fn warnings(&self) -> &[CharcoalWarning]

Warnings accumulated during rendering. Empty slice means a clean build.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
for w in chart.warnings() {
    eprintln!("warning: {w}");
}

pub fn width(&self) -> u32

Chart width in pixels.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
println!("{}×{}", chart.width(), chart.height());

pub fn height(&self) -> u32

Chart height in pixels.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
println!("{}×{}", chart.width(), chart.height());

pub fn save_svg(&self, path: &str) -> Result<(), CharcoalError>

Write the SVG to path (UTF-8, overwrites if exists).

Errors

CharcoalError::Io if the path is not writable or its parent directory does not exist.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
chart.save_svg("output.svg")?;

pub fn save_html(&self, path: &str) -> Result<(), CharcoalError>

Write an HTML document embedding the SVG inline to path.

The file has no external dependencies and can be opened directly in any browser.

Errors

CharcoalError::Io if the path is not writable or its parent directory does not exist.

Examples

let chart = Chart::scatter(&df).x("x").y("y").build()?;
chart.save_html("output.html")?;

pub fn save_png(&self, _path: &str) -> Result<(), CharcoalError>

save_png is only available with the static feature.

Add features = ["static"] to your charcoal dependency in Cargo.toml.

Trait Implementations

impl Clone for Chart

fn clone(&self) -> Chart

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Chart

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.