add Pie Chart trace

 - add examples
 - add section in mdBook

Signed-off-by: Andrei Gherghescu <[email protected]>

Author: andrei-ng

docs/book/src/SUMMARY.md

@@ -10,15 +10,16 @@
     - [Basic Charts](./recipes/basic_charts.md)
         - [Scatter Plots](./recipes/basic_charts/scatter_plots.md)
         - [Line Charts](./recipes/basic_charts/line_charts.md)
-        - [Bar Charts](./recipes/basic_charts/bar_charts.md)        
-        - [Sankey Diagrams](./recipes/basic_charts/sankey_diagrams.md)        
+        - [Bar Charts](./recipes/basic_charts/bar_charts.md)
+        - [Pie Charts](./recipes/basic_charts/pie_charts.md)
+        - [Sankey Diagrams](./recipes/basic_charts/sankey_diagrams.md)
     - [Statistical Charts](./recipes/statistical_charts.md)
         - [Error Bars](./recipes/statistical_charts/error_bars.md)
         - [Box Plots](./recipes/statistical_charts/box_plots.md)
         - [Histograms](./recipes/statistical_charts/histograms.md)
     - [Scientific Charts](./recipes/scientific_charts.md)
        - [Contour Plots](./recipes/scientific_charts/contour_plots.md)
-       - [Heatmaps](./recipes/scientific_charts/heatmaps.md) 
+       - [Heatmaps](./recipes/scientific_charts/heatmaps.md)
     - [Financial Charts](./recipes/financial_charts.md)
        - [Time Series and Date Axes](./recipes/financial_charts/time_series_and_date_axes.md)
        - [Candlestick Charts](./recipes/financial_charts/candlestick_charts.md)

docs/book/src/recipes/basic_charts.md

@@ -6,5 +6,6 @@ Kind | Link
 :---|:----:
 Scatter Plots |[![Scatter Plots](./img/line_and_scatter_plot.png)](./basic_charts/scatter_plots.md)
 Line Charts | [![Line Charts](./img/line_shape_options_for_interpolation.png)](./basic_charts/line_charts.md)
-Bar Charts | [![Scatter Plots](./img/bar_chart_with_error_bars.png)](./basic_charts/scatter_plots.md)
+Bar Charts | [![Bar Charts](./img/bar_chart_with_error_bars.png)](./basic_charts/scatter_plots.md)
+Pie Charts | [![Pie Charts](./img/pie_charts.png)](./basic_charts/pie_charts.md)
 Sankey Diagrams | [![Sankey Diagrams](./img/basic_sankey.png)](./basic_charts/sankey_diagrams.md)

docs/book/src/recipes/basic_charts/pie_charts.md

@@ -0,0 +1,35 @@
+# Pie Charts
+
+The following imports have been used to produce the plots below:
+
+```rust,no_run
+use plotly::common::{Domain, Font, HoverInfo, Orientation};
+use plotly::layout::{
+        Annotation, Layout, LayoutGrid},
+use plotly::layout::Layout;
+use plotly::{Pie, Plot};
+```
+
+The `to_inline_html` method is used to produce the html plot displayed in this page.
+
+
+## Basic Pie Chart
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:basic_pie_chart}}
+```
+
+{{#include ../../../../../examples/basic_charts/out/basic_pie_chart.html}}
+
+## Grouped Pie Chart
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:grouped_donout_pie_charts}}
+```
+
+{{#include ../../../../../examples/basic_charts/out/grouped_donout_pie_charts.html}}
+
+## Pie Chart Text Control
+```rust,no_run
+{{#include ../../../../../examples/basic_charts/src/main.rs:pie_chart_text_control}}
+```
+
+{{#include ../../../../../examples/basic_charts/out/pie_chart_text_control.html}}

docs/book/src/recipes/img/pie_charts.png

@@ -4,13 +4,16 @@ use ndarray::Array;
 use plotly::{
     color::{NamedColor, Rgb, Rgba},
     common::{
-        ColorScale, ColorScalePalette, DashType, Fill, Font, Line, LineShape, Marker, Mode,
-        Orientation, Pattern, PatternShape,
+        ColorScale, ColorScalePalette, DashType, Domain, Fill, Font, HoverInfo, Line, LineShape,
+        Marker, Mode, Orientation, Pattern, PatternShape,
+    },
+    layout::{
+        Annotation, Axis, BarMode, CategoryOrder, Layout, LayoutGrid, Legend, TicksDirection,
+        TraceOrder,
     },
-    layout::{Axis, BarMode, CategoryOrder, Layout, Legend, TicksDirection, TraceOrder},
     sankey::{Line as SankeyLine, Link, Node},
     traces::table::{Cells, Header},
-    Bar, Plot, Sankey, Scatter, ScatterPolar, Table,
+    Bar, Pie, Plot, Sankey, Scatter, ScatterPolar, Table,
 };
 use rand_distr::{Distribution, Normal, Uniform};
 
@@ -819,6 +822,124 @@ fn table_chart(show: bool) -> Plot {
 }
 // ANCHOR_END: table_chart
 
+// Pie Charts
+// ANCHOR: basic_pie_chart
+fn basic_pie_chart(show: bool) -> Plot {
+    let values = vec![2, 3, 5];
+    let labels = vec!["giraffes", "orangutans", "monkeys"];
+    let t = Pie::new(values).labels(labels);
+    let mut plot = Plot::new();
+    plot.add_trace(t);
+
+    if show {
+        plot.show();
+    }
+    plot
+}
+// ANCHOR_END: basic_pie_chart
+
+// ANCHOR: pie_chart_text_control
+fn pie_chart_text_control(show: bool) -> Plot {
+    let values = vec![2, 3, 4, 4];
+    let labels = vec!["Wages", "Operating expenses", "Cost of sales", "Insurance"];
+    let t = Pie::new(values)
+        .labels(labels)
+        .automargin(true)
+        .show_legend(true)
+        .text_position(plotly::common::Position::Outside)
+        .name("Costs")
+        .text_info("label+percent");
+    let mut plot = Plot::new();
+    plot.add_trace(t);
+
+    let layout = Layout::new().height(700).width(700).show_legend(true);
+    plot.set_layout(layout);
+
+    if show {
+        plot.show();
+    }
+    plot
+}
+// ANCHOR_END: pie_chart_text_control
+
+// ANCHOR: grouped_donout_pie_charts
+fn grouped_donout_pie_charts(show: bool) -> Plot {
+    let mut plot = Plot::new();
+
+    let values = vec![16, 15, 12, 6, 5, 4, 42];
+    let labels = vec![
+        "US",
+        "China",
+        "European Union",
+        "Russian Federation",
+        "Brazil",
+        "India",
+        "Rest of World",
+    ];
+    let t = Pie::new(values)
+        .labels(labels)
+        .name("GHG Emissions")
+        .hover_info(HoverInfo::All)
+        .text("GHG")
+        .hole(0.4)
+        .domain(Domain::new().column(0));
+    plot.add_trace(t);
+
+    let values = vec![27, 11, 25, 8, 1, 3, 25];
+    let labels = vec![
+        "US",
+        "China",
+        "European Union",
+        "Russian Federation",
+        "Brazil",
+        "India",
+        "Rest of World",
+    ];
+
+    let t = Pie::new(values)
+        .labels(labels)
+        .name("CO2 Emissions")
+        .hover_info(HoverInfo::All)
+        .text("CO2")
+        .text_position(plotly::common::Position::Inside)
+        .hole(0.4)
+        .domain(Domain::new().column(1));
+    plot.add_trace(t);
+
+    let layout = Layout::new()
+        .title("Global Emissions 1990-2011")
+        .height(400)
+        .width(600)
+        .annotations(vec![
+            Annotation::new()
+                .font(Font::new().size(20))
+                .show_arrow(false)
+                .text("GHG")
+                .x(0.17)
+                .y(0.5),
+            Annotation::new()
+                .font(Font::new().size(20))
+                .show_arrow(false)
+                .text("CO2")
+                .x(0.82)
+                .y(0.5),
+        ])
+        .show_legend(false)
+        .grid(
+            LayoutGrid::new()
+                .columns(2)
+                .rows(1)
+                .pattern(plotly::layout::GridPattern::Independent),
+        );
+    plot.set_layout(layout);
+
+    if show {
+        plot.show();
+    }
+    plot
+}
+// ANCHOR_END: grouped_donout_pie_charts
+
 fn write_example_to_html(plot: Plot, name: &str) {
     std::fs::create_dir_all("./out").unwrap();
     let html = plot.to_inline_html(Some(name));
@@ -869,4 +990,12 @@ fn main() {
 
     // Sankey Diagrams
     write_example_to_html(basic_sankey_diagram(false), "basic_sankey_diagram");
+
+    // Pie Charts
+    write_example_to_html(basic_pie_chart(false), "basic_pie_chart");
+    write_example_to_html(pie_chart_text_control(false), "pie_chart_text_control");
+    write_example_to_html(
+        grouped_donout_pie_charts(false),
+        "grouped_donout_pie_charts",
+    );
 }

examples/basic_charts/src/main.rs

@@ -153,10 +153,16 @@ pub enum ConstrainText {
 
 #[derive(Serialize, Clone, Debug)]
 pub enum Orientation {
+    #[serde(rename = "a")]
+    Auto,
     #[serde(rename = "v")]
     Vertical,
     #[serde(rename = "h")]
     Horizontal,
+    #[serde(rename = "r")]
+    Radial,
+    #[serde(rename = "t")]
+    Tangential,
 }
 
 #[derive(Serialize, Clone, Debug)]
@@ -225,6 +231,7 @@ pub enum PlotType {
     Surface,
     DensityMapbox,
     Table,
+    Pie,
 }
 
 #[derive(Serialize, Clone, Debug)]
@@ -273,6 +280,10 @@ pub enum Position {
     BottomCenter,
     #[serde(rename = "bottom right")]
     BottomRight,
+    #[serde(rename = "inside")]
+    Inside,
+    #[serde(rename = "outside")]
+    Outside,
 }
 
 #[derive(Serialize, Clone, Debug)]

plotly/src/common/mod.rs

@@ -36,7 +36,7 @@ pub use traces::{
 // Bring the different trace types into the top-level scope
 pub use traces::{
     Bar, BoxPlot, Candlestick, Contour, DensityMapbox, HeatMap, Histogram, Image, Mesh3D, Ohlc,
-    Sankey, Scatter, Scatter3D, ScatterMapbox, ScatterPolar, Surface, Table,
+    Pie, Sankey, Scatter, Scatter3D, ScatterMapbox, ScatterPolar, Surface, Table,
 };
 
 pub trait Restyle: serde::Serialize {}

plotly/src/lib.rs

@@ -585,6 +585,7 @@ impl PartialEq for Plot {
 mod tests {
     use std::path::PathBuf;
 
+    #[cfg(feature = "kaleido")]
     use base64::{engine::general_purpose, Engine as _};
     use serde_json::{json, to_value};
 

plotly/src/plot.rs

@@ -10,6 +10,7 @@ pub mod histogram;
 pub mod image;
 pub mod mesh3d;
 mod ohlc;
+pub mod pie;
 pub mod sankey;
 mod scatter;
 mod scatter3d;
@@ -27,6 +28,7 @@ pub use heat_map::HeatMap;
 pub use histogram::Histogram;
 pub use mesh3d::Mesh3D;
 pub use ohlc::Ohlc;
+pub use pie::Pie;
 pub use sankey::Sankey;
 pub use scatter::Scatter;
 pub use scatter3d::Scatter3D;