XrViz¶

An interactive visualisation interface for Xarrays

XrViz is an interactive graphical user interface(GUI) for visually browsing Xarrays. You can view data arrays along various dimensions, examine data values, change color maps, extract series, display geographic data on maps and much more. It is built on Xarray, HvPlot and Panel. It can be used with Intake to ease the process of investigating and loading datasets.

It offers the following functionality:

Quick visualization of xarray data
Customization programatically or interactively via widgets
Mapping of geospatial datasets using Geoviews.
Automatic determination of geospatial coordinates for CF-Convention data using Metpy
Optional aggregation along non-map dimensions (e.g. mean over the time dimension)
Interactive extraction of series plots for non-mapped dimensions (e.g. time series at a point)

Quickstart¶

Installation¶

If you are using Anaconda or Miniconda:

conda install -c conda-forge xrviz

If you are using virtualenv/pip:

pip install xrviz

Note that this will install with the mininum of optional requirements. If you want a more complete install, use conda instead.

If you want to develop:

git clone https://github.com/intake/xrviz
cd xrviz
pip install -e .

Example¶

To open a local or remote data in the interface:

import xarray as xr
from xrviz.dashboard import Dashboard

# open data with xarray
data = xr.tutorial.open_dataset('air_temperature')

# or open remote data with xarray
url = 'http://opendap.co-ops.nos.noaa.gov/thredds/dodsC/NOAA/LOOFS/MODELS/201907/glofs.loofs.fields.forecast.20190720.t06z.nc'
data = xr.open_dataset(url)

# pass the data to Dashboard
dash = Dashboard(data)
dash.show()

Note that dash.show() will open a new tab in browser, while dash.panel is applicable only for a jupyter cell.

You can view the example dashboard by running following in command line (this will open a tab in your browser):

python -c "import xrviz; xrviz.example()"

The above line will initialise the interface, which looks as follows:

Overview¶

The user input section of the interface constitutes of five sub-sections composed of Panel widgets. These sub-sections have been arranged in tabs, each of which has been described in detail in the following sections:

The user can interact with the widgets present in these panes to select desired inputs. Together, they govern the output produced upon pressing the Plot button.

Graphical User Interface¶

The following five panes are part of XrViz’s interface:

Variables¶

This pane displays Xarray variables in the list, with coordinate variables indicated by the graph icon(📈). Attributes for the selected variable and global attributes for the dataset are displayed on the right.

More information about this pane in Display and Describe.

Set_Coords¶

This pane allows the list of data coordinates to be modified by adding or removing variables using the << and >> widgets.

More information about this pane in CoordSetter.

Axes¶

This pane controls which array dimensions should be mapped, how additional dimensions should be handled, and which dimension series plots should be extracted along. The options available in this pane, update upon selection of a new variable.

It has three different sub-sections.

1. Plot Dimensions¶

It has following two selectors:

x: To select which of the available dimensions/coordinates in the data is assigned to the plot’s x (horizontal) axis.
y: To select which of the available dimensions/coordinates in the data is assigned to the plot’s y (vertical) axis.

x selector has both variable dims and coordinates available as options. However, the options available in the y selector depend on the selection for x. If the selection in x is a dimension, y will have remaining dimensions as options. Similarly, for the case when a coordinate has been selected in x, only remaining coordinates will be available in y.

For the data following the CF conventions, the default value of x and y is filled according to guess made using Metpy . In other cases it is filled according to alphabetical order of the available options.

2. Aggregations¶

The remaining dimensions (which have not been selected or present in coordinates selected for x and y) can be aggregated along.

3. Extract Along¶

This selector provides the option to select the dimension along which to create a series graph. The default option is None, with which this feature is disabled. After selecting a dimension and clicking PLOT, the user can click on the main 2D graphical output, and have a graph of the third dimension at that point appear below it. Each click will produce a marker on the main plot and a line in the series graph, which will have same colour as that of the marker. Several lines can be over-plotted. Each line in the series graph displays the value of dimensions/coordinates for which it has been extracted upon hovering over it. Also the series would be extracted in accordance to the values for which main graph has been created. Upon selecting a new dimension to extract along, the previous markers and series graph will clear.

More information about this pane in in Axes.

Note

Clear button is applicable only for series extraction. It clears the markers and series graph when clicked.
Series extraction is independent of aggregation i.e. it is possible to aggregate and extract along a same dimension.

Style¶

This pane provides the options to customize the style of the output graph.

More information about this pane in Style.

Projection¶

This pane provides the option to project the data on a map or cartopy projection in case it is geographical. The geographic plots are created using Geoviews, hence giving the option to visualize geographical, meteorological, and oceanographic datasets.

More information about this pane in Projection.

Command Line Interface¶

The interface can also be launched via command line by:

xrviz show datafile/url

Here datafile or url refers to location of the file. This will open a new tab in the browser, to display the interface.

Set Initial Parameters¶

Users may need to inialize the widgets present in dashboard with custom values instead of the defaults. This could be done by passing initial parametes to the Dashboard upon initialization. All the parametes are passed using the argument initial_params which is of type dict.

The keys present in initial_params must match with the name of the widgets, whose values you want to change. Also the value passed must be present in the available options of that widget. All the keys must be of type str.

Example:

from .sample_data import great_lakes
initial_params = {# Select Variable
                  'Variables': 'temp',

                  # Set Coords
                  'Set Coords': ['lat', 'lon'],

                  # Axes
                  'x': 'lon',
                  'y': 'lat',
                  'sigma': 'animate',

                  # Style
                  'height': 300,
                  'width': 650,
                  'colorbar': True,
                  'cmap': 'Viridis',

                  # Projection
                  'is_geo': True,
                  'basemap': 'OSM',
                  'crs': 'PlateCarree',
                  'projection': 'Orthographic',
                  'crs params': "{'central_longitude': 0.0}",
                  'projection params': "{'central_longitude': -78, 'central_latitude': 43, 'globe': {'ellipse':'sphere'}"
                  }
dash = Dashboard(great_lakes, initial_params=initial_params)
dash.show()

Here crs params and projection params need more attention. The parameter passed to these must be accepted by the selected projection as defined in cartopy projections.

API¶

Variables¶

class xrviz.display.Display(data)¶

Displays a list of data variables for selection.

For each data, its variables are displayed in pn.widgets.MultiSelect. Variables which are data coordinates are annotated with ‘📈’.

Parameters

data: xarray.DataSet

Attributes

panel:: A panel.Row instance which displays the Multiselect widget.

Methods

select_variable(self, variable)

Select a data variable from the available options.

select_variable(self, variable)¶: Select a data variable from the available options.

class xrviz.describe.Describe(data)¶

Displays the properties of the variable selected in the Display section.

This section has two tables as output. The first table shows Variable attributes and the second table shows Global Attributes. Upon selection of a new variable in the Display widget, the first table updates itself with properties of the new selection, while the second table stays same.

Parameters

data: xarray.DataSet

Attributes

panel:: A panel.pane.HTML instance which displays the tables arranged next to each other.

Methods

variable_pane_for_dataset(self, var)

Returns HTML template describing variable and global attributes.

variable_pane_for_dataset(self, var)¶: Returns HTML template describing variable and global attributes.

Set_Coords¶

class xrviz.coord_setter.CoordSetter(data)¶

An input pane for choosing which variables are considered coordinates.

It uses a Cross Selector to display a list of simple and coordinate variables. Simple variables (which are not data coordinates) are available on left side and default coordinates are available on right side. To set variables as coordinates, make selection on left side and click >>. Similarly making selection on right side and clicking << will reset the coordinates. Other panes update themselves accordingly, in response to this change.

Methods

`set_coords`(self, data)	Called when the data attribute of the interface has change in variables considered as coordinates.
`setup_initial_values`(self[, init_params])	To set the variables, whose names have been passed, as coordinates.

set_coords(self, data)¶: Called when the data attribute of the interface has change in variables considered as coordinates.

setup_initial_values(self, init_params={})¶: To set the variables, whose names have been passed, as coordinates.

Axes¶

class xrviz.fields.Fields(data)¶

To select the fields to plot along.

This pane controls which array dimensions should be mapped, how additional dimensions should be handled, and which dimension series plots should be extracted along.

Parameters

data: xarray.DataSet

Attributes

x:

To select which of the available dimensions/coordinates in the data is assigned to the plot’s x (horizontal) axis.

y:

To select which of the available dimensions/coordinates in the data is assigned to the plot’s y (vertical) axis.

Remaining Dims:

Any one of the following aggregations can be applied on each of remaining dimensions:

select: It creates a pn.widgets.Select, to select the value of dimension, for which the graph would be displayed.

animate: It creates a panel.widgets.DiscretePlayer which helps to quickly iterate over all the values for a dimension.

mean: Creates plot along mean of the selected dimension.

max: Creates plot along maximum of the selected dimension.

min: Creates plot along minimum of the selected dimension.

median: Creates plot along median of the selected dimension.

std: Creates plot along standard deviation of the selected dimension.

count: Creates plot along non-nan values of the selected dimension.

Note that for both select and animate, the plot will update according to the value selected in the generated widget. Also, if a dimension has been aggregated, its select widget would not be available.

Extract Along:

This selector provides the option to select the dimension along which to create a series graph.

Methods

`change_dim_selectors`(self, \*args)	Updates the dimensions available for Aggregation and Extract Along upon change in value of `y`.
`change_y`(self[, value])	Updates `y` by removing the value of `x`, from the available options
`check_are_var_coords`(self)	Check if both `x` and `y` are coordinates of the selected variable.
`guess_x_y`(self, var)	To guess the value of `x` and `y` with metpy.parse_cf.
`setup`(self, var)	Fill available options for the selected variable.

change_dim_selectors(self, *args)¶: Updates the dimensions available for Aggregation and Extract Along upon change in value of y.

change_y(self, value=None)¶: Updates y by removing the value of x, from the available options

check_are_var_coords(self)¶: Check if both x and y are coordinates of the selected variable.

guess_x_y(self, var)¶: To guess the value of x and y with metpy.parse_cf. This is applicable only for the case when both x and y are data coordinates.

setup(self, var)¶: Fill available options for the selected variable.

Style¶

class xrviz.style.Style¶

A pane to customise styling of the graphs.

The following options are available in this pane:

height (default 300):
To modify the height of main and series graph.

width (default 700):
To modify the width of the main and series graph.

cmap (default Inferno):
To select a colormap for the main graph.

color_scale (default linear):
To scale the values to be plotted. The scaling options available are linear, exp, log, reciprocal, square and sqrt. Here linear implies no scaling.

cmap limits:
To change the colormap limits. User can fill these limits before plotting a variable. In case not filled by user, automatic filling of limits happen.

lower limit: auto-filled value equals quantile(0.1) of values to be plotted.

upper limit: auto-filled value equals quantile(0.9) of values to be plotted.

In case of dask array, dask.array.percentile is use to compute the limits. tdigest method is used in case crick is present. The value of limits is rounded off to 5 decimal places, for simplicity.

Note that these values are filled with respect to color scaled values. Also these limits clear upon change in variable or color scaling.

compute min/max from all data (default False):

True: all values present in a data variable are used to compute upper and lower colormap limits.

False: only values necessary to create first step/instance of graph are used.

It is better to have its value False for larger datasets, to save computation time.

colorbar (default True):
Provides option to display/hide colorbar.

rasterize (default True):
Provides option to use data shading . It is better to have its value True, to get highly optimized rendering.

Methods

setup_initial_values(self[, init_params])

To select initial values for the widgets in this pane.

setup_initial_values(self, init_params={})¶: To select initial values for the widgets in this pane.

Projection¶

Control¶

class xrviz.control.Control(data)¶

The user input part of the interface

Parameters

data: xarray.DataSet: The data to be visualised. Here, we are mostly concerned with displaying the variables, their attributes, and assigning coordinates to roles upon plotting.

Attributes

1. panel:: A panel.Tabs instance containing the user input panes
2. displayer:: A Display instance, displays a list of data variables for selection.
3. describer:: A Describe instance, describes the properties of the variable selected in the displayer.
4. coord_setter:: A CoordSetter instance for choosing which variables are considered coordinates.
5. fields:: A Fields instance to select the axes to plot with.
6. style:: A Style instance to customise styling of the graphs.
7. projection:: A Projection instance to customise the projection of geographical data.
8. kwargs:: A dictionary gathered from the widgets of the input Panes, of a form which can be passed to the plotting function as kwargs.

Methods

`check_is_projectable`(self, \*args)	Check if the selected variable can be projected geographically.
`set_coords`(self, data)	Called after coordinates have been set, to update the other input panes.

check_is_projectable(self, *args)¶

Check if the selected variable can be projected geographically.

This is possible only when both x and y are present in selected variable’s coordinates.

set_coords(self, data)¶: Called after coordinates have been set, to update the other input panes.

Dashboard¶

class xrviz.dashboard.Dashboard(data, initial_params={})¶

Main entry point to XrViz, an interactive GUI for a given dataset.

Parameters

data: xarray.DataSet: The data to be visualised
initial_params: `dict`: To pre-select values of widgets upon initialization. The keys are generally names of widgets within the input area of the interface. For more details, refer to Set Initial Parameters .

Attributes

1. panel:: A panel.Tabs instance containing the user input panes and output graphs of the interface.
2. control:: A Control instance responsible for input panes (control panel).
3. plot_button:: A pn.widgets.Button that generates graph according to values selected in input panes, upon click.
4. graph:: A HoloViews(DynamicMap) instance containing the main graph.
5. output:: The graph along with the select widgets for index selection.
6. taps_graph:: A holoviews.Points instance to record the location of taps.
7. series_graph:: A HoloViews(Overlay) instance having series extracted.
8. clear_series_button:: A pn.widgets.Button to clear the taps_graph and series_graph.

Methods

`check_is_plottable`(self, var)	Check if a data variable can be plotted.
`clear_series`(self, \*args)	Clears the markers on the image, and the extracted series.
`create_graph`(self, \*args)	Creates a graph according to the values selected in the widgets.
`create_indexed_graph`(self, \*args)	Creates a graph for the dimensions selected in widgets x and y.
`create_selectors_players`(self, graph)	Converts the sliders generated by hvplot into selectors/players.
`create_series_graph`(self, x, y, color[, clear])	Extract a series at a given point, and plot it.
`create_taps_graph`(self, x, y[, clear])	Create an output layer in the graph which responds to taps

check_is_plottable(self, var)¶

Check if a data variable can be plotted.

If a variable is 1-d, disable plot_button for it.

clear_series(self, *args)¶: Clears the markers on the image, and the extracted series.

create_graph(self, *args)¶

Creates a graph according to the values selected in the widgets.

This method is usually invoked by the user clicking “Plot”

It handles the following two cases:

1. Both x, y are present in selected variable’s coordinates. Geographic projection is possible only in this case. It uses create_selectors_players method for creation of the graph. Here the selectors generated automatically by hvplot are used.

2. One or both of x, y are NOT present in selected variable’s coordinates (both x and y are considered as dimensions). It uses create_indexed_graph method for creation of the graph. The selectors are created and linked with graph by XrViz.

create_indexed_graph(self, *args)¶

Creates a graph for the dimensions selected in widgets x and y.

This is used when values selected in x and y are not data coordinates (i.e. one or both values are data dimensions).

create_selectors_players(self, graph)¶

Converts the sliders generated by hvplot into selectors/players.

This is applicable only when both x and y are present in variable coordinates. It converts any sliders generated by hvplot into selectors/players and moves them to the bottom of graph.

create_series_graph(self, x, y, color, clear=False)¶

Extract a series at a given point, and plot it.

The series plotted has same color as that of the marker depicting the location of the tap.

The following cases have been handled:

Case 1:

When both x and y are NOT coords (i.e. are dims)

Case 2:

When both x and y are coords

2a: Both are 1-dimensional

2b: Both are 2-dimensional with same dimensions.

2c: Both are 2-dimensional with different dims or are multi-dimcoordinates. Here we are unable to extract.

Note that Case 1 and Case 2a can be handled with the same code.

create_taps_graph(self, x, y, clear=False)¶

Create an output layer in the graph which responds to taps

Whenever the user taps (or clicks) the graph, a glyph will be overlaid, and a series is extracted at that point.

Example¶

xrviz.example(show=True)¶

Generates interface for the sample dataset.

Parameters

show: bool (True): True: A new browser tab will be opened, and the function will block until interrupted. False: The Dashboard instance is returned without being executed.

XrViz¶

Quickstart¶

Installation¶

Example¶

Overview¶

Graphical User Interface¶

Variables¶

Set_Coords¶

Axes¶

1. Plot Dimensions¶

2. Aggregations¶

3. Extract Along¶

Style¶

Projection¶

Command Line Interface¶

Set Initial Parameters¶

API¶

Variables¶

Set_Coords¶

Axes¶

Style¶

Projection¶

Control¶

Dashboard¶

Example¶

Indices and tables¶