Examples
overview
gallery
alphabetical
by category
by function
by resource
by effect
Links
What's new
Tutorial
Functions
Resources
PyNIO
Colors
FAQ
User forum
Quick links
Related URLs
Bugs
Glossary
Download
Contributors
Privacy policy
Terms of use

What's new in PyNGL and PyNIO

Version 1.3.0b1 | 1.2.0 | 1.1.0 | 1.0.0 | 0.1.1b8 | 0.1.1b7 | 0.1.1b6 | 0.1.1b5 | 0.1.1b4 | 0.1.1b3 | 0.1.1b1 | 0.1.0b1 | Future release

Version 1.3.0b1 - August 18, 2008

Open source

This is our first open source version of PyNGL and PyNIO, and these two packages are now being released separately.

The source code licenses for PyNIO and PyNGL are similar to the The University of Illinois/NCSA Open Source license.

The binary licenses for PyNIO and PyNGL are similar to the old binary license for the previous versions. A separate binary license is necessary because of the additional 3rd party software included.

New features and augmentations in PyNGL

New PyNGL/PyNIO examples

Extended subscripting added to PyNIO

PyNIO now supports an extended form of subscripting to specify subsets using a description string that can reference associated coordinate variables if they exist in the file. Dimensions can be transposed by varying the order of the coordinate axes in the subset specification. An option allows use of the CF 'axis' attribute, if the coordinate variable defines it, to specify dimensions using the standardized short-form aliases 'T', 'Z', 'Y', and 'X'. Depending on specification options the user can request that the data values on subset boundaries be linearly interpolated between grid points or limited to the nearest grid point. In addition, the user can use an auxiliary multidimensional variable to define a subset indirectly.

Support for maskedarray module added

By default PyNIO now returns a masked array for any variable with a '_FillValue' or 'missing_value' attribute. However, there is an option that allows the user to control this behavior in various ways. See new PyNIO options below.

When masked array data is written to a variable in a file opened for writing, masked values are replaced with the fill value specified either by the variable's "_FillValue" or "missing_value" attribute if it exists, or with the fill value currently associated with the masked array if no such attribute exists.

As mentioned in the augmentations list above, support for masked arrays has been added to many of the visualization functions and is included in some of the new analysis functions. These are the masked arrays introduced in numpy V1.0.

See the "overlay1.py" and "irregular.py" examples in the gallery for examples of using masked arrays.

PyNIO Attribute Additions

The attribute "attributes" has been added to both the NioFile and NioVariable types. This attribute contains the same information as is visible in the "__dict__" attribute. It has been added to provide a closer mapping to NetCDF terminology.Use of the "__dict__" attribute to access file and variable attributes is now deprecated.

A new module-level dictionary called "option_defaults" that contains the default values of all options defined by PyNIO has been implemented. By updating this dictionary, a user can change the default value for any settable option. This default option value will be used as the value of any option that is not set by means of "options" keyword argument to the "open_file" constructor, or, if available, by the "set_option" method of NioFile.

New PyNIO options

A new PyNIO option "MaskedArrayMode" has been implemented that allows the user to control PyNIO's behavior with respect to masked arrays. The default setting is "MaskedIfFillAtt", meaning that a masked array is returned if the variable in the file has either a "_FillValue" or a "missing_value" attribute. Other possible settings are "MaskedAlways": return a masked array for all variables; "MaskedNever": always return a regular NumPy array; and "MaskedIfFillAttAndValue": return a masked array only if a fill attribute has been defined and the subset requested actually contains at least one element equal to the fill value; "MaskedExplicit": use options "ExplicitFillValues", "MaskBelowValue", and "MaskAboveValue" to explicitly set one or more fill values and/or regions to mask, ignoring any fill value attributes.

"ExplicitFillValues", by default set to None, can be set to a scalar value or a sequence of values, which all become masked in the output array. The first value is set as the fill_value attribute of the MaskedArray. This option can be combined with additional masked values specified using "MaskBelowValue", and/or "MaskAboveValue".

"MaskBelowValue", by default equal to None, can be set with a single value below which all values become masked, except that if the value is greater than the value set for "MaskAboveValue", a band of masked values is defined.

"MaskAboveValue", by default equal to None, can be set with a single value above which all values become masked, except that if the value is less than the value set for "MaskBelowValue", a band of masked values is defined.

The new option "UseAxisAttribute" is a boolean attribute that specifies whether to use the short form names "t", "z", "y", and "x" as dimension names if the coordinate variable defines the "axis" attribute. As currently implemented, this is an "either/or" choice: if set True and if the "axis" attribute is defined, attempts to use the actual dimension name rather than the short-form name will result in an error.

Note that these new options generalize the concept of PyNIO options because they are not file-format specific. These options apply for any file type.

Also a new optional argument, called format has been added to the NioFile open_file constructor. This argument provide an alternative to the current method of explicitly specifying file formats by adding a "fake" suffix to the filepath argument. The format argument can be set to any of the suffixes that can be tacked on to the filepath argument. Do not confuse the format optional argument with the NetCDF-specific option, "Format", used to specify different NetCDF file types.

Bug fixes

Support for Numeric dropped

In this release of PyNGL and PyNIO, we are dropping support for Numeric. An informal survey indicated that most of not all of our users have made the transition to NumPy, or are at least planning to very soon. We are adding several new data analysis functions, and trying to keep support for Numeric and NumPy was getting to be a bit tedious.

Known issues

Version 1.2.0 - July 23, 2007

With this release, NumPy is now the default array module package for PyNGL and PyNIO. Numeric 24.2 will still be supported. How you import the two packages is different from previous versions: if you download the NumPy version, you can import PyNGL and PyNIO with: 
import Ngl, Nio
If you download the Numeric version, you must import PyNGL and PyNIO with: 
import PyNGL_numeric.Ngl as Ngl
import PyNGL_numeric.Nio as Nio
and then you will be able to use all the "Ngl." and "Nio." calls in the usual way.

New functionality

New functions

New color tables

New resources

New pynglex examples

Version 1.1.0 - November 9, 2006

With this release of PyNGL and PyNIO we now support both NumPy 1.0 and Numeric 24. Support for these two array modules is done via two separate packages that can safely be installed together.

In order to use the Numeric version, which is currently considered the default mode for PyNGL and PyNIO (but won't be once NumPy is considered to be the more prevalent package used), you just need to import Ngl and Nio: 

import Ngl
import Nio
To use the NumPy 1.0 version, you need to import PyNGL_numpy and PyNIO_numpy: 
import PyNGL_numpy.Ngl as Ngl
import PyNGL_numpy.Nio as Nio

New functions

Ngl.delete_wks
Deletes a workstation object.

Ngl.gc_tarea
Finds the area of a spherical triangular patch.

Ngl.gc_qarea
Finds the area of a convex quadrilateral spherical patch.

Version 1.0.0 - July 12, 2006

This release of PyNGL and PyNIO was built with Python 2.4.3 and Numeric 24.2. We also have a test version that was built with NumPy version 0.9.8. Both versions are available for download on the Earth System Grid website.

New website
PyNGL/PyNIO has a newly-designed and significantly improved website.

Support for NumPy version 0.9.8
There's a test version of PyNGL and PyNIO available that works with NumPy version 0.9.8. You can download this version from the same place as the Numeric version, on the Earth System Grid website. Both versions can be installed on the same system as they will not conflict with each other (the package names are "PyNGL" and "PyNGL_numpy").

The test NumPy version must be imported with: 

    import PyNGL_numpy.Ngl as Ngl
    import PyNGL_numpy.Nio as Nio
while the Numeric version of PyNGL and PyNIO can be imported with: 
    import Ngl
    import Nio

Due to the changing nature of NumPy (as it goes through several test phases), we can't guarantee that this test version will work with other versions of NumPy. We are interested in feedback, so please let us know if you download this version and have any kind of success with it.

Changes to default graphical environment
Based on our experience with other graphics packages we develop, we decided to change the default graphics environment for PyNGL. We believe these changes are for the better, but if you don't agree, you can change the default graphical environment for your site using a file called the "sysresfile."

Here's a summary of the changes:

  • The default background color is white and the default foregound color is black for all graphical output (PostScript, PDF, X11 window, and NCGM). Previously, it was the reverse.
  • The default font is helvetica instead of times-roman.
  • The default color table is now "rainbow". It was previously "default".
  • The default function code is now a tilde ('~') instead of a colon (':').

Updates to PyNIO
New 'print' methods were added for the NioFile and NioVariable objects. These print a nicely formatted summary of the contents of a file or an individual variable.

A new 'options' argument was added to 'open_file' to provide support for a number of format-specific options for GRIB and netCDF files. These options allow you to create larger NetCDF files using the 64 bit offset format variant, improve performance when reading or writing large netCDF files, and control various aspects of GRIB files, such as the type of interpolation used to read data on thinned grids.

Doc strings were added for the Nio module and all its objects, methods, and attributes.

New resources added (at the moment, only one)
nglPointTickmarksOutward

New functions added
Several new functions were added:
  • Ngl.free_color - Removes a color entry from a workstation.
  • Ngl.maximize_plot - Maximizes the size of the given plot on the workstation.
  • Ngl.new_color - Adds the given color to the end of the color map of the given workstation.
  • Ngl.new_dash_pattern - Adds new dash patterns to the existing table of dash patterns.
  • Ngl.new_marker - Adds new markers to the existing table of /marker styles.
  • Ngl.pynglpath - Returns full path names for selected abbreviated names.
  • Ngl.set_color - Sets a color in the color map of the given workstation.

Docstrings added for PyNGL functions
Python docstrings were added for all of the PyNGL functions.

Updates to functions
Many PyNGL functions were updated to handle input types of scalar, tuples, lists, and Numeric arrays.

More examples added
Several examples were added, including:
  • coast1.py - generates coastal outlines using three different levels of resolution
  • contour1.py - shows how to turn a linear axis into a log axis
  • contour2.py - uses shading patterns and fill colors to fill contours
  • contour3.py - uses dashed line patterns to dash negative contour lines
  • contour_xyz.py - contours random X, Y, Z data
  • color2.py - uses named colors in a multi-curve XY plot
  • color3.py - draws HSV color wedges and shows how to use color conversion functions
  • color4.py - uses named colors to generate common colors
  • color5.py - draws a Mandelbrot set
  • map2.py - draws polygons, polymarkers, and polylines on a map
  • multi_y.py - generates multiple Y curves with their own axes
  • overlay.py - draws multiple overlays of contours and vectors on a map
  • thickness.py - shows how to create various line thicknesses
  • scatter2.py - shows how to create your own markers
  • xy1.py - shows how to change the style of the axes in an XY plot
  • xy2.py - attaches primitives (polygons, polylines, etc.) to a plot
  • vector_pop.py - generates vectors on a POP grid

For a quick look at all of the available examples, see the new PyNGL gallery.

Updates to Skew-T resources
All of the Skew-T resources associated with the Ngl.skewt_bkg and Ngl.skewt_plt functions have been renamed to be more consistent with the rest of the PyNGL resources. The old names will still work. To see the new names, go to the Skew-T resources page.

Version 0.1.1b8 - September 22, 2005

New location for PyNGL binaries - April 5, 2005

As of April 5, the PyNGL binaries are housed on the Earth System Grid website. For more information, see the download instructions.

Version 0.1.1b7 - March 17, 2005

Version 0.1.1b6 - January 12, 2005

Version 0.1.1b5 - December 12, 2004

Version 0.1.1b4 - December 10, 2004

Version 0.1.1b3 - December 8, 2004

Version 0.1.1b1 - October 18, 2004

Version 0.1.0b1 - September 19, 2004

This version is the first beta release of PyNGL.

PyNGL and PyNIO are products of the Computational & Information Systems Laboratory at the National Center for Atmospheric Research, with support from NSF
Contact webmaster