Panoply

netCDF Visualization Software

v. 1.5.1
 Panoply v. 1.5
by Robert Schmunk
rschmunk@giss.nasa.gov
NASA Goddard Institute for Space Studies
2880 Broadway, New York, NY 10025 USA

Although Panoply was produced at a U.S. Government research institute,

the complete Panoply application cannot be considered public domain be-
cause it includes libraries provided by third parties which have individual
copyrights and licenses.

The following Java libraries and classes are used with permisson under the
GNU Lesser General Public License (http://www.gnu.org/copyleft/lesser.
html):

• netCDF Java library by Unidata

(http://my.unidata.ucar.edu/content/software/netcdf/index.html)
• HTTPClient Java library by Innovation Gmbh
(http://www.innovation.ch/java/HTTPClient/)
• PngEncoder class by J. David Eisenberg
(http://catcode.com/pngencoder/)

We gratefully acknowledge use of the following Java libraries and classes,

used under the terms of a modified General Public License available at the
library website:

GNU JAXP and AElfred2 parser by the GNU Classpath Extensions Project
(http://www.gnu.org/software/classpathx/jaxp/)

We also gratefully acknowledge use of the following Java libraries and

classes:

• QuantizeFilter class by Jerry Huxtable

(http://www.jhlabs.com/ip/)
• JDOM by the JDOM Project
(http://www.jdom.org/)

Source code and compiled Java bytecode for these libraries and classes are
available at the URLs provided.

Additional copies and/or updated versions of Panoply may be downloaded

from http://www.giss.nasa.gov/tools/panoply/.
 Contents
Introduction 1

Contact Information 1

Installation Notes 2

Install and Run Panoply for Mac OS X 2

Install and Run Panoply for Windows 2

Install and Run Panoply “Generic” 3

Quick Start Guide 5

Creating Data Plots in Panoply 5

Datasets and Variables (The Data Browser) 5

The Plot Window 6

The Array(s) Tab 7

The Scale Tab 9

The Colors Tab 9

The Maps Tab/Zonal Grid Tab 11

The Captions Tab 12

The Data Window 13

Plotting Multiple Variables (Difference Plotting) 14

Hint: Choosing the Right Color Bar 15

Creating a Latitude vs. Altitude Plot (Vertical Plot) 16

Special Map Plots (Regional and Vertical Perspective) 17

 Equirectangular Regional Projection 17

Vertical Perspective 18

Exporting Plots 20

Saving Preferences 20

Appendix 1 – netCDF Data Files 21

Coordinate Variables 21

Boundary Variables 22

Relative Time Coordinates 22

Absolute Time Coordinates 23

Special Values 23

Scale Labels 24

Appendix 2 – Colorbars (a.k.a. Palettes or Color Tables) 25

PAL Color Tables 25

PAL-1 Color Tables 26

ACT Color Tables 26

CWC Color Tables 26

Color Table Software 26

Appendix 3 – Map Projections 27

Panoply Software License 35

 Introduction
panoply \PAN-uh-plee\, noun: 1. A splendid or impressive array. ...

Panoply is a Java application that enables the user to plot raster images
of geo-gridded (geo-referenced) data from datasets in netCDF format (see
Appendix 1). Depending on the type of data available, Panoply can be
used to create displays in a variety of ways:

• Plot longitude-latitude data as global maps or zonal averages, using

any of over 40 global map projections
• Overlay continent outlines or masks on longitude-latitude plots, or
just plot a particular region
• Display specific latitude-longitude or latitude-vertical arrays from
larger multidimensional variables as slices

Panoply also functions as a tool for graphical data analysis and reporting
of results by allowing the user to:

• Combine two arrays in one plot by differencing, summing or

averaging
• Use any of the 30 scale colorbars provided (based on PAL, ACT or
CWC color tables), or add a custom colorbar
• Save plots to disk as PNG or GIF images

Your computer must have a Java 1.3 virtual machine or better installed
prior to the installation of Panoply. For the latest version of Java, visit
http://www.java.com.

Contact Information

If you wish to be notified when new versions of Panoply are released, or if

you would like to report a bug, please contact the author at:

Robert B. Schmunk
NASA Goddard Institute for Space Studies
2880 Broadway, New York, NY 10025 USA
rschmunk@giss.nasa.gov

Return to Contents
User’s Guide to Panoply 1
Installation Notes
After uncompressing the Panoply package, you should be able to run it “as
is” from the location where you’ve placed the application.

Install and Run Panoply for Mac OS X

The Panoply package for Mac OS X comes as a StuffIt archive (PanoplyOSX.
sit), which can be uncompressed using the free StuffIt Expander utility
from Allume Systems (http://www.stuffit.com). The package contains a
folder holding the following items:
• Panoply application
• Colorbars (color tables) in a folder called “colorbars”
• Continent masks and outlines in a folder called “overlays”
• Sample netCDF datasets in a folder “sample_data”
• A README file

To run Panoply on Mac OS X, just double-click on the Panoply application.

(Note: Panoply is not compatible with the “classic” Mac OS.)
If you find that Panoply quits immediately when you try to run it for
the first time by double-clicking on its desktop icon, it may be that the
program’s permissions were corrupted when StuffIt Expander opened up
the PanoplyOSX.sit archive. This problem can occur if you have StuffIt 8.0.0
on your machine and have not updated to a later StuffIt 8.0.x version.
Try updating StuffIt and then downloading and installing a fresh Panoply
package.

Install and Run Panoply for Windows

The Panoply package for Windows comes as a zipped archive (PanoplyWin.
zip). You must manually extract this archive, using WinZip, StuffIt Expander
or some other ZIP-compatible program. Some versions of Windows allow
you to run programs from a zipped archive without extraction, but that
won’t work with Panoply.
Extracting the archive creates a folder called “PanoplyWin” which holds the
following items:
• Panoply.exe application
• Java application files in a folder called “jars”
• Colorbars (color tables) in a folder called “colorbars”

2 User’s Guide to Panoply Return to Contents

 • Continent masks and outlines in a folder called “overlays”
• Sample netCDF datasets in a folder “sample_data”
• A README file

To run Panoply, just double-click on the Panoply.exe application.

Windows computers often do not have Java automatically installed. To
ensure that you have an appropriate version of Java on your machine, use
the Sun utility that looks for it on your desktop and automatically downloads
it if necessary. Go to the Java.com website and click on the “Free Download”
button at the top right of the page. Note: It is possible to have a Java plugin
enabled in your web browser that allows you to run applets, but not have a
JRE installed which allows you to run Java applications.
The folder called “jars” must remain in the same location as the Panoply.
exe application. Also, all .jar files in the jars folder must remain there. If
you move or remove that folder or any of its contents, Panoply will not
work.

Install and Run Panoply “Generic”

The “standard” Panoply package comes as either a (a) zipped archive
(PanoplyJ.zip)or (b) tarred and gzipped archive (PanoplyJ.tar.gz), either of
which can be uncompressed by many freeware uncompression utilities.
Both archive types contain a directory, “PanoplyJ”, holding the following
items:
• Java application in a jar file called “Panoply.jar”
• Several other Java “.jar” files
• Sample colorbars (color tables) in a directory called “colorbars”
• Sample continent overlays and outlines in a directory called
“continents”
• Sample netCDF datasets in a directory called “sample_data”
• A README file
On many platforms, you should be able to launch Panoply by double-
clicking on the Panoply.jar file icon. If your computer does not permit that,
you should still be able to launch Panoply from the command line; simply
cd into the directory where Panoply.jar is located and then type java -jar
Panoply.jar
In addition to the Panoply.jar file included in the generic Panoply package,
there are five other Java .jar files. You must keep these in the same directory
as the Panoply.jar file, or Panoply will not run.

Return to Contents
User’s Guide to Panoply 3
4 User’s Guide to Panoply Return to Contents
 Quick Start Guide

Creating Data Plots in Panoply

Once you have Panoply installed, double-click on the Panoply icon to launch
the program. You will be immediately asked to select a netCDF dataset;
navigate to the “sample_data” folder included with Panoply, and select the
“gistemp1998.nc” file.

Datasets and Variables (The Data Browser)

Opening the gistemp1998.nc file will bring up a window, called the data
browser. This window displays the dataset file name as a folder. Double-
clicking the folder name opens it to show individual variables listed by their
abbreviated name in the file; the long name of each variable (usually more
descriptive than the abbreviated name); and the type of variable (whether
latitude-longitude or latitude-vertical). By default, only plottable variables
are shown initially, but you can opt to see all variables in the dataset by
selecting “All Variables” from the drop-down menu at the bottom of the
window.

The data browser displays the names and characteristics of the variables within the
datasets selected.

The details of a given variable within the dataset are shown on the right
side of the data browser. If you don’t wish to see these details, simply click
on the “Hide CDL” icon in the upper right corner of the data browser.

Return to Contents
User’s Guide to Panoply 5
Multiple datasets can be opened in the data browser, which is especially
useful if you plan to compare the same variable in different datasets. To
add more datasets, simply open them in the same way you opened the
initial dataset. The new dataset files will appear as new folders within the
data browser. To remove an extra dataset at any point, simply select the
folder name and click on the “Remove” whiskbroom icon in the upper right
corner of the data browser. If you have already made plots and want to
delete any unused datasets at that point, click instead on the “Remove All”
whiskbroom icon.
When you are ready to create a plot, select a single variable from the list.
At that point, the “Create Plot” icon in the upper right corner of the data
browser becomes available. Click once on this icon, or else double-click the
name of the specific variable you want, to create a plot.

Selecting a variable enables the plotting function in the data browser.

The Plot Window

This is the window in which you can adjust all aspects of a plot to suit your
needs. There are a number of components to this window, any of which
may be selected by clicking on individual tabs either near the top of the
window (to toggle between the plot image and tables showing dataset
values for a given variable), or at the bottom of the window for the Plot tab
(to modify different attributes of a given plot).
Every time you choose to create a plot in a new window (from the data
browser), a large window labeled with the VARIABLE_NAME and the dataset
file name will open first to a map view of the data. Note that you can
set your own preferences regarding which map projection, colorbar, etc.,
Panoply should use each time you create a plot.

6 User’s Guide to Panoply Return to Contents

 The plot window displaying a map
(above) and a zonal average (right).

First, let’s look at how to modify a plot of a single variable.

The Array(s) Tab

In the plot tab for a dataset, the first attribute that can be modified is the
array of data that you wish to show. The plot toggle menu allows you to
switch back and forth between a map plot and a zonal average (the average
variable value across a given latitude).
The interpolate checkbox to the right allows you to show the data as
gridded cells or smoothly transitioning between values.

Return to Contents
User’s Guide to Panoply 7
Map plots and zonal averages displayed in gridded (top row) and interpolated (bottom
row) form.

Within the Array(s) tab, you can also change the time interval of interest
according to the data available in the dataset. In the example below, you
can select the month of the year you want to see plotted by either typing in
a month number or selecting a month from the drop-down menu.

If you are plotting more than one array in a single plot (e.g., if you are
differencing two datasets), the properties for the second array can be
modified in the same way as for the first array. Make sure that you have
the appropriate array selected in the drop-down menu of the array(s) tab
before you begin changing plot properties.

8 User’s Guide to Panoply Return to Contents

 The Scale Tab
This tab controls the way the colorbar scale is displayed below the plot.
You may or may not have the ability to modify some of these settings,
depending upon the type of data in your dataset. The settings within the
Scale tab include:

Units: The unit selection depends upon the units assigned to variables
in the dataset. In the example below, units are given in degrees Kelvin
(K).
Divisions: This setting refers to the number of major segments on the
map colorbar scale or the major y-axis labels of a zonal average plot.
There can be between two and six labeled divisions.
Format: This setting refers to the display of numeric labels as real
numbers in decimal form (%f), numbers in scientific notation (%E), or the
option to display in either form (%G). The labels f, E and G are standard
Fortran variable formats; the other choices in the drop-down menu
(ranging e.g. from %.0f to %.6f) denote the number of significant digits
to be displayed for a particular format. For the average user, %G is a
reasonable format selection.
Scaling Factor: For datasets where the range in values is quite small, a
scaling factor, or exaggeration, expressed in exponential form can be
useful in underscoring variability.
Min., Max./Fit to Data: This setting can be used to impose a scale of a
certain range, for example, if a user wanted to have a scale with minima
and maxima rounded to whole numbers. If the “Always Fit” checkbox is
selected, however, the scale will be fitted precisely to the data, and no
modification of the scale endpoints will be possible.

The Scale tab allows flexibility in the labeling of scales for map colorbars and zonal
average plots.

Return to Contents
User’s Guide to Panoply 9
The Colors Tab
This tab is primarily for use with map plots, as it is in this tab that you can
select which colorbar you want to use.
Colorbar: Thirty different colorbars have
been included in Panoply, and each is
listed in the “Colorbar” drop-down menu;
you can, however, use a custom colorbar
if you wish (see Appendix 2 for details).
The “Flip Scale” checkbox allows you to
reverse the order of colors in a colorbar
selected from the list.
If at any point you would like to see
the spectrum of colors that would be
displayed for a given color bar, go into
the Panoply Windows menu and select
“Colorbars Browser” (shown at right).

Background: This setting can be used for both map plots and zonal average
plots. It allows you to make the plot background either white or black.
Invalids: This setting allows you to indicate areas without data in a map
plot by selecting a particular color (black, dark gray, gray, light gray, or
white) that will contrast appropriately with your Colorbar selection.

The Colors tab

is the tool for al-
tering the visual
impact of a map
plot.

10 User’s Guide to Panoply Return to Contents

 The Maps Tab/Zonal Grid Tab
Whether you are working with a map plot or a zonal average plot, the fourth
tab at the bottom of the plot window will display controls for modifying the
gridded view of the data.
Map plots have a greater number of settings that can be adjusted:

The Maps tab provides the major control for the appearance of your map.

Projection: Over 40 different

map projections have been
included in Panoply, each with
varying properties that make
them suitable for different
purposes (see Appendix 3).
To preview the projections
available, go into the Panoply
Windows menu and select the
“Continent Overlays Browser”
(shown at right).

Return to Contents
User’s Guide to Panoply 11
 Some of the more commonly used map projections are:
Equirectangular: This is a cylindrical map projection, which means
it has straight meridians and parallels that intersect at right angles.
Scale is true at the equator, and along any pair of parallels equidistant
from the equator. While is useful for comparison of narrow regions at
similar latitudes, the increasing distortion of scale toward the polar
regions makes it a less-than-ideal choice for world maps.
Mercator: This projection is perhaps the most famous of the cylindrical
map projections. It differs from other types of cylindrical projections
in that it is conformal: it preserves angles, so that any two lines in the
map follow the same angle as the corresponding original lines on the
Earth, even though shapes become increasingly distorted toward the
poles. For this reason, the Mercator projection is often used in marine
navigation.
Mollweide: This is a pseudocylindrical map projection, which means
that it has straight and parallel latitude lines and equally spaced
meridians, but all but the centermost meridian are curved. This
projection is often used for world maps.
Orthographic: This azimuthal projection is used for perspective views
of hemispheres, and so is especially useful for viewing polar regions.
Area and shape are distorted, but distances along lines of latitude are
true.
Azimuthal Equal Area: This azimuthal projection has the distinction
of being able to show areas in true proportion to the same areas on
Earth. Scale decreases gradually away from the center point, while
distortion increases. This projection is useful for displaying large
regions, such as the Pacific Ocean, that extend equally in all directions
from a center point.
Stereographic: Yet another azimuthal projection, this one is also
useful for polar regions, and in fact is often used for navigation
there. Directions are true from the center point and scale increases
away from the center, and area and shapes are increasingly distorted
toward the outer edge of the map.

Center on: You can select a particular point on the globe to be placed at
the center of the map, a useful feature for highlighting locations that are
typically close a map edge.
Grid color: The default selection is black, but you can select from a range
of colors to emphasize grid lines or to make them more subtle. You can
also adjust the opacity of the grid lines by typing a different percentage
in the adjacent box.

12 User’s Guide to Panoply Return to Contents

 Overlay type: You can display continents as outlines or solid shapes
in realistic form (Earth mask/outline) or in stylized form according to
different model grid cell sizes (10x8 degrees or 5x4 degrees). You may
also choose not to show any continents at all.
Overlay color: As with grid color, the default selection is black, but you
can select from a range of colors to emphasize continent overlays or to
make them more subtle. You can also adjust the opacity of the continents
by typing a different percentage in the adjacent box.

Zonal average grids have just a few options available:

X-Axis Direction: This setting allows you to put the North or South Pole
on the left side of the plot.
Grid opacity: You can adjust the visibility of grid lines on the plot.
Stroke color: The default color is red, but there are a range of colors
available for highlighting the data itself on the plot.

The Zonal Grid tab permits limited customization of your line plot.

The Captions Tab

This tab, the same for both map plots and zonal average plots, allows you
to change the name of the plot window, the plot title (which will be carried
over to any exported images), and the scale caption. The scale caption by
default is the long variable name plus the appropriate units.
Custom title and scale captions are permitted to be quite long, but you
should aim to keep them concise so as to avoid cluttering your plot.

The Captions tab permits customized labeling of your plot.

Return to Contents
User’s Guide to Panoply 13
The Data Window
Tucked behind the map tab in the plot window is the array of data used
to generate the map and zonal average plots, appropriately called the
data window (shown below). Metadata (including the dataset name, long
variable name, units, grid numbering and time slice) are listed at the top
of the window.
Values for individual grid cells are listed by lat/long or lat/vert coordinates,
with the zonal average value listed in a separate column to the right. The
value “NaN” (“not a number”) is given for grid cells that have no available
data (i.e., the “invalid” cells that are assigned a color outside the colorbar
spectrum). The format of the numeric values can also be changed at the
bottom of the window, in lieu of making a selection on the scale tab in the
map window.

14 User’s Guide to Panoply Return to Contents

 Plotting Multiple Variables (Difference Plotting)
Panoply has the capability to display plots that compare data values
between arrays. The compared arrays may be different time intervals for a
single variable within one dataset, or they can be the same variable from
two different datasets (e.g., comparing annual average temperatures for
two different climate simulations).
WARNING: Especially when comparing variables between datasets,
make sure that you are actually selecting the same variable for both
arrays. Panoply can determine to some extent whether two arrays have
compatible units (e.g., Celsius and Kelvin), and will allow you to choose
which unit you want in the Scale tab. However, it will not double-check to
make sure that you are not contrasting temperature with precipitation.
In order to compare data arrays, you need to “open” a second dataset
within the data browser. You can do this in one of two ways:
1. Differencing two time intervals for a single variable within a single
dataset: With one array already open and mapped, go back to the data
browser and select the same variable you have already plotted. In the
“target” drop-down menu at the top, instead of selecting “new plot,” select
the option named after the variable. When you do, you will see the icon to
the left change to “Combine Plot”; click this icon to add the second array to
the plot.
2. Differencing the same variable from two different datasets: With one
array already open and mapped, go back to the data browser. Go into the
Panoply File menu to open a new dataset. In the data browser, double-
click on the dataset folder to display all the variables, and select the same
variable name you have already plotted. In the drop-down menu at the top,
instead of selecting “new plot” select the option named after the variable
already plotted. When you do, you will see the icon to the left change to
“Combine Plot”; click this icon to add the second array to the plot.

Return to Contents
User’s Guide to Panoply 15
Adding a second array to an existing plot creates a new data window behind the first
one, and enables the comparison drop-down menu in the Array(s) tab.

Once you have a second array opened, you will see that the comparison
drop-down menu has become enabled in the Array(s) tab of the map
plot. The menu allows you to examine each array individually as well as
difference them (array 1 – array 2 and vice versa), add them, multiply
them, and average them.

Hint: Choosing the Right Color Bar

When plotting differences, always choose a colorbar (in the Colors tab)
that has white in the exact center of the bar (e.g., panoply_diff PAL-1). In
this way, white = no difference. Then, within the Scale tab, uncheck the
“Always fit” box and set your scale so that the Max = -1 x Min (e.g., Max =
5.0 when Min = -5.0). This creates a color bar with a symmetric scale, so
that it is easy to distinguish positive anomalies (e.g., colors to the right of
white are regions that warmed) and negative anomalies (e.g., colors to the
left of white are regions that cooled).

16 User’s Guide to Panoply Return to Contents

 Creating a Latitude vs. Altitude Plot (Vertical Plot)
If the data are available in your dataset, Panoply has the ability to display
vertical slices for a given line of longitude (meridian). The vertical dimension
may be either positive (altitude) or negative (depth). As an example, open
the sample dataset called “latvert.nc” included with Panoply. The data
browser indicates that the plottable variables in this dataset have latitude,
longitude, and vertical dimensions. When you select one of the variables
and click on the “Create Plot” icon in the upper left corner of the data
browser, you will be asked what kind of plot you would like to create. To
plot a vertical slice, click on the “Lat-Vert Plot” button.

The vertical plot you create shows the changes in the variable “u-wind”
with altitude for each latitude between the north and south poles. The
controls in the tabs across the bottom of the vertical plot window are
similar to those for a zonal average plot, with the exception of the Array(s)
tab. For vertical plots, the “Longitude” control allows you to specify which
meridian slice you would like to see displayed (in degrees east), or zonal
average for each line of latitude (the choice “Average” from the “Longitude”
drop-down menu).
Another minor difference between the controls for zonal average plots
and vertical plots is in the Grid tab. For vertical plots, you can use the
controls here to adjust the Y-axis units and numeric format, and the grid
color and opacity, in addition to the X-axis orientation (North or South
Pole to left).
Just as with map plots, you can open a second array of lat-vert data to
create difference plots comparing a variable along two different meridians
in the same dataset, or a variable along the same meridian in two different
datasets.

Return to Contents
User’s Guide to Panoply 17
Vertical plots al-
low you to display
data along a
single meridian
(in this case, the
Prime Meridian).

Special Map Plots (Regional and Vertical Perspective)

For cases in which you would like to plot only a limited portion of the
globe, or perhaps offer a “bird’s-eye view” of a given area, Panoply includes
two special map projections that can be used to present a different
perspective.

Equirectangular Regional Projection

To limit the area displayed in your map plot, select the Maps tab and
choose the “Equirectangular Regional” projection. Note that when you
do, an additional pair of settings appears in the tab: width (in degrees
longitude) and height (in degrees latitude).
The default display for the Equirectangular Regional projection is half the
area of a regular Equirectangular projection, i.e., the field of view is 180
degrees wide and 90 degrees high, centered on 0˚ latitude, 0˚ longitude.
To adjust the field of view to encompass a particular region, first enter the
new coordinates in the “Center on” field. (Make sure your desired values
are accepted either by clicking the cursor into a new field, or by hitting the
enter key after typing in a value.) Then enter appropriate values for the
width and height of your regional map. Note that Panoply will not force
your map to be proportional; you may have to adjust width and height
several times to produce a proportional map.

18 User’s Guide to Panoply Return to Contents

 The default settings
for the Equirect-
angular Regional
projection cover
half the globe.

Recentering the
map and limit-
ing the height and
width of the map
produces a regional
perspective.

Return to Contents
User’s Guide to Panoply 19
Vertical Perspective
To create a bird’s-eye view of your map plot, select the Maps tab and choose
the “Vertical Perspective” projection. Note that when you do, a new setting
appears: “Center Distance (R),” which alters the map viewer’s perspective
to varying “heights” above a point that you select.

The default display for the Vertical Perspective projection is an orthographic

projection centered on 0˚ latitude, 0˚ longitude, with a perspective from
R=10. To adjust the field of view to display a new perspective, first enter
the new coordinates in the “Center on” field. (Make sure your desired values
are accepted either by clicking the cursor into a new field, or pressing the
enter key after typing in a value.) Then enter a value for the “height” of
your perspective.
Note: A value of R=1 should put you at the surface, but values of R≤1
may not display correctly. In addition, any value of R≥500 is essentially a
regular orthographic projection.

The default settings for the Verti-

cal Perspective projection display
an orthographic projection at the
height of R=10.

The Vertical Perspective projection

can be adjusted to produce a map
with a regional focus yet still retains
a “global” context.

20 User’s Guide to Panoply Return to Contents

 Exporting Plots
Once you have produced an image you are happy with, exporting the plot
is quite simple. Go into the Panoply File menu, select “Save” or “Save as...”
and name the file as you wish. The default file format of plots exported
from Panoply is PNG. To save a file in GIF format, simply add .GIF to the
end of the output file name.

Saving Preferences
If you would like to have your plots default to a particular set of
characteristics, you can set these within the Panoply preference windows.
Any of the characteristics you previously set in the tabs within the plot
window can also be set here.

Return to Contents
User’s Guide to Panoply 21
22 User’s Guide to Panoply Return to Contents
 Appendix 1
netCDF Data Files
The netCDF (network Common Data Form) file format was developed to
assist in the creation, access and sharing of scientific datasets. A detailed
description of the netCDF format is available from the UCAR Unidata
Program Center (http://my.unidata.ucar.edu/content/software/netcdf/
index.html). The following discussion concerns what information Panoply
requires in order to work with the contents of a netCDF dataset.
In general, Panoply works best with netCDF datasets that have been tagged
according to one of the more common defined netCDF conventions, such
as CF, COARDS, and GDT.

Coordinate Variables
When examining the variables in a netCDF dataset, Panoply looks for
certain information to determine whether each variable is “plottable,” and
if so, how to plot it.
For longitude-latitude plots, the variable must have at least two dimensions,
and the last two dimensions must be the latitude and longitude (in that
order). In addition, the latitude dimension must be named either lat or
latitude, and the longitude dimension named lon or longitude.
Values of the longitude coordinate variable must run eastward and be
monotonically increasing. They should have units of “degrees_east.” For
example, a grid that has 10° spacing and is centered on the prime meridian
might have longitude values running from -175.0 up to 175.0. Alternatively,
a grid that has the prime meridian as its left edge would have longitude
values that run from 5.0 to 355.0.
Values of the latitude coordinate variable may run either north to south or
south to north, but they should have units of “degrees_north.” Northern
hemisphere latitudes must be positive, and southern hemisphere latitudes
must be negative.
For latitude-vertical plots, the variable must again have at least two
dimensions. The vertical and latitude dimensions need not be the last two
dimensions of the variable, as Panoply is capable of dealing with variables
that have three dimensions in the vertical, latitude and longitude.

Return to Contents
User’s Guide to Panoply 23
There are two ways of tagging the vertical dimension so that it may be
recognized by Panoply. The easiest to recognize is when the dimension has
units of pressure, and the units should be a string recognized by UDUNITS
(the Unidata units library). If the dimension has units of bars or millibars,
the full unit name should be spelled out rather than abbreviated.
The alternative form of vertical dimension that may be recognized is a
dimension that has a positive attribute, with value of either “up” or “down.”
In the case of a vertical dimension with units of meters, the positive attribute
is necessary to identify that the units indicate either altitude or depth.
Similarly, a vertical dimension which has units of “level” needs the positive
attribute to indicate whether the first level is the top or bottom.
Additionally, for each variable dimension there must be an associated
coordinate variable which has the same name as the dimension. In other
words, if the latitude dimension is called lat then the dataset must have a
variable called lat.

Boundary Variables
In addition to using the coordinate variables to identify the grid points on
which the data are placed, Panoply needs to determine the area each point
in the latitude-longitude grid represents. Consequently, it also checks the
netCDF dataset for associated boundary variables. This checking is done
by testing whether the pertinent coordinate variable has an attribute called
bounds, which identifies another variable containing the boundaries of
the grid cells. A boundary variable will have one more dimension than
its associated coordinate variable, with the second dimension having two
possible values, i.e., the two boundaries.
If a coordinate variable does not have an associate boundary variable,
Panoply will use values halfway between the grid points.

Relative Time Coordinates

A coordinate variable which has units of form <something>, since
<something> (e.g., “hours since 1901-01-01 00:00:00”) is recognized by
Panoply as being of variable type “relative time.”
Panoply understands how to treat relative-time coordinate variables if they
use a recognized calendar. The calendar must be identified, either in the
variable’s calendar attribute or the dataset’s calendar attribute. If both
attributes are present, then the variable attribute has priority. The types of
recognized calendars include:

24 User’s Guide to Panoply Return to Contents

 gregorian: The standard calendar used today. However, for dates in the
past it is actually a hybrid Julian/Gregorian calendar, with a 10-day gap
in October 1582 when much of Europe first switched from the Julian
calendar to the Gregorian.
proleptic_gregorian: A pure Gregorian calendar, representing today’s
dates accurately but also extending indefinitely back into the past.
julian: A pure Julian calendar.
noleap: A 365-day calendar in which February always has 28 days and a
year always 365 days. Might also be denoted no_leap, common_year, or
365_day.
all_leap: A 366-day calendar in which February always has 29 days and
a year always 365 days. Might also be denoted no_leap, common_year,
or 366_day.
360_day: A 360-day calendar in which all 12 months each have exactly
30 days. Might also be denoted 360, but such usage is deprecated.

The last three of these calendar schemes are non-astronomical calendars

used by various climate models.

Absolute Time Coordinates

A coordinate variable that has units of form <time unit> as <format string>
(e.g., “days as %Y%m%d.%f”) is recognized by Panoply as being of variable
type “absolute time.”
For example, a dataset that includes a collection of monthly averages
beginning at the start of the 21st century might specify the coordinate
variable as having units “months as %Y%m” and contain values 200101,
200102, 200103, etc.

Special Values
If a variable has invalid or missing values, then the appropriate attributes
valid_min, valid_max, valid_range, and/or missing_value should be specified
so that Panoply treats them correctly.
Panoply treats all missing or invalid values the same and, when rendering
a plot, draws them all using a single “invalids color.”

Return to Contents
User’s Guide to Panoply 25
Scale Labels
Panoply uses the variable’s long_name and units attributes, if they are
provided, for the default labeling of the scale in a plot. If the long_name
is missing, Panoply checks to see if a standard_name has been provided
instead.

26 User’s Guide to Panoply Return to Contents

 Appendix 2
Colorbars (a.k.a. Palettes or
Color Tables)
When rendering a global map from a data array, Panoply uses color table
information to translate the data values into colors. A scale indicating
the relation between colors and data values is rendered on the plot as a
colorbar.
The color information is stored in separate files, two of which are bundled
into the Panoply application itself, with another 30 provided in the sample
colorbars folder. When launched, Panoply will attempt to open all the
colorbars in the sample folder. If there are colorbars in that folder that you
don’t need, you can remove them and Panoply will not list them as options.
Likewise, you can add your own favorite colorbars to the folder and they
will be automatically opened if they are in a recognized format. You can
also use the Open... item in the File menu to open other colorbars from
other locations on your computer.
There are basically three types of colorbars that Panoply recognizes, each
identified by the filename extension.

PAL Color Tables

This is a fairly common color table format, which specifies 256 colors and
is identified by the .PAL filename extension. Panoply treats the first color in
the table as corresponding to the minimum of the plot scale and the 256th
color as corresponding to the maximum (or vice versa if you opt to “Flip
Scale Colorbar” when plotting).
When specifying plot options, you may have specified scale extrema such
that there are “outliers,” data values which are outside the minimum-
maximum range. In such cases Panoply uses the color value corresponding
to the minimum value on the scale for all values less than that minimum.
Similarly, any values greater than the scale maximum would be rendered
using the color corresponding to the maximum.
A PAL file is 768 bytes long, with the first 256 bytes specifying the red
values, the middle 256 bytes specifying green values, and the final 256
bytes blue values. This means then that if a data value is identified by

Return to Contents
User’s Guide to Panoply 27
Panoply as corresponding to the first color value, then the matching RGB
color value is found by combining bytes 1, 257, and 513 of the file.

An example of a PAL color table (left),

showing the 256 colors available.

At right is a PAL-1 variation on the PAL

color table shown above. Note that only
254 colors are available with this table.
Many of the color tables included with
Panoply are PAL-1 tables.

PAL-1 Color Tables

A PAL-1 color table is a special case of a PAL color table. It is identified by a
.PA1 filename extension (that’s a numeral one at the end, not a lowercase
L) so that Panoply can distinguish between them. A PAL-1 file is structurally
the same as a PAL file, but Panoply treats the first and 256th colors in a
PAL-1 file as being special and only uses colors 2-255 to draw the scale
itself (i.e., a 254-color scale). The first color value in the file is treated
as corresponding to all values in the plot less than the specified scale
minimum; the 256th color is similarly used for all values greater than the
scale maximum.

28 User’s Guide to Panoply Return to Contents

 ACT Color Tables
The .ACT extension stands for Adobe Color Table, and indicates a type of
color file used in some graphics programs from Adobe Systems. An ACT
file usually defines 256 color values, but the format allows for defining a
smaller number. As with a PAL color table, Panoply treats the first color
of an ACT table as representing the scale minimum and also all less-than-
minimum values, and the last color as representing the scale maximum
and all greater-than-maximum values.

Examples of ACT color tables.

CWC Color Tables

The .CWC extension indicates a color file format most commonly used in
Apple Computer’s AppleWorks application (once known as ClarisWorks).
This type of color table has 256 color values. As with a PAL color table,
Panoply treats the first color of a CWC table as representing the scale
minimum and also all less-than-minimum values, and the 256th color as
representing the scale maximum and greater-than-maximum values.

Color Table Software

If you are using Mac OS X, you may find the application ColorBarTender
(http://macupdate.com/info.php/id/11678) useful for creating and editing
color table files. As of its version 2.0 (May 2003), it works with PAL-1 and
CWC colorbars.

Return to Contents
User’s Guide to Panoply 29
30 User’s Guide to Panoply Return to Contents
 Appendix 3
Map Projections
Panoply can plot a global map of longitude-latitude data using numerous
different projections. Although the average user may only ever avail
themselves of one or two of the most common projections, a different map
projection can literally provide a different perspective on the graphical
interpretation of data.
The projections available in Panoply can be classified by aspect (layout) as
follows:
Azimuthal: Azimuthal maps can be thought of as projections to a plane
placed tangent to the globe at a given point, with distortion increasing
away from the tangent point. Projections in this category include Aitoff,
Azimuthal Equal-Area, Azimuthal Equidistant, Eckert-Greifendorff,
Hammer, Orthographic, Stereographic, Vertical Perspective, Wagner VII,
Wagner VIII, and Winkel Tripel.
Cylindrical: Maps of this type have straight and parallel lines of latitude
as well as meridians, and the parallels and meridians meet at right
angles. Panoply projections in this category include Equirectangular,
Gall, Mercator, and Miller Cylindrical.
Pseudocylindrical: Maps of this type have straight and parallel lines of
latitude, but the scale along them varies such that meridians are no
longer perpendicular to latitude, and may not even be straight lines.
Panoply projections in this category include Apian Globular II, Eckert III,
Eckert IV, Eckert V, Eckert VI, Hölzel, Kavraisky VII, McBride–Thomas Flat-
Polar Parabolic, McBride–Thomas Flat-Polar Quartic, McBride–Thomas
Plat-Polar Sinusoidal, Mollweide, Nell-Hammer, Parabolic, Putninš P1,
Putninš P1’, Putninš P3, Putninš P3’, Putninš P4’, Putninš P5, Putninš P5’,
Quartic-Authalic, Sinusoidal (equal area), Wagner I, Wagner II, Wagner
IV, Wagner V, Wagner VI, and Winkel I.
Some Panoply projections do not fit a particular classification, and are
grouped together in a Miscellaneous category. These projections include
Ortelius Oval and Van Der Grinten I.

Below are a series of charts of the available global and hemispheric

projections, along with alternative names. Each projection name is shown
with a simple black-and-white map of Earth (centered on 0°E 0°N) using that
projection.

Return to Contents
User’s Guide to Panoply 31
32 User’s Guide to Panoply Return to Contents
Return to Contents
User’s Guide to Panoply 33
34 User’s Guide to Panoply Return to Contents
Return to Contents
User’s Guide to Panoply 35
36 User’s Guide to Panoply Return to Contents
 For further reading:
Bugayevskiy, Lev M. and John P. Snyder. 1995. Map Projections: A Reference
Manual. London: Taylor and Francis.
Muehrcke, Phillip C. and Juliana O. Muehrcke. 1998. Map Use: Reading-
Analysis-Interpretation, 4th ed. Madison, WI: JP Publications.
Snyder, John P. 1987. Map Projections: A Working Manual. USGS Professional
Paper 1395. Washington, DC: United States Government Printing Office.

Return to Contents
User’s Guide to Panoply 37
38 User’s Guide to Panoply Return to Contents
 Panoply Software License
Although Panoply was produced at a U.S. Government research institute,
the complete Panoply application cannot be considered public domain
software because it includes libraries provided by third parties which have
individual copyrights and licenses. See the acknowledgments on the front
inside cover of this manual for further information about these third-party
libraries.
Scope of License. Subject to all the terms and conditions of this license
and of the individual licenses of any third-party libraries, NASA Goddard
Institute for Space Studies grants the user royalty-free, nonexclusive,
nontransferable, and worldwide rights to reproduce, modify, reverse
engineer, and distribute the Panoply software package, herein referred to
as the Product.
Conditions and Limitations of Use. Neither the U.S. Government, nor any
agency or employee thereof, makes any warranties, expressed or implied,
with respect to the Product provided under this License, including but not
limited to the implied warranties or merchantability and fitness for any
particular purpose.
Liability. In no event shall the U.S. Government, nor any agency or employee
thereof, be liable for any direct, indirect, or consequential damages flowing
from the use of the Product provided under this License.
Non-Assignment. Neither this License nor any rights granted hereunder
are transferable or assignable without the explicit prior written consent of
NASA Goddard Institute for Space Studies.
Names and Logos. User shall not substitute its name or logo in identification
of the Product.
Export of technology. User shall comply with all U.S. laws and regulations
restricting the export of the Product to other countries.

Return to Contents
User’s Guide to Panoply 39