Source code for toyplot

# Copyright 2014, Sandia Corporation. Under the terms of Contract
# DE-AC04-94AL85000 with Sandia Corporation, the U.S. Government retains certain
# rights in this software.

"""Provides the top-level :ref:`convenience-api`, which allows you to create
many plots using a single compact statement.
"""

import logging
import sys

if sys.version_info.major < 3:
    raise RuntimeError("As of version 0.19, Toyplot requires Python 3.  For Python 2 support, use Toyplot version 0.18")

from toyplot.canvas import Canvas

__version__ = "0.20.0-dev"

log = logging.getLogger(__name__)
log.setLevel(logging.WARNING)
log.addHandler(logging.NullHandler())


[docs]class DeprecationWarning(Warning): """Used with :func:`warnings.warn` to mark deprecated API.""" pass
[docs]def bars( a, b=None, c=None, along="x", baseline="stacked", color=None, filename=None, height=None, hyperlink=None, label=None, margin=50, opacity=1.0, padding=10, show=True, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale="linear", xshow=True, ylabel=None, ymax=None, ymin=None, yscale="linear", yshow=True, ): """Convenience function for creating a bar plot in a single call. See :meth:`toyplot.coordinates.Cartesian.bars`, :meth:`toyplot.canvas.Canvas.cartesian`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. axes: :class:`toyplot.coordinates.Cartesian` A new set of 2D axes that fill the canvas. mark: :class:`toyplot.mark.BarMagnitudes` or :class:`toyplot.mark.BarBoundaries` The new bar mark. """ canvas = Canvas(width=width, height=height) axes = canvas.cartesian( label=label, margin=margin, padding=padding, show=show, xlabel=xlabel, xmax=xmax, xmin=xmin, xscale=xscale, xshow=xshow, ylabel=ylabel, ymax=ymax, ymin=ymin, yscale=yscale, yshow=yshow, ) mark = axes.bars( a=a, b=b, c=c, along=along, baseline=baseline, color=color, filename=filename, hyperlink=hyperlink, opacity=opacity, style=style, title=title, ) return canvas, axes, mark
[docs]def fill( a, b=None, c=None, along="x", baseline=None, color=None, filename=None, height=None, label=None, margin=50, opacity=1.0, padding=10, show=True, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale="linear", xshow=True, ylabel=None, ymax=None, ymin=None, yscale="linear", yshow=True, ): """Convenience function for creating a fill plot in a single call. See :meth:`toyplot.coordinates.Cartesian.fill`, :meth:`toyplot.canvas.Canvas.cartesian`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. axes: :class:`toyplot.coordinates.Cartesian` A new set of 2D axes that fill the canvas. mark: :class:`toyplot.mark.FillBoundaries` or :class:`toyplot.mark.FillMagnitudes` The new fill mark. """ canvas = Canvas( height=height, width=width, ) axes = canvas.cartesian( label=label, margin=margin, padding=padding, show=show, xlabel=xlabel, xmax=xmax, xmin=xmin, xscale=xscale, xshow=xshow, ylabel=ylabel, ymax=ymax, ymin=ymin, yscale=yscale, yshow=yshow, ) mark = axes.fill( a=a, b=b, c=c, along=along, baseline=baseline, color=color, filename=filename, opacity=opacity, style=style, title=title, ) return canvas, axes, mark
[docs]def graph( a, b=None, c=None, along="x", ecolor=None, eopacity=1.0, estyle=None, ewidth=1.0, height=None, hmarker=None, layout=None, margin=50, mmarker=None, mposition=0.5, olayout=None, padding=20, tmarker=None, varea=None, vcolor=None, vcoordinates=None, vlabel=None, vlshow=True, vlstyle=None, vmarker="o", vopacity=1.0, vsize=None, vstyle=None, vtitle=None, width=None, ): # pragma: no cover """Convenience function for creating a graph plot in a single call. See :meth:`toyplot.coordinates.Cartesian.graph`, :meth:`toyplot.canvas.Canvas.cartesian`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. axes: :class:`toyplot.coordinates.Cartesian` A new set of 2D axes that fill the canvas. mark: :class:`toyplot.mark.Graph` The new graph mark. """ canvas = Canvas( height=height, width=width, ) axes = canvas.cartesian( aspect="fit-range", margin=margin, padding=padding, show=False, ) mark = axes.graph( a=a, b=b, c=c, along=along, ecolor=ecolor, eopacity=eopacity, estyle=estyle, ewidth=ewidth, hmarker=hmarker, layout=layout, mmarker=mmarker, mposition=mposition, olayout=olayout, tmarker=tmarker, varea=varea, vcolor=vcolor, vcoordinates=vcoordinates, vlabel=vlabel, vlshow=vlshow, vlstyle=vlstyle, vmarker=vmarker, vopacity=vopacity, vsize=vsize, vstyle=vstyle, vtitle=vtitle, ) return canvas, axes, mark
[docs]def image( data, height=None, margin=0, width=None, ): # pragma: no cover """Convenience function for displaying an image in a single call. See :meth:`toyplot.canvas.Canvas.image`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. mark: :class:`toyplot.mark.Image` The new image mark. """ canvas = Canvas( height=height, width=width, ) mark = canvas.image( data=data, margin=margin, ) return canvas, mark
[docs]def matrix( data, blabel=None, blocator=None, bshow=None, colorshow=False, filename=None, height=None, label=None, llabel=None, llocator=None, lshow=None, margin=50, rlabel=None, rlocator=None, rshow=None, step=1, tlabel=None, tlocator=None, tshow=None, width=None, ): """Convenience function to create a matrix visualization in a single call. See :meth:`toyplot.canvas.Canvas.matrix`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. table: :class:`toyplot.coordinates.Table` A new set of table axes that fill the canvas. """ canvas = Canvas( height=height, width=width, ) axes = canvas.matrix( blabel=blabel, blocator=blocator, bshow=bshow, colorshow=colorshow, data=data, filename=filename, label=label, llabel=llabel, llocator=llocator, lshow=lshow, margin=margin, rlabel=rlabel, rlocator=rlocator, rshow=rshow, step=step, tlabel=tlabel, tlocator=tlocator, tshow=tshow, ) return canvas, axes
[docs]def plot( a, b=None, along="x", area=None, aspect=None, color=None, filename=None, height=None, label=None, margin=50, marker=None, mfill=None, mlstyle=None, mopacity=1.0, mstyle=None, mtitle=None, opacity=1.0, padding=10, show=True, size=None, stroke_width=2.0, style=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale="linear", xshow=True, ylabel=None, ymax=None, ymin=None, yscale="linear", yshow=True, ): """Convenience function for creating a line plot in a single call. See :meth:`toyplot.coordinates.Cartesian.plot`, :meth:`toyplot.canvas.Canvas.cartesian`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. axes: :class:`toyplot.coordinates.Cartesian` A new set of 2D axes that fill the canvas. mark: :class:`toyplot.mark.Plot` The new plot mark. """ canvas = Canvas( height=height, width=width, ) axes = canvas.cartesian( aspect=aspect, label=label, margin=margin, padding=padding, show=show, xlabel=xlabel, xmax=xmax, xmin=xmin, xscale=xscale, xshow=xshow, ylabel=ylabel, ymax=ymax, ymin=ymin, yscale=yscale, yshow=yshow, ) mark = axes.plot( a=a, b=b, along=along, area=area, color=color, filename=filename, marker=marker, mfill=mfill, mlstyle=mlstyle, mopacity=mopacity, mstyle=mstyle, mtitle=mtitle, opacity=opacity, size=size, stroke_width=stroke_width, style=style, title=title, ) return canvas, axes, mark
[docs]def scatterplot( a, b=None, along="x", area=None, aspect=None, color=None, filename=None, height=None, hyperlink=None, label=None, margin=50, marker="o", mlstyle=None, mstyle=None, opacity=1.0, padding=10, show=True, size=None, title=None, width=None, xlabel=None, xmax=None, xmin=None, xscale="linear", xshow=True, ylabel=None, ymax=None, ymin=None, yscale="linear", yshow=True, ): """Convenience function for creating a scatter plot in a single call. See :meth:`toyplot.coordinates.Cartesian.scatterplot`, :meth:`toyplot.canvas.Canvas.cartesian`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. axes: :class:`toyplot.coordinates.Cartesian` A new set of 2D axes that fill the canvas. mark: :class:`toyplot.mark.Point` The new scatterplot mark. """ canvas = Canvas( height=height, width=width, ) axes = canvas.cartesian( aspect=aspect, label=label, margin=margin, padding=padding, show=show, xlabel=xlabel, xmax=xmax, xmin=xmin, xscale=xscale, xshow=xshow, ylabel=ylabel, ymax=ymax, ymin=ymin, yscale=yscale, yshow=yshow, ) mark = axes.scatterplot( a=a, b=b, along=along, area=area, color=color, filename=filename, hyperlink=hyperlink, marker=marker, mlstyle=mlstyle, mstyle=mstyle, opacity=opacity, size=size, title=title, ) return canvas, axes, mark
[docs]def table( data=None, brows=None, columns=None, filename=None, height=None, label=None, lcolumns=None, margin=50, rcolumns=None, rows=None, trows=None, width=None, ): """Convenience function to create a table visualization in a single call. See :meth:`toyplot.canvas.Canvas.table`, and :class:`toyplot.canvas.Canvas` for parameter descriptions. Returns ------- canvas: :class:`toyplot.canvas.Canvas` A new canvas object. table: :class:`toyplot.coordinates.Table` A new set of table axes that fill the canvas. """ canvas = Canvas( height=height, width=width, ) axes = canvas.table( brows=brows, columns=columns, data=data, filename=filename, label=label, lcolumns=lcolumns, margin=margin, rcolumns=rcolumns, rows=rows, trows=trows, ) return canvas, axes