Skip to content

Commit

Permalink
Merge pull request quantopian#60 from quantopian/update-docs
Browse files Browse the repository at this point in the history
Updated the README and the sample notebook to reflect the latest state of qgrid
  • Loading branch information
TimShawver committed Feb 13, 2016
2 parents 7a3a5e6 + 5346939 commit 8ca10a2
Show file tree
Hide file tree
Showing 8 changed files with 236 additions and 716 deletions.
61 changes: 0 additions & 61 deletions README.md

This file was deleted.

171 changes: 171 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,171 @@
=====
qgrid
=====
Qgrid is an `IPython widget <https://github.com/ipython/ipywidgets>`_ which uses SlickGrid to render pandas DataFrames
within a Jupyter notebook. We originally developed it for use in `Quantopian's hosted research environment
<https://www.quantopian.com/research?utm_source=github&utm_medium=web&utm_campaign=qgrid-repo>`_, 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.

Overview
--------

`SlickGrid <https://github.com/mleibman/SlickGrid>`_
An interactive javascript grid which allows users to scroll,
sort, and filter hundreds of thousands of rows with extreme responsiveness.

`Pandas <https://github.com/pydata/pandas>`_
A powerful data analysis / manipulation library for Python, and DataFrames are the primary way of storing and
manipulating two-dimensional data in pandas.

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, but it's also fully functional when rendered in `nbviewer
<http://nbviewer.jupyter.org/gist/TimShawver/2600c6648c6aaccaf3bf>`_.

Demo
----
See the demo by viewing `qgrid_demo.ipynb
<http://nbviewer.jupyter.org/gist/TimShawver/2600c6648c6aaccaf3bf>`_ in nbviewer.

Installation
------------

**Dependencies:**

Qgrid runs on `Python 2 or 3 <https://www.python.org/downloads/>`_. You'll also need
`pip <https://pypi.python.org/pypi/pip>`_ for the installation steps below.

Qgrid depends on the following two Python packages:

`Jupyter notebook <https://github.com/jupyter/notebook>`_
This is the interactive Python environment in which qgrid runs.

`Pandas <http://pandas.pydata.org/>`_
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 <https://github.com/quantopian/qgrid/blob/update-docs/requirements.txt>`_
and as such, will be automatically installed (if necessary) when qgrid is installed via pip.

**Installing from PyPI:**

Qgrid is on `PyPI <https://pypi.python.org/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 <https://github.com/quantopian/qgrid/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 locally
--------------------------

#. 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:

.. figure:: docs/images/home_screen.png
:align: left
:target: docs/images/home_screen.png
:width: 800px

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.

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

.. figure:: docs/images/notebook_screen.png
:align: left
:target: docs/images/notebook_screen.png
:width: 800px

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

#. Skip to the Notebook Installation section of the notebook because the Overview is copied from this document.
Read the text and execute the cells as you come to them to complete the demo.

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.

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

git clone https://github.com/quantopian/qgrid.git
cd qgrid

#. Install the current project in `editable <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_
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.

If you have virtualenv and virtualenvwrapper installed, an easy way to verify that this "editable" install succeeded
is to do the following::

cdsitepackages # navigate to the directory where virtualenv installs packages
cat qgrid.egg-link # print out the contents of this symbolic link

You should find that the symbolic link points to the top level directory of the qgrid repository which you ran
the ``pip install -e`` command on.

#. 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.

#. If the code you need to change is in qgrid's javascript, then call the
`nb_install <http://qgrid.readthedocs.org/en/latest/#qgrid.nbinstall>`_ 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 <https://virtualenv.readthedocs.org/en/latest/>`_. Install them like this::

pip install virtualenv
pip install virtualenvwrapper

#. 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.

#. Install qgrid::

pip install qgrid # see the "Installation" section above for more options
7 changes: 7 additions & 0 deletions docs/build.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
require 'github/markup'

output = File.open('readme.html','w')

path = File.join(File.dirname(__FILE__), '../README.rst')
output << GitHub::Markup.render(path, File.read(path))
output.close
Binary file added docs/images/home_screen.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added docs/images/notebook_screen.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
10 changes: 5 additions & 5 deletions qgrid/grid.py
Original file line number Diff line number Diff line change
Expand Up @@ -124,13 +124,16 @@ def set_grid_option(optname, optvalue):
defaults.grid_options[optname] = optvalue


def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
show_toolbar=False):
def show_grid(data_frame, show_toolbar=False, remote_js=None, precision=None,
grid_options=None):
"""
Main entry point for rendering DataFrames as SlickGrids.
Parameters
----------
show_toolbar: bool
Whether to show a toolbar with options for adding/removing rows and
exporting the widget to a static view.
remote_js : bool
Whether to load slickgrid.js from a local filesystem or from a
remote CDN. Loading from the local filesystem means that SlickGrid
Expand Down Expand Up @@ -164,9 +167,6 @@ def show_grid(data_frame, remote_js=None, precision=None, grid_options=None,
'editable': True,
'autoEdit': False
}
show_toolbar: bool
Whether to show a toolbar with options for adding/removing rows and
exporting the widget to a static view.
See Also
Expand Down
Loading

0 comments on commit 8ca10a2

Please sign in to comment.