Qgrid API Documentation¶
Qgrid is an Jupyter notebook widget which uses SlickGrid to render pandas DataFrames as interactive grid controls.
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 binder
Click the badge below or the link above to try out qgrid in your browser. 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, and can also be constructed directly. All of the parameters listed below can be read/updated after instantiation via attributes of the same name as the parameter (since they’re implemented as traitlets).
When new values are set for any of these options after instantiation (such as df, grid_options, etc), the change takes effect immediately by regenerating the SlickGrid control.
Parameters: - df (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.
Notes
The following dictionary is used for
grid_options
if none are provided explicitly:{ 'fullWidthRows': True, 'syncColumnCellResize': True, 'forceFitColumns': True, 'defaultColumnWidth': 150, 'rowHeight': 28, 'enableColumnReorder': False, 'enableTextSelectionOnCells': True, 'editable': True, 'autoEdit': False, 'explicitInitialization': True, 'maxVisibleRows': 15, 'minVisibleRows': 8 }
Most of these options are SlickGrid options which are described in the SlickGrid documentation. The two exceptions are maxVisibleRows and minVisibleRows, which are options that were added specifically for Qgrid and therefore are not documented in the SlickGrid documentation. These options allow you to set an upper and lower bound on the height of your Qgrid widget in terms of number of rows that are visible.
See also
set_defaults
- Permanently set global defaults for the parameters of the QgridWidget constructor, with the exception of the
df
parameter. set_grid_option
- Permanently set global defaults for individual SlickGrid options. Does so by changing the default for the
grid_options
parameter of the QgridWidget constructor.
-
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 SlickGrid 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.
-
add_row
()¶ Append a row at the end of the dataframe by duplicating the last row and incrementing it’s index by 1. The feature is only available for DataFrames that have an integer index.
-
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 usingiloc
.Return type: DataFrame
-
get_selected_rows
()¶ Get the currently selected rows.
Return type: List of integers
-
remove_row
()¶ Remove the current row from the table.
-
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 toFalse
(and in fact, that’s what this function does internally).
-
qgrid.
set_defaults
(show_toolbar=None, precision=None, grid_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 thedf
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 aQgridWidget
.See also
QgridWidget()
- The widget whose default behavior is changed by
set_defaults
.
-
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 theset_defaults
orshow_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)¶ Renders a DataFrame or Series as an interactive qgrid, represented by an instance of the
QgridWidget
class. TheQgridWidget
instance is constructed using the options passed in to this function. Thedata_frame
argument to this function is used as thedf
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 thedf
kwarg.See the
QgridWidget
documentation for descriptions of all of the options that can be set via it’s constructor.Return type: QgridWidget See also
QgridWidget()
- The widget class that is instantiated and returned by this function.
-
qgrid.
QGridWidget
¶ alias of
qgrid.grid.QgridWidget