Skip to content

Creating Data-Driven Charts

Charts are a core feature of SlideFlow, allowing you to visualize your data directly in rendered Slides decks and Docs sections. You can create everything from simple bar charts to complex, multi-trace visualizations using Plotly.

Core Concepts

All charts are defined within the charts list of a presentation.slides[] item in your config.yml. For Google Slides, positioning fields place the chart on the target slide. For Google Docs, charts are inserted inline at the matched section marker. Each chart has a type and a config block.

- type: "chart_type"
  config:
    # ... configuration for the chart

Types of Charts

SlideFlow supports three types of charts:

1. Plotly Graph Objects (plotly_go)

This is the most powerful and flexible way to create charts. It gives you access to the full power of the Plotly Graph Objects library. You define your chart by providing a list of traces and an optional layout_config.

Example:

- type: "plotly_go"
  config:
    title: "Monthly Revenue"
    data_source:
      type: "csv"
      name: "sales_data"
      file_path: "data/sales.csv"
    traces:
      - type: "bar"
        x: "$month"
        y: "$revenue"
    layout_config:
      xaxis:
        title: "Month"
      yaxis:
        title: "Revenue (USD)"

In this example, $month and $revenue are column references that will be replaced with the actual data from the sales_data source. When a scalar is required (for example Plotly indicator.value), use indexed references like $revenue[0] or $revenue[-1].

2. Template Chart (template)

This chart type allows you to use a reusable YAML template to define your chart. This is a good way to maintain a consistent style across repeated reporting outputs. See the Templating guide for more details.

Example:

- type: "template"
  config:
    title: "Monthly Active Users"
    template_name: "bars/bar_basic"
    data_source:
      type: "csv"
      name: "mau_data"
      file_path: "data/mau.csv"
    template_config:
      title: "Monthly Active Users"
      x_column: "month"
      y_column: "mau"
      y_title: "Active Users"

Built-in templates are bundled with SlideFlow. Local templates can override built-ins when names collide.

3. Custom Chart (custom)

For cases where you need complete control over the chart generation logic, you can use a custom Python function. You provide the function name and any additional configuration.

Example:

- type: "custom"
  config:
    title: "My Custom Chart"
    chart_fn: "create_my_special_chart"
    data_source:
      type: "csv"
      name: "custom_data"
      file_path: "data/custom.csv"
    chart_config:
      # ... additional config for your function

Positioning and Sizing

SlideFlow provides a flexible system for positioning and sizing charts on Google Slides. Google Docs charts are inserted inline and ignore slide-positioning fields.

  • x, y, width, height: These properties control the position and size of the chart. They can be numbers or string expressions (e.g., "400 + 50").
  • dimensions_format: This specifies the units for the x, y, width, and height properties. It can be pt (points), emu (English Metric Units), or relative (a ratio of the page size).
  • alignment_format: This allows you to align the chart relative to the slide. For example, center-top will center the chart horizontally and align it to the top of the slide.

Chart Data Transforms

Charts can include data_transforms before traces are rendered. See Data Transforms for the transform contract and registry setup.