nvd3 py Documentation - Read the Docs · nvd3_py Documentation, Release 0.1 The goal of this project is to offer a simple API to createNVD3charts. Simple, in this context, means an

nvd3_py DocumentationRelease 0.1

Marco Giusti

July 06, 2016

Contents

1 Installation 3

2 Development 5

3 Contents: 73.1 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 Django integration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.3 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

i

ii

nvd3_py Documentation, Release 0.1

The goal of this project is to offer a simple API to create NVD3 charts. Simple, in this context, means an API thatmimics the NVD3’s one. Look at this simple comparison from NVD3’s pie chart example:

// Regular pie chart examplenv.addGraph(function() {var chart = nv.models.pieChart()

.x(function(d) { return d.label })

.y(function(d) { return d.value })

.showLabels(true);

d3.select("#chart svg").datum(exampleData()).transition().duration(350).call(chart);

return chart;});

// Pie chart example data. Note how there is only a single array of// key-value pairs.function exampleData() {return [

{"label": "One","value" : 29.765957771107

} ,{

"label": "Two","value" : 0

} ,{

"label": "Three","value" : 32.807804682612

} ,{

"label": "Four","value" : 196.45946739256

} ,{

"label": "Five","value" : 0.19434030906893

} ,{

"label": "Six","value" : 98.079782601442

} ,{

"label": "Seven","value" : 13.925743130903

} ,{

"label": "Eight","value" : 5.1387322875705

}];

}

Python version (values are trimmed for simplicity):

Contents 1

http://nvd3.org/

http://nvd3.org/examples/pie.html

https://github.com/marcogiusti/nvd3_py/blob/master/examples/pie_chart.ipynb


import nvd3

# prepare the datax = ["One", "Two", "Three", "Four", "Five", "Six", "Seven","Eight"]y = [29.76, 0, 32.80, 196.45, 0.19, 98.07, 13.92, 5.138]data = [{"label": l, "value": v} for l, v in zip(x, y)]# build the chartpie_chart = nvd3.PieChart()pie_chart.x("function(d) { return d.label; }")pie_chart.y("function(d) { return d.value; }")pie_chart.showLabels(True)# show the HTMLdata_supplier = nvd3.StaticDataSupplier(data)nvd3.Container(pie_chart, data_supplier)

2 Contents

CHAPTER 1

Installation

The package will not published to PyPI until an acceptable stability and completeness is reached. The package couldbe anyway installed using pip+git:

$ pip install git+https://github.com/marcogiusti/nvd3_py@master#egg=nvd3_py

3

https://pip.pypa.io/en/stable/reference/pip_install/#git


4 Chapter 1. Installation

CHAPTER 2

Development

The development take place in Github. The code is still incomplete, undocumented and not tested, use it with care.

5

https://github.com/marcogiusti/nvd3_py


6 Chapter 2. Development

CHAPTER 3

Contents:

3.1 Examples

The followin examples try to mimic the examples in the NVD3’s web site.

3.1.1 Simple line chart

See the original line chart example. The line chart has the following features:

• ability to combine as many line series’ as you want;

• tooltip which shows all visible series data;

• line transitions that happen when turning on/off series, and when resizing chart;

• can specify whether a series should be an area chart.

import mathimport nvd3

# Simple test data generatordef sin_and_cos():

sin = []sin2 = []cos = []

# Data is represented as an array of {x,y} pairs.for i in range(100):

sin.append({"x": i, "y": math.sin(i / 10.0)})sin2.append({"x": i, "y": math.sin(i / 10.0) * 0.25 + 0.5})cos.append({"x": i, "y": 0.5 * math.cos(i / 10.0)})

# Line chart data should be sent as an array of series objects.return [

{"values": sin, # values - represents the array of {x,y}

# data points"key": "Sine Wave", # key - the name of the series."color": "#ff7f0e" # color - optional: choose your own

# line color.},{

"values": cos,

7

http://nvd3.org/examples/index.html

http://nvd3.org/examples/line.html


"key": "Cosine Wave","color": "#2ca02c"

},{

"values": sin2,"key": "Another sine wave","color": "#7777ff","area": True # area - set to True if you want this line

# to turn into a filled area chart.}

]

chart = nvd3.LineChart()chart.margin({"left": 100}) # Adjust chart margins to give the

# x-axis some breathing room.chart.useInteractiveGuideline(True) # We want nice looking

# tooltips and a guideline!chart.duration(350) # how fast do you want the lines to

# transition?chart.showLegend(True) # Show the legend, allowing users to turn

# on/off line series.chart.showYAxis(True) # Show the y-axischart.showXAxis(True) # Show the x-axis

# Chart x-axis settingschart.xaxis.axisLabel("Time (ms)")chart.xaxis.tickFormat("d3.format(',r')");

# Chart y-axis settingschart.yaxis.axisLabel("Voltage (v)")chart.yaxis.tickFormat("d3.format('.02f')");

# Done setting the chart up? Time to render it!data = sin_and_cos() # You need data...data_supplier = nvd3.StaticDataSupplier(data)nvd3.Container(chart, data_supplier, width=600, height=400)

8 Chapter 3. Contents:


3.1.2 Scatter / Bubble Chart

See the original scatter chart example.

import randomimport nvd3

SHAPES = ['circle', 'cross', 'triangle-up', 'triangle-down','diamond', 'square']

def normal(mu=0, sigma=1):return random.gauss(mu, sigma)

def _get_point(j):l = len(SHAPES)shape = SHAPES[j % l] if random.random() > 0.95 else "circle"point = {

"x": normal(),"y": normal(),"size": random.random(),"shape": shape

}return point

3.1. Examples 9

http://nvd3.org/examples/scatter.html


def _get_points(points):return [_get_point(j) for j in xrange(points)]

def random_data(groups, points): # groups, # points per groupdata = [{"key": "Group %d" % i, "values": _get_points(points)}

for i in xrange(groups)]return data

chart = nvd3.ScatterChart()chart.showDistX(True) # showDist, when true, will display those little

# distribution lines on the axis.chart.showDistY(True)chart.duration(350)chart.color("d3.scale.category10().range()")# Configure how the tooltip looks.# chart.tooltipContent("""function(key) {# return '<h3>' + key + '</h3>';# }""")

# Axis settingschart.xaxis.tickFormat("d3.format('.02f')")chart.yaxis.tickFormat("d3.format('.02f')")

data_supplier = nvd3.StaticDataSupplier(random_data(4, 40))nvd3.Container(chart, data_supplier, width=600, height=400)



3.1.3 Pie chart

Regular pie chart

import nvd3

# prepare the datax = ["One", "Two", "Three", "Four", "Five", "Six", "Seven","Eight"]y = [29.76, 0, 32.80, 196.45, 0.19, 98.07, 13.92, 5.138]data = [{"label": l, "value": v} for l, v in zip(x, y)]# build the chartpie_chart = nvd3.PieChart()pie_chart.x("function(d) { return d.label; }")pie_chart.y("function(d) { return d.value; }")pie_chart.showLabels(True)# show the HTMLdata_supplier = nvd3.StaticDataSupplier(data)nvd3.Container(pie_chart, data_supplier)

3.1. Examples 11


Donut chart

import nvd3

x = ["One", "Two", "Three", "Four", "Five", "Six", "Seven","Eight"]y = [29.76, 0, 32.80, 196.45, 0.19, 98.07, 13.92, 5.138]data = [{"label": l, "value": v} for l, v in zip(x, y)]

chart = nvd3.PieChart()chart.x("function(d) { return d.label; }")chart.y("function(d) { return d.value; }")



chart.showLabels(True) # Display pie labelschart.labelThreshold(.05) # Configure the minimum slice size for

# labels to show upchart.labelType("percent") # Configure what type of data to show in

# the label. Can be "key", "value" or# "percent"

chart.donut(True) # Turn on Donut mode. Makes pie chart look tasty!chart.donutRatio(.35) # Configure how big you want the donut hole

# size to be.

data_supplier = nvd3.StaticDataSupplier(data)nvd3.Container(chart, data_supplier)

3.1. Examples 13


3.1.4 Stacked/Grouped multi-bar chart

See the original multi-bar chart example.

import mathimport randomimport nvd3

def bump(a, m):x = 1 / (.1 + random.random())y = 2 * random.random() - .5z = 10 / (.1 + random.random())for i in range(m):

w = (i / float(m) - y) * za[i] += x * math.exp(-w * w)

# Inspired by Lee Byron's test data generator.def stream_layers(n, m, o=0):

def function(_):a = [o + o * random.random() for i in xrange(m)]for _ in range(5):

bump(a, m)return map(lambda (i, d): {"x": i, "y": max(0, d)}, enumerate(a))

return map(function, xrange(n))

# Generate some nice data.def example_data():

def entry((i, data)):return {"key": "Stream #" + str(i), "values": data}

a = stream_layers(3, int(round(10 + random.random() * 100)), 0.1)return map(entry, enumerate(a))

chart = nvd3.MultiBarChart()chart.duration(350)chart.reduceXTicks(True) # If 'false', every single x-axis tick label

# will be rendered.chart.rotateLabels(0) # Angle to rotate x-axis labels.chart.showControls(True) # Allow user to switch between 'Grouped' and

# 'Stacked' mode.chart.multibar.groupSpacing(0.1) # Distance between each group of

# bars.chart.xaxis.tickFormat("d3.format(',f')")chart.yaxis.tickFormat("d3.format(',.1f')")

data_supplier = nvd3.StaticDataSupplier(example_data())nvd3.Container(chart, data_supplier, width=600, height=400)


http://nvd3.org/examples/multiBar.html


3.2 Django integration

The package includes a Django app to help integrating nvd3_py in Django.

3.2.1 Quick start

1. Add “django_nvd3” to your INSTALLED_APPS settings like this:

INSTALLED_APPS = [..."django_nvd3",

]

2. Load the tags in your template:

{% load nvd3_tags %}

3. Use it.

3.2.2 Reference

django_nvd3.templatetags.nvd3_tags.nvd3_static(use_cdnjs=False)Load the required JavaScript and CSS files.

Usage:

3.2. Django integration 15


<html><head>

...{# serve the static files yourself... #}{% nvd3_static %}{# ...or use cdnjs #}{% nvd3_static use_cdnjs=True %}...

</head><body>

...

django_nvd3.templatetags.nvd3_tags.nvd3_static_data(chart, data, width=500,height=400)

Include the chart in the page with the given data.

Parameters

• chart (nvd3.Chart) – The chart to render.

• data – the data to pass to the chart.

• width – SVG tag width.

• height – SVG tag height.

Usage:

{% nvd3_static_data chart data 400 300 %}

django_nvd3.templatetags.nvd3_tags.nvd3_remote_json(chart, url, width=400,height=500)

Include the chart in the page loading the data from a server.

Parameters

• chart (nvd3.Chart) – The chart to render.

• url (str) – the url where to retrieve the data.

• width – SVG tag width.

• height – SVG tag height.

Usage:

{% nvd3_remote_json chart url 400 300 %}

3.3 References

3.3.1 Base models

_Model

class nvd3._Model(name)This class represent a model in NVS3. A model in NVD3 is an object with some settable options. Theseoptions are callables, to be more correct, they are setters. In python they are setters too: if you normally writechart.showLabels(true) in JavaScript, this become chart.showLabels(True) in Python.



nameThe name of the object. It is in the form myobj for the main objects and in the form myobj.attr forthe attributes.

_option_namesTuple of options that the model supports.

_raw_optionsTuple of raw options that should not be trasformed in some kind of javascript object.

js_options()Returns the JavaScript representation of this model. This representation does not instantiate the object butis a collection of function calls to set the properties of the object.

NVD3 base models

class nvd3.Line(name)Represents a nv.models.line() in NVD3. Available properties:

width

Is raw no.

Type int.

height

Is raw no.

Type int.

definedAllows a line to be not continuous when it is not defined.

Is raw yes.

interpolateSet the interpolation mode. The possible values are listed in the d3’s line.interpolate() documentation.Default: ’linear’.

Is raw no.

Note: As now interpolate accepts only str.

clipEdgeIf True, masks lines within x and y scale.

Is raw no.

marginValid keys are: top, right, bottom and left, values must be ints.

Is raw no.

Type dict.

duration

Is raw no.

isAreaDecides if a line is an area or just a line.

3.3. References 17

https://github.com/d3/d3-3.x-api-reference/blob/master/SVG-Shapes#line_interpolate


Is raw yes.

xAccessor to get the x value from a data point.

Is raw yes.

yAccessor to get the y value from a data point.

Is raw yes.

colorA function that returns a color.

Is raw yes.

class nvd3.Axis(name)Represents a nv.models.axis() in NVD3. Available properties:

axisLabelDistance

Is raw no.

Type int.

staggerLabels

Is raw no.

Type bool.

rotateLabels

Is raw no.

Type int.

rotateYLabel

Is raw no.

Type bool.

showMaxMin

Is raw no.

Type bool.

axisLabel

Is raw no.

Type str.

heightOnly used for tickLabel currently.

Is raw no.

Type int.

ticksControl how ticks are generated for the axis.

Is raw no.

Type int.



widthOnly used for tickLabel currently.

Is raw no.

Type int.

fontSize

Is raw no.

Type str.

marginSee nvd3.Line.margin for a valid format.

Is raw no.

duration

scale

dispatch

isOrdinal

orient

tickValues

tickSubdivide

tickSize

tickPadding

tickFormat

domain

range

rangeBand

rangeBands

class nvd3.Legend(name)Represents a nv.models.legend() in NVD3. Available properties:

•width

•height

•key

•keyFormatter

•align

•maxKeyLength

•rightAlign

•padding

•radioButtonMode

•expanded

•vers

3.3. References 19


•margin

•color

•updateState

class nvd3.Tooltip(name)Represents a nv.models.tooltip() in NVD3. Available properties:

•duration

•gravity

•distance

•snapDistance

•classes

•enabled

•hideDelay

•contentGenerator

•valueFormatter

•headerFormatter

•keyFormatter

•headerEnabled

•position

class nvd3.Focus(name)Represents a nv.models.focus() in NVD3. Available properties:

•width

•height

•showXAxis

•showYAxis

•brushExtent

•margin

•duration

•color

•interpolate

•xTickFormat

•yTickFormat

•x

•y

•rightAlignYAxis

class nvd3.Pie(name)Represents a nv.models.pie() in NVD3. Available properties:

•arcsRadius



•width

•height

•showLabels

•title

•titleOffset

•labelThreshold

•valueFormat

•x

•id

•endAngle

•startAngle

•padAngle

•cornerRadius

•donutRatio

•labelsOutside

•labelSunbeamLayout

•donut

•growOnHover

•margin

•y

•color

•labelType

3.3.2 Charts

class nvd3.ChartChart base class. Instantiate the object and set the various properties.

js()Returns the JavaScript code that create the relative SVG chart. The whole code is enveloped in a functionthat accept the data of the chart and return the chart object.

class nvd3.PieChartRepresents a nv.models.pieChart() in NVD3. Available properties:

•arcsRadius

•width

•height

•showLabels

•title

•titleOffset

3.3. References 21


•labelThreshold

•valueFormat

•x

•id

•endAngle

•startAngle

•padAngle

•cornerRadius

•donutRatio

•labelsOutside

•labelSunbeamLayout

•donut

•growOnHover

•margin

•y

•color

•labelType

class nvd3.LineChartRepresents a nv.models.lineChart() in NVD3. Available properties:

•width

•height

•showLegend

•legendPosition

•showXAxis

•showYAxis

•rightAlignYAxis

•useInteractiveGuideline

•x

•y

•focusEnable

•defaultState

•noData

•focusHeight

•focusShowAxisX

•focusShowAxisY

•brushExtent



•focusMargin

•margin

•duration

•color

•interpolate

•xTickFormat

•yTickFormat

3.3.3 Data suppliers

3.3.4 Containers

3.3. References 23



Index

Symbols_option_names (nvd3._Model attribute), 17_raw_options (nvd3._Model attribute), 17

AaxisLabel (nvd3.Axis attribute), 18axisLabelDistance (nvd3.Axis attribute), 18

CclipEdge (nvd3.Line attribute), 17color (nvd3.Line attribute), 18

Ddefined (nvd3.Line attribute), 17dispatch (nvd3.Axis attribute), 19domain (nvd3.Axis attribute), 19duration (nvd3.Axis attribute), 19duration (nvd3.Line attribute), 17

FfontSize (nvd3.Axis attribute), 19

Hheight (nvd3.Axis attribute), 18height (nvd3.Line attribute), 17

Iinterpolate (nvd3.Line attribute), 17isArea (nvd3.Line attribute), 17isOrdinal (nvd3.Axis attribute), 19

Jjs() (nvd3.Chart method), 21js_options() (nvd3._Model method), 17

Mmargin (nvd3.Axis attribute), 19margin (nvd3.Line attribute), 17

Nname (nvd3._Model attribute), 16nvd3._Model (built-in class), 16nvd3.Axis (built-in class), 18nvd3.Chart (built-in class), 21nvd3.Focus (built-in class), 20nvd3.Legend (built-in class), 19nvd3.Line (built-in class), 17nvd3.LineChart (built-in class), 22nvd3.Pie (built-in class), 20nvd3.PieChart (built-in class), 21nvd3.Tooltip (built-in class), 20nvd3_remote_json() (in module

django_nvd3.templatetags.nvd3_tags), 16nvd3_static() (in module

django_nvd3.templatetags.nvd3_tags), 15nvd3_static_data() (in module

django_nvd3.templatetags.nvd3_tags), 16

Oorient (nvd3.Axis attribute), 19

Rrange (nvd3.Axis attribute), 19rangeBand (nvd3.Axis attribute), 19rangeBands (nvd3.Axis attribute), 19rotateLabels (nvd3.Axis attribute), 18rotateYLabel (nvd3.Axis attribute), 18

Sscale (nvd3.Axis attribute), 19showMaxMin (nvd3.Axis attribute), 18staggerLabels (nvd3.Axis attribute), 18

TtickFormat (nvd3.Axis attribute), 19tickPadding (nvd3.Axis attribute), 19ticks (nvd3.Axis attribute), 18tickSize (nvd3.Axis attribute), 19tickSubdivide (nvd3.Axis attribute), 19

25


tickValues (nvd3.Axis attribute), 19

Wwidth (nvd3.Axis attribute), 18width (nvd3.Line attribute), 17

Xx (nvd3.Line attribute), 18

Yy (nvd3.Line attribute), 18

26 Index

Documents

nvd3 py Documentation - Read the Docs · nvd3_py Documentation, Release 0.1 The goal of this project is to offer a simple API to createNVD3charts. Simple, in this context, means an