Plot View

Last Updated: August 10, 2015

Tethys Platform provides two interactive plotting engines: D3 and Highcharts. The Plot view options objects have been designed to be engine independent, meaning that you can configure a D3 plot using the same syntax as a Highcharts plot. This allows you to switch which plotting engine to use via configuration. This article describes each of the plot views that are available.

Warning

Highcharts is free-of-charge for certain applications (see: Highcharts JS Licensing). If you need a guaranteed fee-free solution, D3 is recommended.

Note

D3 plotting implemented for Line Plot, Pie Plot, Bar Plot, Scatter Plot, and Timeseries Plot.

Line Plot

class tethys_sdk.gizmos.LinePlot(series, height='500px', width='500px', engine='d3', title='', subtitle='', spline=False, x_axis_title='', x_axis_units='', y_axis_title='', y_axis_units='', **kwargs)

Used to create line plot visualizations.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

spline

If True, lines are smoothed using a spline technique.

Type:

bool

x_axis_title

Title of the x-axis.

Type:

str

x_axis_units

Units of the x-axis.

Type:

str

y_axis_title

Title of the y-axis.

Type:

str

y_axis_units

Units of the y-axis.

Type:

str

Controller Example

python
from tethys_sdk.gizmos import LinePlot

line_plot_view = LinePlot(
    height='500px',
    width='500px',
    engine='highcharts',
    title='Plot Title',
    subtitle='Plot Subtitle',
    spline=True,
    x_axis_title='Altitude',
    x_axis_units='km',
    y_axis_title='Temperature',
    y_axis_units='°C',
    series=[
       {
           'name': 'Air Temp',
           'color': '#0066ff',
           'marker': {'enabled': False},
           'data': [
               [0, 5], [10, -70],
               [20, -86.5], [30, -66.5],
               [40, -32.1],
               [50, -12.5], [60, -47.7],
               [70, -85.7], [80, -106.5]
           ]
       },
       {
           'name': 'Water Temp',
           'color': '#ff6600',
           'data': [
               [0, 15], [10, -50],
               [20, -56.5], [30, -46.5],
               [40, -22.1],
               [50, -2.5], [60, -27.7],
               [70, -55.7], [80, -76.5]
           ]
       }
    ]
)

context = {
    'line_plot_view': line_plot_view,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo line_plot_view %}

Scatter Plot

class tethys_sdk.gizmos.ScatterPlot(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', x_axis_title='', x_axis_units='', y_axis_title='', y_axis_units='', **kwargs)

Use to create a scatter plot visualization.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

spline

If True, lines are smoothed using a spline technique.

Type:

bool

x_axis_title

Title of the x-axis.

Type:

str

x_axis_units

Units of the x-axis.

Type:

str

y_axis_title

Title of the y-axis.

Type:

str

y_axis_units

Units of the y-axis.

Type:

str

Controller Example

python
from tethys_sdk.gizmos import ScatterPlot

male_dataset = {
    'name': 'Male',
    'color': '#0066ff',
    'data': [
        [174.0, 65.6], [175.3, 71.8], [193.5, 80.7], [186.5, 72.6],
        [187.2, 78.8], [181.5, 74.8], [184.0, 86.4], [184.5, 78.4],
        [175.0, 62.0], [184.0, 81.6], [180.0, 76.6], [177.8, 83.6],
        [192.0, 90.0], [176.0, 74.6], [174.0, 71.0], [184.0, 79.6],
        [192.7, 93.8], [171.5, 70.0], [173.0, 72.4], [176.0, 85.9],
        [176.0, 78.8], [180.5, 77.8], [172.7, 66.2], [176.0, 86.4],
        [173.5, 81.8], [178.0, 89.6], [180.3, 82.8], [180.3, 76.4],
        [164.5, 63.2], [173.0, 60.9], [183.5, 74.8], [175.5, 70.0],
        [188.0, 72.4], [189.2, 84.1], [172.8, 69.1], [170.0, 59.5],
        [182.0, 67.2], [170.0, 61.3], [177.8, 68.6], [184.2, 80.1],
        [186.7, 87.8], [171.4, 84.7], [172.7, 73.4], [175.3, 72.1],
        [180.3, 82.6], [182.9, 88.7], [188.0, 84.1], [177.2, 94.1],
        [172.1, 74.9], [167.0, 59.1], [169.5, 75.6], [174.0, 86.2],
        [172.7, 75.3], [182.2, 87.1], [164.1, 55.2], [163.0, 57.0],
        [171.5, 61.4], [184.2, 76.8], [174.0, 86.8], [174.0, 72.2],
        [177.0, 71.6], [186.0, 84.8], [167.0, 68.2], [171.8, 66.1]
    ]
}

female_dataset = {
    'name': 'Female',
    'color': '#ff6600',
    'data': [
        [161.2, 51.6], [167.5, 59.0], [159.5, 49.2], [157.0, 63.0],
        [155.8, 53.6], [170.0, 59.0], [159.1, 47.6], [166.0, 69.8],
        [176.2, 66.8], [160.2, 75.2], [172.5, 55.2], [170.9, 54.2],
        [172.9, 62.5], [153.4, 42.0], [160.0, 50.0], [147.2, 49.8],
        [168.2, 49.2], [175.0, 73.2], [157.0, 47.8], [167.6, 68.8],
        [159.5, 50.6], [175.0, 82.5], [166.8, 57.2], [176.5, 87.8],
        [170.2, 72.8], [174.0, 54.5], [173.0, 59.8], [179.9, 67.3],
        [170.5, 67.8], [160.0, 47.0], [154.4, 46.2], [162.0, 55.0],
        [176.5, 83.0], [160.0, 54.4], [152.0, 45.8], [162.1, 53.6],
        [170.0, 73.2], [160.2, 52.1], [161.3, 67.9], [166.4, 56.6],
        [168.9, 62.3], [163.8, 58.5], [167.6, 54.5], [160.0, 50.2],
        [161.3, 60.3], [167.6, 58.3], [165.1, 56.2], [160.0, 50.2],
        [170.0, 72.9], [157.5, 59.8], [167.6, 61.0], [160.7, 69.1],
        [163.2, 55.9], [152.4, 46.5], [157.5, 54.3], [168.3, 54.8],
        [180.3, 60.7], [165.5, 60.0], [165.0, 62.0], [164.5, 60.3]
    ]
}

scatter_plot_view = ScatterPlot(
    width='500px',
    height='500px',
    engine='highcharts',
    title='Scatter Plot',
    subtitle='Scatter Plot',
    x_axis_title='Height',
    x_axis_units='cm',
    y_axis_title='Weight',
    y_axis_units='kg',
    series=[
        male_dataset,
        female_dataset
    ]
)

context = {
    'scatter_plot_view': scatter_plot_view,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo scatter_plot_view %}

Polar Plot

class tethys_sdk.gizmos.PolarPlot(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', categories=None, **kwargs)

Use to create a polar plot visualization.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

categories

List of category names, one for each data point in the series.

Type:

list

Controller Example

python
from tethys_sdk.gizmos import PolarPlot

web_plot = PolarPlot(
    height='500px',
    width='500px',
    engine='highcharts',
    title='Polar Chart',
    subtitle='Polar Chart',
    pane={
      'size': '80%'
    },
    categories=['Infiltration', 'Soil Moisture', 'Precipitation', 'Evaporation',
              'Roughness', 'Runoff', 'Permeability', 'Vegetation'],
    series=[
      {
          'name': 'Park City',
          'data': [0.2, 0.5, 0.1, 0.8, 0.2, 0.6, 0.8, 0.3],
          'pointPlacement': 'on'
      },
      {
          'name': 'Little Dell',
          'data': [0.8, 0.3, 0.2, 0.5, 0.1, 0.8, 0.2, 0.6],
          'pointPlacement': 'on'
      }
    ]
)

context = {
    'web_plot': web_plot,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo web_plot %}

Pie Plot

class tethys_sdk.gizmos.PiePlot(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', **kwargs)

Use to create a pie plot visualization.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

Controller Example

python
from tethys_sdk.gizmos import PieChart

pie_plot_view = PiePlot(
    height='500px',
    width='500px',
    engine='highcharts',
    title='Pie Chart',
    subtitle='Pie Chart',
    series=[
          {'name': 'Firefox', 'value': 45.0},
          {'name': 'IE', 'value': 26.8},
          {'name': 'Chrome', 'value': 12.8},
          {'name': 'Safari', 'value': 8.5},
          {'name': 'Opera', 'value': 8.5},
          {'name': 'Others', 'value': 0.7}
    ]
)

context = {
    'pie_plot_view': pie_plot_view,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo pie_plot_view %}

Bar Plot

class tethys_sdk.gizmos.BarPlot(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', horizontal=False, categories=None, axis_title='', axis_units='', group_tools=True, y_min=0, **kwargs)

Bar Plot

Displays as either a bar or column chart.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

horizontal

If True, bars are displayed horizontally, otherwise they are displayed vertically.

Type:

bool

categories

A list of category titles, one for each bar.

Type:

list

axis_title

Title of the axis.

Type:

str

axis_units

Units of the axis.

Type:

str

y_min

Minimum value of y axis.

Type:

int,float

Controller Example

python
from tethys_sdk.gizmos import BarPlot

bar_plot_view = BarPlot(
    height='500px',
    width='500px',
    engine='highcharts',
    title='Bar Chart',
    subtitle='Bar Chart',
    vertical=True,
    categories=[
        'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
    ],
    axis_units='millions',
    axis_title='Population',
    series=[{
            'name': "Year 1800",
            'data': [100, 31, 635, 203, 275, 487, 872, 671, 736, 568, 487, 432]
        }, {
            'name': "Year 1900",
            'data': [133, 200, 947, 408, 682, 328, 917, 171, 482, 140, 176, 237]
        }, {
            'name': "Year 2000",
            'data': [764, 628, 300, 134, 678, 200, 781, 571, 773, 192, 836, 172]
        }, {
            'name': "Year 2008",
            'data': [973, 914, 500, 400, 349, 108, 372, 726, 638, 927, 621, 364]
        }
    ]
)

context = {
    'bar_plot_view': bar_plot_view,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo bar_plot_view %}

Time Series

class tethys_sdk.gizmos.TimeSeries(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', y_axis_title='', y_axis_units='', y_min=0, **kwargs)

Use to create a timeseries plot visualization

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

y_axis_title

Title of the axis.

Type:

str

y_axis_units

Units of the axis.

Type:

str

Controller Example

python
from tethys_sdk.gizmos import TimeSeries

timeseries_plot = TimeSeries(
    height='500px',
    width='500px',
    engine='highcharts',
    title='Irregular Timeseries Plot',
    y_axis_title='Snow depth',
    y_axis_units='m',
    series=[{
        'name': 'Winter 2007-2008',
        'data': [
            [datetime(2008, 12, 2), 0.8],
            [datetime(2008, 12, 9), 0.6],
            [datetime(2008, 12, 16), 0.6],
            [datetime(2008, 12, 28), 0.67],
            [datetime(2009, 1, 1), 0.81],
            [datetime(2009, 1, 8), 0.78],
            [datetime(2009, 1, 12), 0.98],
            [datetime(2009, 1, 27), 1.84],
            [datetime(2009, 2, 10), 1.80],
            [datetime(2009, 2, 18), 1.80],
            [datetime(2009, 2, 24), 1.92],
            [datetime(2009, 3, 4), 2.49],
            [datetime(2009, 3, 11), 2.79],
            [datetime(2009, 3, 15), 2.73],
            [datetime(2009, 3, 25), 2.61],
            [datetime(2009, 4, 2), 2.76],
            [datetime(2009, 4, 6), 2.82],
            [datetime(2009, 4, 13), 2.8],
            [datetime(2009, 5, 3), 2.1],
            [datetime(2009, 5, 26), 1.1],
            [datetime(2009, 6, 9), 0.25],
            [datetime(2009, 6, 12), 0]
        ]
    }]
)

context = {
    'timeseries_plot': timeseries_plot,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo timeseries_plot %}

Area Range

class tethys_sdk.gizmos.AreaRange(series=None, height='500px', width='500px', engine='d3', title='', subtitle='', y_axis_title='', y_axis_units='', **kwargs)

Use to create a area range plot visualization.

series

A list of series dictionaries.

Type:

list, required

height

Height of the plot element. Any valid css unit of length.

Type:

str

width

Width of the plot element. Any valid css unit of length.

Type:

str

engine

The plot engine to be used for rendering, either 'd3' or 'highcharts'. Defaults to 'd3'.

Type:

str

title

Title of the plot.

Type:

str

subtitle

Subtitle of the plot.

Type:

str

y_axis_title

Title of the axis.

Type:

str

y_axis_units

Units of the axis.

Type:

str

Controller Example

python
from tethys_sdk.gizmos import AreaRange

averages = [
    [datetime(2009, 7, 1), 21.5], [datetime(2009, 7, 2), 22.1], [datetime(2009, 7, 3), 23],
    [datetime(2009, 7, 4), 23.8], [datetime(2009, 7, 5), 21.4], [datetime(2009, 7, 6), 21.3],
    [datetime(2009, 7, 7), 18.3], [datetime(2009, 7, 8), 15.4], [datetime(2009, 7, 9), 16.4],
    [datetime(2009, 7, 10), 17.7], [datetime(2009, 7, 11), 17.5], [datetime(2009, 7, 12), 17.6],
    [datetime(2009, 7, 13), 17.7], [datetime(2009, 7, 14), 16.8], [datetime(2009, 7, 15), 17.7],
    [datetime(2009, 7, 16), 16.3], [datetime(2009, 7, 17), 17.8], [datetime(2009, 7, 18), 18.1],
    [datetime(2009, 7, 19), 17.2], [datetime(2009, 7, 20), 14.4],
    [datetime(2009, 7, 21), 13.7], [datetime(2009, 7, 22), 15.7], [datetime(2009, 7, 23), 14.6],
    [datetime(2009, 7, 24), 15.3], [datetime(2009, 7, 25), 15.3], [datetime(2009, 7, 26), 15.8],
    [datetime(2009, 7, 27), 15.2], [datetime(2009, 7, 28), 14.8], [datetime(2009, 7, 29), 14.4],
    [datetime(2009, 7, 30), 15], [datetime(2009, 7, 31), 13.6]
]

ranges = [
    [datetime(2009, 7, 1), 14.3, 27.7], [datetime(2009, 7, 2), 14.5, 27.8], [datetime(2009, 7, 3), 15.5, 29.6],
    [datetime(2009, 7, 4), 16.7, 30.7], [datetime(2009, 7, 5), 16.5, 25.0], [datetime(2009, 7, 6), 17.8, 25.7],
    [datetime(2009, 7, 7), 13.5, 24.8], [datetime(2009, 7, 8), 10.5, 21.4], [datetime(2009, 7, 9), 9.2, 23.8],
    [datetime(2009, 7, 10), 11.6, 21.8], [datetime(2009, 7, 11), 10.7, 23.7], [datetime(2009, 7, 12), 11.0, 23.3],
    [datetime(2009, 7, 13), 11.6, 23.7], [datetime(2009, 7, 14), 11.8, 20.7], [datetime(2009, 7, 15), 12.6, 22.4],
    [datetime(2009, 7, 16), 13.6, 19.6], [datetime(2009, 7, 17), 11.4, 22.6], [datetime(2009, 7, 18), 13.2, 25.0],
    [datetime(2009, 7, 19), 14.2, 21.6], [datetime(2009, 7, 20), 13.1, 17.1], [datetime(2009, 7, 21), 12.2, 15.5],
    [datetime(2009, 7, 22), 12.0, 20.8], [datetime(2009, 7, 23), 12.0, 17.1], [datetime(2009, 7, 24), 12.7, 18.3],
    [datetime(2009, 7, 25), 12.4, 19.4], [datetime(2009, 7, 26), 12.6, 19.9], [datetime(2009, 7, 27), 11.9, 20.2],
    [datetime(2009, 7, 28), 11.0, 19.3], [datetime(2009, 7, 29), 10.8, 17.8], [datetime(2009, 7, 30), 11.8, 18.5],
    [datetime(2009, 7, 31), 10.8, 16.1]
]

area_range_plot_object = AreaRange(
    title='July Temperatures',
    y_axis_title='Temperature',
    y_axis_units='*C',
    width='500px',
    height='500px',
    series=[{
        'name': 'Temperature',
        'data': averages,
        'zIndex': 1,
        'marker': {
            'lineWidth': 2,
        }
    }, {
        'name': 'Range',
        'data': ranges,
        'type': 'arearange',
        'lineWidth': 0,
        'linkedTo': ':previous',
        'fillOpacity': 0.3,
        'zIndex': 0
    }]
)


context = {
    'area_range_plot_object': area_range_plot_object,
}

Template Example

python
{% load tethys_gizmos %}

{% gizmo area_range_plot_object %}

JavaScript API

For advanced features, the JavaScript API can be used to interact with the HighCharts object that is generated by the Plot View JavaScript library.

TETHYS_PLOT_VIEW.initHighChartsPlot(jquery_element)

This method initializes a chart generated from an AJAX request. An example is demonstrated in the Dam Break javascript tutorial.

Note

In order to use this, you will either need to use a PlotView gizmo on the main page or register the dependencies in the main html template page using the import_gizmo_dependency tag with the plot_view name in the import_gizmos block.

For example:

python
{% block import_gizmos %}
    {% import_gizmo_dependency plot_view %}
{% endblock %}

Three elements are required:

  1. A controller for the AJAX call with a plot view gizmo.

python
@controller(
    url="dam-break/map/hydrograph",
)
def hydrograph_ajax(request):
    """
    Controller for the hydrograph ajax request.
    """

    # add a plot view gizmo
    flood_plot = TimeSeries(
                    ...
    )

    context = {"flood_plot": flood_plot}

    return render(request, "dam_break/hydrograph_ajax.html", context)
  1. A template for with the tethys gizmo (e.g. hydrograph_ajax.html)

html+django
{% load tethys_gizmos %}

{% gizmo flood_plot %}
  1. The AJAX call in the javascript

javascript
$(function() { //wait for page to load

    $.ajax({
        url: 'hydrograph',
        method: 'GET',
        data: {
            'peak_flow': 500, //example data to pass to the controller
        },
        success: function(data) {
            // add plot to page
            $("#plot_view_div").html(data);

            //Initialize Plot
            TETHYS_PLOT_VIEW.initHighChartsPlot($('.highcharts-plot'));
        }
    });

});

Highcharts JavaScript API

The Highcharts plots can be modified via JavaScript by using jQuery to select the Highcharts div and calling the highcharts() method on it. This will return the JavaScript object that represents the plot, which can be modified using the Highcharts API.

python
var plot = $('#my-plot').highcharts();