perspective-python API
perspective.table
contains Table
and View
, the data primitives of Perspective.
For usage, see the Python User Guide.
Table
View
perspective.core
contains modules that implements perspective-python
in various environments,
most notably PerspectiveWidget
and PerspectiveTornadoHandler
.
Additionally, perspective.core
defines several enums that provide easy access to aggregate options, different plugins, sort directions etc.
For usage of PerspectiveWidget
and PerspectiveTornadoHandler
, see the User Guide in the sidebar.
PerspectiveWidget
PerspectiveWidget
is a Perspective integration into JupyterLab.
class perspective.widget.widget.PerspectiveWidget(**kwargs)
Bases: ipywidgets.widgets.domwidget.DOMWidget
, perspective.viewer.viewer.PerspectiveViewer
:class`~perspective.PerspectiveWidget` allows for Perspective to be used in the form of a JupyterLab IPython widget.
Using perspective.Table, you can create a widget that extends the full functionality of perspective-viewer. Changes on the viewer can be programatically set on the :class`~perspective.PerspectiveWidget` instance, and state is maintained across page refreshes.
Examples
>>> from perspective import Table, PerspectiveWidget
>>> data = {
... "a": [1, 2, 3],
... "b": [
... "2019/07/11 7:30PM",
... "2019/07/11 8:30PM",
... "2019/07/11 9:30PM"
... ]
... }
>>> tbl = Table(data, index="a")
>>> widget = PerspectiveWidget(
... tbl,
... group_by=["a"],
... sort=[["b", "desc"]],
... filter=[["a", ">", 1]]
... )
>>> widget.sort
[["b", "desc"]]
>>> widget.sort.append(["a", "asc"])
>>> widget.sort
[["b", "desc"], ["a", "asc"]]
>>> widget.update({"a": [4, 5]}) # Browser UI updates
_init_(data, index=None, limit=None, server=False, client=True, **kwargs)
Initialize an instance of :class`~perspective.PerspectiveWidget`
with the given table/data and viewer configuration.
If a pivoted DataFrame or MultiIndex table is passed in, the widget
preserves pivots and applies them. See PerspectiveViewer.__init__ for
arguments that transform the view shown in the widget.
Args:
data (`Table\`|:obj:\`View\`|:obj:\`dict\`|:obj:\`list\`|:obj:\`pandas.DataFrame\`|:obj:\`bytes\`|:obj:\`str`): a
perspective.Table instance, a perspective.View instance, or
a dataset to be loaded in the widget.
Keyword Arguments:
index (`str`): A column name to be used as the primary key.
Ignored if server is True.
limit (`int`): A upper limit on the number of rows in the Table.
Cannot be set at the same time as index, ignored if server
is True.
server (`bool`): Whether to run Perspective in “server-only”
mode, where the front-end client does not have its own Table,
and instead reads all data and operations from Python.
client (`bool`): If True, convert the dataset into an Apache Arrow
binary and create the Table in Javascript using a copy of the
data. Defaults to False.
kwargs (`dict`): configuration options for the PerspectiveViewer,
and Table constructor if data is a dataset.
Examples:
```python
>>> widget = PerspectiveWidget(
... {"a": [1, 2, 3]},
... aggregates={"a": "avg"},
... group_by=["a"],
... sort=[["b", "desc"]],
... filter=[["a", ">", 1]],
... expressions=["// new column
```
“Sales” + “Profit””])
load(data, **options)
Load the widget with data. If running in client mode, this method serializes the data and calls the browser viewer’s load method. Otherwise, it calls Viewer.load() using super().
update(data)
Update the widget with new data. If running in client mode, this method serializes the data and calls the browser viewer’s update method. Otherwise, it calls Viewer.update() using super().
clear()
Clears the widget’s underlying Table.
In client mode, clears the _data attribute of the widget.
replace(data)
Replaces the widget’s Table with new data conforming to the same schema. Does not clear user-set state. If in client mode, serializes the data and sends it to the browser.
delete(delete_table=True)
Delete the Widget’s data and clears its internal state. If running in client mode, sends the delete() command to the browser. Otherwise calls delete on the underlying viewer.
Parameters
delete_table (bool) – whether the underlying Table will be deleted. Defaults to True.
class perspective.viewer.viewer.PerspectiveViewer(**kwargs)
Bases: perspective.viewer.viewer_traitlets.PerspectiveTraitlets
, object
PerspectiveViewer wraps the perspective.Table API and exposes an API around creating views, loading data, and updating data.
_init_(plugin='Datagrid', columns=None, group_by=None, split_by=None, aggregates=None, sort=None, filter=None, expressions=None, plugin_config=None, settings=True, theme=None, editable=False)
Initialize an instance of PerspectiveViewer with the given viewer
configuration. Do not pass a Table or data into the constructor -
use the `load()` method to provide the viewer with data.
Keyword Arguments:
columns (`list` of `str`): A list of column names to be
visible to the user.
group_by (`list` of `str`): A list of column names to
use as group by.
split_by (`list` of `str`): A list of column names
to use as split by.
aggregates (`dict` of `str` to `str`): A dictionary
of column names to aggregate types, which specify aggregates
for individual columns.
sort (`list` of `list` of `str`): A list of lists,
each list containing a column name and a sort direction
(`asc`, `desc`, `asc abs`, `desc abs`, `col asc`,
`col desc`, `col asc abs`, `col desc abs`).
filter (`list` of `list` of `str`): A list of lists,
each list containing a column name, a filter comparator, and a
value to filter by.
expressions (`list` of `str`): A list of string
expressions which are applied to the view.
plugin (`str`/`perspective.Plugin`): Which plugin to
select by default.
plugin_config (`dict`): A configuration for the plugin, i.e.
the datagrid plugin or a chart plugin.
settings(`bool`): Whether the perspective query settings
panel should be open.
theme (`str`): The color theme to use.
editable (`bool`): Whether to allow editability using the grid.
Examples:
```python
>>> viewer = PerspectiveViewer(
... aggregates={"a": "avg"},
... group_by=["a"],
... sort=[["b", "desc"]],
... filter=[["a", ">", 1]],
... expressions=["// new column
```
“Sales” + “Profit””]
… )
property table()
Returns the perspective.Table
under management by the viewer.
load(data, **options)
Given a perspective.Table
, a perspective.View
,
or data that can be handled by perspective.Table
, pass it to the
viewer. Like init, load accepts a perspective.Table, a dataset,
or a schema. If running in client mode, load defers to the browser’s
Perspective engine. This means that loading Python-only datasets,
especially ones that cannot be serialized into JSON, may cause some
issues.
load()
resets the state of the viewer :
- If a
perspective.Table
has already been loaded,\*\*options
is ignored as the options already set on theTable
take precedence.
- If a
perspective.View
is loaded, the options on theperspective.Table
linked to the view take precedence.
If data is passed in, a perspective.Table
is automatically created
by this method, and the options passed to \*\*config
are extended to
the new Table. If the widget already has a dataset, and the new data
has different columns to the old one, then the widget state (pivots,
sort, etc.) is cleared to prevent applying settings on columns that
don’t exist.
Parameters
data (
Table\
|:obj:`View`|:obj:`dict`|:obj:`list`|:obj:`pandas.DataFrame`|:obj:`bytes`|:obj:`str`) – a perspective.Table instance, a perspective.View instance, or a dataset to be loaded in the viewer.
Keyword Arguments
name (
str
) – An optional name to reference the table by so it can be accessed from the front-end. If not provided, a name will be generated.index (
str
) – A column name to be used as the primary key. Ignored if aTable
orView
is supplied.limit (
int
) – A upper limit on the number of rows in the Table. Cannot be set at the same time as index. Ignored if aTable
orView
is supplied.
Examples
>>> from perspective import Table, PerspectiveViewer
>>> data = {"a": [1, 2, 3]}
>>> tbl = Table(data)
>>> viewer = PerspectiveViewer()
>>> viewer.load(tbl)
>>> viewer.load(data, index="a") # viewer state is reset
>>> viewer2 = PerspectiveViewer()
>>> viewer2.load(tbl.view())
update(data)
Update the table under management by the viewer with new data. This function follows the semantics of Table.update(), and will be affected by whether an index is set on the underlying table.
Parameters
data (
dict\
|:obj:`list`|:obj:`pandas.DataFrame`) – thedata for the table. (update) –
clear()
Clears the rows of this viewer’s Table
.
replace(data)
Replaces the rows of this viewer’s Table with new data.
Parameters
data (
dict\
|:obj:`list`|:obj:`pandas.DataFrame`) – new dataset into the table - must conform to the table's schema. (to) –
save()
Get the viewer’s attribute as a dictionary, symmetric with restore so that a viewer’s configuration can be reproduced.
restore(**kwargs)
Restore a given set of attributes, passed as kwargs (e.g. dictionary). Symmetric with save so that a given viewer’s configuration can be reproduced.
reset()
Resets the viewer’s attributes and state, but does not delete or modify the underlying Table.
Examples
widget = PerspectiveWidget(data, group_by=[“date”], plugin=Plugin.XBAR) widget.reset() widget.plugin #
delete(delete_table=True)
Delete the Viewer’s data and clears its internal state. If
delete_table
is True, the underlying perspective.Table and the
internal View object will be deleted.
Parameters
delete_table (
bool
) – whether the underlying Table will be deleted. Defaults to True.
PerspectiveTornadoHandler
PerspectiveTornadoHandler
is a ready-made Perspective server that interfaces seamlessly with
@finos/perspective-viewer
in Javascript.
PerspectiveManager
PerspectiveManager
implements a communication protocol between Perspective runtimes in different languages.
Through its process()
method, it allows runtimes to communicate instructions and interoperate.