Visualization Control System Principles

VCS Allows scientists to produce highly customized plots. Everything can be precisely and logically controlled.

To download this Jupyter Notebook, right click on the link and choose "Download Linked File As..." or "Save Link as...". Remember where you saved the downloaded file, which should have an .ipynb extension. (You'll need to launch the Jupyter notebook or JupyterLab instance from the location where you store the notebook file.)

In [1]:
# VCS Object definitions
import vcs
import cdms2
import os
vcs.download_sample_data_files()
with cdms2.open(os.path.join(vcs.sample_data,"clt.nc")) as f:
    clt = f("clt")
    u = f("u")
    v = f("v")
with cdms2.open(os.path.join(vcs.sample_data,"sampleCurveGrid4.nc")) as f:
    curv = f("sample")
with cdms2.open(os.path.join(vcs.sample_data,"sampleGenGrid3.nc")) as f:
    gen = f("sample")

x = vcs.init(geometry=(600,400),bg=True)

# Styling for the notebook
from IPython.core.display import HTML
HTML("""
<style>
.output_png {
    display: table-cell;
    text-align: center;
    vertical-align: middle;
}
</style>
""")
Downloading: 'BlueMarble.ppm' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/BlueMarble.ppm
Downloading: 'clt.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/clt.nc
Downloading: 'geo.1deg.ctl' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/geo.1deg.ctl
Downloading: 'geo.1deg.gmp' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/geo.1deg.gmp
Downloading: 'geo.1deg.grb' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/geo.1deg.grb
Downloading: 'meshfill.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/meshfill.nc
Downloading: 'navy_land.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/navy_land.nc
Downloading: 'rlut_CERES_000001-000012_ac.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/rlut_CERES_000001-000012_ac.nc
Downloading: 'sampleCurveGrid4.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sampleCurveGrid4.nc
Downloading: 'sampleGenGrid3.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sampleGenGrid3.nc
Downloading: 'sftbyrgn.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sftbyrgn.nc
Downloading: 'sftlf_10x10.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sftlf_10x10.nc
Downloading: 'sftlf_visus.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sftlf_visus.nc
Downloading: 'so_Omon_ACCESS1-0_historical_r1i1p1_185001-185412_2timesteps.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/so_Omon_ACCESS1-0_historical_r1i1p1_185001-185412_2timesteps.nc
Downloading: 'so_Omon_GISS-E2-R_historicalNat_r5i1p1_185001-187512_2timesteps.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/so_Omon_GISS-E2-R_historicalNat_r5i1p1_185001-187512_2timesteps.nc
Downloading: 'so_Omon_HadGEM2-CC_historical_r1i1p1_185912-186911_2timesteps.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/so_Omon_HadGEM2-CC_historical_r1i1p1_185912-186911_2timesteps.nc
Downloading: 'so_Omon_MPI-ESM-LR_1pctCO2_r1i1p1_185001-185912_2timesteps.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/so_Omon_MPI-ESM-LR_1pctCO2_r1i1p1_185001-185912_2timesteps.nc
Downloading: 'swan.four.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/swan.four.nc
Downloading: 'ta_ncep_87-6-88-4.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/ta_ncep_87-6-88-4.nc
Downloading: 'tas_ccsr-95a.xml' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a.xml
Downloading: 'tas_ccsr-95a_1979.01-1979.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1979.01-1979.12.nc
Downloading: 'tas_ccsr-95a_1980.01-1980.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1980.01-1980.12.nc
Downloading: 'tas_ccsr-95a_1981.01-1981.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1981.01-1981.12.nc
Downloading: 'tas_ccsr-95a_1982.01-1982.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1982.01-1982.12.nc
Downloading: 'tas_ccsr-95a_1983.01-1983.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1983.01-1983.12.nc
Downloading: 'tas_ccsr-95a_1984.01-1984.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ccsr-95a_1984.01-1984.12.nc
Downloading: 'sftlf_ccsr.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sftlf_ccsr.nc
Downloading: 'tas_dnm-95a.xml' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a.xml
Downloading: 'tas_dnm-95a_1979.01-1979.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1979.01-1979.12.nc
Downloading: 'tas_dnm-95a_1980.01-1980.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1980.01-1980.12.nc
Downloading: 'tas_dnm-95a_1981.01-1981.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1981.01-1981.12.nc
Downloading: 'tas_dnm-95a_1982.01-1982.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1982.01-1982.12.nc
Downloading: 'tas_dnm-95a_1983.01-1983.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1983.01-1983.12.nc
Downloading: 'tas_dnm-95a_1984.01-1984.12.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_dnm-95a_1984.01-1984.12.nc
Downloading: 'sftlf_dnm.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/sftlf_dnm.nc
Downloading: 'taylor.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/taylor.nc
Downloading: 'test_anim.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/test_anim.nc
Downloading: 'test_col.asc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/test_col.asc
Downloading: 'testgrib2.ctl' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/testgrib2.ctl
Downloading: 'testgrib2.grib2' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/testgrib2.grib2
Downloading: 'testgrib2.idx' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/testgrib2.idx
Downloading: 'testpp.pp' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/testpp.pp
Downloading: 'thermo.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/thermo.nc
Downloading: 'vertical.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/vertical.nc
Downloading: 'tas_ukmo_con.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ukmo_con.nc
Downloading: 'tas_gavg_rnl_ecm.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_gavg_rnl_ecm.nc
Downloading: 'tas_ecm_1979.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_ecm_1979.nc
Downloading: 'tas_cru_1979.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_cru_1979.nc
Downloading: 'psl_6h.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/psl_6h.nc
Downloading: 'ts_da.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/ts_da.nc
Downloading: 'tas_mo.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_mo.nc
Downloading: 'tas_mo_clim.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_mo_clim.nc
Downloading: 'tas_6h.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/tas_6h.nc
Downloading: 'th_yr.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/th_yr.nc
Downloading: 'th_yr.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/th_yr.nc
Downloading: 'th_yr.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/th_yr.nc
Downloading: 'geos5-sample.nc' from 'https://cdat.llnl.gov/cdat/sample_data/' in: /Users/davis278/miniconda3/envs/cdat81-mesa/share/cdat/sample_data/geos5-sample.nc
Out[1]:

Introduction

Back to Top

Essentially a vcs plot can be broken down into three parts:

WHAT is plotted (e.g data and labels) HOW it is rendered (isolines, boxfill, isofill, vectors, etc...) and WHERE (the location on the page where each element is to be plotted)

What

Back to Top

This is the scientific piece of information that the user is trying to represent for others (or oneself) to understand. It can be as raw as a simple numpy object. It is recommended to use CDMS's transient variables. CDMS transient variables contain metadata such as name, units, and geospatial information that can be used by VCS to better represent the data.

The [tutorials] section has many CDMS examples. The CDMS documentation can be found here.

How

Back to Top

This describes the data representation. At the highest level it is a graphics method i.e boxfill, isofill, vectors, streamlines, line plot, etc., but it also contains information to further control these plot types, e.g. which colors to use, which levels, line thickness, etc.

Graphic methods also describe how axes and labels should be represented (e.g. which axis values to show and which text to use for the values. The user might want to show the -20. longitude represented as 20S or the date 2020-01-15 shown as Jan 2020.

Currently VCS supports the following graphic methods:

Boxfill

Back to Top

Boxfill is used to represent 2-dimensional arrays, filling each array cell with a color representing its value. In the case of rectilinear grids where x and y axes can be represented by a 1-dimensional array, we use the axes bounds to determine the extent of each cell. This is especially useful if an axis is not increasing constantly (e.g. a gaussian grid or pressure levels).

For more information on boxfill, please see the dedicated tutorial.

In [2]:
gm = vcs.createboxfill()
x.plot(clt, gm)
Out[2]:

Isoline

Back to Top

An isoline is a line on a map, chart, or graph that connects points of equal value.

In [3]:
gm = vcs.createisoline()
x.clear()
x.plot(clt,gm)
Out[3]:

Isofill

Back to Top

The isofill graphic method is similar to isolines (and usually plotted in conjounction with it) except that the area between two consecutive isolines is filled with a color representing the range of values in this area.

In [4]:
x.clear()
gm = vcs.createisofill()
x.plot(clt,gm)
Out[4]:

Meshfill

Back to Top

Meshfill is very similar to boxfill, but is used to represent data on generic grids (a.k.a. native representation) based on the input data and a mesh.

In [5]:
x.clear()
gm = x.createmeshfill()
gm.mesh = True
x.plot(gen, gm)
Out[5]:

Streamlines

Back to Top

For more information on streamlines please see the dedicated tutorial.

In [6]:
x.clear()
gm = vcs.createstreamline()
x.plot(u,v,gm)
Out[6]:

Vector Plots

Back to Top

A vector plot is a collection of arrows with a given magnitude and direction, each attached to a point in the plane.

In [7]:
x.clear()
gm = vcs.createvector()
x.plot(u,v, gm)
Out[7]:

Line (1D) Plots

Back to Top

A line plot is a graph that shows the frequency of data along a number line.

For more information on 1D or line plots please see the dedicated tutorial.

Also of interest is the EzPlot Example tutorial.

In [8]:
x.clear()
gm = vcs.create1d()
x.plot(clt[:,34,23])  # extract a time series at one point on the globe and plot it in 1D
Out[8]:

Taylor Diagrams

Back to Top

Taylor diagrams are mathematical diagrams designed to graphically indicate which of several approximate representations (or models) of a system, process, or phenomenon is most realistic.

Please see the Taylor Diagrams tutorial for more information.

Where

Back to Top

Where each element of a plot is located on the page is the most complicated part of VCS but also one of the most powerful. Templates precisely control the location of every component on the plot. For detailed information on templates, please see the VCS Templates tutorial.

Useful Objects

Back to Top

VCS uses the following objects to customize a plot.

Text Objects

Back to Top

Text objects allow you to insert text anywhere on the plot. Text objects are made by combining two different objects: text orientation objects and text table objects.

For more details on text in vcs see this dedicated tutorial.

In [9]:
x.clear()
txt = vcs.createtext()
txt.string="A Text Object"
txt.height=25
txt.x = [.5]
txt.y=[.5]
txt.list()
x.plot(txt)
---------- Text combined (Tc) member (attribute) listings ----------
secondary method = Tc
 ---------- Text Table (Tt) member (attribute) listings ----------
Tt_name = __texttable_716978655205147
font = 1
spacing = 2
expansion = 100
color = [0.0, 0.0, 0.0, 100.0]
fillincolor = 0
priority = 1
string = ['A Text Object']
viewport = [0.0, 1.0, 0.0, 1.0]
worldcoordinate = [0.0, 1.0, 0.0, 1.0]
x = [0.5]
y = [0.5]
projection = default
 ---------- Text Orientation (To) member (attribute) listings ----------
To_name = __textorientation_700637427673277
height = 25
angle = 0
path = right
halign = left
valign = half
Out[9]:

Line/Polygon Objects

Back to Top

Line objects allow you to draw lines on the plot. By closing the line you can draw a polygon.

In [10]:
x.clear()
line = vcs.createline()
line.x = [0.1, .5,  0.9]
line.y = [0.1, .2, 0.9]
x.plot(line)
Out[10]:

Filled Polygon Objects

Back to Top

The filled ploygon object allows you to draw a filled polygon on the plot.

In [11]:
x.clear()
filled = vcs.createfillarea()
filled.x = [0.1, .5,  0.9]
filled.y = [0.1, .2, 0.9]
x.plot(filled)
Out[11]:

Marker Objects

Back to Top

The marker object allows you to draw one or more markers on a plot.

In [12]:
x.clear()
mrk = vcs.createmarker()
mrk.type = "hurricane"
mrk.x = [.5]
mrk.y = [.5]
mrk.size = 15
x.plot(mrk)
Out[12]:

Colormap Objects

Back to Top

Colormap objects are used to control the colors on vcs plots. They can be attached to a secondary object, graphic methods, or canvases.

For more details on existing color maps in VCS see the Color Map tutorial. For information on creating your own colormap, see this tutorial.

Projection Objects

Back to Top

When plotting latitude/longitude plots (2d graphic methods) you can specifiy and control the projection associated with the plot. Projection objects are then attached to the graphic method.

In [13]:
x.clear()
gm = vcs.createisofill()
proj = vcs.createprojection()
proj.type="lambert"
proj.list()
proj.originlatitude=30.
gm.projection = proj
x.plot(clt(latitude=(10,50),longitude=(-130,-70)), gm)
---------- Projection (Proj) member (attribute) listings ----------
secondary method = Proj
name = __projection_688508166476525
type = lambert conformal c
smajor = 1e+20
sminor = 1e+20
standardparallel1 = 1e+20
standardparallel2 = 1e+20
centralmeridian = 1e+20
originlatitude = 1e+20
falseeasting = 1e+20
falsenorthing = 1e+20
Out[13]:

The CDAT software was developed by LLNL. This tutorial was written by Charles Doutriaux. This work was performed under the auspices of the U.S. Department of Energy by Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344.

If you have questions about this notebook, please email our CDAT Support address, cdat-support@llnl.gov.