Merge pull request #31 from JamesxX/bar-element

Bar element and barchart

Author: johannes-wolf

gallery/barchart.typ

@@ -17,7 +17,7 @@
   chart.barchart(mode: "clustered",
                  size: (9, auto),
                  label-key: 0,
-                 value-key: (..range(1, 5)),
+                 value-key: (..range(1, 4)),
                  bar-width: .8,
                  x-tick-step: 2.5,
                  data2,

manual.pdf

@@ -226,4 +226,19 @@ You can use the following options to customize each axis of the plot. You must p
   to its end.
 ]
 
-// = Chart
+#pagebreak()
+== Add
+
+#doc-style.parse-show-module("/src/plot/elements/bar.typ", first-heading-level: 2)
+
+
+#pagebreak()
+= Chart
+
+== Bar
+
+#doc-style.parse-show-module("/src/charts/bar/simple.typ", first-heading-level: 2)
+#pagebreak()
+#doc-style.parse-show-module("/src/charts/bar/clustered.typ", first-heading-level: 2)
+#pagebreak()
+#doc-style.parse-show-module("/src/charts/bar/stacked.typ", first-heading-level: 2)

manual.typ

@@ -0,0 +1 @@
+#import "charts/bar/bar.typ" as bar: stacked, clustered, simple

src/chart.typ

@@ -0,0 +1,3 @@
+#import "clustered.typ": clustered
+#import "stacked.typ": stacked, stacked100
+#import "simple.typ": simple

src/charts/bar/bar.typ

@@ -0,0 +1,99 @@
+#import "/src/cetz.typ": canvas, palette
+#import "plotter.typ": plotter
+
+/// Render a clustered bar chart
+///
+///  ```example
+///   cetz-plot.chart.bar.clustered(
+///     size: (4,4),
+///     (
+///       ([One],   1, 1, 2, 3),
+///       ([Two],   3, 1, 1 ,1),
+///       ([Three], 3, 2, 1, 3),
+///     ),
+///     label-key: 0,
+///     y-keys: (1,2,3,4),
+///     labels: (
+///       $0 -> 24$, 
+///       $25 -> 49$,
+///       $50 -> 74$, 
+///       $75 -> 100$
+///     ),
+///   )
+///   ```
+/// - data (array): An array of clusers to plot. Each entry can include a label
+///   for the cluster, shown on the `x` axis, a number of `y` coordinates that
+///   represent the magnitude of a bar that starts at 0, and optionally a
+///   corresponding number of `y-error` magnitudes for each bar.
+/// - labels (array): An array of either content or none, to be shown in the legend
+///   for its corresponding series. The n'th y-keys series is labelled by the
+///   n'th label (or none).
+/// - label-key (string, int): The key at which the x-axis label is described in
+///   each data entry.
+/// - y-keys (array): The n'th entry in `y-keys` corresponds to the key at which 
+///   the `y` coordinate can be found in each data entry, for the n'th series.
+/// - y-error-keys (any): The n'th entry in `y-error-keys` corresponds to the key at 
+///   which the `y-error` magnitude (as a float or as a tuple) can be found in
+///   each data entry, for the n'th series.
+/// - bar-width (float): The width of the bar along the `x` axis, in data-viewport
+///   space. The bar is drawn centered about its `x` coordinate, therefore, the bar 
+///   extends by $#raw("bar-width")\/2$ either side.
+/// - bar-spacing (float): The spacing between bars within a cluster, in data-viewprot 
+///   space.
+/// - bar-style (style): Style to use, can be used with a `palette` function
+/// - axes (axes): Name of the axes to use for plotting. Reversing the axes
+///   means rotating the plot by 90 degrees. 
+/// - ..plot-args (variadic): Additional plotting parameters and axis options to be 
+///   passed to @@plot
+#let clustered(
+  data,
+  labels: (),
+  label-key: 0,
+  y-keys: (1,),
+  y-error-keys: none,
+  bar-width: 0.7,
+  bar-spacing: 0,
+  bar-style: palette.red,
+  axes: ("x", "y"),
+  ..plot-args
+) = {
+  let series-count = y-keys.len()
+  bar-width /= series-count
+  let cluster-width = series-count * bar-width + (series-count - 1) * bar-spacing
+
+  let series-data = ()
+
+  for (series-index, y-key) in y-keys.enumerate() {
+
+    series-data.push(
+      (
+        label: if label-key != none {labels.at(series-index)},
+        data: for (observation-index, observation) in data.enumerate() { 
+          let x = observation-index - cluster-width/2 + series-index * (bar-width + bar-spacing) + bar-width/2
+          let y = observation.at(y-key, default: 0)
+          ((
+            x: x,
+            y: y,
+            y-error: if y-error-keys != none {
+              let err-key = y-error-keys.at(series-index, default: none)
+              if err-key != none {observation.at(err-key, default: 0)}
+            }
+          ),)
+        }
+      )
+    )
+  }
+
+  plotter(
+    data,
+    series-data,
+    x-key: "x", 
+    y-key: "y",
+    y-error-key: if y-error-keys != none {"y-error"},
+    label-key: label-key,
+    bar-width: bar-width,
+    bar-style: bar-style,
+    axes: axes,
+    ..plot-args,
+  )
+}

src/charts/bar/clustered.typ

@@ -0,0 +1,71 @@
+#import "/src/cetz.typ": draw, styles, palette
+#import "/src/plot.typ": plot
+#import "/src/plot/add.typ" as add: series, bar, errorbar
+#import "style.typ": barchart-default-style
+
+#let plotter(
+  data,
+  series-data,
+  x-key: "x", 
+  y-key: "y",
+  y-error-key: none,
+  y-offset-key: none,
+  label-key: none,
+  bar-width: 0.7,
+  bar-style: palette.red,
+  axes: ("x", "y"),
+  ..plot-args,
+) = {
+
+  draw.group(ctx => {
+
+    // Setup styles
+    let style = styles.resolve(
+      ctx.style, 
+      merge: (:),
+      root: "barchart", 
+      base: barchart-default-style
+    )
+    draw.set-style(..style)
+  
+    plot(
+      
+      // To do: Is there a better way to setup the x-axis using custom axis-style
+      x-min: -0.75, x-max: data.len() - 0.25,
+      x-tick-step: if label-key == none {1},
+      x-ticks: if label-key != none {
+        data.map((d)=>d.at(label-key, default: none)).enumerate()
+      } else {()},
+
+      y-grid: true,
+
+      plot-style: bar-style,
+      ..plot-args,
+
+      // Body argument: An array of series
+      for (label, data) in series-data {
+        add.series(
+          label: label,
+          {
+            add.bar(
+              data,
+              x-key: x-key,
+              y-key: y-key,
+              y-offset-key: y-offset-key,
+              bar-width: bar-width,
+              axes: axes,
+            )
+
+            if y-error-key != none {
+              add.errorbar(
+                data,
+                x-key: x-key,y-key: y-key, y-error-key: y-error-key,
+                axes: axes,
+              )
+            }
+          }
+        )
+      }
+    )
+  })
+}

src/charts/bar/plotter.typ

@@ -0,0 +1,112 @@
+#import "/src/cetz.typ": canvas, palette, draw, styles
+#import "/src/plot.typ": plot
+#import "/src/plot/add.typ" as add: series, bar, errorbar
+#import "style.typ": barchart-default-style
+
+/// Render a single series as a barchart
+///
+///  ```example
+///   cetz-plot.chart.bar.simple(
+///     size: (4,4),
+///     label-key: 0,
+///     y-key: 1,
+///     y-error-key: 2,
+///     label: [label],
+///     (
+///       ([One], 1, 0.5),
+///       ([Two], 3, 0.75),
+///       ([Three], 2, 1),
+///     ),
+///   )
+///   ```
+/// - data (array): An array of bars to plot. Each entry can include a label
+///   for the bar, shown on the `x` axis, a `y` coordinates that
+///   represents the magnitude of a bar that starts at 0, and optionally a
+///   `y-error` magnitude.
+/// - label (content, none): Optional label to be shown in legend
+/// - label-key (string, int): The key at which the x-axis label is described in
+///   each data entry.
+/// - y-key (string, int): The key at which the `y` coordinate is described in each
+///   data entry.
+/// - y-error-key (string, int, none): Optionally where `y-error` coordinate is 
+///   described in each data entry. 
+/// - bar-width (float): The width of the bar along the `x` axis, in data-viewport
+///   space. The bar is drawn centered about its `x` coordinate, therefore, the bar 
+///   extends by $#raw("bar-width")\/2$ either side.
+/// - bar-style (style): Style to use, can be used with a `palette` function
+/// - axes (axes): Name of the axes to use for plotting. Reversing the axes
+///   means rotating the plot by 90 degrees. 
+/// - ..plot-args (variadic): Additional plotting parameters and axis options to be 
+///   passed to @@plot
+#let simple(
+  data,
+  label: none,
+  label-key: 0,
+  y-key: 1,
+  y-error-key: none,
+  bar-width: 0.7,
+  bar-style: palette.red,
+  axes: ("x", "y"),
+  ..plot-args
+) = {
+
+  let data = data.enumerate().map(((index, entry))=> (
+    index,
+    entry.at(y-key, default: 0),
+    if y-error-key != none {entry.at(y-error-key, default: none)},
+    entry.at(label-key, default: none)
+  ))
+
+  draw.group(ctx => {
+
+    // Setup styles
+    let style = styles.resolve(
+      ctx.style, 
+      merge: (:),
+      root: "barchart", 
+      base: barchart-default-style
+    )
+    draw.set-style(..style)
+  
+    plot(
+      
+      // To do: Is there a better way to setup the x-axis using custom axis-style
+      x-min: -0.75, x-max: data.len() - 0.25,
+      x-tick-step: if label-key == none {1},
+      x-ticks: if label-key != none {
+        data.map((d)=>d.at(3, default: none)).enumerate()
+      } else {()},
+
+      y-grid: true,
+
+      plot-style: bar-style,
+      ..plot-args,
+
+      {
+        add.series(
+          label: label,
+          {
+            add.bar(
+              data,
+              x-key: 0,
+              y-key: 1,
+              bar-width: bar-width,
+              axes: axes,
+            )
+
+            if y-error-key != none {
+              add.errorbar(
+                data,
+                x-key: 0,
+                y-key: 1, 
+                y-error-key: 2,
+                axes: axes,
+              )
+            }
+          }
+        )
+      }
+    )
+  })
+
+}