Qgrid is an IPython widget which uses a javascript library called SlickGrid to render pandas DataFrames within a Jupyter notebook. It was developed for use in Quantopian's hosted research environment.
and filter hundreds of thousands of rows with extreme responsiveness.
Qgrid renders pandas DataFrames as SlickGrids, which enables users to explore the entire contents of a DataFrame using intuitive sorting and filtering controls. It's designed to be used within Jupyter notebook, and it's also mostly functional when rendered by [nbviewer](http://nbviewer.ipython .org/github/quantopian/qgrid/blob/master/qgrid_demo.ipynb).
First, import the qgrid module as you would any other module in Python. If that doesn't work, something may have gone wrong while installing the qgrid package using pip. I would go through the package installation steps on the GitHub page again with a new virtualenv to make sure everything installed correctly.
import qgrid
This step is required because at this point all you've done to install qgrid is to call pip install
. Pip doesn't know which folder your Jupyter notebook widgets need to get copied to (let's call this the "widgets folder"), only the Jupyter notebook process knows that. So you need to run one line of code from within the Jupyter notebook to copy qgrid to the widgets folder. This only has to be done once for a particular version of qgrid. That being said, if you're running qgrid from it's source code and making changes to it's source code, you'll need to run this line every time you make a change, or else the changes won't do anything. See our API docs for the nbinstall function for more details.
qgrid.nbinstall(overwrite=True) # copies javascript dependencies to your /nbextensions folder
API documentation is hosted on readthedocs: http://qgrid.readthedocs.org/en/latest/
The API documentation can also be accessed via the "?" operator in IPython. To use the "?" operator, type the name of the function followed by "?" to see the documentation for that function, like this:
qgrid.nbinstall?
qgrid.show_grid?
qgrid.set_defaults?
qgrid.set_grid_options?
import pandas as pd
import numpy as np
randn = np.random.randn
# Set this pandas option to prevent the grid from being too big
pd.set_option('display.max_rows', 8)
# Get a pandas DataFrame containing the daily prices for the S&P 500 from 1/1/2011 - 1/1/2014
from pandas.io.data import get_data_yahoo
spy = get_data_yahoo(
symbols='SPY',
start=pd.Timestamp('2011-01-01'),
end=pd.Timestamp('2014-01-01'),
adjust_price=True,
)
spy
Open | High | Low | Close | Volume | Adj_Ratio | |
---|---|---|---|---|---|---|
Date | ||||||
2011-01-03 | 114.369788 | 115.173110 | 113.458149 | 114.676679 | 138725200 | 0.902611 |
2011-01-04 | 114.929410 | 114.965515 | 113.900434 | 114.613497 | 137409700 | 0.902611 |
2011-01-05 | 114.252451 | 115.281427 | 114.144135 | 115.209216 | 133975300 | 0.902611 |
2011-01-06 | 115.254350 | 115.380715 | 114.640575 | 114.983564 | 122519000 | 0.902611 |
... | ... | ... | ... | ... | ... | ... |
2013-12-26 | 176.190385 | 176.786218 | 176.171176 | 176.690112 | 63365000 | 0.961004 |
2013-12-27 | 176.920758 | 176.997626 | 176.497914 | 176.680507 | 61814000 | 0.961004 |
2013-12-30 | 176.699717 | 176.843876 | 176.421032 | 176.651678 | 56857000 | 0.961004 |
2013-12-31 | 176.891930 | 177.487747 | 176.757376 | 177.487747 | 86119900 | 0.961004 |
754 rows × 6 columns
The table above is Jupyter notebook's default representation of the 'spy' DataFrame.
qgrid.show_grid(spy)
The cell above shows the same 'spy' DataFrame rendered as a qgrid. Qgrids allows you to scroll, sort, and filter hundreds of thousands of rows with extreme responsiveness. If you double click on the cells they become editable, and the edits change the values stored in the DataFrame as you would expect.
The show_grid
function takes a number of optional parameters to allow you to configure the behavior of the grid it generates. In the following example we use a couple of these optional parameters:
show_toolbar
to True causes some buttons to be shown above the grid. These buttons allow you to add and remove rows, as well as export a version of qgrid that will be functional when rendered by nbviewer. Note that these buttons won't be visible on nbviewer.jupyter.org, only when qgrid is running within a jupyter notebook.grid_options
takes a dict and allows you to pass any of the "grid options" listed in SlickGrid's documentation. In this example we make use of two of these options, forceFitColumns
and defaultColumnWidth
, to improve qgrid's ability to handle a large number of columnsYou can read about these and the rest of the optional parameters for the show_grid
function in our API documentation.
If you find yourself frequently passing the same options into show_grid
, the set_defaults
function may be useful to you. It allows you to set the same options that you would normally pass to show_grid
, but through a separate function which sets the options for the lifetime of the kernel rather than for a single grid. See the API documentation for the set_defaults
function for more information.
qgrid.show_grid(spy, show_toolbar=True, grid_options={'forceFitColumns': False, 'defaultColumnWidth': 200})
The same 'spy' DataFrame rendered as a qgrid again, this time some options tweaked. The toolbar buttons are visible, the columns are wider, and a horizontal scroll bar has appeared.
df2 = pd.DataFrame({
'A' : 1.,
'B' : pd.Timestamp('20130102'),
'C' : pd.Series(randn(8),index=list(range(8)),dtype='float32'),
'D' : np.array([3] * 8,dtype='int32'),
'E' : pd.Categorical(["test","train","test","train", "test", "train", "test", "train"]),
'F' : 'foo' })
df2
A | B | C | D | E | F | |
---|---|---|---|---|---|---|
0 | 1 | 2013-01-02 | -0.354230 | 3 | test | foo |
1 | 1 | 2013-01-02 | 1.203130 | 3 | train | foo |
2 | 1 | 2013-01-02 | -0.126574 | 3 | test | foo |
3 | 1 | 2013-01-02 | 1.527866 | 3 | train | foo |
4 | 1 | 2013-01-02 | -0.114737 | 3 | test | foo |
5 | 1 | 2013-01-02 | -0.002311 | 3 | train | foo |
6 | 1 | 2013-01-02 | -1.252144 | 3 | test | foo |
7 | 1 | 2013-01-02 | 0.409399 | 3 | train | foo |
The show_grid
function is just a convenience function which internally constructs an instance of QGridWidget and renders it with jupyter notebook's display
function. The following code shows how to construct a QGridWidget directly, so that you can retrieve or update the DataFrame it uses internally.
from IPython.display import display
grid = qgrid.QGridWidget(df=df2)
display(grid)
If you make edits to the data using the grid above, they will be reflected in the DataFrame that is returned by grid.df
.
grid.df
A | B | C | D | E | F | |
---|---|---|---|---|---|---|
0 | 1 | 2013-01-02 | -0.354230 | 3 | test | foo |
1 | 1 | 2013-01-02 | 1.203130 | 3 | train | foo |
2 | 1 | 2013-01-02 | -0.126574 | 3 | test | foo |
3 | 1 | 2013-01-02 | 1.527866 | 3 | train | foo |
4 | 1 | 2013-01-02 | -0.114737 | 3 | test | foo |
5 | 1 | 2013-01-02 | -0.002311 | 3 | train | foo |
6 | 1 | 2013-01-02 | -1.252144 | 3 | test | foo |
7 | 1 | 2013-01-02 | 0.409399 | 3 | train | foo |