Integration Guide for Other Systems

This document outlines how people who are maintaining other systems, such as the graphite web application, or any other back-end system for depicting graphs, or custom-authored pages integrating graphs, can best interface with and use wordgraph.


The text generated by wordgraph can be integrated in two ways: during page generation on the server, or potentially as a web API for client-side graph generation from javascript. There is no permanent, public web service for wordgraph. (That would be awesome! If you want to contribute server resources, let me know! Better yet – help set it up too!). The “beaten path” (insofar as a two-day-old product can support) is to integrate the text generation directly into the server-side web application which is generating the HTML for your pages.

The text produced can be dropped into the ALT text for the html image elements, providing screen readers with a way to find the text without presenting it to visual users. Alternatively, the text could be placed inside a text element underneath the graph if you wish to present the text to all web users.

The use of the package is not technically restricted to web applications, but GUI framework integration is beyond the experience of the package authors and so is not addressed in this guide.

The basic approach is to install the wordgraph package into your application, then call into its top-level method as follows. More detailed instructions for supported packages will be provided in following sections of this document. The text that is returned can be customised in a number of ways. These options are addressed in the API documentation as they do not directly affect system integration.

> import wordgraph
> text = wordgraph.describe(data, source_type)


This system is designed for potential inclusion into the graphite software package. The source data for the original tests and input cases for wordgraph comes from the JSON data which is supplied by that system when its graphs are generated. Unfortunatey, a full integration walkthrough is not available at this stage. A simple example walkthrough would be an extremely useful community contribution. Calling wordgraph with the JSON data and the source type of ‘graphite’ is all that is required.

> import wordgraph
> text = wordgraph.describe(data, source_type='graphite')


Matplotlib support is currently stalled, and not yet complete. The goal is to support this through direct introspection of the “figure” objects produced by matplotlib. Many users of matplotlib will be using either the ‘pylab’ or ‘pyplot’ / ‘plt’ interface for generating their graphs. These implicitly create a “currently active” figure which can be retrieved using “plt.gcf()”. Users creating figures by hand can pass them in individually.

> import wordgraph
> text = wordgraph.describe(figure, source_type='matplotlib')

It will be difficult to fully support complex plots, in particular it will be challenging to support figures which consist of multiple sub-plots. Until the package is substantially further expanded, please pass these in individually.

Custom or one-off graphs

Custom or one-off graphs can be supported in a number of different ways. If you have a time-series graph and the raw data, the simplest approach is most likely to re-create the graphite standard data structure and utilise the graphite interface.

If you wish to create a more complex graph description, you could consider using an alternative API entry point. It is not especially complicated to create the underlying data dictionaries which contain the describable values expected by the language generation subsystems. You could consider directly interfacing with the wordgraph “realisers”. Please look at the API docs and the tests directory for additional information on how to go about this approach.

Extensions and Other Systems

The package maintainers would love to support a wider variety of systems to help support the community. However, it is important to realise that there is no money made from this activity, and those who are supporting it are doing so on a strictly volunteer basis. What this means is that sometimes it may take some time to respond to complex emails, and the extent of support available will be highly variable depending on the other commitments of the individuals involved. If you would like to read more about how open source development works, search for “Open Source development” and there will be a wealth of information returned to you.

There is a lot that can make it easier to support integration of a new system. Obviously, “pull requests” (code contributions) are a direct way of improving the functionality of the system. However, the following contributions will all be gratefully received:

  1. Stories about how you are using the system, who this helps, and the impacts made.
  2. Input data examples from other systems
  3. Detailed descriptions of requirements for improvements to any aspect of the system
  4. Example graphs and expected text
  5. Defect or issue reports where something didn’t meet expectations

The package maintainers will do their best to support additional use cases and requests as best possible.