Skip to content

Charts, Tables, and Output

show — display inline

Pivotal has three main output commands:

  • show previews the active table inline.
  • plot creates a chart from the active table.
  • table creates a formatted report table from the active table.

Use pivot plot when you want to aggregate and chart in one step without creating a separate summary table.

Display the current state of the active table inline in the notebook or terminal output.

with sales
    filter price > 100
    show

Variants

show          # full table
show head     # first 5 rows
show summary  # descriptive statistics (like df.describe())
show shape    # row and column counts
show columns  # column names

show can appear mid-pipeline — it displays the table at that point without interrupting subsequent operations:

with sales
    filter status == "active"
    show head              # peek at filtered data
    group by region
        agg sum revenue as total
    show                   # display final summary

plot — create a chart

Create a matplotlib chart from the active table.

Basic syntax

with summary
    plot <chart_name>
        kind <chart_type>
        x <col>
        y <col>
        title "<title>"

plot uses the current active table as its source, so it fits naturally after group by, pivot, select, or other reshaping steps.

Shorthand kind

The chart type can be specified directly after plot:

with summary
    plot bar revenue_chart
        x category
        y total
        title "Revenue by Category"

Chart types

Type Description
bar Vertical bar chart
line Line chart
scatter Scatter plot
hist Histogram
box Box plot
area Area chart

Options

Option Description
kind "<type>" Chart type
x <col> X-axis column
y <col> Y-axis column (or multiple: y col1, col2)
title "<text>" Chart title
legend <true/false> Show/hide legend
c <col> Colour-by column (scatter)
colormap "<name>" Matplotlib colormap name
by <col> Create faceted subplots by this column
cols <n> Number of columns in faceted layout
style "<file>" Path to a matplotlib style file
show Render inline (in addition to viewer)

Labels can be supplied after a plotted value:

with summary
    plot line sales_chart
        x month "Month"
        y revenue "Revenue"

Examples

with trends
    plot line price_trend
        x date
        y price
        title "Price Over Time"
        legend False

with raw
    plot scatter price_qty
        x price
        y quantity
        c category
        colormap "viridis"
        title "Price vs Quantity"

with sales
    plot bar regional_chart
        x category
        y revenue
        by region
        cols 2
        title "Revenue by Category and Region"

pivot plot — chart with inline aggregation

pivot plot groups and aggregates the source table then plots the result directly, without producing a separate summary table. The y line takes one or more func col pairs separated by commas, allowing different aggregation functions per column.

Basic syntax

with sales
    pivot plot bar revenue_chart
        x region
        y sum amount

Multiple y columns (different funcs per column)

with matches
    pivot plot line season_chart
        x season
        y mean home_team_goal, mean away_team_goal "Goals"

With filter

Place a filter statement before pivot plot to pre-filter the source data:

with sales
    filter year > 2020
    pivot plot bar recent_chart
        x category
        y sum revenue, mean price

Options

Option Description
x <col> X-axis (group-by) column
y <func> <col>, ... One or more func col pairs; optional label string at end
by <col> Facet into subplots by this column
cols <n> Number of columns in faceted layout (default 2)
canvas <size> Figure canvas size
show Render inline in addition to viewer

Aggregation functions: mean sum count min max median

table — publication-ready table

Create a formatted table using Great Tables. Requires pip install pivotal[tables].

Basic table

with results
    table summary
        title "Sales Summary"
        format number 2

Full options

with results
    table report
        title "Season Results"
        subtitle "All matches, 2023–24"
        font size 11
        font "Georgia"
        stub team, division "Club"
        spanner goals, win_rate "Performance"
        spanner revenue "Financials"
        label goals as "Goals Scored", win_rate as "Win %"
        format number 1
        format revenue as currency GBP
        format win_rate as percent 1
        summary sum as "Total", mean as "Average"
        stripe
        canvas a4
        style "my_table_style.py"
        show

Options reference

Title and layout

Option Description
title "<text>" Table title
subtitle "<text>" Table subtitle
canvas <size> Page size: a4, a4_landscape, a3, a3_landscape, letter, slide
stripe Alternating row shading

Font

font size 11          # font size in pt
font "Georgia"        # font family

Stub (row labels)

The stub is the leftmost identifying column(s):

stub product                     # single column
stub product "Product"           # with custom header label
stub product, category           # column + group-by
stub product, category "Item"    # all three

Spanners (column groups)

Group columns under a shared header:

spanner price, quantity "Metrics"
spanner revenue, cost, profit "Financials"
auto spanner    # infer from MultiIndex column names

Column labels

label goals as "Goals Scored", win_rate as "Win %", revenue as "Revenue (£)"

Formatting

format number 2           # all numeric cols, 2 decimal places
format integer            # all numeric cols, no decimals
format col as number 2    # specific column
format col as currency GBP
format col as percent 1
format col as date

Summary rows

summary sum                          # one "Total" row
summary sum as "Total"               # explicit label
summary sum as "Total", mean as "Avg"  # multiple summary rows

Inline display

table my_table
    title "Results"
    show    # render inline in notebook