Getting Started¶

Canvas is a framework that wraps task-specific visualization components for different environments. To load data into Canvas, only a Pandas-like metadata table is required. Canvas can be used in Jupyter Notebooks, created directly from Python scripts, and loaded as standalone web-based dashboards. Individual components have access to a shared state, which is kept in a shared toolbar component. This toolbar component synchronizes state between all active components and provides common interaction patterns.

Installation¶

To install the main Canvas package, run:

pip install canvas_ux

You can then install individual components, for example:

pip install canvas_summary

See Available Components for a list of all the other component packages. If you want to install all available components, run:

pip install "canvas_ux[widgets]"

Canvas works great with DeepView. You can use DeepView to generate analysis data for Canvas, for example for the Summary and scatterplot components. If you want to run the precomputed Canvas example that uses DeepView, run:

pip install "canvas_ux[examples]"

Usage¶

Canvas can either be used as individual components in a Jupyter Notebook or as a combination of components in a standalone web dashboard. We currently do not support Jupyter Lab.

Jupyter Notebook¶

First, we import the Canvas class and any components we would like to use, in this case only the CanvasSummary component.

from canvas_ux import Canvas
from canvas_summary import CanvasSummary

Next, for this example, we’ll create a simple Pandas DataFrame with some mock data.

import random
import pandas as pd

a = [random.random() * 100 for i in range(100)]
b = [random.random() * 10 for i in range(100)]
c = [random.random() for i in range(100)]

df = pd.DataFrame(zip(a, b, c), columns=['a', 'b', 'c'])
print(df.head())

           a         b         c
59.580617  6.976321  0.010547
62.707507  3.506051  0.812532
50.865468  4.308873  0.236048
89.494103  8.857749  0.168161
94.595381  1.067343  0.751413

Combining these, we can create a Canvas instance and use our components to explore the data.

symph = Canvas(df)
symph.widget(CanvasSummary)

That’s it! You can import different components and pass them to symph.widget(). To see other components, check out more Examples.

Standalone Dashboard¶

There are two ways to create and use a standalone dashboard.

Dashboard from a Notebook¶

If you are working from a notebook, you can export the current Canvas instance to a static folder using export().

symph.export('./standalone/')

Dashboard from a Python Script¶

You can also create a standalone version from a Python script, making it possible to run on remote services or as a chron job.

To do this, we use the standalone() function which takes in which components you would like to include.

from canvas_ux import Canvas
from canvas_summary import CanvasSummary

import random
import pandas as pd

a = [random.randint(0, 100) for i in range(100)]
b = [random.randint(50, 200) for i in range(100)]
c = [random.randint(0, 1) for i in range(100)]

df = pd.DataFrame(zip(a, b, c), columns=['a', 'b', 'c'])

symph = Canvas(df)
symph.standalone([CanvasSummary], './standalone/')

You can then serve the Canvas export from the command line python -m http.server to see the dashboard. The static directory can be deployed to a service like GitHub Pages to share with others.