Skip to main content

ncvue: A minimal GUI for a quick view of netcdf files, aiming to be a drop-in replacement for ncview and panoply

Project description

A minimal GUI for a quick view of netCDF files. Aiming to be a drop-in replacement for ncview and panoply.

Zenodo DOI PyPI version Conda version License Build status

About ncvue

ncvue is a minimal GUI for a quick view of netCDF files. It is aiming to be a drop-in replacement for ncview and panoply, being slightly more general than ncview targeting maps but providing animations, zooming and panning capabilities unlike panoply. If ncvue is used with maps, it supports mostly structured grids, more precisely the grids supported by cartopy.

ncvue is a Python script that can be called from within Python or as a command line tool. It is not supposed to produce publication-ready plots but rather provide a quick overview of the netCDF file(s).

The complete documentation for ncvue is available from:

https://mcuntz.github.io/ncvue/

Installation

ncvue is an application written in Python. If you have Python installed, then the best is to install ncvue within the Python universe. The easiest way to install ncvue is thence via pip:

pip install ncvue

or using Conda:

conda install -c conda-forge ncvue

ncvue uses CustomTkinter if it is installed. CustomTkinter is not on Conda. ncvue can also use xarray to open netCDF files if it is installed. If you also want to open multiple files with xarray (xarray.open_mfdataset), dask needs to be installed.

pip install dask xarray customtkinter

or:

conda install -c conda-forge dask xarray

Sometimes tkinter is not enabled in the system’s Python version. One has to do, for example, sudo apt install python3-tk on Linux or brew install python3 python-tk on macOS with Homebrew.

We also provide standalone macOS applications that come with everything needed to run ncvue including Python:

and a tentative Windows installer (to be checked):

ncvue 4.0 should work from macOS 10.13 (High Sierra) onward on Intel processors. ncvue > 5.0 is either for Intel processors or for Apple Silicon (ARM) chips. It comes in the standard Aqua look or uses the CustomTkinter UI-library. The apps > v5.0 are notarized by Apple and might take a short while on first opening.

Quick usage guide

ncvue can be run from the command line:

ncvue
ncvue netcdf_file.nc
ncvue netcdf_file1.nc netcdf_file2.nc

A new netCDF file can be opened from within ncvue using the buttons Open File or Open xarray.

ncvue analyses the netCDF file looking for unlimited dimensions, longitude, latitude, and treats datetime variables. If several files are given, they are treated the same as groups in a netCDF file.

One can set another missing value on the command line on top of the _FillValue and missing_value attributes:

ncvue -m '-9999' netcdf_file.nc

The command line option -h gives a quick usage message.

One can also use xarray to open the netCDF file(s) using the command line option -x

ncvue -x netcdf_file.nc

If several files are given with -x, then xarray.open_mfdataset is used to open the files as a single dataset:

ncvue -x netcdf_file1.nc netcdf_file2.nc

ncvue can be called from within Python:

from ncvue import ncvue
ncvue(['netcdf_file.nc'])

The netCDF has to be given in a list within Python.

Note, ncvue uses the TkAgg backend of matplotlib. It must be called before any other call to matplotlib. This also means that you cannot launch it from ipython –pylab. It can be called from within a standard iPython, though, or using ipython –gui tk.

General layout

On opening, ncvue presents three panels for different plotting types: Scatter or Line plots, Contour plots, and Maps. This is the look in macOS light mode:

Graphical documentation of ncvue layout

All three panes are organised in this fashion: the plotting canvas, the Matplotlib navigation toolbar and the pane, where one can choose the plotting variables and dimensions, as well as plotting options. You can always choose another panel on top, and open another, identical window for the same netCDF file(s) with the button “New Window” on the top right.

If CustomTkinter is installed, then the general layout looks like:

ncvue layout with CustomTkinter in light mode

or in dark mode:

ncvue layout with CustomTkinter in dark mode

CustomTkinter does not work well with Conda.

Map panel

If ncvue detects latitude and longitude variables with a size greater than 1, it opens the Map panel by default. This is the Map panel on macOS, describing all buttons, sliders, entry boxes, spinboxes, and menus:

Graphical documentation of Map panel

If it happens that the detection of latitudes and longitudes did not work automatically, you can choose the correct variables manually. Or you might also leave the latitudes and longitudes empty, which uses then the indexes, and one can hence display the matrix within the netCDF file(s). You might want to switch off the coastlines in this case.

You might want to switch off the automatically detected “global” option sometimes if your data is on a rotated grid, or if you want to exclude some regions such as below minus -60 °S.

All dimensions can be set from 0 to the size of the dimension-1, to “all”, or to any of the arithmetic operators “mean”, “std” (standard deviation), “min”, “max”, “ptp” (point-to-point amplitude, i.e. max-min), “sum”, “median”, “var” (variance).

Be aware that the underlying cartopy/matplotlib may (or may not) need a long time to plot the data (with the pseudocolor ‘mesh’ option) if you change the central longitude of the projection to anything else than the central longitude of your data, which is automatically detected if “central lon” is set to None. Setting “central lon” to the central longitude of the input data normally eliminates the problem.

Scatter/Line panel

If ncvue does not detect latitude and longitude variables with a size greater than 1, it opens the Scatter/Line panel by default. This is the Scatter/Line panel in macOS dark mode (Aqua look), describing all buttons, sliders, entry boxes, spinboxes, and menus:

Graphical documentation of Scatter/Line panel

The default plot is a line plot with solid lines (line style ‘ls’ is ‘-‘). One can set line style ‘ls’ to None and set a marker symbol (marker), e.g. ‘o’ for circles, to get a scatter plot. A large variety of line styles, marker symbols, and color notations are supported. They are listed in the tooltips that appear if you hove longer than 0.5 s above an entry field.

ncvue builds automatically a datetime variable from the time axis. This is correctly interpreted by the underlying matplotlib also when zooming or panning the axes. But it is also much slower than using the index. Leaving x empty uses the index for the x-axis and is very fast. Plotting a line plot with 52608 time points takes about 2.2 s on my MacBook Pro using the datetime variable and about 0.3 s using the index (i.e. empty x-variable). This is especially true if one plots multiple lines with ‘all’ entries from a specific dimension. Plotting all 10 depths of soil water content for the 52608 time points, as in the example below, takes also about 0.3 s if using the index as x-variable but more than 11.1 s when using the datetime variable.

Example of multiple lines in the Scatter/Line panel

Contour panel

The last panel provide by ncvue draws contour plots. This is the Contour panel in macOS dark mode, describing all buttons, sliders, entry boxes, spinboxes, and menus:

Graphical documentation of Contour panel

This produces also either pseudocolor plots (‘mesh’ ticked) or filled contour plots (‘mesh’ unticked) just as the Map panel but without any map projection.

License

ncvue is distributed under the MIT License. See the LICENSE file for details.

Copyright (c) 2020-2025 Matthias Cuntz

ncvue uses CustomTkinter if installed. Otherwise it uses the Azure 2.0 theme by rdbende on Linux and Windows.

Standalone applications are produced with cx_Freeze, currently maintained by Marcelo Duarte.

The project structure of ncvue was very originally based on a template provided by Sebastian Müller but has evolved considerably since.

Different netCDF test files were provided by Juliane Mai.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ncvue-6.1.tar.gz (1.1 MB view details)

Uploaded Source

Built Distribution

ncvue-6.1-py3-none-any.whl (1.1 MB view details)

Uploaded Python 3

File details

Details for the file ncvue-6.1.tar.gz.

File metadata

  • Download URL: ncvue-6.1.tar.gz
  • Upload date:
  • Size: 1.1 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for ncvue-6.1.tar.gz
Algorithm Hash digest
SHA256 f46be0a6d6438a43fe8642bce8340804ac87347c7d1ce47a964f2345488bf5ed
MD5 64e72f3dfb0e7f658fdae6183fd44a20
BLAKE2b-256 3489bd74fbbec300065961a597c10dd164d616c3c68e7be91468d63689c9996c

See more details on using hashes here.

Provenance

The following attestation bundles were made for ncvue-6.1.tar.gz:

Publisher: main.yml on mcuntz/ncvue

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file ncvue-6.1-py3-none-any.whl.

File metadata

  • Download URL: ncvue-6.1-py3-none-any.whl
  • Upload date:
  • Size: 1.1 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for ncvue-6.1-py3-none-any.whl
Algorithm Hash digest
SHA256 3d5c3a73b0f5d3d3f4f1b6d6ac54e4bffc02e44851736d88f4f2141dd4a0ff9a
MD5 9021953d394db56e5176440b7a9636fe
BLAKE2b-256 cd8a7d8f424181b882303b419a5c36942df80408e412218ed35eb7aae62517e0

See more details on using hashes here.

Provenance

The following attestation bundles were made for ncvue-6.1-py3-none-any.whl:

Publisher: main.yml on mcuntz/ncvue

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page