.. _data-tables:
Data tables, with rows containing observations and columns containing variables or series, are arguably the cornerstone of science. Much of the functionality of Toyplot or any other plotting package can be reduced to a process of mapping data series from tables to properties like coordinates and colors. To facilitate this, Toyplot provides :class:toyplot.data.Table - an ordered, heterogeneous collection of named, equal-length columns, where each column is a Numpy masked array. Toyplot data tables are used for internal storage and manipulation by all of the individual types of plot, and can be useful for managing data prior to ingestion into Toyplot.
Be careful not to confuse the data tables described in this section with :ref:table-axes, which are used to visualize tabular data.
In [1]:
import toyplot.data
import numpy
In [2]:
table = toyplot.data.Table()
table["x"] = numpy.arange(10)
table["x*2"] = table["x"] * 2
table["x^2"] = table["x"] ** 2
table
Out[2]:
You can see from this small example that Toyplot tables provide automatic pretty-printing when used with Jupyter notebooks, like other Toyplot objects (Jupyter pretty-printing is provided as a convenience - to create tabular data graphics, you will likely want the additional control provided by :ref:table-axes).
Tables behave much like Python dicts, allowing you to assign and access columns using indexing notation with column names. The keys(), values(), and items() methods also act like their standard library counterparts, providing column-oriented access to the table contents ... but note that, unlike a normal Python dict, a Toyplot table remembers the order in which columns were added to the table, and always returns them in the same order:
In [3]:
for name in table.keys():
print name
In [4]:
for column in table.values():
print column
In [5]:
for name, column in table.items():
print name, column
However, tables also behave similarly to Python lists, providing length and slicing operations for row-oriented access to their contents:
In [6]:
len(table)
Out[6]:
In [7]:
table[2:5]
Out[7]:
Note from above that slicing a table returns another table, with the same set of columns but fewer rows. Similarly, you can create a new table using a subset of an existing table's columns:
In [8]:
table.columns(["x*2", "x"])
Out[8]:
... this also allows you to reorder the columns in a table.
Finally, as a convenience for documentation and tutorials only, Toyplot provides basic functionality to load a table from a CSV file - but please note that Toyplot is emphatically not a data manipulation library! For real work you should use the Python standard library :mod:csv module to load data, or functionality provided by libraries such as Numpy or Pandas.
In the following example, we load a set of temperature readings:
In [9]:
table = toyplot.data.read_csv("temperatures.csv")
table[0:10]
Out[9]:
Then, we convert the readings from Celsius to Fahrenheit and plot them over time:
In [10]:
table["TMAX_F"] = ((table["TMAX"].astype("float64") * 0.1) * 1.8) + 32
table["TMIN_F"] = ((table["TMIN"].astype("float64") * 0.1) * 1.8) + 32
In [11]:
canvas = toyplot.Canvas(width=600, height=300)
axes = canvas.axes(xlabel="Day", ylabel=u"Temperature \u00b0F")
axes.plot(table["TMAX_F"], color="red", stroke_width=1)
axes.plot(table["TMIN_F"], color="blue", stroke_width=1);
In [ ]: