Visualisation backends

Three backends draw the charts, and they do not all offer the same ones: compare and spiral plots and the date slider exist only in bokeh, and seaborn has no map. pyvoa.visualizer.AllVisu routes each request to the right one according to the vis argument.

pyvoa.visu_matplotlib

The matplotlib visualisation backend.

Static charts: the date, versus and yearly plots, the three histogram kinds, and maps. Every figure is created by the decomatplotlib decorator, which also stamps the pyvoa logo on it when ‘pyvoalogo’ is True.

class pyvoa.visu_matplotlib.visu_matplotlib[source]

Bases: object

The matplotlib backend, drawing static charts.

Offers the ‘date’, ‘versus’ and ‘yearly’ plots, the three histogram kinds and maps. Every figure is created by the decomatplotlib decorator, which also stamps the pyvoa logo on it when asked to, so the methods here receive the axes to draw on rather than making them. Each returns those axes, or None when ‘return_pltaxis’ is False.

__init__()[source]

Pick the matplotlib backend that suits the environment.

Chooses the inline backend inside a Jupyter kernel and TkAgg on a plain terminal or an IPython console, falling back to TkAgg if the detection itself fails. Where Tk cannot load, without a display, the backend matplotlib resolved by itself is kept. Doing this at construction keeps the choice out of the drawing methods.

A backend named by the MPLBACKEND environment variable, matplotlib’s own way of asking for one, is left alone. Without that, a script drawing on Agg (to write png files) or the test suite was switched to TkAgg at every chart, and where a display is available each plt.show() then opened a window and waited for it to be closed.

decomatplotlib()[source]

Decorate creating the figure every matplotlib chart draws on.

Builds a 10x5 figure and its axes, sets the title, and, when ‘pyvoalogo’ is True (it is False by default), stamps the pyvoa logo faintly in the background. The figure, its axes and the pyplot module are passed on as the ‘fig’, ‘ax’ and ‘plt’ keyword arguments, so the drawing methods only have to draw.

matplotlib_date_plot(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_versus_plot(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_yearly_plot(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_pie(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_horizontal_histo(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_histo(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

matplotlib_map(**kwargs)[source]: Build the figure, stamp the logo, then call the drawing method.

pyvoa.visu_bokeh

The bokeh visualisation backend.

The most complete of the three backends: the only one offering the compare and spiral plots and the date slider, alongside the plots, histograms and maps the others share. Figures are returned as bokeh objects.

pyvoa.visu_bokeh.safe_output_notebook()[source]

Enable bokeh’s notebook output, but only inside a notebook.

Calling output_notebook() from a plain interpreter emits a warning and achieves nothing, so the environment is detected first and the failure reported through verb() rather than raised.

class pyvoa.visu_bokeh.visu_bokeh[source]

Bases: object

The bokeh backend, drawing interactive charts.

The most complete of the three: it is the only one offering the ‘compare’ and ‘spiral’ plots and the date slider, alongside the plots, histograms and maps the others share. Figures are returned as bokeh objects and shown in the notebook by front.

__init__()[source]

Set the colour cycles and the default figure size.

Category20 gives the twenty colours locations are cycled through, and Category10 the five used where fewer are needed.

static rollerJS()[source]

Return the hover formatter shared by the bokeh charts.

Reads pyvoa/js/rollover_callback.js and wraps it in a CustomJSHover, so that the tooltip formatting lives in a javascript file rather than in a string here.

Returns:: the formatter.
Return type:: CustomJSHover

static pyvoalogo(logo)[source]

Read a logo file and return it as a data: URL.

Embedding the image in the document rather than linking it keeps a saved chart self-contained.

Parameters:: logo (str) – path to the png.
Returns:: a ‘data:image/png;base64,…’ URL.
Return type:: str

deco_bokeh()[source]

Decorate building the bokeh figure a chart is drawn on.

Gives each location a stable colour from the Category20 cycle, then creates the figure and its title, plus the logo watermark when ‘pyvoalogo’ is True (an empty spacer otherwise), and passes them on to the drawing method.

static bokeh_legend(bkfigure)[source]

Make a double-click on the figure hide and show the legend.

Parameters:: bkfigure – the bokeh figure to attach the callback to.

get_listfigures()[source]: Return the figures built by the last call.

set_listfigures(fig)[source]: Record the figures built, wrapping a single one in a list.

bokeh_plot()[source]

Decorate dropping the geometry before a non-map chart is drawn.

The non-map charts have no use for the geometry column. The location names need no work here: AllVisu has already cut them to ‘maxlettersdisplayed’.

bokeh_versus_plot(**kwargs)[source]

Create a versus plot according to arguments.

Parameters:

input (pd.DataFrame) – The table the front end assembled: a ‘date’ column, a ‘where’ column, one column per variable of which, and the ‘colors’ column deco_bokeh adds.
which (list) – Exactly two variables, drawn against each other: the first on the x axis, the second on the y axis.
title (str) – The title of the figure.
mode ({'mouse', 'vline', 'hline'}) – How the hover tool follows the pointer.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type and passes them in, under ‘bokeh_figure_linear’ and ‘bokeh_figure_log’.

bokeh_date_plot(**kwargs)[source]

Create a date plot according to arguments.

Parameters:

input (pd.DataFrame) – The table the front end assembled: a ‘date’ column, a ‘where’ column, one column per variable of which, and the ‘colors’ column deco_bokeh adds.
which (list) – The variable(s) to draw against time, one line per variable and per location.
title (str) – The title of the figure.
mode ({'mouse', 'vline', 'hline'}) – How the hover tool follows the pointer.
guideline (bool) – Whether to draw the guide lines.
scale ({'linear', 'log'}) – The axis type the tab of that name carries.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type and passes them in, under ‘bokeh_figure_linear_date’ and ‘bokeh_figure_log_date’.

bokeh_spiral_plot(**kwargs)[source]

Draw one location’s series as an Archimedean spiral.

Each year is one turn, the day of the year giving the angle, so that seasonality shows up as alignment between successive turns. The value is drawn as a ribbon whose width straddles the baseline. The 29th of February is dropped so that a day number means the same date every year.

Parameters:: **kwargs – the drawing arguments, including ‘input’ (a single location) and ‘which’.
Raises:: PyvoaError – if the selection holds more than one location.

bokeh_menu_plot(**kwargs)[source]

Create a date plot with a scrolling menu of locations.

Requires more than two locations.

Parameters:

input (pd.DataFrame) – The table the front end assembled: a ‘date’ column, a ‘where’ column, one column per variable of which, and the ‘colors’ column deco_bokeh adds.
which (list) – The variable(s) to draw against time. The menu picks the location.
mode ({'mouse', 'vline', 'hline'}) – How the hover tool follows the pointer.
guideline (bool) – Whether to draw the guide lines.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type, titles them and passes them in, under ‘bokeh_figure_linear_date’ and ‘bokeh_figure_log_date’.

bokeh_yearly_plot(**kwargs)[source]

Create a yearly plot according to arguments.

Draws every year of the series on the same twelve-month axis, so that the seasons can be compared.

Parameters:

input (pd.DataFrame) – The table the front end assembled: a ‘date’ column, a ‘where’ column, one column per variable of which, and the ‘colors’ column deco_bokeh adds.
which (list) – The variable(s) to draw, one curve per year.
mode ({'mouse', 'vline', 'hline'}) – How the hover tool follows the pointer.
guideline (bool) – Whether to draw the guide lines.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type, titles them and passes them in, under ‘bokeh_figure_yearly’ and ‘bokeh_figure_yearly_log’.

decodateslider()[source]

Decorate adding a date slider to a chart.

Wires a slider to the figure so the drawn date can be moved through the series. Histograms are not covered: the slider is declined there, with a message. Bokeh only; front refuses ‘dateslider’ for other backends.

bokeh_histo(**kwargs)[source]

Create a 1D histogram by value according to arguments.

Parameters:

input (pd.DataFrame) – The table the front end assembled: a ‘date’ column, a ‘where’ column, one column per variable of which, and the ‘colors’ column deco_bokeh adds.
which (str) – The variable whose values are binned. The visualizer has already reduced a list to its single element by this point.
bins (int) – The number of bins. Defaults to the value declared in the keyword catalogue, ten.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type and passes them in, under ‘bokeh_figure_linear’ and ‘bokeh_figure_loglog’.

bokeh_horizonhisto(**kwargs)[source]

Draw a horizontal bar chart, one bar per location.

Bars are ranked by value and labelled with it. Only maxcountrydisplayed locations are shown at a time, the rest reachable through the widget.

Parameters:: **kwargs – the drawing arguments, including ‘which’, the column data source, and optionally ‘dateslider’.
Return type:: The bokeh figure.

addcolumnshisto(mypd, which, maxcountrydisplayed)[source]

Add the geometry columns a horizontal bar chart needs.

Computes each bar’s left, right, top and bottom edges, and the position and text of its label, so the chart can be drawn from plain rectangles.

Parameters:

mypd (pd.DataFrame) – one row per location.
which (str) – the column holding the value.
maxcountrydisplayed (int) – how many bars fit on screen at once.

Returns:

mypd with the drawing columns added.

Return type:

pd.DataFrame

addcolumnspie(df, column_name)[source]

Add the angle columns a pie chart needs.

Turns each value into its share of the total and into the start and end angles of its wedge.

Parameters:

df (pd.DataFrame) – one row per location.
column_name (str) – the column holding the value.

Returns:

df with ‘percentage’, ‘angle’, ‘starts’ and ‘ends’.

Return type:

pd.DataFrame

bokeh_pie(**kwargs)[source]

Create a pie chart according to arguments.

Parameters:

columndatasrc (bokeh.models.ColumnDataSource) – The slices to draw – one row per location, with its angle, its colour and its share – as the histogram decorator prepared them. This chart is given that source rather than the table itself.
which (str) – The variable whose share each location takes a slice of. The visualizer has already reduced a list to its single element here.
mode ({'mouse', 'vline', 'hline'}) – How the hover tool follows the pointer.
dateslider (bool) – Whether a slider over the dates is drawn beside the chart.
controls (bokeh widgets, optional) – The widgets to lay out beside the chart, the date slider among them.

Notes

The figures themselves and the logo watermark are not arguments a caller provides: deco_bokeh builds one figure per axis type and passes them in, under ‘bokeh_figure_linear’.

bokeh_map(**kwargs)[source]

Draw a choropleth map of one variable.

Colours each location by its value and, unless the map is drawn dense, lays it over the background tiles named by ‘tile’ (‘openstreet’ when none is named). The locations the source says nothing about are drawn in pink, and a location without a geometry of its own is counted but not drawn. The pyvoa logo is laid over the figure only when ‘pyvoalogo’ is True, as on the other charts.

The map is framed on every location, pink ones included, as the matplotlib map is. Its plot frame, not counting the colour bar and the notes below it, keeps the proportions of that extent: its short side is 350 px, unless the long side would then pass 800 px, which is then held at 800 px.

Parameters:

**kwargs – the drawing arguments, including the GeoJSON source, the colour mapper, ‘which’, ‘typeofmap’ and ‘tile’.

Returns:

The bokeh figure holding the map, in a column under the slider when
'dateslider' is asked for, and in a row with the logo when
'pyvoalogo' is.

static bokeh_savefig(fig, name)[source]

Write a bokeh figure to a png file.

Parameters:

fig – the figure to export.
name (str) – the destination file name.

static convert_tile(tilename)[source]: Return tiles url according to folium or bokeh resquested.

pyvoa.visu_seaborn

The seaborn visualisation backend.

Static statistical charts: the date, versus and yearly plots and the three histogram kinds. It has no map, which is why AllVisu refuses map() for this backend. Built on matplotlib, so the figures it returns are matplotlib ones.

class pyvoa.visu_seaborn.visu_seaborn[source]

Bases: object

The seaborn backend, drawing static statistical charts.

Offers the ‘date’, ‘versus’ and ‘yearly’ plots and the three histogram kinds; it has no map, which is why AllVisu refuses map() for this backend. Built on matplotlib, so the figures it returns are matplotlib ones.

__init__()[source]

Pick the matplotlib backend that suits the environment.

Chooses the inline backend inside a Jupyter kernel and TkAgg on a plain terminal or an IPython console, falling back to TkAgg if the detection itself fails.

decoplotseaborn()[source]: Decorate seaborn plot.

decohistseaborn()[source]: Decorate seaborn histogram.

seaborn_date_plot(**kwargs)[source]

Draw one line per location against time.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_yearly_plot(**kwargs)[source]

Draw one curve per calendar year, against the day of the year.

Superimposes the years so their shapes can be compared directly. The 29th of February is dropped, so that a given day number means the same date in a leap year and a common one.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ (a single variable) and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_versus_plot(**kwargs)[source]

Plot one variable against another, rather than against time.

Takes exactly two variables, the first on the x axis and the second on the y axis, one line per location.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ (two variables) and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_hist_value(**kwargs)[source]

Draw the distribution of a variable’s values.

Bins the values themselves, over every location and date selected, rather than showing one bar per location.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_hist_horizontal(**kwargs)[source]

Draw one horizontal bar per location.

The bars are the value each location reaches on the last date selected, sorted; with the ‘sumall’ option every location is summed into one bar.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_pie(**kwargs)[source]

Draw nothing: the seaborn pie chart is not implemented.

The method exists so that the dispatch finds a callable for typeofhist='pie' under this backend, but its body only labels the axes of the empty figure the decorator made. Use bokeh or matplotlib for a pie.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ and the ‘plt’ and ‘sns’ supplied by the decorator.

seaborn_heatmap(**kwargs)[source]

Draw a month-by-year heatmap of a variable.

Pivots the series into months against years and annotates each cell, with the total written under the map. It warns on every call that it has not been checked.

Parameters:: **kwargs – the drawing arguments, including ‘input’, ‘what’ and the ‘plt’ and ‘sns’ supplied by the decorator.

pyvoa.visu_folium

The folium visualisation backend.

Interactive leaflet maps. Only maps are implemented here, folium having no time-series or histogram equivalent, so AllVisu falls back to another backend for plots and histograms. Reached through map(typeofmap='folium').

class pyvoa.visu_folium.visu_folium[source]

Bases: object

The folium backend, drawing interactive leaflet maps.

Only maps are implemented here: folium has no time-series or histogram equivalent, which is why AllVisu falls back to another backend for plot() and hist(). Selected through map(typeofmap=’folium’).

__init__()[source]: Set the size, in pixels, of the figure the maps are drawn in.

folium_map(**kwargs)[source]

Draw a choropleth map of one variable with folium.

Colours each location by its value using a four-stop viridis-like scale between the smallest and the largest value present, greys out the ones with no value, and attaches a tooltip giving the location and its value in scientific notation. The colour bar is relabelled through a snippet of javascript so that its ticks are shown in scientific notation too.

Parameters:: **kwargs – the drawing arguments prepared by AllVisu. - input (gpd.GeoDataFrame): the data to draw, carrying a ‘where’ column, a geometry and the column named by ‘what’. - what (str): the column to colour by. - title (str): the caption of the colour bar.
Returns:: the map, ready to be displayed in a notebook.
Return type:: folium.Map