Skip to content

Latest commit

 

History

History
174 lines (118 loc) · 7.66 KB

README.rst

File metadata and controls

174 lines (118 loc) · 7.66 KB

qgrid

Qgrid is an IPython 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 a cell (new in v0.3.0).

We originally developed qgrid it for use in Quantopian's hosted research environment, but no longer have a specific project in mind for using qgrid in the research environment. For that reason we haven't been investing much time in developing new features, and almost all of the forward development has come from the community. We've mainly just been reviewing PR's, writing docs, and occasionally making small contributions.

Demo

See the demo by viewing qgrid_demo.ipynb in nbviewer.

API Documentation

API documentation is hosted on readthedocs.

Installation

Python Dependencies:

Qgrid runs on Python 2 or 3. You'll also need pip for the installation steps below.

Qgrid depends on the following three Python packages:

Jupyter notebook
This is the interactive Python environment in which qgrid runs.
ipywidgets
In order for Jupyter notebooks to be able to run widgets, you have to also install this ipywidgets package. It's maintained by the Jupyter organization, the same people who created Jupyter notebook.
Pandas
A powerful data analysis / manipulation library for Python. Qgrid requires that the data to be rendered as an interactive grid be provided in the form of a pandas DataFrame.

These are listed in requirements.txt and will be automatically installed (if necessary) when qgrid is installed via pip.

Installing from PyPI:

Qgrid is on PyPI and can be installed like this:

pip install qgrid

If you need to install a specific version of qgrid, pip allows you to specify it like this:

pip install qgrid==0.2.0

See the Releases page for more details about the versions that are available.

Installing from GitHub:

The latest release on PyPI is often out of date, and might not contain the latest bug fixes and features that you want. To run the latest code that is on master, install qgrid from GitHub instead of PyPI:

pip install git+https://github.com/quantopian/qgrid

Running the demo notebook locally

The qgrid repository includes a demo notebook which will help you get familiar with the functionality that qgrid provides. This demo notebook doesn't get downloaded to your machine when you install qgrid with pip, so you'll need to clone the qgrid repository to get it. Here are the steps to clone the repository and run the demo notebook:

  1. Clone the repository from GitHub and cd into it the top-level directory:

    git clone https://github.com/quantopian/qgrid.git
    cd qgrid
    
  2. Go to the top-level directory of the qgrid repository and run the notebook:

    cd ~/qgrid
    jupyter notebook
    

    The advantage of running the notebook from the top-level directoy of the qgrid repository is the sample notebook that comes with qgrid will be available on the first page that appears when the web browser launches. Here's what you can expect that page to look like:

    docs/images/home_screen.png

    The "notebook dashboard" for the jupyter notebook which shows all the files in the current directory. Notice the demo notebook which is qgrid_demo.ipynb.

  3. Click on qgrid_demo.ipynb to open it. Here's what that should like:

    docs/images/notebook_screen.png

    The demo notebook, qgrid_demo.ipynb, rendered by a locally-running Jupyter notebook.

  4. Click the "Cell" menu at the top of the notebook and click "Run All" to run all the cells in the notebook and render a few sample qgrids.

    docs/images/qgrid_screen.png

    A sample qgrid, as seen in the demo notebook, qgrid_demo.ipynb.

Running from source

If you'd like to contribute to qgrid, or just want to be able to modify the source code for your own purposes, you'll want to clone this repository and run qgrid from your local copy of the repository. The following steps explain how to do this.

  1. Clone the repository from GitHub and cd into it the top-level directory:

    git clone https://github.com/quantopian/qgrid.git
    cd qgrid
    
  2. Install the current project in editable mode:

    pip install -e .
    

    This will install the packages that qgrid depends on in the normal way, but will do something special for the qgrid package itself. Instead of copying the qgrid directory to the site-packages directory of the environment where it was installed (like a virualenv), pip will create a symbolic link which links to the directory you passed in to the pip install -e. The result is changes that you make to the source code will be reflected as soon as you restart the notebook.

  3. Follow the instructions in the previous section to run qgrid. Now when you make changes to qgrid's Python code, those changes will take effect as soon as you restart the Jupyter notebook server.

  4. If the code you need to change is in qgrid's javascript, then call the nb_install function from within the notebook to copy your latest changes to the "nbextensions" folder (i.e. where widgets must put their javascript for it to be found by the notebook).

Setting up your virtualenv

Using virtualenv is the recommended way of keeping Python dependencies for various project isolated. The following step help you set up a virtualenv for qgrid (which I'm sure most of you know how to do already).

Before you proceed with this section you'll need virtualenv and virtualenvwrapper. Install them like this:

pip install virtualenv
pip install virtualenvwrapper
  1. Create a virtualenv for Jupyter notebook and qgrid:

    mkvirtualenv qgrid # create virtualenv called qgrid, and use Python 2 inside that virtualenv
    

    This will work but on my machine the resulting virtualenv will use whatever version of python comes up when you run python --version, which in my case is Python 2. If you want to use Python 3, specify the path to the version of Python you want to use, which for me looks like this:

    mkvirtualenv --python=/usr/local/bin/python3 qgrid # create virtualenv called qgrid, and use Python 3 inside that virtualenv
    

    You may have to change the /usr/local/bin/python3 path depending on how you installed Python 3. If you're unsure, type which python3 to get the path to your Python 3 installation.

  2. Install qgrid:

    pip install qgrid # see the "Installation" section above for more options