API Reference#

The two main components to cuxfilter are DataFrame for connecting the dashboard to a cuDF backed dataframe, and Dashboard for setting dashboard options.

DataFrame#

class cuxfilter.dataframe.DataFrame(data)#

A cuxfilter GPU DataFrame object

Attributes:
data
edges

Methods

dashboard(charts[, sidebar, layout, theme, ...])

Creates a cuxfilter.DashBoard object

from_arrow(dataframe_location)

read an arrow file from disk as cuxfilter.DataFrame

from_dataframe(dataframe)

create a cuxfilter.DataFrame from cudf.DataFrame/dask_cudf.DataFrame (zero-copy reference)

load_graph(graph)

create a cuxfilter.DataFrame from cudf.DataFrame/dask_cudf.DataFrame (zero-copy reference) from a graph object

preprocess_data

validate_dask_index

dashboard(charts: list, sidebar: list = [], layout=<class 'cuxfilter.layouts.layouts.Layout0'>, theme=<class 'cuxfilter.themes.default.LightTheme'>, title='Dashboard', data_size_widget=True, warnings=False, layout_array=None)#

Creates a cuxfilter.DashBoard object

Parameters:
charts: list

list of cuxfilter.charts

layout: cuxfilter.layouts
theme: cuxfilter.themes, default cuxfilter.themes.default.
title: str

title of the dashboard, default “Dashboard”

data_size_widget: boolean

flag to determine whether to diplay the current datapoints selected in the dashboard, default True

warnings: boolean

flag to disable or enable runtime warnings related to layouts, default False

Returns:
cuxfilter.DashBoard object

Examples

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh
>>> df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> # create a dashboard object
>>> d = cux_df.dashboard([line_chart_1])
classmethod from_arrow(dataframe_location)#

read an arrow file from disk as cuxfilter.DataFrame

Parameters:
dataframe_location: str or arrow in-memory table
Returns:
cuxfilter.DataFrame object

Examples

Read dataframe as an arrow file from disk

>>> import cuxfilter
>>> import pyarrow as pa
>>> # create a temporary arrow table
>>> arrowTable = pa.Table.from_arrays([['foo', 'bar']], names=['name'])
>>> # read arrow table, can also ready .arrow file paths directly
>>> cux_df = cuxfilter.DataFrame.from_arrow(df)
classmethod from_dataframe(dataframe)#

create a cuxfilter.DataFrame from cudf.DataFrame/dask_cudf.DataFrame (zero-copy reference)

Parameters:
dataframe_location: cudf.DataFrame or dask_cudf.DataFrame
Returns:
cuxfilter.DataFrame object

Examples

Read dataframe from a cudf.DataFrame/dask_cudf.DataFrame

>>> import cuxfilter
>>> import cudf
>>> cudf_df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(cudf_df)
classmethod load_graph(graph)#

create a cuxfilter.DataFrame from cudf.DataFrame/dask_cudf.DataFrame (zero-copy reference) from a graph object

Parameters:
tuple object (nodes, edges) where nodes and edges are cudf DataFrames
Returns:
cuxfilter.DataFrame object

Examples

load graph from cugraph object

>>> import cuxfilter
>>> import cudf, cugraph
>>> edges = cudf.DataFrame(
>>>     {
>>>         'source': [0, 1, 2, 3, 4],
>>>         'target':[0,1,2,3,4],
>>>         'weight':[4,4,2,6,7],
>>>     }
>>> )
>>> G = cugraph.Graph()
>>> G.from_cudf_edgelist(edges, destination='target')
>>> cux_df = cuxfilter.DataFrame.load_graph((G.nodes(), G.edges()))

load graph from (nodes, edges)

>>> import cuxfilter
>>> import cudf
>>> nodes = cudf.DataFrame(
>>>     {
>>>         'vertex': [0, 1, 2, 3, 4],
>>>         'x':[0,1,2,3,4],
>>>         'y':[4,4,2,6,7],
>>>         'attr': [0,1,1,1,1]
>>>     }
>>> )
>>> edges = cudf.DataFrame(
>>>     {
>>>         'source': [0, 1, 2, 3, 4],
>>>         'target':[0,1,2,3,4],
>>>         'weight':[4,4,2,6,7],
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.load_graph((nodes,edges))

DashBoard#

class cuxfilter.dashboard.DashBoard(charts=[], sidebar=[], dataframe=None, layout=<class 'cuxfilter.layouts.layouts.Layout0'>, theme=<class 'cuxfilter.themes.default.LightTheme'>, title='Dashboard', data_size_widget=True, show_warnings=False, layout_array=None)#

A cuxfilter GPU DashBoard object. Examples ——–

Create a dashboard

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh, panel_widgets
>>> df = cudf.DataFrame(
>>>     {'key': [0, 1, 2, 3, 4], 'val':[float(i + 10) for i in range(5)]}
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> line_chart_2 = bokeh.bar(
>>>     'val', 'key', data_points=5, add_interaction=False
>>> )
>>> sidebar_widget = panel_widgets.card("test")
>>> d = cux_df.dashboard(charts=[line_chart_1, line_chart_2],
>>> sidebar=[sidebar_widget])
>>> d
`cuxfilter DashBoard
[title] Markdown(str)
[chart0] Markdown(str, sizing_mode='stretch_both'), ['nav'])
[chart1] Column(sizing_mode='scale_both', width=1600)
    [0] Bokeh(Figure)
[chart2] Column(sizing_mode='scale_both', width=1600)
    [0] Bokeh(Figure)`
>>> # d.app() for serving within notebook cell,
>>> # d.show() for serving as a separate web-app
>>> d.app() #or d.show()
displays interactive dashboard

do some visual querying/ crossfiltering

Attributes:
charts

Charts in the dashboard as a dictionary.

queried_indices

Read-only propery queried_indices returns a merged index of all queried index columns present in self._query_str_dict as a cudf.Series.

server

Methods

add_charts([charts, sidebar])

Adding more charts to the dashboard, after it has been initialized.

app([sidebar_width, width, height])

Run the dashboard with a bokeh backend server within the notebook.

export()

Export the cudf.DataFrame based on the current filtered state of the dashboard.

show([notebook_url, port, threaded, ...])

Run the dashboard with a bokeh backend server within the notebook.

stop()

stop the bokeh server

add_charts(charts=[], sidebar=[])#

Adding more charts to the dashboard, after it has been initialized.

Parameters:
charts: list

list of cuxfilter.charts objects

sidebar: list

list of cuxfilter.charts.panel_widget objects

Notes

After adding the charts, refresh the dashboard app tab to see the updated charts. Charts of type widget cannot be added to sidebar but widgets can be added to charts(main layout)

Examples

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh, panel_widgets
>>> df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> d = cux_df.dashboard([line_chart_1])
>>> line_chart_2 = bokeh.bar(
>>>     'val', 'key', data_points=5, add_interaction=False
>>> )
>>> d.add_charts(charts=[line_chart_2])
>>> # or
>>> d.add_charts(charts=[], sidebar=[panel_widgets.card("test")])
app(sidebar_width=280, width=1200, height=800)#

Run the dashboard with a bokeh backend server within the notebook.

Parameters:
sidebar_width: int, optional, default 280

width of the sidebar in pixels

width: int, optional, default 1200

width of the dashboard in pixels

height: int, optional, default 800

height of the dashboard in pixels

Examples

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh
>>> df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> d = cux_df.dashboard([line_chart_1])
>>> d.app(sidebar_width=200, width=1000, height=450)
property charts#

Charts in the dashboard as a dictionary.

export()#

Export the cudf.DataFrame based on the current filtered state of the dashboard.

Also prints the query string of the current state of the dashboard.

Returns:
cudf.DataFrame based on the current filtered state of the dashboard.

Examples

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh
>>> df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> line_chart_2 = bokeh.bar(
>>>     'val', 'key', data_points=5, add_interaction=False
>>> )
>>> d = cux_df.dashboard(
>>>    [line_chart_1, line_chart_2],
>>>    layout=cuxfilter.layouts.double_feature
>>> )
>>> # d.app() for serving within notebook cell,
>>> # d.show() for serving as a separate web-app
>>> d.app() #or d.show()
displays interactive dashboard
>>> queried_df = d.export()
final query 2<=key<=4
show(notebook_url='http://localhost:8888', port=0, threaded=False, service_proxy=None, sidebar_width=280, height=800, **kwargs)#

Run the dashboard with a bokeh backend server within the notebook.

Parameters:
notebook_url: str, optional, default localhost:8888
  • URL where you want to run the dashboard as a web-app,

including the port number.

  • Can use localhost instead of ip if running locally.

port: int, optional

Has to be an open port

service_proxy: str, optional, default None,

available options: jupyterhub

threaded: boolean, optional, default False

whether to run the server in threaded mode

sidebar_width: int, optional, default 280

width of the sidebar in pixels

height: int, optional, default 800

height of the dashboard in pixels

**kwargs: dict, optional

additional keyword arguments to pass to the server

Examples

>>> import cudf
>>> import cuxfilter
>>> from cuxfilter.charts import bokeh
>>> df = cudf.DataFrame(
>>>     {
>>>         'key': [0, 1, 2, 3, 4],
>>>         'val':[float(i + 10) for i in range(5)]
>>>     }
>>> )
>>> cux_df = cuxfilter.DataFrame.from_dataframe(df)
>>> line_chart_1 = bokeh.line(
>>>     'key', 'val', data_points=5, add_interaction=False
>>> )
>>> d = cux_df.dashboard([line_chart_1])
>>> d.show(url='localhost:8889')
stop()#

stop the bokeh server