Django-Chartit¶
Django Chartit is a Django app that can be used to easily create charts from the data
in your database. The charts are rendered using Highcharts
and jQuery
JavaScript libraries. Data in your database can be plotted as simple line
charts, column charts, area charts, scatter plots, and many more chart types.
Data can also be plotted as Pivot Charts where the data is grouped and/or
pivoted by specific column(s).
Changelog¶
- 0.2.8 (December 4, 2016)
PivotChart
andPivotDataPool
will be deprecated soon. Both are marked with deprecation warnings. There is a lot of duplication and special handling between those classes and theChart
andDataPool
classes which make it harder to expand the feature set for django-chartit. The next release will focus on consolidating all the functionality intoChart
andDataPool
so that users will still be able to draw pivot charts. You will have to construct your pivot charts manually though!DataPool
terms now supports model properties. Fixes #35. Model properties are not supported forPivotDataPool
! WARNING: when using model properties chartit can’t make use of ``QuerySet.values()`` internally. This means results will not be groupped by the values of the fields you supplied. This may lead to unexpected query results/charts!DataPool
now supportsRawQuerySet
as data source. Fixes #44.RawQuerySet
is not supported forPivotDataPool
! WARNING: when using ``RawQuerySet`` don’t use double underscores in field names because these are interpreted internally by chartit and will cause exceptions. For example don’t do this ``SELECT AVG(rating) as rating__avg`` instead write it as ``SELECT AVG(rating) as rating_avg``!- README now tells how to execute
demoproject/
- 0.2.7 (September 14, 2016)
- Don’t use
super(self.__class__)
b/c that breaks chart class inheritance. Fixes #41
- Don’t use
- 0.2.6 (August 16, 2016)
- Merge
chartit_tests/
withdemoproject/
- Load test DB with real data to use during testing
- Add more tests
- Update the path to demoproject.settings when building docs. Fixes a problem which caused some API docs to be empty
- Fix ValueError: not enough values to unpack (expected 2, got 0) with PivotChart when the QuerySet returns empty data
- Dropped requirement on
simplejson
- Properly handle unicode data in Pivot charts. Fixes #5
- Demo project updated with Chart and PivotChart examples of rendering DateField values on the X axis
- Allow charting of
extra()
orannotate()
fields. Fixes #8 and #12 - Refactor
RecursiveDefaultDict
to allow chart objects to be serialized to/from cache. Fixes #10 - Add information about supported 3rd party JavaScript versions. Fixes #14
- Merge
- 0.2.5 (August 3, 2016)
- Workaround Python 3 vs. Python 2 list sort issue which breaks charts with multiple data sources displayed on the same axis!
- Make demoproject/ compatible with Django 1.10
- 0.2.4 (August 2, 2016)
- Fix for
get_all_field_names()
andget_field_by_name()
removal in Django 1.10. Fixes #39 - Updated for django.db.sql.query.Query.aggregates removal
- Fix for
- 0.2.3 (July 30, 2016)
- New to_json() method for charts. Useful for creating Highcharts in AJAX
- Merged with django-chartit2 fork by Grant McConnaughey which adds Python 3 and latest Django 1.8.x and 1.9.x support
- Allow dictionary fields in conjunction with lambda fields. Closes #26
- Documentation improvements
- Lots of code cleanups and style improvements
- 0.2.2 as django-chartit2 (January 28, 2016)
- Fixed another issue that prevented installation via PyPI
- 0.2.0 as django-chartit2 (January 20, 2016):
- Fixed issue that could prevent installation via PyPI
- 0.1 (November 5, 2011)
- Initial release of django-chartit
Features¶
- Plot charts from models.
- Plot data from multiple models on the same axis on a chart.
- Plot pivot charts from models. Data can be pivoted by across multiple columns.
- Legend pivot charts by multiple columns.
- Combine data from multiple models to plot on same pivot charts.
- Plot a pareto chart, paretoed by a specific column.
- Plot only a top few items per category in a pivot chart.
- Python 3 compatibility
- Django 1.8 and 1.9 compatibility
- Documentation to ReadTheDocs
- Automated testing via Travis CI
- Test coverage tracking via Coveralls
Installation¶
You can install Django-Chartit from PyPI. Just do
$ pip install django_chartit
Then, add chartit to INSTALLED_APPS in “settings.py”.
You also need supporting JavaScript libraries. See the Required JavaScript Libraries section for more details.
How to Use¶
Plotting a chart or pivot chart on a webpage involves the following steps.
- Create a
DataPool
orPivotDataPool
object that specifies what data you need to retrieve and from where. - Create a
Chart
orPivotChart
object to plot the data in theDataPool
orPivotDataPool
respectively. - Return the
Chart
/PivotChart
object from a djangoview
function to the django template. - Use the
load_charts
template tag to load the charts to HTML tags with specific ids.
It is easier to explain the steps above with examples. So read on.
How to Create Charts¶
Here is a short example of how to create a line chart. Let’s say we have a simple model with 3 fields - one for month and two for temperatures of Boston and Houston.
class MonthlyWeatherByCity(models.Model):
month = models.IntegerField()
boston_temp = models.DecimalField(max_digits=5, decimal_places=1)
houston_temp = models.DecimalField(max_digits=5, decimal_places=1)
And let’s say we want to create a simple line chart of month on the x-axis and the temperatures of the two cities on the y-axis.
from chartit import DataPool, Chart
def weather_chart_view(request):
#Step 1: Create a DataPool with the data we want to retrieve.
weatherdata = \
DataPool(
series=
[{'options': {
'source': MonthlyWeatherByCity.objects.all()},
'terms': [
'month',
'houston_temp',
'boston_temp']}
])
#Step 2: Create the Chart object
cht = Chart(
datasource = weatherdata,
series_options =
[{'options':{
'type': 'line',
'stacking': False},
'terms':{
'month': [
'boston_temp',
'houston_temp']
}}],
chart_options =
{'title': {
'text': 'Weather Data of Boston and Houston'},
'xAxis': {
'title': {
'text': 'Month number'}}})
#Step 3: Send the chart object to the template.
return render_to_response({'weatherchart': cht})
And you can use the load_charts
filter in the django template to render
the chart.
<head>
<!-- code to include the highcharts and jQuery libraries goes here -->
<!-- load_charts filter takes a comma-separated list of id's where -->
<!-- the charts need to be rendered to -->
{% load chartit %}
{{ weatherchart|load_charts:"container" }}
</head>
<body>
<div id='container'> Chart will be rendered here </div>
</body>
How to Create Pivot Charts¶
Here is an example of how to create a pivot chart. Let’s say we have the following model.
class DailyWeather(models.Model):
month = models.IntegerField()
day = models.IntegerField()
temperature = models.DecimalField(max_digits=5, decimal_places=1)
rainfall = models.DecimalField(max_digits=5, decimal_places=1)
city = models.CharField(max_length=50)
state = models.CharField(max_length=2)
We want to plot a pivot chart of month (along the x-axis) versus the average rainfall (along the y-axis) of the top 3 cities with highest average rainfall in each month.
from django.db.models import Avg
from chartit import PivotDataPool, PivotChart
def rainfall_pivot_chart_view(request):
# Step 1: Create a PivotDataPool with the data we want to retrieve.
rainpivotdata = PivotDataPool(
series=[{
'options': {
'source': DailyWeather.objects.all(),
'categories': ['month'],
'legend_by': 'city',
'top_n_per_cat': 3,
},
'terms': {
'avg_rain': Avg('rainfall'),
}
}]
)
# Step 2: Create the PivotChart object
rainpivcht = PivotChart(
datasource=rainpivotdata,
series_options=[{
'options': {
'type': 'column',
'stacking': True
},
'terms': ['avg_rain']
}],
chart_options={
'title': {
'text': 'Rain by Month in top 3 cities'
},
'xAxis': {
'title': {
'text': 'Month'
}
}
}
)
# Step 3: Send the PivotChart object to the template.
return render_to_response({'rainpivchart': rainpivcht})
And you can use the load_charts
filter in the django template to render
the chart.
<head>
<!-- code to include the highcharts and jQuery libraries goes here -->
<!-- load_charts filter takes a comma-separated list of id's where -->
<!-- the charts need to be rendered to -->
{% load chartit %}
{{ rainpivchart|load_charts:"container" }}
</head>
<body>
<div id='container'> Chart will be rendered here </div>
</body>
Rendering multiple charts¶
It is possible to render multiple charts in the same template. The first
argument to load_charts
is the Chart object or a list of Chart objects,
and the second is a comma separated list of HTML IDs where the charts will
be rendered.
When calling Django’s render
you have to pass all you charts as a list:
return render(request, 'index.html',
{
'chart_list' : [chart_1, chart_2],
}
)
Then in your template you have to use the proper syntax:
<head>
{% load chartit %}
{{ chart_list|load_charts:"chart_1,chart_2" }}
</head>
<body>
<div id="chart_1">First chart will be rendered here</div>
<div id="chart_2">Second chart will be rendered here</div>
</body>
Demo¶
The above examples are just a brief taste of what you can do with
Django-Chartit. For more examples and to look at the charts in actions, check
out the demoproject/
directory. To execute the demo run the commands
cd demoproject/
PYTHONPATH=../ python ./manage.py migrate
PYTHONPATH=../ python ./manage.py runserver
Required JavaScript Libraries¶
The following JavaScript Libraries are required for using Django-Chartit.
- jQuery - versions 1.6.4 and 1.7 are known to work well with django-chartit.
- Highcharts - versions 2.1.7 and 2.2.0 are known to work well with django-chartit.
Note
While Django-Chartit
itself is licensed under the BSD license,
Highcharts
is licensed under the Highcharts license and jQuery
is licensed under both
MIT License and GNU General Public License (GPL) Version 2. It is your own
responsibility to abide by respective licenses when downloading and using
the supporting JavaScript libraries.
Quick API Reference¶
Full module documentation¶
License¶
- Copyright (c) 2011, Praveen Gollakota.
- Copyright (c) 2016, Grant McConnaughey.
- Copyright (c) 2016, Alexander Todorov.
- and other contributors.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.