Overview

scripton.orion is a plotting toolkit based on Observable's Plot JavaScript library for displaying tabular data. It translates its API into Python and allows directly using data from sources like Pandas dataframes and NumPy arrays.

Here's an example —

import pandas

from scripton import orion as Plot

penguins = pandas.read_csv('penguins.csv')

Plot.plot(
    grid=True,
    color={'legend': True},
    marks=[
        Plot.dot(
            penguins,
            x='flipper_length_mm',
            y='body_mass_g',
            fill='species',
            tip=True
        ),
        Plot.density(
            penguins,
            x='flipper_length_mm',
            y='body_mass_g',
            stroke='species'
        )
    ]
)

`orion.plot`

def plot(
    *,
    key: str | None = None,
    **options: Unpack[PlotOptions]
) -> None:
    ...

Various plot options (corresponding to the ones mentioned in Observable Plot's documentation) can be specified as keyword arguments. For instance, the grid=True option in the introductory example results in the grid being rendered.
The marks option specifies which "Marks" (plot elements like bars, lines, and dots) make up the plot. The next section explores these in more detail.

Marks

Marks represent geometric shapes (like bars, lines, and dots) that comprise the plot.
A single plot can contain multiple marks. For instance, the example above layers the dot and density marks. The marks are layered in the order specified.
For plots containing a single mark, it's often convenient to directly invoke the Mark's .plot method (instead of passing the mark to orion.plot):

# Same as: Plot.plot(marks=[Plot.line(prices, x='Date', y='Close')]) Plot.line(prices, x='Date', y='Close').plot()
Mark functions typically accept two arguments: data and options. For instance:

def dot(data: Data, options: DotOptions) -> Mark: ...
The introductory example uses a Pandas dataframe for the data argument. In addition, a few other formats are supported and covered in the following section.

For a more detailed overview of Marks, please see Observable's documentation on the topic.

Data Formats

The data to be plotted can be provided in a few different ways:

As a Pandas DataFrame. The mark options dictionary will typically refer to the column names.

This example plots the following Apple stock price DataFrame loaded from a csv file using Pandas:

import pandas from scripton import orion as Plot table = pandas.read_csv('aapl_stock.csv', parse_dates=['Date']) Plot.line(table, x='Date', y='Close').plot()
As a Python dict mapping column names to numeric arrays (typically NumPy 1D arrays). The mark options will typically refer to the arrays by their corresponding dictionary keys.

import numpy as np from scripton import orion as Plot t = np.linspace(0, 4 * np.pi, 100) ( Plot .line( { 'time': t, 'signal': np.cos(t) }, x='time', y='signal' ) .plot() )
As a list of dict instances, where each dictionary corresponds to a single datum/item. Each dictionary is expected to have the same set of keys.

from scripton import orion as Plot data = [ {"Model": "LaMDA", "Parameters (Billion)": 137}, {"Model": "GPT-3", "Parameters (Billion)": 175}, {"Model": "Jurassic", "Parameters (Billion)": 178}, {"Model": "Gopher", "Parameters (Billion)": 280}, {"Model": "Chinchilla", "Parameters (Billion)": 70}, ] ( Plot .barY( data, x='Model', y='Parameters (Billion)' ) .plot() )