perspective-python API

perspective.table contains Table and View, the data primitives of Perspective.

For usage, see the Python User Guide.

Table

class perspective.table.Table(data, limit=None, index=None)

Bases: object

_init_(data, limit=None, index=None)

Construct a Table using the provided data or schema and optional configuration dictionary.

Table instances are immutable - column names and data types cannot be changed after creation. If a schema is provided, the Table will be empty. Subsequent updates MUST conform to the column names and data types provided in the schema.

  • Parameters

    data (dict/list/pandas.DataFrame) – Data or schema which initializes the Table.

  • Keyword Arguments

    • index (str) – A string column name to use as the Table primary key.

    • limit (int) – The maximum number of rows the Table should have. Cannot be set at the same time as index. Updates past the limit will begin writing at row 0.

compute()

Returns whether the computed column feature is enabled.

clear()

Removes all the rows in the Table, but preserves everything else including the schema and any callbacks or registered View.

replace(data)

Replaces all rows in the Table with the new data that conforms to the Table schema.

  • Parameters

    data (dict/list/pandas.DataFrame) – New data that will be filled into the Table.

size()

Returns the row count of the Table.

schema(as_string=False)

Returns the schema of this Table, a dict mapping of string column names to python data types.

  • Keyword Arguments

    as_string (bool) – returns the data types as string representations, if True

  • Returns

    A key-value mapping of column names to data types.

  • Return type

    dict

columns(computed=False)

Returns the column names of this Table.

  • Keyword Arguments

    computed (bool) – Whether to include computed columns in this array. Defaults to False.

  • Returns

    a list of string column names

  • Return type

    list

computed_schema()

Returns a schema of computed columns added by the user.

  • Returns

    a key-value mapping of column names to computed

    columns. Each value is a dictionary that contains column_name, column_type, and computation.

  • Return type

    dict

is_valid_filter(filter)

Tests whether a given filter expression string is valid, e.g. that the filter term is not None or an unparsable date/datetime. null/ not null operators don’t need a comparison value.

  • Parameters

    filter (string) – The filter expression to validate.

  • Returns

    Whether this filter is valid.

  • Return type

    bool

update(data)

Update the Table with new data.

Updates on Table without an explicit index are treated as appends. Updates on Table with an explicit index should have the index as part of the data param, as this instructs the engine to locate the indexed row and write into it. If an index is not provided, the update is treated as an append.

  • Parameters

    data (dict/list/pandas.DataFrame) – The data with which to update the Table.

Examples
>>> tbl = Table({"a": [1, 2, 3], "b": ["a", "b", "c"]}, index="a")
>>> tbl.update({"a": [2, 3], "b": ["a", "a"]})
>>> tbl.view().to_dict()
{"a": [1, 2, 3], "b": ["a", "a", "a"]}

remove(pkeys)

Removes the rows with the primary keys specified in pkeys.

If the Table does not have an index, remove() has no effect. Removes propagate to views derived from the table.

  • Parameters

    pkeys (list) – a list of primary keys to indicate the rows that should be removed.

Examples
>>> tbl = Table({"a": [1, 2, 3]}, index="a")
>>> tbl.remove([2, 3])
>>> tbl.view().to_records()
[{"a": 1}]

view(columns=None, row_pivots=None, column_pivots=None, aggregates=None, sort=None, filter=None)

Create a new View from this Table via the supplied keyword arguments.

A View is an immutable set of transformations applied to the data stored in a Table, which can be used for querying, pivoting, aggregating, sorting, and filtering.

  • Keyword Arguments

    • columns (list of str) – A list of column names to be visible to the user.

    • row_pivots (list of str) – A list of column names to use as row pivots.

    • column_pivots (list of str) – A list of column names to use as column pivots.

    • 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.

  • Returns

    A new View

    instance bound to this Table.

  • Return type

    View

Examples
>>> tbl = Table({"a": [1, 2, 3]})
>>> view = tbl.view(filter=[["a", "==", 1]]
>>> view.to_dict()
>>> {"a": [1]}

on_delete(callback)

Register a callback to be invoked when the delete() method is called on this Table.

  • Parameters

    callback (func) – A callback function to invoke on delete.

Examples
>>> def deleter():
...     print("Delete called!")
>>> table.on_delete(deleter)
>>> table.delete()
>>> Delete called!

remove_delete(callback)

De-register the supplied callback from the delete() event for this Table

Examples
>>> def deleter():
...     print("Delete called!")
>>> table.on_delete(deleter)
>>> table.remove_delete(deleter)
>>> table.delete()

delete()

Delete this Table and clean up associated resources, assuming it has no View instances registered to it (which must be deleted first).

View

class perspective.table.view.View(Table, **kwargs)

Bases: object

A View object represents a specific transform (pivot, filter, sort, etc) configuration on an underlying Table. View objects cannot be directly instantiated - they must be derived from an existing Table via the view() method.

View instances receive all updates from the Table from which they are derived, and can be serialized (via to_\* methods) or trigger a callback when it is updated. View objects will remain in memory and actively process updates until delete() method is called.

get_config()

Returns a copy of the immutable configuration kwargs from which this View was instantiated.

  • Returns

    kwargs supplied to the

    perspective.Table.view() method.

  • Return type

    dict

sides()

An integer representing the # of hierarchial axis on this View.

0 - Neither row_pivots nor column_pivots properties are set.

1 - row_pivots is set.

2 - column_pivots is set (and also maybe row_pivots).

  • Returns

    0 <= N <= 2

  • Return type

    int

num_rows()

The number of aggregated rows in the View.

This count includes the total aggregate rows for all row_pivots depth levels, and can also be affected by any applied filter.

  • Returns

    Number of rows.

  • Return type

    int

num_columns()

The number of aggregated columns in the View. This is affected by the column_pivots that are applied to the View.

  • Returns

    Number of columns.

  • Return type

    int

get_row_expanded(idx)

Returns whether row at idx is expanded or collapsed.

  • Returns

    Is this row expanded?

  • Return type

    bool

expand(idx)

Expands the row at ‘idx’, i.e. displaying its leaf rows.

  • Parameters

    idx (int) – Row index to expand.

collapse(idx)

Collapses the row at ‘idx’, i.e. hiding its leaf rows.

  • Parameters

    idx (int) – Row index to collapse.

set_depth(depth)

Sets the expansion depth of the pivot tree.

  • Parameters

    depth (int) – Depth to collapse all nodes to, which may be no greater then the length of the row_pivots property.

column_paths()

Returns the names of the columns as they show in the View, i.e. the hierarchial columns when column_pivots is applied.

  • Returns

    obj`str`: Aggregated column names.

  • Return type

    list of

schema(as_string=False)

The schema of this View, which is a key-value map that contains the column names and their Python data types.

If the columns are aggregated, their aggregated types will be shown returned instead.

  • Keyword Arguments

    as_string (bool) – returns data types as string representations, if True.

  • Returns

    A map of str column name to str or

    type, depending on the value of as_string kwarg.

  • Return type

    dict

on_update(callback, mode=None)

Add a callback to be fired when perspective.Table.update() is called on the parent Table.

Multiple callbacks can be set through calling on_update multiple times, and will be called in the order they are set. Callback must be a callable function that takes exactly 0 or 1 parameter, depending on whether on_update is called with mode=”rows”. A RuntimeError will be thrown if the callback has mis-configured parameters.

  • Parameters

    • callback (callable) – a callable function reference that will be called when perspective.Table.update() is called.

    • mode (str) – if set to “rows”, the callback will be passed an Arrow-serialized dataset of the rows that were updated. Defaults to “none”.

Examples
>>> def updater():
...     print("Update fired!")
>>> view.on_update(updater)
>>> table.update({"a": [1]})'
>>> Update fired!

remove_update(callback)

Given a callback function, remove it from the list of callbacks.

  • Parameters

    callback (func) – a function reference that will be removed.

Examples
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view2 = table.view()
>>> def callback():
...     print("called!")
>>> view.on_update(callback)
>>> view2.on_update(callback)
>>> table.update(new_data)
called!
>>> view2.remove_update(callback)
>>> table.update(new_data) # callback removed and will not fire

on_delete(callback)

Set a callback to be run when the perspective.View.delete() method is called on this View.

  • Parameters

    callback (callable) – A callback to run after perspective.View.delete() method has been called.

Examples
>>> def deleter():
>>>     print("Delete called!")
>>> view.on_delete(deleter)
>>> view.delete()
>>> Delete called!

delete()

Delete the View and clean up all associated callbacks.

This method must be called to clean up resources used by the View, as it will last for the lifetime of the underlying Table otherwise.

Examples
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view.delete()

remove_delete(callback)

Remove the delete callback associated with this View.

  • Parameters

    callback (callable) – A reference to a callable function that will be removed from delete callbacks.

Examples
>>> table = perspective.Table(data)
>>> view = table.view()
>>> view2 = table.view()
>>> def callback():
...     print("called!")
>>> view.on_delete(callback)
>>> view2.on_delete(callback)
>>> view.delete()
called!
>>> view2.remove_delete(callback)
>>> view2.delete() # callback removed and will not fire

to_records(**kwargs)

Serialize the View’s dataset into a list of dict containing each row.

By default, the entire dataset is returned, though this can be windowed via kwargs. When row_pivots are applied, a __ROW_PATH__ column name will be generated in addition to the applied columns. When column_pivots are applied, column names will be qualified with their column group name.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A list of dict, where each dict

    represents a row of the current state of the View.

  • Return type

    list of dict

to_dict(**options)

Serialize the View’s dataset into a dict of str keys and list values. Each key is a column name, and the associated value is the column’s data packed into a list. If the View is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys and list values, where

    key = column name and value = column values.

  • Return type

    dict

to_numpy(**options)

Serialize the view’s dataset into a dict of str keys and numpy.array values. Each key is a column name, and the associated value is the column’s data packed into a numpy array.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys

    and numpy array values, where key = column name and value = column values.

  • Return type

    dict of numpy.array

to_df(**options)

Serialize the view’s dataset into a pandas dataframe.

If the view is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A DataFrame serialization of the current

    state of this View.

  • Return type

    pandas.DataFrame

to_csv(**options)

Serialize the View’s dataset into a CSV string.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

    • date_format (str) – How datetime objects should be formatted in the CSV.

  • Returns

    A CSV-formatted string containing the serialized data.

  • Return type

    str

to_json(**kwargs)

Serialize the View’s dataset into a list of dict containing each row.

By default, the entire dataset is returned, though this can be windowed via kwargs. When row_pivots are applied, a __ROW_PATH__ column name will be generated in addition to the applied columns. When column_pivots are applied, column names will be qualified with their column group name.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A list of dict, where each dict

    represents a row of the current state of the View.

  • Return type

    list of dict

to_columns(**options)

Serialize the View’s dataset into a dict of str keys and list values. Each key is a column name, and the associated value is the column’s data packed into a list. If the View is aggregated, the aggregated dataset will be returned.

  • Keyword Arguments

    • start_row (int) – (Defaults to 0).

    • end_row (int) – (Defaults to perspective.View.num_rows()).

    • start_col (int) – (Defaults to 0).

    • end_col (int) – (Defaults to perspective.View.num_columns()).

    • index (bool) – Whether to return an implicit pkey for each row (Defaults to False).

    • leaves_only (bool) – Whether to return only the data at the end of the tree (Defaults to False).

  • Returns

    A dictionary with string keys and list values, where

    key = column name and value = column values.

  • Return type

    dict 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(table_or_data, index=None, limit=None, client=False, **kwargs)

Bases: ipywidgets.widgets.widget.Widget, 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,
...     row_pivots=["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_(table_or_data, index=None, limit=None, client=False, **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.

  • Parameters

    table_or_data (perspective.Table|dict|list|pandas.DataFrame) – The Table or data that will be viewed in the widget.

  • Keyword Arguments

    • index (str) – A column name to be used as the primary key. Ignored if a Table 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 a Table is passed in.

    • 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 table_or_data is a dataset.

Examples
>>> widget = PerspectiveWidget(
...     {"a": [1, 2, 3]},
...     aggregates={"a": "avg"},
...     row_pivots=["a"],
...     sort=[["b", "desc"]],
...     filter=[["a", ">", 1]])

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(plugin='hypergrid', columns=None, row_pivots=None, column_pivots=None, aggregates=None, sort=None, filters=None, plugin_config=None, dark=None, editable=False)

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='hypergrid', columns=None, row_pivots=None, column_pivots=None, aggregates=None, sort=None, filters=None, plugin_config=None, dark=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.

    • row_pivots (list of str) – A list of column names to use as row pivots.

    • column_pivots (list of str) – A list of column names to use as column pivots.

    • 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.

    • plugin (str/perspective.Plugin) – Which plugin to select by default.

    • plugin_config (dict) – Custom config for all plugins by name.

    • dark (bool) – Whether to invert the colors.

Examples
>>> viewer = PerspectiveViewer(
...     aggregates={"a": "avg"},
...     row_pivots=["a"],
...     sort=[["b", "desc"]],
...     filter=[["a", ">", 1]]
... )

property table()

Returns the perspective.Table under management by the viewer.

property view()

Returns the perspective.View currently shown by the viewer.

This property changes every time the viewer configuration changes.

load(table_or_data, **options)

Given a perspective.Table or data that can be handled by perspective.Table, pass it to the viewer.

load() resets the state of the viewer. If a perspective.Table is passed into table_or_data, **options is ignored as the options already set on the Table take precedence. If data is passed in, a perspective.Table is automatically created by this function, and the options passed to **config are extended to the new Table.

  • Parameters

    table_or_data (Table`|`dict`|`list`|`pandas.DataFrame) – a perspective.Table instance or a dataset to be displayed 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 a Table 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 a Table is passed in.

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

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`|`list`|`pandas.DataFrame) – the update data for the table.

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`|`list`|`pandas.DataFrame) – new data to set into the table - must conform to the table’s schema.

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.

delete(delete_table=True)

Delete the Viewer’s data and clears its internal state. If delete_table is True, the underlying perspective.Table and all associated

`

View`s will be deleted.

  • Parameters

    delete_table (bool) – whether the underlying Table will be deleted. Defaults to True.

PerspectiveManager

PerspectiveManager implements a communication protocol between Perspective runtimes in different languages. Through its process() method, it allows runtimes to communicate instructions and interoperate.

class perspective.manager.manager.PerspectiveManager(lock=False)

Bases: object

PerspectiveManager is an orchestrator for running Perspective on the server side.

The core functionality resides in process(), which receives JSON-serialized messages from a client (usually perspective-viewer in the browser), executes the commands in the message, and returns the results of those commands back to the post_callback. The manager cannot create tables or views - use host_table or host_view to pass Table/View instances to the manager. Because Perspective is designed to be used in a shared context, i.e. multiple clients all accessing the same Table, PerspectiveManager comes with the context of sessions - an encapsulation of the actions and resources used by a single connection to Perspective.

  • When a client connects, for example through a websocket, a new session

    should be spawned using new_session().

  • When the websocket closes, call close() on the session instance to

    clean up associated resources.

lock()

Block messages that can mutate the state of

`

Table`s and

`

View`s under management.

All

`

PerspectiveManager`s exposed over the internet should be locked to prevent content from being mutated by clients.

unlock()

Unblock messages that can mutate the state of

`

Table`s and

`

View`s under management.

host(item, name=None)

Given a Table or View, place it under management and allow operations on it to be passed through the Manager instance.

  • Parameters

    table_or_view (Table/View) – a Table or View to be managed.

  • Keyword Arguments

    name (str) – an optional name to allow retrieval through get_table or get_view. A name will be generated if not provided.

host_table(name, table)

Given a reference to a Table, manage it and allow operations on it to occur through the Manager.

If a function for queue_process is defined (i.e., by PerspectiveTornadoHandler), bind the function to Table and have it call the manager’s version of queue_process.

host_view(name, view)

Given a View, add it to the manager’s views container.

get_table(name)

Return a table under management by name.

get_view(name)

Return a view under management by name.

callback(*args, **kwargs)

Return a message to the client using the post_callback method.

clear_views(client_id)

Garbage collect views that belong to closed connections.

perspective.manager.session.random()

class perspective.manager.session.PerspectiveSession(manager)

Bases: object

Encapsulates the actions and resources of a single connection to Perspective.

_init_(manager)

Create a new session object, keeping track of a unique client_id and the manager the session belongs to.

PerspectiveSession should not be constructed directly. Instead, use PerspectiveManager.new_session() to create a new session.

process(message, post_callback)

Pass a message to the manager’s process method, which passes the result to post_callback.

Additionally, intercept calls to on_update in order to track the callbacks that were created through this session. This allows for cleaning up callbacks after a session closes, which may not necessarily involve calling delete() on associated views.

close()

Remove the views and callbacks that were created within this session when the session ends.

← perspective-viewer API