Skip to content

Commit

Permalink
Pandas -> pandas (fixes #9) [skip ci]
Browse files Browse the repository at this point in the history
  • Loading branch information
sheppard committed Nov 17, 2014
1 parent 9343c53 commit 53a8d56
Show file tree
Hide file tree
Showing 5 changed files with 29 additions and 29 deletions.
20 changes: 10 additions & 10 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,9 @@
Django REST Pandas
==================

#### [Django REST Framework] + [Pandas] = A Model-driven Visualization API
#### [Django REST Framework] + [pandas] = A Model-driven Visualization API

**Django REST Pandas** (DRP) provides a simple way to generate and serve [Pandas] DataFrames via the [Django REST Framework]. The resulting API can serve up CSV (and a number of [other formats](#supported-formats)) for consumption by a client-side visualization tool like [d3.js].
**Django REST Pandas** (DRP) provides a simple way to generate and serve [pandas] DataFrames via the [Django REST Framework]. The resulting API can serve up CSV (and a number of [other formats](#supported-formats)) for consumption by a client-side visualization tool like [d3.js].

The design philosophy of DRP enforces a strict separation between data and presentation. This keeps the implementation simple, but also has the nice side effect of making it trivial to provide the source data for your visualizations. This capability can often be leveraged by sending users to the same URL that your visualization code uses internally to load the data.

Expand All @@ -21,12 +21,12 @@ The [climata-viewer] project uses Django REST Pandas and [wq/chart.js] to provid
## Related Work
The field of Python-powered data analysis and visualization is growing, and there are a number of similar solutions that may fit your needs better.

* [Django Pandas] provides a custom ORM model manager with Pandas support. By contrast, Django REST Pandas works at the *view* level, by integrating Pandas via custom Django REST Framework serializers and renderers.
* [DRF-CSV] provides straightforward CSV renderers for use with Django REST Framework. It may be useful if you just want a CSV API and don't have a need for the Pandas DataFrame functionality.
* [Django Pandas] provides a custom ORM model manager with pandas support. By contrast, Django REST Pandas works at the *view* level, by integrating pandas via custom Django REST Framework serializers and renderers.
* [DRF-CSV] provides straightforward CSV renderers for use with Django REST Framework. It may be useful if you just want a CSV API and don't have a need for the pandas DataFrame functionality.
* [mpld3] provides a direct bridge from [matplotlib] to [d3.js], complete with seamless [IPython] integration. It is restricted to the (large) matplotlib chart vocabularly but should be sufficient for many use cases.
* [Bokeh] is a complete client-server visualization platform. It does not leverage d3 or Django, but is notable as a comprehensive, forward-looking approach to addressing similar use cases.

The goal of Django REST Pandas is to provide a generic REST API for serving up Pandas dataframes. In this sense, it is similar to the Plot Server in Bokeh, but more generic in that it does not assume any particular visualization format or technology. Further, DRP is optimized for integration with public-facing Django-powered websites (unlike mpld3 which is primarily intended for use within IPython).
The goal of Django REST Pandas is to provide a generic REST API for serving up pandas dataframes. In this sense, it is similar to the Plot Server in Bokeh, but more generic in that it does not assume any particular visualization format or technology. Further, DRP is optimized for integration with public-facing Django-powered websites (unlike mpld3 which is primarily intended for use within IPython).

In summary, DRP is designed for use cases where:

Expand All @@ -37,7 +37,7 @@ In summary, DRP is designed for use cases where:

The following output formats are provided by default. These are provided as [renderer classes] in order to leverage the content type negotiation built into Django REST Framework. This means clients can specify a format via `Accepts: text/csv` or by appending `.csv` to the URL (if the URL configuration below is used).

Format | Content Type | Pandas DataFrame Function | Notes
Format | Content Type | pandas DataFrame Function | Notes
-------|--------------|---------------------------|--------
CSV | `text/csv` | `to_csv()` |
TXT | `text/plain` | `to_csv()` | Useful for testing, as most browsers will download a CSV file instead of displaying it
Expand Down Expand Up @@ -110,14 +110,14 @@ urlpatterns = format_suffix_patterns(urlpatterns)
The default `PandasView` will serve up all of the available data from the provided model in a simple tabular form. You can also use a `PandasViewSet` if you are using Django REST Framework's [ViewSets] and [Routers], or a `PandasSimpleView` if you would just like to serve up some data without a Django model as the source.

### Implementation Notes
The underlying implementation is a set of [serializers] that take the normal serializer result and put it into a dataframe. Then, the included [renderers] generate the output using the built in Pandas functionality.
The underlying implementation is a set of [serializers] that take the normal serializer result and put it into a dataframe. Then, the included [renderers] generate the output using the built in pandas functionality.

Perhaps counterintuitively, the CSV renderer is the default in Django REST Pandas, as it is the most stable and useful for API building. While the Pandas JSON serializer is improving, the primary reason for making CSV the default is the compactness it provides over JSON when serializing time series data. This is particularly valuable for Pandas dataframes, in which:
Perhaps counterintuitively, the CSV renderer is the default in Django REST Pandas, as it is the most stable and useful for API building. While the pandas JSON serializer is improving, the primary reason for making CSV the default is the compactness it provides over JSON when serializing time series data. This is particularly valuable for pandas dataframes, in which:

- each record has the same keys, and
- there are (usually) no nested objects

While a normal CSV file only has a single row of column headers, Pandas can produce files with nested columns. This is a useful way to provide metadata about time series that is difficult to represent in a plain CSV file. However, it also makes the resulting CSV more difficult to parse. For this reason, you may be interested in [wq/pandas.js], a d3 extension for loading the complex CSV generated by Pandas Dataframes.
While a normal CSV file only has a single row of column headers, pandas can produce files with nested columns. This is a useful way to provide metadata about time series that is difficult to represent in a plain CSV file. However, it also makes the resulting CSV more difficult to parse. For this reason, you may be interested in [wq/pandas.js], a d3 extension for loading the complex CSV generated by pandas Dataframes.

```javascript
// mychart.js
Expand All @@ -141,7 +141,7 @@ function render(error, data) {
You can override the default renderers by setting `PANDAS_RENDERERS` in your `settings.py`, or by overriding `renderer_classes` in your `PandasView` subclass. `PANDAS_RENDERERS` is intentionally set separately from Django REST Framework's own `DEFAULT_RENDERER_CLASSES` setting, as it is likely that you will be mixing DRP views with regular DRF views.

[Django REST Framework]: http://django-rest-framework.org
[Pandas]: http://pandas.pydata.org
[pandas]: http://pandas.pydata.org
[d3.js]: http://d3js.org
[wq.app]: http://wq.io/wq.app
[wq/chart.js]: http://wq.io/docs/chart-js
Expand Down
26 changes: 13 additions & 13 deletions README.rst
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
Django REST Pandas
==================

*Django REST Framework + Pandas = A Model-driven Visualization API*
*Django REST Framework + pandas = A Model-driven Visualization API*

**Django REST Pandas** (DRP) provides a simple way to generate and serve
`Pandas <http://pandas.pydata.org>`__ DataFrames via the `Django REST
`pandas <http://pandas.pydata.org>`__ DataFrames via the `Django REST
Framework <http://django-rest-framework.org>`__. The resulting API can
serve up CSV (and a number of other formats)
for consumption by a client-side visualization tool like
Expand Down Expand Up @@ -46,13 +46,13 @@ and there are a number of similar solutions that may fit your needs
better.

- `Django Pandas <https://github.com/chrisdev/django-pandas/>`__
provides a custom ORM model manager with Pandas support. By contrast,
Django REST Pandas works at the *view* level, by integrating Pandas
provides a custom ORM model manager with pandas support. By contrast,
Django REST Pandas works at the *view* level, by integrating pandas
via custom Django REST Framework serializers and renderers.
- `DRF-CSV <https://github.com/mjumbewu/django-rest-framework-csv>`__
provides straightforward CSV renderers for use with Django REST
Framework. It may be useful if you just want a CSV API and don't have
a need for the Pandas DataFrame functionality.
a need for the pandas DataFrame functionality.
- `mpld3 <http://mpld3.github.io/>`__ provides a direct bridge from
`matplotlib <http://matplotlib.org/>`__ to
`d3.js <http://d3js.org>`__, complete with seamless
Expand All @@ -65,7 +65,7 @@ better.
similar use cases.

The goal of Django REST Pandas is to provide a generic REST API for
serving up Pandas dataframes. In this sense, it is similar to the Plot
serving up pandas dataframes. In this sense, it is similar to the Plot
Server in Bokeh, but more generic in that it does not assume any
particular visualization format or technology. Further, DRP is optimized
for integration with public-facing Django-powered websites (unlike mpld3
Expand Down Expand Up @@ -95,7 +95,7 @@ Framework. This means clients can specify a format via
configuration below is used).

.. csv-table::
:header: "Format", "Content Type", "Pandas Dataframe Function", "Notes"
:header: "Format", "Content Type", "pandas Dataframe Function", "Notes"
:widths: 50, 150, 70, 500

CSV,``text/csv``,``to_csv()``,
Expand All @@ -116,7 +116,7 @@ Getting Started

.. code:: bash
pip install rest-pandas
pip3 install rest-pandas
Usage Example
~~~~~~~~~~~~~
Expand Down Expand Up @@ -187,25 +187,25 @@ The underlying implementation is a set of
that take the normal serializer result and put it into a dataframe.
Then, the included
`renderers <https://github.com/wq/django-rest-pandas/blob/master/rest_pandas/renderers.py>`__
generate the output using the built in Pandas functionality.
generate the output using the built in pandas functionality.

Perhaps counterintuitively, the CSV renderer is the default in Django
REST Pandas, as it is the most stable and useful for API building. While
the Pandas JSON serializer is improving, the primary reason for making
the pandas JSON serializer is improving, the primary reason for making
CSV the default is the compactness it provides over JSON when
serializing time series data. This is particularly valuable for Pandas
serializing time series data. This is particularly valuable for pandas
dataframes, in which:

- each record has the same keys, and
- there are (usually) no nested objects

While a normal CSV file only has a single row of column headers, Pandas
While a normal CSV file only has a single row of column headers, pandas
can produce files with nested columns. This is a useful way to provide
metadata about time series that is difficult to represent in a plain CSV
file. However, it also makes the resulting CSV more difficult to parse.
For this reason, you may be interested in
`wq/pandas.js <http://wq.io/docs/pandas-js>`__, a d3 extension for
loading the complex CSV generated by Pandas Dataframes.
loading the complex CSV generated by pandas Dataframes.

.. code:: javascript
Expand Down
8 changes: 4 additions & 4 deletions README.rst.patch
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
4,5c4
< `Django REST Framework <http://django-rest-framework.org>`__ + `Pandas <http://pandas.pydata.org>`__ = A Model-driven Visualization API
< `Django REST Framework <http://django-rest-framework.org>`__ + `pandas <http://pandas.pydata.org>`__ = A Model-driven Visualization API
< ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
---
> *Django REST Framework + Pandas = A Model-driven Visualization API*
> *Django REST Framework + pandas = A Model-driven Visualization API*
10c9
< serve up CSV (and a number of `other formats <#supported-formats>`__)
---
> serve up CSV (and a number of other formats)
98,114c97,107
< +----------+---------------------------------------+-----------------------------+------------------------------------------------------------------------------------------+
< | Format | Content Type | Pandas DataFrame Function | Notes |
< | Format | Content Type | pandas DataFrame Function | Notes |
< +==========+=======================================+=============================+==========================================================================================+
< | CSV | ``text/csv`` | ``to_csv()`` |
< +----------+---------------------------------------+-----------------------------+------------------------------------------------------------------------------------------+
Expand All @@ -27,7 +27,7 @@
< +----------+---------------------------------------+-----------------------------+------------------------------------------------------------------------------------------+
---
> .. csv-table::
> :header: "Format", "Content Type", "Pandas Dataframe Function", "Notes"
> :header: "Format", "Content Type", "pandas Dataframe Function", "Notes"
> :widths: 50, 150, 70, 500
>
> CSV,``text/csv``,``to_csv()``,
Expand Down
2 changes: 1 addition & 1 deletion rest_pandas/renderers.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@

class PandasBaseRenderer(BaseRenderer):
"""
Renders DataFrames using their built in Pandas implementation.
Renders DataFrames using their built in pandas implementation.
Only works with serializers that return DataFrames as their data object.
Uses a StringIO to capture the output of dataframe.to_[format]()
"""
Expand Down
2 changes: 1 addition & 1 deletion setup.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
from setuptools import setup, find_packages

LONG_DESCRIPTION = """
Serves up Pandas dataframes via the Django REST Framework for client-side (i.e. d3.js) visualizations
Serves up pandas dataframes via the Django REST Framework for client-side (i.e. d3.js) visualizations
"""


Expand Down

0 comments on commit 53a8d56

Please sign in to comment.