Harnessing the power of ag-Grid in Jupyter
Post authored by Louis Raison and Olivier Borderies
First some observations:
- Python has an excellent, hugely popular package to deal with tabular data: pandas.
- JavaScript has a fantastic, very popular library to manipulate tabular data: ag-Grid.
- Jupyter has a fantastic, versatile notebook and ecosystem built on Python (1) and JavaScript.
- ipywidgets is a pivotal package that enables bridging between Python and JavaScript.
Surely you see where I’m going: There should be a way to use ag-Grid with pandas Dataframes in a Jupyter notebook !
In this article we:
- briefly introduce ipyaggrid, a custom ipywidget (2) that harnesses the power of ag-Grid and exposes it to the Jupyter notebook user manipulating pandas DataFrames.
- explain the main lines of our approach.
For detailed info go straight to ipyaggrid’s documentation. It contains:
- a detailed user guide, including many examples — snapshots and live via mybinder.org.
- a developer guide, helpful for this, and maybe other, custom ipywidgets.
(1) Jupyter has many kernels available but Python is the initial and most popular one, and the only one we consider in this article.
(2) See the article Authoring Custom Jupyter Widgets for more background info.
ag-Grid
The first benefit of ag-Grid to the notebook user is to vastly expand the display options for a dataframe.
ag-Grid has a very rich feature set and is superbly documented, with several examples for each feature, which can be edited live in plunker or downloaded for further customization. In addition to the many examples, ag-Grid API is remarkably consistent and it documentation very well structured. As a result even advanced features are quite discoverable and accessible to non-specialists.
Beyond the improved dynamic display of grids (e.g. filtering, sorting, pivoting, aggregating, etc), the API allows various user actions (e.g. selecting cells/ranges, editing, exporting, etc).
Naturally you need an ag-Grid license for the enterprise features, marked with the symbol below.
Transparent Access
In order for ipyaggrid to give full access to the underlying ag-Grid JavaScript library, without adding an extra layer of syntax that would inevitably limit the options, be cumbersome for the user to learn, and a liability for the developer to maintain, we opted for a fully transparent approach.
Thus a user can go almost straight from an example from the ag-Grid documentation to an ipyaggrid instance. See the examples in the ipyaggrid documentation.
The flip side is: A user must learn some JavaScript to customize ag-Grid. There is deliberately no attempt to offer a Python-JavaScript conversion layer. We think it would be a weakpoint.
Indeed regular Jupyter-Python users can use ipyaggrid without writing any JavaScript as many ag-Grid options are available by simple configuration and the defaults are often sensible.
On the other hand, if a full access was not available power users would quickly get frustrated and look for other ways to turn their pandas dataframes to ag-Grid grids.
Practically ag-Grid configuration options are dictionaries containing mostly strings and numbers, and also occasionally JavaScript custom functions (strings on the Python side), which ipyaggrid will eval() to actual JavaScript functions. It is also possible to pass custom CSS.
However to cater for frequent users, ipyaggrid has several Python params that automate the most used features, e.g. quickfilter, export to CSV/Excel, and adds extra features we thought are convenient:
- export grid or selection by row/columns/range
- multi-options (dropdown menu to select from several gridOptions)
- managing data (delete, modify…) from Python and JavaScript, etc
- center display of grid
Most of these extras are assembled in a menu bar on top of the grid. See the doc
You can experiment with some of these features on mybinder:
Consequence on Security: JavaScript Injection
The transparent approach has many benefits but involves JavaScript injection. In other words, a notebook user can write and spread a notebook containing malicious JavaScript code. Somebody opening such a notebook will not be exposed directly as the notebook will be Not Trusted, until they run the cells. The main danger is identity theft: The malicious code could search the browser and try and steal credentials. Indeed allowing JavaScript injection is a security risk, and users should be aware of it.
So you should NOT open and run a notebook from an untrusted source — irrespective of the presence of ipyaggrid — no more than you should visit malicious web sites.
But arguably absolute distrust is not optimal in all circumstances !
There are many cases where the assumption of a minimal level of trust — here that no member of the group will try to hack you — yields significant benefits — here the extra power of ag-Grid — makes the risk worth it.
In any event, it is good practice to run Jupyter notebook in your browser’s private mode.
Its sandboxed environment goes a long way towards protecting you from identity theft. In an age of invasive online monitoring, legal or not, and heightened concern for security and privacy, the standard recommendations should apply to Jupyter content (notebooks) too.
We even tend to think that it is a safe habit to run Jupyter notebooks outside you default browser, for example Opera or Minbrowser to get even more isolation.
Harnessing a JavaScript Purebred
Writing an ipywidget as a thin wrapper on a powerful JavaScript library is like harnessing a pure bred ! 😄
It requires either skill or time, and we think even the expert will get some bruises in the taming...
As structured and documented as the JavaScript purebred is, modern JavaScript involves a lot of scaffolding and bugs are not always explicit — to say the least. So the task is challenging but the benefits are significant.
After the purebred’s fury is gone and it accepts an ipywidget saddle, then it becomes a great asset for the community !
