.. _convenience-api:

Convenience API

With Toyplot, a figure always consists of three parts:

  • A :py:class:canvas <toyplot.canvas.Canvas>
  • One or more sets of :py:mod:axes <toyplot.axes> added to the canvas.
  • One or more :py:mod:marks <toyplot.mark> added to the axes.

Creating these entities separately gives you the maximum flexibility, allowing you to add multiple axes (even overlapping axes) to one canvas, splitting the marks among the different axes, etc. However for simple figures containing a single set of axes and a single mark, this way of working can be tedious. Toyplot's convenience API combines the three calls to create canvas, axes, and mark into a single function that can handle many of your plotting needs with a minimum of code.

Consider the following verbose example:


In [1]:
import numpy
y = numpy.linspace(0, 1, 20) ** 2

In [2]:
import toyplot
canvas = toyplot.Canvas(width=300)
axes = canvas.axes()
axes.plot(y);


051015200.00.51.0

Using the convenience API, it can be reduced to a single call to :py:func:toyplot.plot:


In [3]:
canvas, axes, mark = toyplot.plot(y, width=300)


051015200.00.51.0

Of course, if you're using the convenience API there's a good chance you don't need the function's return value (a (canvas, axes, mark) tuple) at all, making it even more compact:


In [4]:
toyplot.plot(y, width=300);


051015200.00.51.0

If you check the reference documentation for :py:func:toyplot.plot, you will see that its parameters include the union of the parameters for :py:class:toyplot.canvas.Canvas, :py:meth:toyplot.canvas.Canvas.axes, and :py:meth:toyplot.axes.Cartesian.plot, except where parameter names might conflict.

Similar convenience API functions are provided for :py:func:bar <toyplot.bars>, :py:func:fill <toyplot.fill>, and :py:func:scatter <toyplot.scatterplot> plots:


In [5]:
toyplot.bars(y, width=300);


010200.00.51.0

In [6]:
toyplot.fill(numpy.column_stack((y, y*2)), width=300);


051015200.00.51.01.52.0

In [7]:
numpy.random.seed(1234)
toyplot.scatterplot(numpy.random.normal(size=50), width=300);


01020304050-202

In [8]:
toyplot.matrix(numpy.random.normal(size=(10, 10)), width=300);


012345678900.841008794931-1.44581007704-1.4019732815-0.100918199949-0.548242449187-0.1446195083690.354020332199-0.03551302527810.5657383060631.545658804631-0.974236333767-0.07034487710410.307968855216-0.2084987631061.03380073256-2.400453633812.03060362084-1.142631289020.2118833867780.7047206243172-0.7854352117630.4620597371620.7042282254620.523507967894-0.926254313532.007842950780.226962541871-1.152659109250.6319794458090.039512686693430.464392325051-3.563516660621.321105615470.1526305522050.164529542932-0.4300956908760.7673687357520.984919841910.2708358488271.3919861934540.0798423130086-0.399964580697-1.02785055868-0.5847182112610.816593926548-0.0819470518267-0.3447660142550.528288145297-1.06898878348-0.51188130912750.2912053597430.5665336963540.5035917591110.2852956847820.484288112751.36348151243-0.781105283625-0.4680176663371.22457435513-1.2811082751460.875475504274-1.71071532403-0.4507651031360.749163805919-0.203932866101-0.1821754116660.680656004381-1.818498990390.04707163532570.3948442093277-0.248432054381-0.617706647997-0.6828839964490.436257604341-1.703012774110.393710599139-0.479324003575-0.2990162929660.6941032876790.6786296737180.2395559950040.1512266292940.816127233361.89353446760.639632763194-0.962028831905-2.085265642121.93024676747-1.735348874471.210383704990.797435419428-0.3798107840470.702562224002-0.8503462716551.1768124501-0.5243361026320.7009077309160.984188070722-0.1217284086672.36576862884

In [9]:
columns = ["Year", "MPG", "Model"]
canvas, table = toyplot.table(toyplot.data.read_csv("cars.csv").columns(columns)[:10], width=300)
table.column(2).width = 130


YearMPGModel70.018.0chevrolet chevelle malibu70.015.0buick skylark 32070.018.0plymouth satellite70.016.0amc rebel sst70.017.0ford torino70.015.0ford galaxie 50070.014.0chevrolet impala70.014.0plymouth fury iii70.014.0pontiac catalina70.015.0amc ambassador dpl

If you need greater control over the positioning of the axes within the canvas, need to add multiple axes to one canvas, or need to add multiple marks to one set of axes, you'll have to create the canvas and axes explicitly.