Geographic visualizations for HoloViews

GeoViews is a Python library that makes it easy to explore and visualize geographical, meteorological, and oceanographic datasets, such as those used in weather, climate, and remote sensing research.

GeoViews is built on the HoloViews library for building flexible visualizations of multidimensional data. GeoViews adds a family of geographic plot types based on the Cartopy library, plotted using either the Matplotlib or Bokeh packages. With GeoViews, you can now work easily and naturally with large, multidimensional geographic datasets, instantly visualizing any subset or combination of them, while always being able to access the raw data underlying any plot. Here’s a simple example:

import geoviews as gv
import geoviews.feature as gf
import xarray as xr
from cartopy import crs

gv.extension('bokeh', 'matplotlib')
(gf.ocean + gf.land + gf.ocean * gf.land * gf.coastline * gf.borders).opts(
    'Feature', projection=crs.Geostationary(), global_extent=True, height=325)

GeoViews is designed to work well with the Iris and xarray libraries for working with multidimensional arrays, such as those stored in netCDF files. GeoViews also accepts data as NumPy arrays and Pandas data frames. In each case, the data can be left stored in its original, native format, wrapped in a HoloViews or GeoViews object that provides instant interactive visualizations.

The following example loads a dataset originally taken from iris-sample-data and quickly builds an interactive tool for exploring how the data changes over time:

dataset = gv.Dataset(xr.open_dataset('./data/ensemble.nc'))
ensemble = dataset.to(gv.Image, ['longitude', 'latitude'], 'surface_temperature')

gv.output(ensemble.opts(cmap='viridis', colorbar=True, fig_size=120, backend='matplotlib') * gf.coastline(),
          backend='matplotlib')

GeoViews also natively supports geopandas datastructures allowing us to easily plot shapefiles and choropleths:

import geopandas as gpd
import geodatasets as gds

nybb = gpd.read_file(gds.get_path('nybb'))
poly_data = nybb.to_crs(crs.GOOGLE_MERCATOR.proj4_init)
gv.tile_sources.OSM * gv.Polygons(poly_data, vdims='BoroName', crs=crs.GOOGLE_MERCATOR).opts(height=500, width=500, tools=["hover"])
This web page was generated from a Jupyter notebook and not all interactivity will work on this website. Right click to download and run locally for full Python-backed interactivity.

Please see the User Guide for further documentation.

If you have any issues or wish to contribute code., you can visit our GitHub site or file a topic on the HoloViz Discourse.

Installation#

You can install GeoViews and its dependencies using pip:

pip install geoviews

Alternatively you can use conda to install geoviews:

conda install -c pyviz geoviews

Or, the geoviews-core package, which only installs the minimal dependencies required to run geoviews:

conda install -c pyviz geoviews-core

Once installed you can copy the examples into the current directory using the geoviews command and run them using the Jupyter notebook:

geoviews examples
cd geoviews-examples
jupyter notebook

(Here geoviews examples is a shorthand for geoviews copy-examples --path geoviews-examples && geoviews fetch-data --path geoviews-examples.)

In the classic Jupyter notebook environment and JupyterLab, first make sure to load the gv.extension(). For versions of jupyterlab>=3.0 the necessary extension is automatically bundled in the pyviz_comms package, which must be >=2.0. However note that for version of jupyterlab<3.0 you must also manually install the JupyterLab extension with:

conda install -c conda-forge jupyterlab
jupyter labextension install @pyviz/jupyterlab_pyviz

Once you have installed JupyterLab and the extension launch it with:

jupyter-lab

If you want to try out the latest features between releases, you can get the latest dev release by specifying -c pyviz/label/dev in place of -c pyviz.

Additional dependencies#

If you need to install libraries only available from conda-forge, such as Iris (to use data stored in Iris cubes) or xesmf, you should install from conda-forge:

conda create -n env-name -c pyviz -c conda-forge geoviews iris xesmf
conda activate env-name

Note – Do not mix conda-forge and defaults. I.e., do not install packages from conda-forge into a GeoViews environment created with defaults. If you are using the base environment of mini/anaconda, or an environment created without specifying conda-forge before defaults, and you then install from conda-forge, you will very likely have incompatibilities in underlying, low-level dependencies. These binary (ABI) incompatibilities can lead to segfaults because of differences in how non-Python packages are built between conda-forge and defaults.


GeoViews itself is installable using pip, as long as you’re using cartopy>=0.22.0; otherwise you will first need to have installed the dependencies of cartopy, or have set up your system to be able to build them.