pyvoa.front

The user-facing entry point. Importing the module instantiates the front class once and copies every public method of that singleton onto the module itself, so the two spellings below are the same object:

import pyvoa.front as pf

pf.setwhom('owid')          # the module-level name
pf.plot(where='France')

Each method is documented once, on the class. The module-level name is a reference to the same bound method, so help(pf.plot) shows what is written here.

class pyvoa.front.front

Bases: object

The user-facing front end of pyvoa.

Holds the database currently selected, the backend currently chosen and the drawing options kept between calls, and exposes the whole library as methods: setwhom() selects a database, get() queries it, plot(), hist() and map() draw it, and the list*() family says what each argument accepts.

The module instantiates this class once and copies every public method onto itself, so a user writes pf.get(...) rather than building a front of their own. whattodo() prints the whole argument reference in one table.

__init__()

Build the pyvoa front end.

Instantiates the database catalogue and the keyword-argument catalogue, detects which of the three visualisation backends are actually installed, and caches the lists the list*() methods answer with. No database is selected and no backend is chosen at this point: setwhom() and setvis() do that.

whattodo()

Return the table of every argument pyvoa accepts, and of its values.

Puts the selection arguments of get(), plot(), hist() and map() beside the drawing options, each with the values it takes. It is the whole reference the individual list*() methods answer one question of at a time.

Returns:

Indexed by the methods an argument belongs to – the drawing options are gathered under ‘setoptvis’ – with the columns ‘Arguments’ and ‘Available options’, sorted by argument name, descending.

Return type:

pd.DataFrame

setlive(live=True)

Choose where the data are downloaded from.

By default, pyvoa reads every file from a frozen Zenodo archive, so that a given release always returns the same data. Calling setlive(True) switches to the live upstream sources, i.e. the ‘urlparent’ field of the json database description files for the epidemiological data.

The live sources are the most recent ones, but they may have moved, changed format or disappeared. Some datasets have no live source declared; those keep using the archive and a warning is issued.

Parameters:

live (bool) – True to use the live sources, False for the archive.

Returns:

The data source mode which has been set.

Return type:

bool

getlive()

Say whether the live upstream sources are in use.

Returns:

True when the live upstream sources are used, False when the frozen Zenodo archive is.

Return type:

bool

set_verbose_mode(v)

Set how much pyvoa prints.

The verbosity is global to the library: it governs info(), verb(), PyvoaInfo() and PyvoaWarning() wherever they are called, not only the front end.

Parameters:

v (int) – 0 to silence everything, 1 for information and warnings, which is the default, 2 to add the debug output. At verbosity 2 pandas and the standard warnings filter are set back to their default noise; below it, both are quietened.

Returns:

The verbosity which has been set.

Return type:

int

Raises:

PyvoaError – If v is not 0, 1 or 2.

get_verbose_mode()

Return how much pyvoa prints.

Returns:

0 if silent, 1 for information and warnings, 2 for debug.

Return type:

int

setwhom(base, **kwargs)

Select the database the following calls read from.

With reload=True, the default, downloads it, parses it, builds its geography and saves the result as pickles; with reload=False, reads the table, the variables and the locations back from those pickles instead. Either way it then prints the summary get_echoinfo() gives. Asking for the database already selected is not skipped: it is done again, as reload says. This is the call every other one depends on: nothing but listwhom() works before it.

Parameters:

• base (str) – The database to select; listwhom() lists them.

• reload (bool, optional) – True, the default, parses the source again. False reads the pickle of a previous parse instead, without parsing, and fails if the database has never been loaded on this machine. getwhom() with detailed and getwhichinfo(), which read what only the parser knows, parse it then, once.

Raises:

PyvoaError – If reload is not a boolean, or if base is not a database pyvoa knows.

get_echoinfo(dico=None)

Print a summary of the selected database.

Reports the variables it offers, a handful of example locations, and the first and last dates it covers. Output goes through info(), so it is silent unless the verbosity allows it. setwhom() calls it with what it has just parsed or read back.

Parameters:

dico (dict, optional) – ‘lwhich’, the variables; ‘lwhere’, the locations, as listwhere() gives them; ‘mypd’, the parsed table, whose ‘date’ column gives the dates. A ‘reload’ key is accepted and ignored. Left out, the summary is that of the database currently selected.

Raises:

PyvoaError – If called without dico before any database was selected.

listwhere(cluster_and_not=True)

List the locations the current database can be asked for.

Asks the builder of the selected database, whose listwhere describes what a location is for each granularity; when the database was selected with reload=False, returns the list saved with the pickle instead.

Parameters:

cluster_and_not (bool) – If True, the default, return the individual locations and the clusters – names standing for a group of locations, such as a continent. If False, return the clusters only.

Returns:

The locations, sorted.

Return type:

list of str or str

help()

Print the full pyvoa command reference to the terminal.

Delegates to pyvoa.help.display_full_help().

input_wrapper()

Validate and format the input arguments of a chart method.

Ensures the arguments are properly formatted and validated before they reach the decorated function. Transforms ‘where’, ‘which’ and ‘option’ into lists when they are not already, and checks the compatibility of the visualisation options with the function asked for (‘get’, ‘plot’, ‘hist’ or ‘map’).

Parameters:

func (function) – The function to be decorated.

Returns:

The decorated function, with input handling and validation.

Return type:

function

Raises:

PyvoaError – If the input arguments are not properly formatted, or if there are compatibility issues between the visualisation options and the requested function.

input_visuwrapper()

Refuse a chart the requested backend cannot draw.

Checks that the input arguments of the decorated function are compatible with the function asked for, in particular that ‘hist’ and ‘map’ are given a single variable and that a date slider is asked for only under bokeh.

Parameters:

func (function) – The function to be decorated.

Returns:

The decorated function, with input handling and validation.

Return type:

function

Raises:

PyvoaError – If the input arguments are not properly formatted, or if there are compatibility issues between the visualisation options and the requested function.

decoget()

Decorate casting the assembled table to the requested output type.

Reads the ‘output’ keyword and converts the DataFrame the wrapper built into a pandas or geopandas frame, a dict, a list or a numpy array. It decorates get() and plot(); hist() and map() do without it.

get(**kwargs)

Query the current database and return the data as a table.

This is the data-access entry point of pyvoa. It applies the selection described by the keyword arguments to the database chosen with setwhom(), and returns the result in the format asked for by output. plot(), hist() and map() take the same selection arguments and draw the result instead of returning it.

A database must have been selected with setwhom() beforehand, unless a table of your own is passed as input.

Parameters:

• where (str or list of str, optional) – The location(s) to select. Defaults to every location the database holds; listwhere() lists them.

• which (str or list of str, optional) – The variable(s) to read. Defaults to the death count when the database has one – the first of ‘tot_deaths’, ‘total_deaths’, ‘tot_dc’, ‘total_dc’ and ‘tot_dchosp’ it offers – otherwise to its first cumulative variable, named tot_... or total_..., in the order listwhich() gives, and failing that to the first variable of that list.

• what ({'current', 'daily', 'weekly'}, optional) – How the values are reported. Defaults to ‘current’; see listwhat().

• when (str, optional) – A date as dd/mm/yyyy, or a range as dd/mm/yyyy:dd/mm/yyyy. Either side of the range may be left empty.

• option (str or list of str, optional) – One or more of ‘’, ‘nonneg’, ‘smooth7’, ‘sumall’ or ‘normalize:pop…’; see listoption().

• input (pandas.DataFrame, optional) – Read this table instead of the database. It must carry a ‘date’ column, a ‘where’ column and at least one column of data; a ‘code’ column is kept when there is one, but is not required. Selecting on a table of your own sets the current database to ‘in-house data’. when cuts it as it cuts a database, and the table itself is never modified; a frame returned by get() can be passed back.

• output ({'geopandas', 'pandas', 'list', 'dict', 'array'}, optional) – The type to return. Defaults to ‘geopandas’; see listoutput(). A table with no geometry to speak of – one read from input, or a database whose geography could not be resolved – comes back as a plain pandas frame whatever this says.

Returns:

The selected data, in the type named by output. The columns are ‘date’, ‘where’, ‘code’ when the source carries one, then one column per variable of which, named after it and suffixed with the options applied (‘tot_deaths smooth7’, say); ‘geopandas’ adds the ‘geometry’ column, and the other four types drop it. ‘dict’ is a to_dict('split'), so it holds ‘index’, ‘columns’ and ‘data’; ‘list’ is a list of rows and ‘array’ the equivalent numpy array.

Return type:

pandas.DataFrame or geopandas.GeoDataFrame or list or dict or numpy.ndarray

Raises:

PyvoaError – If no database has been selected and no input was given, if input is not a DataFrame or lacks its ‘date’, ‘where’ or data column, if a keyword or one of its values is not recognised, if a location asked for in where is absent from the database, or if typeofplot or typeofhist is passed, both belonging to plot() and hist().

Notes

The signature above is the one this method answers to, not the one written in the source below it: the decorators consume these keyword arguments and hand the undecorated body the assembled table. whattodo() lists every argument together with the values it accepts.

Location names are returned whole: the cut to maxlettersdisplayed is made for the chart labels of plot(), hist() and map() only. For the two frame outputs, ‘where’ is an ordered Categorical, ranked by the value each location reaches on the last date selected, which is the order the charts draw in.

decomap()

Decorate preparing the geometry a map is drawn from.

Settles ‘typeofmap’ against the database: a national one (‘not dense’ by default) may be drawn dense or not, while a world-wide one has no such choice and is forced back to None. Then hands the geometry to the backend and shows the map it returns.

decohist()

Decorate building a histogram and handing it on to be shown.

Merges the stored drawing options into the call, drops the geometry column that bokeh has no use for, and asks the backend for the figure. The single-variable rule is enforced earlier, in input_visuwrapper.

map(**kwargs)

Draw the selected data on a choropleth map.

Selects data exactly as get() does, then renders it geographically with the current visualisation backend. Like hist(), it takes a single variable. setvis() must have chosen a backend first, and setwhom() a database whose geography is known.

Parameters:

• where (str or list of str, optional) – The location(s) to select. Defaults to every location the database holds; listwhere() lists them.

• which (str or list of str, optional) – The variable(s) to read. Defaults to the death count when the database has one – the first of ‘tot_deaths’, ‘total_deaths’, ‘tot_dc’, ‘total_dc’ and ‘tot_dchosp’ it offers – otherwise to its first cumulative variable, named tot_... or total_..., in the order listwhich() gives, and failing that to the first variable of that list.

• what ({'current', 'daily', 'weekly'}, optional) – How the values are reported. Defaults to ‘current’; see listwhat().

• when (str, optional) – A date as dd/mm/yyyy, or a range as dd/mm/yyyy:dd/mm/yyyy. Either side of the range may be left empty.

• option (str or list of str, optional) – One or more of ‘’, ‘nonneg’, ‘smooth7’, ‘sumall’ or ‘normalize:pop…’; see listoption().

• input (pandas.DataFrame, optional) – Read this table instead of the database. It must carry a ‘date’ column, a ‘where’ column and at least one column of data; a ‘code’ column is kept when there is one, but is not required. Selecting on a table of your own sets the current database to ‘in-house data’. when cuts it as it cuts a database, and the table itself is never modified; a frame returned by get() can be passed back.

• typeofmap (str or list of str, optional) – How the geography is drawn, among ‘not dense’, ‘dense’ and ‘show_values’; listmap() lists them. ‘show_values’ writes the value of each location on the map, at a point that always lies inside its shape, with three significant figures: plainly between 0.001 and 999 (570, 0.0123), in scientific notation otherwise (5.49×10⁷), on both backends. A location with no value, no geometry of its own, or outside the visible extent, is left unlabelled. It combines with the other values in a list, as in typeofmap=['dense', 'show_values'].

• tile ({'openstreet', 'esri'}, optional) – The background tiles; listtile() lists them. Defaults to ‘openstreet’ (OpenStreetMap), the first of them, under bokeh and matplotlib alike. A dense map is drawn without tiles.

• projection ({'eckert4', 'mercator'}, optional) – listprojection() lists them. Under matplotlib, the projection of the map: ‘eckert4’, the default, is equal-area, so that a surface reads as what it is, and centred on the data for a national map; the tiles are reprojected onto it, and stop at the 180th meridian, beyond which they do not exist. ‘mercator’ is Web Mercator. Bokeh, whose tiles exist in Web Mercator only, always draws Mercator and ignores it.

• vis ({'matplotlib', 'bokeh', 'seaborn'}, optional) – The backend to draw with; listvis() gives the ones actually installed.

• title (str, optional) – The text drawn on the figure.

• copyright (str, optional) – The text drawn on the figure.

• mode ({'mouse', 'vline', 'hline'}, optional) – The hover mode.

• guideline (bool, optional) – Whether to draw the guide lines.

• scale ({'linear', 'log'}, optional) – The scale of the value axis. Defaults to ‘linear’.

• maxlettersdisplayed (int, optional) – Length past which a location name is cut in the labels, legends and tooltips of the chart, followed by ‘…’; 20 by default, 5 at least. Two names cut to the same label keep their full length. The data themselves are not affected: get() returns the names whole.

• maxcountrydisplayed (int, optional) – How many locations the chart shows at most; 12 by default. The time series and the histograms by location keep that many; the pie charts and the histograms by value gather the others into a ‘SumOthers’ slice. Must be a positive integer.

• pyvoalogo (bool, optional) – Stamp the pyvoa logo on the figure. Defaults to False.

• return_pltaxis (bool, optional) – Under matplotlib, return the axes the chart was drawn on, the default, rather than None. The other backends ignore it.

• dateslider (bool, optional) – Add a slider over the dates. Bokeh only.

Returns:

Under matplotlib, the axes of the map, or None if return_pltaxis is False; under bokeh, None. Either way the map is shown, unless setbatch() was called, and kept for savefig(); a bokeh figure is not returned, so that a notebook does not print it a second time.

Return type:

object

Raises:

PyvoaError – If no backend has been set up, if which names more than one variable, if dateslider is asked for outside bokeh, if a keyword or one of its values is not recognised, or if typeofplot or typeofhist is passed, both belonging to plot() and hist().

Notes

The signature above is the one this method answers to, not the one written in the source below it: the decorators consume these keyword arguments and hand the undecorated body the map it has built. whattodo() lists every argument together with the values it accepts.

hist(**kwargs)

Draw the selected data as a histogram or a pie chart.

Selects data exactly as get() does, then renders it with the current visualisation backend instead of returning it. Unlike plot(), it takes a single variable. setvis() must have chosen a backend first, and setwhom() a database.

Parameters:

• where (str or list of str, optional) – The location(s) to select. Defaults to every location the database holds; listwhere() lists them.

• which (str or list of str, optional) – The variable(s) to read. Defaults to the death count when the database has one – the first of ‘tot_deaths’, ‘total_deaths’, ‘tot_dc’, ‘total_dc’ and ‘tot_dchosp’ it offers – otherwise to its first cumulative variable, named tot_... or total_..., in the order listwhich() gives, and failing that to the first variable of that list.

• what ({'current', 'daily', 'weekly'}, optional) – How the values are reported. Defaults to ‘current’; see listwhat().

• when (str, optional) – A date as dd/mm/yyyy, or a range as dd/mm/yyyy:dd/mm/yyyy. Either side of the range may be left empty.

• option (str or list of str, optional) – One or more of ‘’, ‘nonneg’, ‘smooth7’, ‘sumall’ or ‘normalize:pop…’; see listoption().

• input (pandas.DataFrame, optional) – Read this table instead of the database. It must carry a ‘date’ column, a ‘where’ column and at least one column of data; a ‘code’ column is kept when there is one, but is not required. Selecting on a table of your own sets the current database to ‘in-house data’. when cuts it as it cuts a database, and the table itself is never modified; a frame returned by get() can be passed back.

• typeofhist ({'location', 'value', 'pie'}, optional) – The kind of histogram. Defaults to ‘location’; listhist() lists them.

• bins (int, optional) – The number of bins. Defaults to 10.

• orientation ({'horizontal', 'vertical'}, optional) – The direction the bars run in.

• vis ({'matplotlib', 'bokeh', 'seaborn'}, optional) – The backend to draw with; listvis() gives the ones actually installed.

• title (str, optional) – The text drawn on the figure.

• copyright (str, optional) – The text drawn on the figure.

• mode ({'mouse', 'vline', 'hline'}, optional) – The hover mode.

• guideline (bool, optional) – Whether to draw the guide lines.

• scale ({'linear', 'log'}, optional) – The scale of the value axis. Defaults to ‘linear’.

• maxlettersdisplayed (int, optional) – Length past which a location name is cut in the labels, legends and tooltips of the chart, followed by ‘…’; 20 by default, 5 at least. Two names cut to the same label keep their full length. The data themselves are not affected: get() returns the names whole.

• maxcountrydisplayed (int, optional) – How many locations the chart shows at most; 12 by default. The time series and the histograms by location keep that many; the pie charts and the histograms by value gather the others into a ‘SumOthers’ slice. Must be a positive integer.

• pyvoalogo (bool, optional) – Stamp the pyvoa logo on the figure. Defaults to False.

• return_pltaxis (bool, optional) – Under matplotlib, return the axes the chart was drawn on, the default, rather than None. The other backends ignore it.

• dateslider (bool, optional) – Add a slider over the dates. Bokeh only.

Returns:

Under matplotlib, the axes of the chart, or None if return_pltaxis is False; under bokeh, None. Either way the chart is shown, unless setbatch() was called, and kept for savefig(); a bokeh figure is not returned, so that a notebook does not print it a second time.

Return type:

object

Raises:

PyvoaError – If no backend has been set up, if which names more than one variable, if a keyword or one of its values is not recognised, or if typeofplot is passed, which belongs to plot().

Notes

The signature above is the one this method answers to, not the one written in the source below it: the decorators consume these keyword arguments and hand the undecorated body the figure it has built. whattodo() lists every argument together with the values it accepts.

decoplot()

Decorate preparing the data of a time-series plot.

Reads ‘typeofplot’, refuses ‘versus’ with more than two variables, and merges the stored drawing options into the call.

plot(**kwargs)

Draw the selected data as a time series.

Selects data exactly as get() does, then renders it with the current visualisation backend instead of returning it. setvis() must have chosen a backend first, and setwhom() a database.

Parameters:

• where (str or list of str, optional) – The location(s) to select. Defaults to every location the database holds; listwhere() lists them.

• which (str or list of str, optional) – The variable(s) to read. Defaults to the death count when the database has one – the first of ‘tot_deaths’, ‘total_deaths’, ‘tot_dc’, ‘total_dc’ and ‘tot_dchosp’ it offers – otherwise to its first cumulative variable, named tot_... or total_..., in the order listwhich() gives, and failing that to the first variable of that list.

• what ({'current', 'daily', 'weekly'}, optional) – How the values are reported. Defaults to ‘current’; see listwhat().

• when (str, optional) – A date as dd/mm/yyyy, or a range as dd/mm/yyyy:dd/mm/yyyy. Either side of the range may be left empty.

• option (str or list of str, optional) – One or more of ‘’, ‘nonneg’, ‘smooth7’, ‘sumall’ or ‘normalize:pop…’; see listoption().

• input (pandas.DataFrame, optional) – Read this table instead of the database. It must carry a ‘date’ column, a ‘where’ column and at least one column of data; a ‘code’ column is kept when there is one, but is not required. Selecting on a table of your own sets the current database to ‘in-house data’. when cuts it as it cuts a database, and the table itself is never modified; a frame returned by get() can be passed back.

• typeofplot ({'date', 'compare', 'versus', 'spiral', 'yearly'}, optional) – The kind of plot. Defaults to ‘date’; listplot() lists them. ‘compare’ and ‘spiral’ are bokeh only, and ‘versus’ takes exactly two variables.

• vis ({'matplotlib', 'bokeh', 'seaborn'}, optional) – The backend to draw with; listvis() gives the ones actually installed.

• title (str, optional) – The text drawn on the figure.

• copyright (str, optional) – The text drawn on the figure.

• mode ({'mouse', 'vline', 'hline'}, optional) – The hover mode.

• guideline (bool, optional) – Whether to draw the guide lines.

• scale ({'linear', 'log'}, optional) – The scale of the value axis. Defaults to ‘linear’.

• maxlettersdisplayed (int, optional) – Length past which a location name is cut in the labels, legends and tooltips of the chart, followed by ‘…’; 20 by default, 5 at least. Two names cut to the same label keep their full length. The data themselves are not affected: get() returns the names whole.

• maxcountrydisplayed (int, optional) – How many locations the chart shows at most; 12 by default. The time series and the histograms by location keep that many; the pie charts and the histograms by value gather the others into a ‘SumOthers’ slice. Must be a positive integer.

• pyvoalogo (bool, optional) – Stamp the pyvoa logo on the figure. Defaults to False.

• return_pltaxis (bool, optional) – Under matplotlib, return the axes the chart was drawn on, the default, rather than None. The other backends ignore it.

• dateslider (bool, optional) – Add a slider over the dates. Bokeh only.

Returns:

Under matplotlib, the axes of the chart, or None if return_pltaxis is False; under bokeh, None. Either way the chart is shown, unless setbatch() was called, and kept for savefig(); a bokeh figure is not returned, so that a notebook does not print it a second time.

Return type:

object

Raises:

PyvoaError – If no backend has been set up, if ‘versus’ is asked for with other than two variables, if a keyword or one of its values is not recognised, or if typeofhist is passed, which belongs to hist().

Notes

The signature above is the one this method answers to, not the one written in the source below it: the decorators consume these keyword arguments and hand the undecorated body the figure it has built. whattodo() lists every argument together with the values it accepts.

setnamefunction(name)

Record which method produced the last result.

Parameters:

name (callable) – The method being run; only its name is kept. savefig() reads it back, to refuse to save a table as if it were a figure.

getnamefunction()

Return the name of the method that produced the last result.

Returns:

‘get’, ‘plot’, ‘hist’ or ‘map’, or None if none has been called yet.

Return type:

str or None

listoutput()

List the types get() can return.

Returns:

The values ‘output’ accepts, the first of which is the default.

Return type:

list of str

listvis()

List the backends the charts can be drawn with.

Returns:

Those of ‘matplotlib’ and ‘bokeh’ that are installed. Seaborn is dropped from the list here, and stays dropped for the rest of the session, even when the package is installed.

Return type:

list of str

listmap()

List the map types available.

Returns:

the values ‘typeofmap’ accepts. ‘folium’ is left out: it is selected through map(typeofmap=’folium’) but is not a rendering mode of the other backends.

Return type:

list

listwhom(detailed=False)

List the databases pyvoa ships.

Parameters:

detailed (bool, optional) – If True, describe each database rather than only naming it. Defaults to False.

Returns:

The database names, sorted; or, if detailed, a DataFrame indexed by them, with their ‘iso3’ code and their ‘granularity’. Their variables are not listed: they are only known once a database is parsed, see listwhich().

Return type:

list of str or pandas.DataFrame

listwhat()

List the ways a variable can be reported.

Returns:

The values ‘what’ accepts: ‘current’ for the value as the database gives it, ‘daily’ and ‘weekly’ for its variation over that span.

Return type:

list of str

listchart()

List the charts the current backend can draw.

Returns:

the plot, histogram and map types supported by the backend chosen with setvis(), indexed by method name.

Return type:

pd.Series

Raises:

PyvoaError – if no backend has been set.

listhist()

List the histogram types the current backend can draw.

Returns:

The values ‘typeofhist’ accepts under the backend chosen with setvis().

Return type:

list of str

Raises:

PyvoaError – If no backend has been set.

listplot()

List the plot types the current backend can draw.

Returns:

The values ‘typeofplot’ accepts under the backend chosen with setvis(). They are not the same for every backend: bokeh draws ‘compare’ and ‘spiral’, the others do not.

Return type:

list of str

Raises:

PyvoaError – If no backend has been set.

listoption()

List the transformations ‘option’ can apply to a variable.

Returns:

‘nonneg’, ‘smooth7’, ‘sumall’ and the ‘normalize:pop…’ scales. The empty option, which is the default and does nothing, is left out.

Return type:

list of str

listargument()

List the selection keywords.

Returns:

The arguments get(), plot(), hist() and map() all take: ‘where’, ‘option’, ‘which’, ‘what’, ‘when’, ‘input’ and ‘output’. listargumentvalue() gives what each one accepts.

Return type:

list of str

listargumentvalue()

List the values each selection keyword accepts.

Returns:

One entry per keyword of listargument(), in the same order. A keyword with a fixed set of values – ‘option’, ‘what’, ‘output’ – carries that set, its default first; one taking free-form input – ‘where’, ‘which’, ‘when’, ‘input’ – carries only the empty value standing for its default.

Return type:

list

listtile()

List the background tiles a map can be drawn on.

Returns:

The values ‘tile’ accepts.

Return type:

list of str

Raises:

PyvoaError – If no backend has been set, or if the current backend draws no map at all.

listprojection()

List the projections a map can be drawn in.

Returns:

The values ‘projection’ accepts, the default first: ‘eckert4’, an equal-area projection, then ‘mercator’. Under bokeh, whose tiles exist in Web Mercator only, a map is always drawn in Mercator, and the list is [‘mercator’].

Return type:

list of str

Raises:

PyvoaError – If no backend has been set, or if the current backend draws no map at all.

listwhich()

List the variables the current database offers.

Asks the builder of the selected database; when it was selected with reload=False, returns the list saved with the pickle instead.

Returns:

The values ‘which’ accepts. Beware that the default of ‘which’ is not necessarily the first of them, as get() describes.

Return type:

list of str

listpop()

List the population scales ‘option’ can normalise by.

Returns:

The ‘normalize:pop’ option and its per-100, per-1000, … variants, each dividing the variable by the population of the location at that scale.

Return type:

list of str

getwhom(db=None, detailed=False, return_error=True)

Return the database currently selected.

Parameters:

• db (str, optional) – Print the catalogue entry of this database instead of reporting the current one, and return None. Only has an effect together with detailed.

• detailed (bool, optional) – Also print the ISO3 code, the granularity and the variables of the database. Defaults to False.

• return_error (bool, optional) – Whether the absence of a selected database is an error. True, the default, raises; False returns None instead.

Returns:

The name of the current database.

Return type:

str or None

Raises:

PyvoaError – If no database has been selected and return_error is True.

getdbmetadata(db=None)

Return the JSON description of a database.

Parameters:

db (str) – the database to describe. Defaults to the one selected with setwhom().

Returns:

its metadata – geography, datasets, urls and columns.

Return type:

dict

Raises:

PyvoaError – if db is not a known database, or if none was given and none has been selected.

getwhichinfo(which=None)

Describe one variable of the current database, or all of them.

Parameters:

which (str, optional) – The variable to describe. Its definition and the url it was parsed from are printed, and nothing is returned. Left out, the description of every dataset of the database is returned instead.

Returns:

The description of the database, or None when which was given.

Return type:

pandas.DataFrame or None

Raises:

PyvoaError – If which is not a variable of the current database.

getdatabase()

Return the whole database, as parsed, for every location and variable.

The table get() selects from, before any selection: this is the raw material, not a query. When the database was selected with reload=False, the table saved with the pickle is returned, with a warning.

Returns:

Every variable of the current database, for every location and date.

Return type:

pandas.DataFrame

setkwargsvisu(**kwargs)

Keep drawing options to apply to the charts that follow.

Calling it again adds to the options already kept rather than replacing them, and an option given as empty or False is ignored, so that a stored value can never be unset this way.

Parameters:

**kwargs – Any of the drawing options whattodo() lists under ‘setoptvis’.

getkwargsvisu()

Return the drawing options set by setkwargsvisu().

Returns:

the stored options, or None if none have been set.

Return type:

dict

setvis(vis=' ')

Choose the backend the charts are drawn with.

plot(), hist() and map() refuse to draw until this has been called once.

Parameters:

vis (str) – The backend to draw with. listvis() gives the ones actually installed, among ‘matplotlib’, ‘bokeh’ and ‘seaborn’.

Raises:

PyvoaError – If that backend is not among the installed ones.

Examples

>>> pv.setvis('matplotlib')

setbatch()

Stop the charts from being shown as they are built.

In batch mode the chart methods return their figure without displaying it, which is what a script writing files rather than driving a notebook wants.

getvis()

Return the backend the charts are drawn with.

Returns:

The backend set by setvis(), or None while none has been chosen.

Return type:

str or None

saveoutput(**kwargs)

Save output to a specified format.

This method saves a pandas DataFrame to a file in the specified format. It requires a pandas DataFrame to be provided and allows for customization of the save format and file name.

Parameters:

**kwargs – Keyword arguments that can include: - pandas (pd.DataFrame): The DataFrame to save. This is mandatory. - saveformat (str): ‘excel’ or ‘csv’. Default is ‘excel’. - savename (str): The file name, without its extension. Left empty, it defaults to ‘pyvoa_out’, so the file is written as pyvoa_out.xlsx or pyvoa_out.csv.

Raises:

PyvoaError – If the provided DataFrame is empty, if mandatory arguments are not provided, if the format is neither ‘excel’ nor ‘csv’, or if no database has been selected yet with setwhom().

Notes

The dates of the table given are written as dd/mm/yyyy strings, and that conversion is made on the table itself, not on a copy: the frame you pass comes back with its ‘date’ column turned to text. Pass a copy to keep it usable afterwards.

savefig(name)

Save the last chart drawn to a file.

Parameters:

name (str) – The file to write. Under bokeh the chart is an html page and ‘.html’ is appended; the other backends write the image format the extension asks for, the figure trimmed to its content.

Raises:

PyvoaError – If the last call was get(), whose result is a table and belongs to saveoutput() instead.

Module-level helpers

pyvoa.front.getversion()

Return the installed pyvoa version, for the welcome message.

Imports pyvoa.__version__ lazily and falls back to ‘unknown’ rather than raising, so that a broken or partial installation still prints a banner instead of failing at import time.

Returns:

the version, or ‘unknown’.

Return type:

str