Qgrid API Documentation¶

Qgrid is a Jupyter notebook widget which uses SlickGrid to render pandas DataFrames within a Jupyter notebook. This allows you to explore your DataFrames with intuitive scrolling, sorting, and filtering controls, as well as edit your DataFrames by double clicking cells.

Qgrid was developed for use in Quantopian’s hosted research environment and is available for use in that environment as of June 2018.

Other qgrid resources¶

This page hosts only the API docs for the project. You might also be interested in these other qgrid-related resources:

qgrid on GitHub: This is where you’ll find the source code and the rest of the documentation for the project, including the instructions for installing and running qgrid.
qgrid demo on Quantopian: Click the badge below try out the latest beta of qgrid in Quantopian’s hosted research environment. If you’re already signed into Quantopian you’ll be brought directly to the demo notebook. Otherwise you’ll be prompted to register (it’s free):
qgrid demo on binder: Click the badge below or the link above to try out qgrid using binder. You’ll see a brief loading screen and then a notebook will appear:

`qgrid` Module¶

class qgrid.QgridWidget(df=None, grid_options=None, precision=None, show_toolbar=None)¶

The widget class which is instantiated by the show_grid method. This class can be constructed directly but that’s not recommended because then default options have to be specified explicitly (since default options are normally provided by the show_grid method).

The constructor for this class takes all the same parameters as show_grid, with one exception, which is that the required data_frame parameter is replaced by an optional keyword argument called df.

See also

show_grid: The method that should be used to construct QgridWidget instances, because it provides reasonable defaults for all of the qgrid options.

df¶: DataFrame – Get/set the DataFrame that’s being displayed by the current instance. This DataFrame will NOT reflect any sorting/filtering/editing changes that are made via the UI. To get a copy of the DataFrame that does reflect sorting/filtering/editing changes, use the get_changed_df() method.

grid_options¶: dict – Get/set the grid options being used by the current instance.

precision¶: integer – Get/set the precision options being used by the current instance.

show_toolbar¶: bool – Get/set the show_toolbar option being used by the current instance.

column_options¶: bool – Get/set the column options being used by the current instance.

column_definitions¶: bool – Get/set the column definitions (column-specific options) being used by the current instance.

add_row(row=None)¶

Append a row at the end of the DataFrame. Values for the new row can be provided via the row argument, which is optional for DataFrames that have an integer index, and required otherwise. If the row argument is not provided, the last row will be duplicated and the index of the new row will be the index of the last row plus one.

Parameters:	row (list (default: None)) – A list of 2-tuples of (column name, column value) that specifies the values for the new row.

See also

QgridWidget.remove_rows(): The method for removing a row (or rows).

change_grid_option(option_name, option_value)¶

Change a SlickGrid grid option without rebuilding the entire grid widget. Not all options are supported at this point so this method should be considered experimental.

Parameters:	option_name (str) – The name of the grid option to be changed. option_value (str) – The new value for the grid option.

change_selection(rows=[])¶

Select a row (or rows) in the UI. The indices of the rows to select are provided via the optional rows argument.

Parameters:	rows (list (default: [])) – A list of indices of the rows to select. For a multi-indexed DataFrame, each index in the list should be a tuple, with each value in each tuple corresponding to a level of the MultiIndex. The default value of `[]` results in the no rows being selected (i.e. it clears the selection).

edit_cell(index, column, value)¶

Edit a cell of the grid, given the index and column of the cell to edit, as well as the new value of the cell. Results in a cell_edited event being fired.

Parameters:	index (object) – The index of the row containing the cell that is to be edited. column (str) – The name of the column containing the cell that is to be edited. value (object) – The new value for the cell.

get_changed_df()¶

Get a copy of the DataFrame that was used to create the current instance of QgridWidget which reflects the current state of the UI. This includes any sorting or filtering changes, as well as edits that have been made by double clicking cells.

Return type:	DataFrame

get_selected_df()¶

Get a DataFrame which reflects the current state of the UI and only includes the currently selected row(s). Internally it calls get_changed_df() and then filters down to the selected rows using iloc.

Return type:	DataFrame

get_selected_rows()¶

Get the currently selected rows.

Return type:	List of integers

off(names, handler)¶

Remove a qgrid event handler that was registered with the current instance’s on method.

Parameters:	names (list, str, All (default: All)) – The names of the events for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all events. handler (callable) – A callable that was previously registered with the current instance’s `on` method.

See also

QgridWidget.on(): The method for hooking up instance-level handlers that this off method can remove.

on(names, handler)¶

Setup a handler to be called when a user interacts with the current instance.

Parameters:

names (list, str, All) – If names is All, the handler will apply to all events. If a list of str, handler will apply to all events named in the list. If a str, the handler will apply just the event with that name.
handler (callable) – A callable that is called when the event occurs. Its signature should be handler(event, qgrid_widget), where event is a dictionary and qgrid_widget is the QgridWidget instance that fired the event. The event dictionary at least holds a name key which specifies the name of the event that occurred.

Notes

Here’s the list of events that you can listen to on QgridWidget instances via the on method:

[
    'cell_edited',
    'selection_changed',
    'viewport_changed',
    'row_added',
    'row_removed',
    'filter_dropdown_shown',
    'filter_changed',
    'sort_changed',
    'text_filter_viewport_changed',
    'json_updated'
]

The following bullet points describe the events listed above in more detail. Each event bullet point is followed by sub-bullets which describe the keys that will be included in the event dictionary for each event.

cell_edited The user changed the value of a cell in the grid.
- index The index of the row that contains the edited cell.
- column The name of the column that contains the edited cell.
- old The previous value of the cell.
- new The new value of the cell.
filter_changed The user changed the filter setting for a column.
- column The name of the column for which the filter setting was changed.
filter_dropdown_shown The user showed the filter control for a column by clicking the filter icon in the column’s header.
- column The name of the column for which the filter control was shown.
json_updated A user action causes QgridWidget to send rows of data (in json format) down to the browser. This happens as a side effect of certain actions such as scrolling, sorting, and filtering.
- triggered_by The name of the event that resulted in rows of data being sent down to the browser. Possible values are change_viewport, change_filter, change_sort, add_row, remove_row, and edit_cell.
- range A tuple specifying the range of rows that have been sent down to the browser.
row_added The user added a new row using the “Add Row” button in the grid toolbar.
- index The index of the newly added row.
- source The source of this event. Possible values are api (an api method call) and gui (the grid interface).
row_removed The user added removed one or more rows using the “Remove Row” button in the grid toolbar.
- indices The indices of the removed rows, specified as an array of integers.
- source The source of this event. Possible values are api (an api method call) and gui (the grid interface).
selection_changed The user changed which rows were highlighted in the grid.
- old An array specifying the indices of the previously selected rows.
- new The indices of the rows that are now selected, again specified as an array.
- source The source of this event. Possible values are api (an api method call) and gui (the grid interface).
sort_changed The user changed the sort setting for the grid.
- old The previous sort setting for the grid, specified as a dict with the following keys:
  column The name of the column that the grid was sorted by
  
  ascending Boolean indicating ascending/descending order
- new The new sort setting for the grid, specified as a dict with the following keys:
  column The name of the column that the grid is currently sorted by
  
  ascending Boolean indicating ascending/descending order
text_filter_viewport_changed The user scrolled the new rows into view in the filter dropdown for a text field.
- column The name of the column whose filter dropdown is visible
- old A tuple specifying the previous range of visible rows in the filter dropdown.
- new A tuple specifying the range of rows that are now visible in the filter dropdown.
viewport_changed The user scrolled the new rows into view in the grid.
- old A tuple specifying the previous range of visible rows.
- new A tuple specifying the range of rows that are now visible.

The event dictionary for every type of event will contain a name key specifying the name of the event that occurred. That key is excluded from the lists of keys above to avoid redundacy.

See also

on(): Same as the instance-level on method except it listens for events on all instances rather than on an individual QgridWidget instance.
QgridWidget.off(): Unhook a handler that was hooked up using the instance-level on method.

remove_row(rows=None)¶: Alias for remove_rows, which is provided for convenience because this was the previous name of that method.

remove_rows(rows=None)¶

Remove a row (or rows) from the DataFrame. The indices of the rows to remove can be provided via the optional rows argument. If the rows argument is not provided, the row (or rows) that are currently selected in the UI will be removed.

Parameters:	rows (list (default: None)) – A list of indices of the rows to remove from the DataFrame. For a multi-indexed DataFrame, each index in the list should be a tuple, with each value in each tuple corresponding to a level of the MultiIndex.

See also

QgridWidget.add_row(): The method for adding a row.
QgridWidget.remove_row(): Alias for this method.

toggle_editable()¶: Change whether the grid is editable or not, without rebuilding the entire grid widget.

qgrid.enable(dataframe=True, series=True)¶

Automatically use qgrid to display all DataFrames and/or Series instances in the notebook.

Parameters:	dataframe (bool) – Whether to automatically use qgrid to display DataFrames instances. series (bool) – Whether to automatically use qgrid to display Series instances.

qgrid.disable()¶: Stop using qgrid to display DataFrames and Series instances in the notebook. This has the same effect as calling enable with both kwargs set to False (and in fact, that’s what this function does internally).

qgrid.set_defaults(show_toolbar=None, precision=None, grid_options=None, column_options=None)¶

Set the default qgrid options. The options that you can set here are the same ones that you can pass into QgridWidget constructor, with the exception of the df option, for which a default value wouldn’t be particularly useful (since the purpose of qgrid is to display a DataFrame).

See the documentation for QgridWidget for more information.

Notes

This function will be useful to you if you find yourself setting the same options every time you create a QgridWidget. Calling this set_defaults function once sets the options for the lifetime of the kernel, so you won’t have to include the same options every time you instantiate a QgridWidget.

See also

QgridWidget(): The widget whose default behavior is changed by set_defaults.

qgrid.on(names, handler)¶

Setup a handler to be called when a user interacts with any qgrid instance.

Parameters:

names (list, str, All) – If names is All, the handler will apply to all events. If a list of str, handler will apply to all events named in the list. If a str, the handler will apply just the event with that name.
handler (callable) – A callable that is called when the event occurs. Its signature should be handler(event, qgrid_widget), where event is a dictionary and qgrid_widget is the QgridWidget instance that fired the event. The event dictionary at least holds a name key which specifies the name of the event that occurred.

Notes

There is also an on method on each individual QgridWidget instance, which works exactly like this one except it only listens for events on an individual instance (whereas this module-level method listens for events on all instances).

See that instance-level method (linked below) for a list of all events that can be listened to via this module-level on method. Both methods support the same events with one exception: the instance_create event. This event is only available at the module-level and not on individual QgridWidget instances.

The reason it’s not available on individual qgrid instances is because the only time it fires is when a new instance is created. This means it’s already done firing by the time a user has a chance to hook up any event listeners.

Here’s the full list of events that can be listened for via this module-level on method:

[
    'instance_created',
    'cell_edited',
    'selection_changed',
    'viewport_changed',
    'row_added',
    'row_removed',
    'filter_dropdown_shown',
    'filter_changed',
    'sort_changed',
    'text_filter_viewport_changed',
    'json_updated'
]

See also

QgridWidget.on(): Same as this on method except it listens for events on an individual QgridWidget instance rather than on all instances. See this method for a list of all the types of events that can be listened for via either on method.
off(): Unhook a handler that was hooked up using this on method.

qgrid.off(names, handler)¶

Remove a qgrid event handler that was registered with the on method.

Parameters:	names (list, str, All (default: All)) – The names of the events for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all events. handler (callable) – A callable that was previously registered with the ‘on’ method.

See also

on(): The method for hooking up handlers that this off method can remove.

qgrid.set_grid_option(optname, optvalue)¶

Set the default value for one of the options that gets passed into the SlickGrid constructor.

Parameters:	optname (str) – The name of the option to set. optvalue (object) – The new value to set.

Notes

The options you can set here are the same ones that you can set via the grid_options parameter of the set_defaults or show_grid functions. See the SlickGrid documentation for the full list of available options.

qgrid.show_grid(data_frame, show_toolbar=None, precision=None, grid_options=None, column_options=None, column_definitions=None, row_edit_callback=None)¶

Renders a DataFrame or Series as an interactive qgrid, represented by an instance of the QgridWidget class. The QgridWidget instance is constructed using the options passed in to this function. The data_frame argument to this function is used as the df kwarg in call to the QgridWidget constructor, and the rest of the parameters are passed through as is.

If the data_frame argument is a Series, it will be converted to a DataFrame before being passed in to the QgridWidget constructor as the df kwarg.

Return type:

QgridWidget

Parameters:

data_frame (DataFrame) – The DataFrame that will be displayed by this instance of QgridWidget.
grid_options (dict) – Options to use when creating the SlickGrid control (i.e. the interactive grid). See the Notes section below for more information on the available options, as well as the default options that this widget uses.
precision (integer) – The number of digits of precision to display for floating-point values. If unset, we use the value of pandas.get_option(‘display.precision’).
show_toolbar (bool) – Whether to show a toolbar with options for adding/removing rows. Adding/removing rows is an experimental feature which only works with DataFrames that have an integer index.
column_options (dict) – Column options that are to be applied to every column. See the Notes section below for more information on the available options, as well as the default options that this widget uses.
column_definitions (dict) – Column options that are to be applied to individual columns. The keys of the dict should be the column names, and each value should be the column options for a particular column, represented as a dict. The available options for each column are the same options that are available to be set for all columns via the column_options parameter. See the Notes section below for more information on those options.
row_edit_callback (callable) – A callable that is called to determine whether a particular row should be editable or not. Its signature should be callable(row), where row is a dictionary which contains a particular row’s values, keyed by column name. The callback should return True if the provided row should be editable, and False otherwise.

Notes

The following dictionary is used for grid_options if none are provided explicitly:

{
    # SlickGrid options
    'fullWidthRows': True,
    'syncColumnCellResize': True,
    'forceFitColumns': True,
    'defaultColumnWidth': 150,
    'rowHeight': 28,
    'enableColumnReorder': False,
    'enableTextSelectionOnCells': True,
    'editable': True,
    'autoEdit': False,
    'explicitInitialization': True,

    # Qgrid options
    'maxVisibleRows': 15,
    'minVisibleRows': 8,
    'sortable': True,
    'filterable': True,
    'highlightSelectedCell': False,
    'highlightSelectedRow': True
}

The first group of options are SlickGrid “grid options” which are described in the SlickGrid documentation.

The second group of option are options that were added specifically for Qgrid and therefore are not documented in the SlickGrid documentation. The following bullet points describe these options.

maxVisibleRows The maximum number of rows that Qgrid will show.
minVisibleRows The minimum number of rows that Qgrid will show
sortable Whether the Qgrid instance will allow the user to sort columns by clicking the column headers. When this is set to False, nothing will happen when users click the column headers.
filterable Whether the Qgrid instance will allow the user to filter the grid. When this is set to False the filter icons won’t be shown for any columns.
highlightSelectedCell If you set this to True, the selected cell will be given a light blue border.
highlightSelectedRow If you set this to False, the light blue background that’s shown by default for selected rows will be hidden.

The following dictionary is used for column_options if none are provided explicitly:

{
    # SlickGrid column options
    'defaultSortAsc': True,
    'maxWidth': None,
    'minWidth': 30,
    'resizable': True,
    'sortable': True,
    'toolTip': "",
    'width': None

    # Qgrid column options
    'editable': True,
}

The first group of options are SlickGrid “column options” which are described in the SlickGrid documentation.

The editable option was added specifically for Qgrid and therefore is not documented in the SlickGrid documentation. This option specifies whether a column should be editable or not.

See also

set_defaults(): Permanently set global defaults for the parameters of show_grid, with the exception of the data_frame and column_definitions parameters, since those depend on the particular set of data being shown by an instance, and therefore aren’t parameters we would want to set for all QgridWidet instances.
set_grid_option(): Permanently set global defaults for individual grid options. Does so by changing the defaults that the show_grid method uses for the grid_options parameter.
QgridWidget(): The widget class that is instantiated and returned by this method.

qgrid.QGridWidget¶: alias of qgrid.grid.QgridWidget

Qgrid API Documentation¶

Other qgrid resources¶

qgrid Module¶

`qgrid` Module¶