Python: the flint module

flint builds a Flint chart in a Python notebook. A cell that ends in a chart draws it. The module is imported in every Python notebook before the first cell, so flint.bar(...) works as written; in another module, import flint.

For guides with examples, see charts and tables and Python notebooks. The C# equivalent is Plot.

Data

Every function takes data first. It can be:

a pandas DataFrame, read with to_dict("records");
a list of dicts, one per row;
a dict of lists, one list per column; the columns are zipped into rows. Columns of different lengths raise ValueError: the columns have different lengths.

More than flint.MAX_ROWS (50,000) rows raises ValueError: a chart takes at most 50000 rows; aggregate the data first. Values that JSON cannot hold, such as a timestamp, are written as their text.

Chart functions

Each returns a Chart. A null title leaves the chart untitled.

Signature	Chart	Channels set
`flint.bar(data, x, y, title=None)`	Bar Chart	`x`, `y`
`flint.stacked_bar(data, x, y, color, title=None)`	Stacked Bar Chart	`x`, `y`, `color`
`flint.line(data, x, y, title=None)`	Line Chart	`x`, `y`. `y` is a field name or a list or tuple of names, a series each.
`flint.area(data, x, y, title=None)`	Area Chart	`x`, `y`
`flint.scatter(data, x, y, title=None)`	Scatter Plot	`x`, `y`
`flint.pie(data, category, value, title=None)`	Pie Chart	`color` = category, `size` = value
`flint.donut(data, category, value, title=None)`	Donut Chart	`color` = category, `size` = value
`flint.histogram(data, x, title=None)`	Histogram	`x`
`flint.heatmap(data, x, y, color, title=None)`	Heatmap	`x`, `y`, `color`
`flint.chart(chart_type, data, **encodings)`	Any of `flint.CHART_TYPES`	The keywords. `title` is the title; every other keyword is a channel (`x="Day"`, `y=["a", "b"]`).
`flint.from_spec(spec)`	Whatever the spec says	A spec written elsewhere, as a `dict` or as JSON text.

flint.bar(sales, x="Product", y="Sales", title="Sales per product")
flint.chart("Heatmap", grid, x="Day", y="Hour", color="Visits", title="Visits")

flint.chart matches the type name without regard to case and writes it as Flint names it. A name that is not a chart type raises ValueError listing every valid name.

flint.from_spec returns an object that draws the spec and has to_json(). It does not check the spec: a spec that cannot be drawn shows Flint's reason in the cell.

flint.from_spec({
    "data": {"values": [{"q": "Q1", "plan": 120, "actual": 108}]},
    "chart_spec": {"chartType": "Line Chart", "encodings": {"x": "q", "y": ["plan", "actual"]}},
})

Module values

Name	Value
`flint.CHART_TYPES`	A list of the 39 chart type names.
`flint.MIME`	`"application/vnd.flint+json"`, the output type a chart travels as.
`flint.MAX_ROWS`	`50000`

Chart

flint.Chart(chart_type, data) is a chart being built. The functions above create one; construct it directly when the type is a variable. Every method that sets something returns the same chart, so calls chain.

Method	Description
`.encode(channel, *fields)`	Puts fields on any channel by name: `x`, `y`, `color`, `size`, `group`, `shape`, `column`, `row`, `open`, `high`, `low`, `close` and the rest of Flint's channels. Empty fields are ignored. One field is written as a string, several as a list.
`.x(field)`	The field on the x axis.
`.y(*fields)`	The field or fields on the y axis.
`.color(field)`	A series per value of the field.
`.size(field)`	Sizes the marks by the field.
`.group(field)`	Groups bars side by side.
`.title(text)`	The title above the chart. `None` leaves it unchanged.
`.semantic(field, kind)`	What a field means: `"Date"`, `"Amount"`, `"Percentage"`, `"Category"` and the other Flint semantic types. Decides scale, format and colors. Fields without one are inferred.
`.property(name, value)`	A property of the chart type, written under `chartProperties`: `innerRadius`, `showPoints`, `stackMode`, `binCount`, `cornerRadius` and others.
`.spec()`	The Flint spec, as a `dict`.
`.to_json()`	The spec as JSON text.

(flint.line(rows, x="Year", y=["Plan", "Actual"])
    .title("Revenue")
    .semantic("Year", "Year")
    .semantic("Plan", "Amount")
    .property("showPoints", True))

A chart prints as <Bar Chart: 3 rows, "Sales per product"> where it cannot be drawn, and shows the same text beside the drawing in the notebook's text output.

The spec

chart.spec() returns:

{
    "data": {"values": [...]},
    "semantic_types": {...},            # only when .semantic() was called
    "chart_spec": {
        "chartType": "Bar Chart",
        "title": "...",                 # only when a title was set
        "encodings": {"x": "Product", "y": "Sales"},
        "chartProperties": {...},       # only when .property() was called
    },
}

This is the JSON a ```flint fence in a chat reply holds, so a spec from a model can be drawn with flint.from_spec, and one built here can be pasted into a chat.