What was added in previous releases of NCL

• Striding across the leftmost (aggregated) dimension did not work correctly:

    f    = addfiles("file*07*.nc","r")
    xnew = f[:]->x(::5,:,:)
  

• The second serious bug is that if the data extracted from the first file of an aggregated variable was reduced to a single value, the returned variable was incorrectly internally tagged as a oscalar. When accessed without subscripts, this had the strange effect of returning the proper number of elements but giving them all the value of the first element. Here's an example of the problem:

    fnames = (/ "file01.nc", "file02.nc" /)
    fp = addfiles(fnames, "r")
    days = fp[:]->days
    print(days)
    days = days / sum(days)
    print(days)
  

  Adding a subscript makes it work correctly:

     days(:) = days(:) / sum(days)
  

• There was also a bug that resulted in files not being closed properly when the when the file list variable was deleted.

Bugs fixed

• vinth2p, vinth2p_ecmwf, vintp2p_ecmwf

  A bug was discovered that affects the top two interpolated levels only. The underlying vinth2p, vinth2p_ecmwf, vintp2p_ecmwf codes were taken directly from the original CCM Processor (http://www.cgd.ucar.edu/cms/processor/subject/vertical.interp.html).

  These subroutines have been used possibly since the late 1980s. Recently, Mark Branson (Colorado State University), was examining interpolated values at the uppermost interpolated levels. He discovered a bug.

  An example will be used to illustrate the bug:

  Consider temperatures [TM (K)] at the following model hybrid levels [PM (hPa)]:

            PM      TM        <=== Raw Data
          3.64    226.77
          7.59    225.53
         14.36    224.89
         24.61    221.39
         38.27    213.97
        [snip]
  

  Let's say that interpolation to the following pressure levels (PI) is desired:

          PI = (/ 5, 7, 10, 20, 30, 50, ...... /)
  

  The following shows the values interpolated by the vinth2p and vinth2p_ecmwf functions before (v5.1.0) and after (v5.1.1) the bug fix:

          PI    v5.1.0    v5.1.1    diff
           5    225.78    226.34   0.564
           7    225.59    225.72   0.129
          10    225.30    225.30   0.000 No differences
          20    222.96    222.96   0.000
      [snip]
  

  The differences could be 'small' or 'large'. It depends upon the vertical distribution of the variable.

• wrf_user_unstagger had a bug with regard to getting the diagnostics "ua" and "va".

• There was a bug in reading a character variable that contained a missing value off a NetCDF file. The missing value would not be set correctly.

• Several functions (like sprinti and sprintf) had a bug that caused an input variable to incorrectly have an extra attribute added upon return.

"shea_util.ncl" has new dependency

If you are loading the "shea_util.ncl" script, then you will need to load "contributed.ncl" before "shea_util.ncl":

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

"shea_util" now depends on some functions in "contributed.ncl".

Changes to WRAPIT

For Linux and MacOS systems, the default fortran compiler used has been changed from "g77" to "gfortran". If you need to use the "g77" compiler, then use the new "-g77" option:

  WRAPIT -g77 your_file.f

Deprecated functions

changeCase/changeCaseChar/replaceSingleChar

These functions were deprecated. Use built-in functions str_switch, str_lower, str_upper, and str_sub_str.

Version 5.1.0

4 March 2009

• New map functionality
• New functions
• New and updated WRF-NCL functions
• New functionality
• Major upgrade for "addfiles"
• New color tables
• New and updated resources
• Bug fixes

New map functionality

New map databases have been added to NCL that provide improved map outlines, and new map outlines like the provinces of China, and the states of Brazil, India, and Australia. Some of the Antarctica ice shelves have also been added.

Three new map projections have been provided as well: Hammer, Aitoff, and Winkel tripel.

A new-and-improved Mollweide projection has been added that replaces the original Mollweide projection. The old Mollweide, like a true Mollweide, has an elliptical perimeter twice as wide as it is high (though with different dimensions) and its parallels are straight and horizontal, as in a true Mollweide, but the shapes of the land masses are noticeably different.

You can get the original Mollweide projection back by setting the mpProjection resource to "PseudoMollweide".

For some example scripts of these new features, see examples 16 through 19 at http://www.ncl.ucar.edu/Applications/maponly.shtml.

New functions

area_hi2lores, area_hi2lores_Wrap

Interpolates from high resolution grids to low resolution grids using local area averaging.

bin_sum

Calculates binned sums and counts over multiple invocations of the procedure.

bin_avg

Calculate gridded binned averages and counts.

cfftb, cfftf, cfftf_frq_reorder

These functions perform forward/backward complex fourier transforms and reorder returned output to span -0.5 to 0.5.

conform_dims

This function is basically identical to conform except that you pass in the dimension sizes of the new array size that you want to conform to, rather than the array itself. This method is preferable because you don't need to create the array before using this function.

covcorm

Calculates a covariance or correlation matrix.

crossp3

Compute cross products of multiple vectors of length 3.

dz_height

Calculates the height layer thicknesses at each grid point over varying surface terrain.

evssm_lapack

Calculates the eigenvalues and eigenvectors of a real matrix stored in symmetric storage mode.

genNormalDist

Generate a normal distribution give the mean and standard deviation.

get_script_name and get_script_prefix_name

These two built-in functions return the name of a script of commands for NCL to run, if provided, at the command line. get_script_prefix_name will strip any script name tag, if it exists.

Note: get_script_name was originally an unadvertised function in the shea_util.ncl script, and behaved slightly different in that it returned only the prefix of the NCL script name. To get the behavior similar to this old version of the function, use the new get_script_prefix_name function, which doesn't require any script to be loaded in order to use it.

gsn_blank_plot

This function creates a blank plot. This can be useful if you just need a canvas to draw on, or if you need to further annotate an existing plot.

gsn_csm_attach_zonal_means

This function attaches a zonal means plot to the given map plot. This function is basically the equivalent of setting the special resource gsnZonalMean to True when calling gsn_csm_contour_map, so you don't need to call this function unless you want to attach a zonal means plot to a plot that wasn't created with gsn_csm_contour_map.

kron_product

Computes the Kronecker product for 2D matrices.

latRegWgt

Generates [sin(lat+dlat/2)-sin(lat-dlat/2) weights for equally spaced (regular) global grids that will sum to 2.0.

mjo_cross_coh2pha

Calculates space-time coherence-squared and phase using the array returned by mjo_cross_segment.

mjo_cross_segment

Calculates space-time cross spectrum for a single time segment.

NormCosWgtGlobe

Creates normalized cosine weights that sum to 2.0 just like gaussian weights. This function is not really new, but it was never documented before.

numeric2int

Convert any numeric type to integer with options for rounding or truncation.

obj_anal_ic

Iterative correction objective analysis (Cressman, Barnes).

pdfx

Calculate the probability density distribution of a variable.

quadroots

Determine roots of a quadratic equation [ a*x^2 + b*x + c].

rcm2points_Wrap

Interpolates curvilinear grids (RCM, WRF, NARR) to user specified locations and retains meta data.

rcm2rgrid_Wrap

Interpolates RCM, WRF and NARR grids to rectilinear lat/lon grid and retains meta data.

region_ind

Returns the indices (subscripts) of two-dimensional latitude/longitude arrays that span user specified latitude/longitude boundaries.

relhum_ttd

Calculate relative humidity given temperature and dew point temperature.

replaceSingleChar

Within a string replace one character with another character.

rgrid2rcm_Wrap

Interpolates a rectilinear lat/lon grid to curvilinear grids like those used by the RCM, WRF and NARR models/datasets and retains meta data.

short2flt_hdf

Converts values of type short to values of type float using the "scale" and "offset" attributes (if present).

This function has been around awhile, but not documented.

spcorr

Computes Spearman rank order correlation coefficient.

triple2grid_Wrap

Places randomly-spaced data onto the nearest locations of a grid described by one-dimensional coordinate arrays and preserves meta data.

utm2latlon, latlon2utm

Functions for converting between UTM and lat/lon coordinates.

wk_smooth121

Specialized 1-2-1 smoother associated with Wheeler-Kiladis space-time spectra.

wkSpaceTime (wkSpaceTime_cam)

Calculates Wheeler-Kiladis space-time spectra (using a generic CAM interface).

wmvect, wmvectmap, wmvlbl

These are basic functions primarily for use with non-gridded data. For gridded data then you could use a vector plot with vcGlyphStyle set to one of the appropriate styles.

ut_convert

Converts a time variable from one set of units to another.

yyyymmdd_time

Creates a one-dimensional array containing year-month-day [yyyymmdd] values.

New and updated WRF-NCL functions

Special thanks to Cindy Bruyere of NCAR/MMM for her development of the WRF-NCL visualization scripts, and to her and Soyoung Ha, also of NCAR/MMM, for the addition, overhaul, and extensive testing of the WRF-NCL analysis scripts.

wrf_avo

Calculates absolute vorticity from WRF model output.

wrf_cape_2d

Computes maximum convective available potential energy (CAPE), maximum convective inhibition (CIN), lifted condensation level (LCL), and level of free convection (LFC).

wrf_cape_3d

Computes convective available potential energy (CAPE) and convective inhibition (CIN).

wrf_dbz

Calculates simulated equivalent radar reflectivity factor [dBZ] from WRF model output.

wrf_eth

Calculates equivalent potential temperature from WRF model output.

wrf_ij_to_ll

Finds the nearest longitude, latitude locations to the specified model grid indices (i,j).

wrf_latlon_to_ij

Replaced with wrf_ll_to_ij

wrf_ll_to_ij

Finds the nearest model grid indices (i,j) to the specified location(s) in longitude and latitude.

wrf_overlays, wrf_map_overlays

Functions to overlay multiple plots, created from other ARW WRF plot functions. These functions replace the soon-to-be-obsolete wrf_overlay and wrf_map_overlay procedures.

wrf_smooth_2d

Updated to handle missing data.

wrf_pvo

Calculates potential vorticity from WRF model output.

wrf_user_getvar

Updated to add several new diagnostics:

• "avo" - absolute vorticity [10-5 s-1]
• "cape_2d" - 2D fields mcape/mcin/lcl/lfc
• "cape_3d" - 3D fields cape and cin
• "dbz" - reflectivity [dBZ]
• "mdbz" - maximum reflectivity [dBZ]
• "geopt"/"geopotential" - full model geopotential [m2 s-2]
• "lat" - latitude
• "lon" - longitude
• "p"/"pres" - full model pressure [Pa]
• "pvo" - potential vorticity [PVU]
• "rh2" - 2m relative humidity [%]
• "ter" - model terrain height [m]
• "uvmet" - U and V components of wind rotated to earth coordinates

wrf_user_ll_to_ij, wrf_user_ij_to_ll

Finds the nearest model grid indices (i,j) to the specified location(s) in longitude and latitude (and vice versa).

wrf_user_unstagger

Unstaggers an input variable along a specified dimension.

wrf_interp_1d, wrf_interp_3d_z, wrf_rh, wrf_slp, wrf_td, wrf_tk, wrf_uvmet

Updated to attach named dimensions to the output variable.

New functionality

boxplot

This plotting function now recognizes the gsnMaximize resource.

conform

This function was updated to allow string input.

Support added for GRIB2 files from NWS National Digital Forecast Database

These files are available from http://www.weather.gov/ndfd/anonymous_ftp.htm. (Thanks to Jennifer Adams, GrADS developer, for bringing them to our attention.)

New and updated GRIB 1 NCEP tables

Support was added for the following GRIB 1 tables:

• US Weather Service - NCEP (Parameter table version 133)
• US Weather Service - NCEP Aviation World Area Forecast/ICAO (Parameter table version 140)
• US Weather Service - NCEP (Parameter table version 141)
• Japanese Meteorological Agency (Parameter table version 3)

The following tables were extensively updated:

• US Weather Service - NCEP Oceanographic Parameters (Parameter table version 128)
• US Weather Service - NCEP (Parameter table version 129)
• US Weather Service - NCEP Land Modeling and Land Data Assimilation (Parameter table version 130)
• US Weather Service - NCEP North American Regional Reanalysis (Parameter table version 131)

New GRIB 1 and 2 file option TimePeriodSuffix

A new file option for GRIB 1 and 2 files allows the user to suppress the time period suffix consisting of a numerical quantity and a units indicator (e.g. '6h', meaning a 6 hour time period) from the ends of statistically-processed varables. This allows a user to concatenate variables from different files that for reasons too complicated to go into here differ in the time period suffix, even though they are in fact simply different forecast times of the same variable. By default the value of this option is True, meaning that the suffix appears. Use setfileoption to set it False, which causes the time period suffix to be removed from all statistically-processed variables in NCL's representation of the file. The part of the suffix that indicates the type of statistical processing (e.g. '_acc', meaning accumulation) remains. Be aware that setting this option False can in some cases cause name collisions between variables that should be considered distinct. In this case, variable names after the first instance have an incrementing numerical suffix, beginning with '_1', appended to disambiguate the names.

Simpler method for creating literal values for various integer types

You can now create NCL variables of type long, short, and byte on the fly, using the special literals 'l', 'h', and 'b':

 long_var  = 32l
 short_var = 5h
 byte_var  = 2b

Old way:

 long_var = new(1,long)
 long_var = 32

 short_var = inttoshort(5)

 byte_var = inttobyte(2)

New option to ncl_filedump and ncl_convert2nc to support GRIB 1 and 2 option TimePeriodSuffix

The option TimePeriodSuffix described above is supported in the NCL tools ncl_convert2nc and ncl_filedump as option

[-tps]

The default value is True -- setting this option causes the time period suffix to be removed, as noted above.

rcm2rgrid, rgrid2rcm, rcm2points

These functions have been improved to make them significantly faster in the case where you have multiple grids to interpolate.

Suffixes ".gr", ".gr1", and ".gr2" now recognized as GRIB 1 and 2 suffixes.

gsn_histogram

New attribute "BinLocs" is returned, which is an array of the bin locations on the X axis.

Support added for a convention of setting GRIB1 subcenter octet to 98 (the ECMWF center number)

The French Weather Service apparently uses a convention of setting the GRIB1 subcenter octet to the ECMWF center number to indicate that even though the file is not generated by ECMWF it uses ECMWF parameter tables and local definitions. NCL adds knowledge of this convention to allow certain FWS files to be interpreted correctly. The convention is additionally honored for all ECMWF-associated countries and organizations on the theory that, even if it is only used in France, it is unlikely that the subcenter octet will be set to the value 98 for any other reason.

PopLatLon

This function was updated to recognize the grid destination (grd_dst) "1.9x2.5".

transpose

Handles one-dimensional variables. Improved documentation

ut_calendar / ut_inv_calendar

These functions were updated to add recognition of calendars "360", "365" and "noleap". Thanks to David W. Pierce, the developer of ncview, for these additions.

This ut_calendar function was also updated to add a new option for returning the dates as arrays of integers rather than floats.

Major upgrade for "addfiles"

The file list variable type, which references multiple files as the return value of the addfiles function, has new functionality. Conforming variables aggregated over the file set now are returned with attribute and coordinate variable metadata. Additionally, the leftmost aggregated dimension can now be subscripted correctly using integer, coordinate, or vector subscripting. However, there is currently one caveat for vector subscripts on the leftmost dimension: the array of vector subscripts must be non-decreasing. There can be repeated indexes but no index in the array can be less than a previous index. Hopefully, this restriction will be removed in a future release.

This new functionality replaces the need for using addfiles_GetVar to retrieve variables from a span of files. It will also run faster and be more flexible.

New color tables

• amwg_blueyellowred
• radar

New resources

gsnAboveYRefLineBarFillScales / gsnBelowYRefLineBarFillScales

If gsnYRefLine is set, gsnXYBarChart is set to True, and gsnAboveYRefLineBarPatterns and/or gsnBelowYRefLineBarPatterns are set, then this resource indicates what fill scales to use for the fill patterns. Values less than 1.0 give you a more dense pattern.

gsnPanelScalePlotIndex

This resource allows you to specify which plot being passed to gsn_panel is to be used to determine the scale factor for resizing all the plots. This is useful if the first plot is smaller than of the other plots in the list.

This resource will not be useful if your plots are very different in size.

gsnPolarTime / gsnPolarUT

These resources allow you to turn on labeling using local time instead of longitude labels, for plots generated by one of the gsn_csm_xxxx_polar functions.

gsnXYFillColors, gsnXYAboveFillColors, gsnXYBelowFillColors

These resources can be used to fill between Y curves in an XY plot generated by gsn_csm_xy. See example 24 on the XY applications page.

lgItemOrder

This resource allows you to change the ordering of legend items. See example 9 on the legend applications page for an example.

Updated resources

gsnZonalMean

If this resource is set to True, then a zonal mean XY plot will be drawn next to a contour/map plot. This resource has been around for awhile for the gsn_csm_contour_map_ce function, and it now works for the gsn_csm_contour_map function (polar plots excepted).

vpClipOn

This resource is now recognized by the XyPlot, and hence if set to True, markers that fall outside the plotting area will be clipped. Note: to maintain backwards compatibility, this resource defaults to False for xy plots.

Bug fixes

cssgrid, csc2s

Fixed a bug in which if some of the input data arrays contained missing values, they were not being ignored as advertised.

dpres_plevel

Fixed a bug which occurred when the surface pressure was exactly 1000hPa or 100000Pa.

eofunc_varimax_reorder

This function is actually called "eof_varimax_reorder" in versions 4.3.1 and 5.0.0. It was supposed to be "eofunc_varimax_reorder"; this has been fixed in 5.1.0.

gsn_csm routines that overlay vectors/streamlines and contours on the same plot.

Fixed a problem where the gsnAddCyclic resource was not always being set correctly in gsn_csm functions that overlay both contours and vectors in a single plot (gsn_csm_streamline_contour_map, gsn_csm_vector_scalar, gsn_csm_vector_scalar_map_ce, etc).

RasterFill contour mode

Fixed a bug that sometimes resulted in the data cells being slightly misaligned when plotted over a global map when in raster fill mode without smoothing. Also fixed a problem that caused irregular coordinates to be treated as regularly spcaed when they were close (but not close enough) to a regular spacing.

Memory bug

Fixed a significant bug that resulted in an unnecessary copy of a data variable when assigned to a file variable with the (/ /) syntax (to indicate that attributes are not to be copied). Even if you specify that you don't want attributes written, NCL still needs to check to make sure the _FillValue attributes are the same. If not, then it doesn't try to change the file variable fill value (because you are not copying attributes), but instead it has to make a copy of the variable you are assigning in order to ensure that its missing values are updated to match the fill value that is assigned to the file variable.

The logic was wrong and it was copying the variable even when the fill values were the same.

GRIB 1 reader

1. Fixed a bug that resulted in incorrect coordinates being generated for Lambert Conformal grids over the Southern hemisphere.
2. In order to fix a problem reading WRF GRIB files, if a GRIB record has the grid number octet set to 0, it is treated as meaning the same as if it were set to 255. Both these values are now assumed to mean that the grid is defined in the GDS (Grid Description Section) part of the GRIB record. This change will be visible to users: it will result in changes to the names of dimensions, coordinate variables, and regular variables. Note that the developers of the WRF GRIB output code have a agreed that setting this octet to 0 is an error on their part and that in the future it will be set to 255. This change to NCL ensures that current and future WRF GRIB files will have the same naming scheme when opened in NCL.
3. Modified the scaling of certain instances of the 'Dx' and 'Dy' coordinate variable attributes to ensure that the units for these values can uniformly be assumed to be in meters. Prior to the change, in a few cases the units were kilometers.
4. Fixed a problem that resulted in a core dump when the record representing the first horizontal slice of a variable array was missing.

GRIB 2 reader

1. Modified the way the GRIB2 codetable path is determined. Now if the NIO_GRIB2_CODETABLES environment variable is set it takes precedence over the common path found through NCARG_ROOT.
2. Fixed a problem that resulted in a core dump when the record representing the first horizontal slice of a variable array was missing.

NetCDF reader/writer

Fixed a problem that occurred when a single execution of NCL results in more than 32767 separate NetCDF file opens and closes. The id returned by the NetCDF library can become a negative value in this case. NCL was treating this condition as an error when it is actually legitimate.

OPeNDAP-enabled versions of NCL

Fixed a bug that resulted in the following error when exiting NCL after opening any local NetCDF file or any remote file served by OPeNDAP:

ncclose: ncid 0: NetCDF: Not a valid ID

If a local file is opened for writing this error could result in loss of data in the file. The workaround for earlier versions of NCL is either to ensure that all NCL file variables are deleted before exiting, or, to use setfileoption to set both the options DefineMode and SuppressClose to False.

Problem involving files with very large dimensions (larger than around 10 million elements)

Fixed a bug that resulted in the return of incorrect data when requesting a variable subset from a file where one of the dimensions has more than around 10 million elements.

Version 5.0.0

6 November 2007

• Open source!
• New tool for checking validity of SCRIP input grid files
• New functions
• New functionality
• New resources
• Performance enhancements
• Bug fixes

Open source

This is our first official open source release for NCL.

This release also includes full source code and binaries for NCAR Graphics, so you no longer have to install the two packages separately.

New tool for checking validity of SCRIP input grid files

A new tool called "scrip_check_input" tests whether the coordinates of all cells in a SCRIP input grid file are entered in counterclockwise order and also tests whether the cell centers are in the interior or on the boundary of the cells.

New functions

generate_unique_indices

Generate unique, random integer subscripts.

Suite of color conversion functions

hlsrgb - Converts HLS color values to RGB.

hsvrgb - Converts HSV color values to RGB.

rgbhls - Converts RGB color values to HLS.

rgbhsv - Converts RGB color values to HSV.

rgbyiq - Converts RGB color values to YIQ.

yiqrgb - Converts YIQ color values to RGB.

maximize_output

This is not a new function, but one that hadn't been documented. It allows you to maximize the size of plots that have been drawn in a single frame.

status_exit

A new version of the exit procedure that allows the user to pass an exit status code to the operating system.

vintp2p_ecmwf

Interpolates data at multidimensional pressure levels to constant pressure coordinates and uses an ECMWF formulation to extrapolate values below ground.

stat2, stat4, stat_medrng, stat_trim, dim_stat4

These functions were updated so that if a subsection of the input is all missing, a fatal error is no longer issued. Rather, all missing values will be returned in the appropriate locations in the output array.

system

This function was updated to allow the user to turn off paging of output from this command, if desired.

cnLabelBarEndStyle

This resource allows you to select from among three styles for the ends of contour plot labelbar. The cnLabelBarEndLabelsOn resource is now deprecated and replaced with this one.

• The GRIB code was improved to eliminate unnecessary memory usage when reading a variable that contains "missing" records. (Missing records occur when a GRIB file does not have records corresponding to all the elements of its dimensions as defined by NCL.) Formerly NCL created an array filled with missing values for each missing record. Now it only creates a single such array for each distinct grid in the file and shares this array among all the missing records of each variable that shares the grid.

• Along with the above change, the ncl_convert2nc script was modified to copy very large variables in multiple chunks using loops and subscripting. Given large enough variables (greater than 250 MB), this can dramatically reduce memory requirements on the system without adversely affecting execution time.

Bug fixes

• wmstnm - correction to the wind barb directions when station model data is displayed over a map.

• v5d_write - fixed a bug whereby input values for the number of timesteps and the number of variables were tested improperly. Documentation has been updated to reflect this fix, and the proper calling sequence for this function.

• The NCL object table code was reworked to remove a limit of 2^31 - 1 on the total number of objects that could be created. The table was also reconfigured to improve performance for complex scripts where very large numbers of objects are created.

• The exit procedure now ensures that graphics and data files are properly closed before NCL's execution ends.

Version 4.3.1

10 August 2007

• ARW WRF functions
• Partial support for NetCDF 4
• New functions
• Low-level three-dimensional visualization routines
• New functionality
• New resources
• Bugs fixed

Added a suite of routines to aid in visualizing ARW WRF model data.

wrf_contour - Creates a contour plot from ARW WRF model output.
wrf_map - Creates a map background for ARW WRF model data.
wrf_map_overlay - Overlays different plot id's over a map background.
wrf_map_zoom - Zooms into a portion of the ARW WRF model domain, and creates a map background.
wrf_overlay - Overlays multiple plots, created from other ARW WRF plot functions.
wrf_user_getvar - Extracts data from ARW WRF model output, and does basic diagnostics calculations.
wrf_user_intrp3d - Interpolates ARW WRF model data vertically or horizontally.
wrf_latlon_to_ij (built-in function) - updated to return missing values if any of the input lat/lon values are out-of-range.
wrf_user_list_times - Extracts the list of available times in the ARW WRF model output.
wrf_vector - Creates a vector plot from ARW WRF model output.

Partial support for NetCDF 4

For some systems (*), you can now specify a "Format" of "NetCDF4Classic" in the setfileoption procedure to create a file using the NetCDF 4 classic model format. The classic model constrains the interface to the constructs provided by NetCDF 3 and earlier. However, the underlying file format, like that of all NetCDF 4 files, is HDF 5. Files written in this format can take advantage of the built-in file compression available in HDF 5. Use the "CompressionLevel" option to enable compression. Also the HDF 5 format removes virtually all restrictions on file and individual variable size. NCL version 4.3.1 provides beta-level support for this format because NetCDF 4 and the release of HDF 5 that it depends on are both still in the beta-testing phase of development. It should probably not be used for mission-critical file creation.

This option is not required for reading NetCDF 4 classic files. If your version of NCL supports NetCDF 4 (*), then it will be able to automatically detect whether you have a NetCDF 3 or 4 file.

(*) Some systems (like any 64-bit system) do not have support for NetCDF 4 because the NetCDF 4 software has not yet been ported and/or tested on those systems. You can quickly tell if your version of NCL has NetCDF 4 support by running ncl interactively and typing one line:

  setfileoption("nc","format","netcdf4classic")

warning:FileSetFileOption: invalid value supplied for option format

    setfileoption("nc","compressionlevel",5)

New functions

dim_sum_wgt_Wrap

Computes the weighted sum of a variable's rightmost dimension at all other dimensions *and* retains metadata.

eofunc_varimax_reorder

Reorder the results returned by eof_varimax into descending order by percent variance explained.

filwgts_lanczos

Calculates one-dimensional filter weights. This is not a new function, but a renaming of the old filwgts_lancos function. The old function will remain intact for backwards compatibility.

dim_sum_wgt_Wrap

Computes the weighted sum of a variable's rightmost dimension at all other dimensions and retains metadata.

Suite of gc_xxxx functions

gc_aangle - finds the acute angle between two great circles on the globe.
gc_clkwise - tests clockwise/counterclockwise ordering of points on spherical polygon.
gc_dangle - finds the directed angle between two great circles having a specified intersection point.
gc_inout - determines if a specified point is inside or outside of a spherical polygon.
gc_onarc - determines if a point on the globe lies on a specified great circle arc.
gc_pnt2gc - finds the angular distance from a point to a great circle.
gc_qarea - finds the area of a quadrilateral patch on the unit sphere.
gc_tarea - finds the area of a triangular patch on the unit sphere.

getVarFillValue

Retrieves the missing value of a variable; otherwise, it returns the default _FillValue.

poisson_grid_fill

Replaces all _FillValue values in a grid with values derived from solving Poisson's equation via relaxation.

A suite of 3D visualization routines based on the low-level TDPACK package were added. There are too many to list here, but you can see them by visiting the graphics routines page, and looking at the functions that start with "td".

New functionality

• betainc - missing values are now recognized and handled accordingly.

• write_matrix - updated to handle data of type short and byte.

• setfileoption - fundamental change in the writing of netCDF files - the "SuppressClose" and "DefineMode" options now both default to True. Also, the addition of the "NetCDF4Classic" value for the "Format" option. See the section on partial support for NetCDF 4.

  In previous versions, when you wrote data to a netCDF file, the netCDF file was opened and closed before and after every write. You could turn this off by using setfileoption to set the "SuppressClose" option to True. This is now the default, which should improve performance.

  In previous versions, also, the "DefineMode" option was set to False by default, which meant that each write operation was performed atomically. It now defaults to True, which can improve performance dramatically if care is taken to define all dimensions, attributes, and variables and assign attribute values before writing actual data to the file.

• stringtodouble - updated to recognize 'd' and 'D' as additional double-specific exponent specifiers optionally substituting for 'e' and 'E'.

• New options "-itime" and "-ftime" in ncl_convert2nc and ncl_filedump

• gsnDebugWriteFileName - a resource to help facilitate the debugging of NCL gsn_xxxx and gsn_csm_xxxx visualization scripts.

  If you set this resource to a string and rerun the plotting script you are having problems with, then it will write the data being plotting and the plot resources and their values to a new netCDF file. It will also create a new NCL script that reads in this new netCDF file and sets all the same plot options, so that your plot can be recreated identically. This prevents users from having to send us their full scripts and data. The new files will be called xxx.nc, xxx.ncl, and xxx.res, where xxx is what the resource is set to.

  To use this resource before version 4.3.1 is available, download gsn_code.ncl.debug and gsn_csm.ncl.debug, put them in $NCARG_ROOT/lib/ncarg/nclscripts/csm (or wherever you want), and then load these scripts instead of the original ones:

    load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl.debug"
    load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl.debug"
  

  Rerun your script with res@gsnDebugWriteFileInfo set to whatever string you like, and then you can give us the resultant new netCDF and NCL script.

• ShadeCOI - fixed a bug in which the function would fail if the input "time" variable was not a float.

• triple2grid - fixed a serious bug. Please see the function documentation for more information.

• Fixed a problem encountered in reading a netCDF file where the data variable type was float, there was no _FillValue, but there was a missing_value attribute of type double. Since "MissingToFillValue" is True by default, NCL was creating a virtual _FillValue of the same type and value as the missing_value. This resulted in NCL becoming confused when the file variable was assigned to a regular variable because the _FillValue attribute of regular variables is not allowed to be anything other than the same type as the variable.

  This is being fixed by overriding the MissingToFillValue setting and refusing to create the virtual _FillValue. The following warning is issued for each such variable:

      warning:NetOpenFile: MissingToFillValue option set True, but missing_value
      attribute and data variable (x) types differ: not adding virtual _FillValue
      attribute
  

• Fixed a problem with reading a NetCDF file when a 1D variable and a dimension name have the same name, but the 1D variable is not a coordinate variable and is a different size from the dimension it shares a name with.

• Fixed a problem in the GRIB1 reader that resulted in a core dump when reading files that contain GDS grids of the same type but different sizes.

Version 4.3.0

1 May 2007

• New GRIB2 reader
• New features available for both GRIB 1 and 2
• Important changes to GRIB1 reader interface - PLEASE READ
• Other changes to the GRIB1 reader
• Possible incompatible change to getFillValue function
• New functions
• New functionality
• New resources
• New color tables
• Important bug fixes

New GRIB2 reader

This version of NCL includes a new GRIB2 reader. GRIB2 files are supported by addfile, addfiles, ncl_filedump, and ncl_convert2nc.

Detailed information is available in the "Information on supported data formats" section of the NCL Reference Manual.

New features available for both GRIB 1 and 2

• NCL now supports GRIB files containing ensemble forecasts with multiple ensemble members or probability forecasts (which are derived from ensemble forecasts) with multiple thresholds. These files are represented with an "ensemble" or "probability" dimension. Actually the ensemble dimension (but not the probability dimension) has been available since 4.2.0.a34 but was inadvertently not mentioned in those release notes. These dimensions will be described in more detail in the "Information on supported data formats" section of the NCL Reference Manual.

• A new GRIB file option named "SingleElementDimensions" allows the user to specify that variables with only a single initial time, forecast time, level, ensemble or probability value, usually handled as attributes, be treated as containing single element dimensions. The option allows any or all of these attributes to be turned into dimensions provided they have an actual value. This is described in more detail in the setfileoption procedure documentation.

Important changes to the GRIB1 reader interface - PLEASE READ

• Fundamental change to reading of GRIB1 files - the default type for the "initial_time" coordinate array has been changed from "string" to "numeric".

  Prior to version 4.3.0, NCL used an array of strings to represent the coordinate values of an initial time dimension. This representation proved to be problematic, both because it did not conform to standard CF and COARDS conventions, and because it was difficult to use in a context where numerical properties such as monotonicity were usually expected.

  To change the type back to "string", you can set the "InitialTimeCoordinateType" option in the setfileoption procedure:

    setfileoption ("grb","InitialTimeCoordinateType","string")
  

• Change to default algorithm used for dealing with thinned grids on a GRIB file - the default used to be linear interpolation, but since cubic interpolation has been shown to produce better results, we've made cubic interpolation the default.

  To change the type back to "linear", you can set the "ThinnedGridInterpolation" option in the setfileoption procedure:

    setfileoption ("grb","ThinnedGridInterpolation","linear")
  

  "Linear" is still the default for bitmask arrays.

Possible incompatible change to getFillValue function

For example, in the line below:

  q = new( 10, typeof(w), getFillValue(w))

In release a034, the string "No_FillValue" was introduced for use within the new statement. Use of "No_FillValue" as the third argument of new would result in no _FillValue being assigned to "q".

A side effect of this new behavior is that the following will result in a fatal error:

  q@_FillValue = getFillValue(w)

It should be noted that getFillValue was only intended to be used within the new statement.

Other changes to the GRIB1 reader

• The GRIB1 reader can now handle files that are greater than 2GB in size.

• The built-in GRIB1 parameter tables describing data from the DWD (German National Meteorological Service) have been updated to reflect new variables. As well, new tables have been added. These updated and new tables are referenced in the NCL Reference Manual section for GRIB data.

• NCL now recognizes a DWD-specific extension that allows it to distinguish between satellite image records that all have the same parameter number and parameter table version.

• NCL also recognizes the DWD convention for specifying hybrid level values.

• The GRIB1 reader has been modified to handle varying time units for variables that have records with different time units indicators. See:

  http://www.nco.ncep.noaa.gov/pmb/docs/on388/table4.html

  If in parsing a record that belongs to a particular variable it encounters a time unit indicator different from the established indicator, it compares them and chooses the one with the shortest duration to be the common unit. Then it sets the time period for each record based on converting it into the common units. For periods of a month or greater, this is currently not entirely accurate, because it is based on a year of 365.25 days and the average number of hours in a month. However, because no files of this type have yet been encountered (and may never be), it does not seem worthwhile to develop anything more accurate at this point. The code does print warnings (probably too many) if this situation is encountered.

• The GRIB1 reader prints more variable attributes. An attribute called parameter_table_version contains the parameter table version to which the variable parameter number belongs. If forecast_time is an attribute (no forecast_time dimension is associated with the variable) an associated attribute called forecast_time_units gives the units of the forecast_time value.

New functions

cumsum

Calculates the cumulative sum.

dim_cumsum (dim_cumsum_Wrap)

Calculates the cumulative sum along the rightmost dimension (and retains metadata).

dpres_plevel (dpres_plevel_Wrap)

Calculates the pressure layer thicknesses of a constant pressure level coordinate system (and retains metadata).

fft2db

Performs a two-dimensional discrete backward Fourier transform (Fourier synthesis).

fft2df

Performs a two-dimensional discrete forward Fourier transform (i.e., Fourier analysis) of a real periodic array

gsn_contour_shade

Shades contour regions given low and/or high values using colors or patterns.

gsn_table

Draws a table with text.

ind_nearest_coord

Determines indices of locations closest to a coordinate array.

indStrSubset

Returns the indices corresponding to the location of the substring, if it is a subset of the other given string.

isStrSubset

Returns True or False if one string is a subset of another string.

mod

Emulates the Fortran "mod" intrinsic function.

printMinMax

Prints the minimum and maximum values of a variable.

student_t

Calculates the two-tailed probability of the Student-t distribution.

where

Performs array assignments based on a conditional array.

New functionality

cz2ccm

This function was updated to allow "phis" to be three dimensions.

eofunc

The scaled eigenvalues are now returned.

eofunc_varimax

Previously, this function (a) did not return the percent variance explained and (b) did not allow missing (_FillValues). Both issues have been addressed. Additional options have been added to specify the form of the returned matrix.

fbindirread, fbindirwrite, fbinrecread, fbinrecwrite, fbinnumrec

These functions were updated to allow reads and writes of files that are greater than 2 GB in size. Note that this change allows you to access records that occur past the 2 GB point in the file, but not to read into variables that would be larger than 2 GB. Thus, there is no improvement to cbinread, cbinwrite, fbinread, fbinwrite because they read/write the complete file starting from the beginning into or out of a single variable.

gsn_histogram

Added three new attributes: BeginBarLocs, MidBarLocs, and EndBarLocs. See histogram example 12 for usage.

hyi2hyo

If the intflg argument is set to one,values outside of the input pressure range will be set to the values of the closest input pressure value.

getFillValue

Updated so that if no _FillValue or missing_value attribute is present, it does not return a _FillValue.

pres2hybrid

Now allows two options for extrapolating the data.

print, printVarSummary, printFileVarSummary

All the printing procedures have been updated to print the actual values of array-valued attributes instead of the notation <ARRAY> as long as the array has 10 or fewer elements.

vinth2p_ecmwf

This function was updated to allow "datai" to be five dimensions.

wmbarb

Recognizes data with missing values and does not plot wind barbs in those places. Also, can now input arrays of any dimension.

wmbarbmap

Recognizes data with missing values and does not plot wind barbs in those places.

New resources

gsnContourPosLineDashPattern

Allows you to set a dash pattern for contour lines above the value 0.0.

gsnPanelXF, gsnPanelYF

Allows you to change the X and Y positions of the upper left corner of individual plots in a set of paneled plots. See example 19 in the panel applications page.

gsnPanelDebug

If set to True, turns on debug information for gsn_panel. See example 19 in the panel applications page.

New color tables

• BlueDarkOrange18
• BlueDarkRed18
• BlueGreen14
• BrownBlue12
• Cat12
• GreenMagenta16
• posneg_1
• posneg_2
• prcp_1
• prcp_2
• prcp_3
• StepSeq25

Important bug fixes

Fix to annoying "<identifier> IS A FUNCTION NOT A PROCEDURE" fatal error mesage.

Before this version, if you called an NCL function but treated it as a procedure (i.e. didn't assign it to a variable), you would get a useless error message:

fatal:syntax error: <identifier> IS A FUNCTION NOT A PROCEDURE

This has been fixed so you should now get the name of the function, as well as the line number it occurred on. For example:

ncl 0> abs(-1)
fatal:syntax error: abs is a function not a procedure; return value must be referenced
fatal:error at line 0
ncl 1> 

Bug in clmMon2clmDay

The linint1_Wrap function was invoked prior to being loaded within contributed.ncl. This will be fixed in 4.3.0, but you can fix it yourself by moving clmMon2clmDay after linint1_Wrap is defined.

Bug in dtrend and dtrend_msg

If return_info was set to True, and the input y was double and had more than one dimension, then you would get a segmentation fault or incorrect results.

Bug in reading HDF variable attributes of type string that have null characters in them.

If NCL read in an HDF file that had an attribute with null characters in it, then the attribute value was truncated at that first null character. This bug has been fixed, and the null characters are replaced with a single space (but only if there are more non-null characters after it).

Memory leak fixed

A user reported a memory leak problem in which the way you implement a logical expression in an "if" statement had a serious effect on your code if executed multiple times. The code:

   if (flags(x)) then

was not working as efficiently as this code:

   if (flags(x).eq.True) then

Optimization problem (not a bug!) with hyi2hyo on Linux systems.

There was an odd optimization problem with hyi2hyo on Linux systems that would cause it to think you were trying to pass in a 1D array for xi, when you indeed had a 3D array.

Bug in lspoly

lspoly would only work if the input was float or double.

Bug in 'mpSpecifiedFill[Colors,Patterns,Scales] resources

The mpSpecifiedFillColors, mpSpecifiedFillPatterns, and mpSpecifiedFillScales resources were not working because of changes introduced to handle subarea group designators such as "counties" and "states".

Bug in numAsciiRow

If you call numAsciiRow, it may appear to hang. This will be fixed in 4.3.0, but you can fix it yourself by editing the file:

$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl

and changing the line:

  nrow_s    = systemfunc("'wc' -l" + fNam +" | awk '{print $1}'" )

to have a space after the "-l":

  nrow_s    = systemfunc("'wc' -l " + fNam +" | awk '{print $1}'" )

Bug in rtest

rtest did not check the size of the Nr argument. Now if Nr<3 the returned value(s) will be set to the appropriate _FillValue.

Version 4.2.0.a034

26 September 2006

New applications

ncl_convert2nc

Converts one or more GRIB, HDF and/or HDF-EOS files to netCDF formatted files. Note: this application is replacing ncl_grib2nc which has been deprecated in this release.

New functions

array_append_record

Attaches [appends] additional records [leftmost dimension] to a previously existing array.

cdft_p

Calculates the probability given a t-value and the degrees of freedom.

cdft_t

Calculates the t-value given the probability and the degrees of freedom.

clmMon2clmDay

Creates a daily climatology from a monthly climatology.

delete_VarAtts

Deletes one or more attributes associated with a variable.

dim_avg_wgt and dim_avg_wgt_Wrap

Computes the weighted average of a variable's rightmost dimension at all other dimensions. The _Wrap version of this function retains metadata.

dim_sum_wgt

Computes the weighted sum of a variable's rightmost dimension at all other dimensions. dim_sum_wgt_Wrap, which retains metadata, was inadvertently not added in this version. (It will be added in version 4.3.1.) If you need this function, email Dennis Shea.

erf/erfc

Evaluates the real error function and the real complementary error function respectively.

get_file_suffix

Returns the suffix of a file name.

gsn_add_annotation

Adds an annotation to a plot.

gsn_create_labelbar

Creates a labelbar. This function is similar to the procedure gsn_labelbar_ndc, except it returns the id of the labelbar, which can then be used with functions like gsn_add_annotation.

gsn_create_legend

Creates a legend. This function is similar to the procedure gsn_legend_ndc, except it returns the id of the legend, which can then be used with functions like gsn_add_annotation.

isbigendian

Returns True if you are on a big endian machine.

isMonotonic

Checks one-dimensional array for monoticity.

loadscript

Loads the given NCL script.

lspoly

Calculates a set of coefficients for a weighted least squares polynomial fit to the given data.

niceLatLon2D

Checks two-dimensional latitude and longitude arrays for "nice" structure.

pres2hybrid and pres2hybrid_Wrap

Interpolates data on constant pressure levels to hybrid levels.

rho_mwjf

Computes ocean water density given a specified range for potential temperature (deg Celisus) and salinity (psu).

rip_cape_2d

Computes convective available potential energy (CAPE), convective inhibition (CIN), lifted condensation level (LCL), and level of free convection (LFC).

rip_cape_3d

Computes convective available potential energy (CAPE) and convective inhibition (CIN).

stdatmus_p2tdz

Calculates the corresponding temperature, density, and height based on the 1976 U.S. standard atmosphere, given the pressure.

stdatmus_z2tdp

Calculates the corresponding temperature, density, and pressure based on the 1976 U.S. standard atmosphere, given the height.

strlen

Returns the length of a string variable.

table_attach_rows

Attaches [appends] additional rows to a previously existing two-dimensional [table] array.

wgt_vert_avg_beta

Computes weighted vertical average or sum using pressure thickness and beta factors.

wrf_rh, wrf_tk

Calculate relative humidity and temperature from WRF model output.

yyyymmdd_to_yyyyfrac

Converts a one dimensional array containing yyyymmdd values to yyyy and fractional year.

yyyymmddhh_to_yyyyfrac

Converts a one dimensional array containing yyyymmddhh values to yyyy and fractional year.

New functionality

new statement

The new statement has a new value you can use for the optional third argument: "No_FillValue". If you set this, then the variable created by new will not have a _FillValue attribute attached to it, and the values in the variable will be undefined.

NCL can now parse MS-DOS style end-of-line characters.

These characters sometimes show up as "^M" or "\r" characters in certain ASCII editors.

Strings in NCL can now be longer than 256 characters.

NCL was updated so that you can now have strings longer than 256 characters, within the memory limitations of the system, of course. Note that symbols (variable, dimension, and attribute names) still are limited in length to 256 characters.

abs and fabs

The abs function will supercede fabs, as it will accept all supported numeric data types, and its return value will be of the same type as its input. Function fabs will continue to be available, and support the float and double data types only.

gc_latlon

This function was updated to allow multi-dimensional input for the latitude, longitude arrays.

setfileoption

This function was updated to include two more options: DefaultNCEPPTable and MissingToFillValue.

stat2, stat4, stat_trim, stat_medrng

These functions were updated to allow numeric input, and float or double output.

triple2grid

This function was updated to allow the third argument to be multi-dimensional.

vinth2p

This function was updated to allow the first argument to have up to 5 dimensions.

New resources

mpMaskOutlineSpecifiers and mpOutlineMaskingOn.

These resources allow you to turn on map outline masking and indicate which outlined map areas you want to "mask" from your plot. They should be used in conjunction with mpOutlineSpecifiers and/or mpOutlineBoundarySets.

Important bug fixes

Bug in exp_tapersh procedure

We fixed a bug in which if your input values were not double, the weights aren't being applied to the data, and hence you got the same values back.

Bug in single value coordinate subscripting, when coordinate values were decreasing.

We fixed a bug in which if you had decreasing coordinate array values, and you selected a single value using coordinate subscripting, NCL was returning the wrong closest index.

Bug in coordinate array returned for a variable that was created by reversing the stride of an existing variable, e.g. b = a(1::-2)

We fixed the above bug, and it will be in the next release of NCL.

Bug in line number reporting for NCL error messages.

Sometimes the line numbers for NCL error messages were off by one. This has been fixed in this release.

Bug if you didn't have a newline after the very last line in your NCL script.

In previous versions of NCL, if you didn't have a after the very last line in your NCL script, you would get a confusing and fatal error message:

fatal:syntax error: line -1 before or near  

This has been fixed in this release, and you won't get any error message.

Bug in shsgC/shsgc

A user discovered a bug in these functions that would cause NaNs (not-a-number) to be returned if the input variable was over a certain size. The latest version of the Spherepack library (V3.1) fixes this problem, so we incorporated this library into this version of NCL.

GRIB bugs

There was a "bug" encountered with the monthly GODAS files where monthly average variables were given different names depending on the number of days in the month. Now, if the calculations work out properly to show that the first day of the time period is the 1st day of the month and the last day of the time period is the last day of the month, then the suffix applied is "ave1m" instead of "aveXXd". Leap years are accounted for.

There was a bug in GRIB code's handling of time indicator index 10 in which the indicator index wasn't being tacked on to the variable name.

Paging bug with print functions

If you used printing functions like print or printVarSummary interactively in version a033, the output would scroll continuously and not allow paging.

Bug with setting NCL_DEF_SCRIPTS_DIR or NCL_DEF_LIB_DIR to invalid directories.

If you set the environment variables NCL_DEF_SCRIPTS_DIR or NCL_DEF_LIB_DIR to invalid directories, you may get a bus error or a segmentation fault, followed by a core dump. To work around this problem, don't set these environment variables, or set them to valid directories.

Bug in with using markers in an XY plot when missing values were present.

We fixed a bug in which if you were generating an XY plot with markers, and your X or Y values contained missing values, the markers were still appearing.

Version 4.2.0.a033

23 January 2006

Command line arguments and options The next version of NCL will have a long-requested enhancement added, and that is the ability to include options and arguments on the NCL command line. For more information and some examples, see the "Command line arguments and options" section in the NCL Reference Manual.

Command line tools

ncl_filedump

Prints the contents of supported files (netCDF, HDF, GRIB, HDF-EOS2, and CCM History Tape).

ncl_grib2nc

Converts NCL-supported GRIB files to netCDF-formatted files.

calcDayAnomTLL

Calculates daily anomalies from a daily climatology.

cancor

Performs canonical correlation analysis between two sets of variables.

clmDayTLL

Calculates daily climatology from daily mean data.

echo_on/echo_off

These procedures toggle the echoing of NCL statements as they are encountered. You can use them in conjunction with the new "-x" command line option.

generate_2d_array

Generates a "nice" 2D array of pseudo random data, especially for use in 2D graphics.

gsn_csm_xy3

Creates and draws an XY plot with three different Y axes.

This function is similar to gsn_csm_xy2 except it allows three vertical scales for three different quantities.

hyi2hyo, hyi2hyo_Wrap

Interpolates from data on one set of hybrid levels to data another set of hybrid levels.

local_min_1d, local_max_1d

Determines the relative minima/maxima for a 1-dimensional array.

omega_ccm, omega_ccm_driver

Calculates omega (vertical pressure velocity) using the model diagnostic method.

pack_values

Compress (pack) values of type float or double to values of type short or byte.

setfileoption

This procedure allows the user to set a number of file-format-specific options. It has an option to determine the algorithm used for expanding thinned data from a GRIB file, an option for indicating whether a binary file should be read or written as big endian or little endian, and several options for the writing of netCDF files which can significantly speed up this process.

shsgc_R42, shsgc_R42_Wrap

Computes spherical harmonic synthesis of a scalar quantity via rhomboidally truncated (R42) spherical harmonic coefficients onto a (108x128) gaussian grid.

smthClmDayTLL

Calculates a smooth mean daily annual cycle.

yyyymm_time

Creates a one-dimensional array containing year-month [yyyymm] values.

yyyymm_to_yyyyfrac

Converts a one dimensional array containing yyyymm values to yyyy and fractional year [eg: 1973.25]. Most frequently used to create a one-dimensional array used for "x-y" plots.

z2geouv

Computes the geostrophic zonal and meridional wind components using geopotential height.

New functionality

asciiread

This function has been enhanced in the reading of float values to avoid treating "nan" or "inf" as numeric values if they occur as part of a word such as "nanny" or "infidel".

copy_VarCoords

Made this function more flexible; it can now handle the tasks that copy_VarCoords_1 and copy_VarCoords_2 used to do.

gsn_histogram

A new resource called gsnHistogramBarWidthPercent has been created that allows you to specify the width of the histogram bars as a percentage of the width of the bin that it falls in. The values must be in the range 0 to 100, and they must be smaller for comparison histograms.

New map projections

Two new map projections have been added, "CylindricalEqualArea" and "RotatedMercator". For more information, see the mpProjection resource in the list of map (mp) resources.

Line resources in map (mp) resources

Enabled support for the "transparent" color index for the following map line resources:

• mpGeophysicalLineColor
• mpUSStateLineColor
• mpNationalLineColor
• mpGridLineColor
• mpLimbLineColor
• mpPerimLineColor
• mpLabelFontColor

Any gsn_csm non-map plotting script.

Previously, for functions like gsn_csm_vector and gsn_csm_contour, the special "lat2d" and "lon2d" attributes were not recognized. This is because generally, you only want to use this kind of information when you are creating a contour or vector plot over map.

However, if you want to overlay multiple contour and/or vector plots on a map, you need to be able to create them using gsn_csm_vector and gsn_csm_contour so you can then use them in an overlay call.

So, the "lat2d" and "lon2d" special attributes are now recognized by these kind of gsn_csm routines.

natgrid, natgrids, natgridd

These functions now do automatic culling of duplicate input coordinate points. Given this, the previous "dup" parameter has been made obsolete.

psplit

Added a "-c" option that flags psplit to simply report the number of pages in the input file and exit.

Printing strings that contain missing values.

If you try to concatenate a value that a missing to a valid string, and then print the string, you would getting nothing but a missing value:

  x = new(1,float)
  print("x = " + x)

would produce:

(0)     -999

With the next release of NCL, you will get:

(0)     x = -999

Important bug fixes

eofunc

The version of eofunc in Version 4.2.0.a032 had an error. The exact nature of the error was never determined. Prior to release in a032, the eofunc function had been tested by five different people and all agreed it was correct. After release of a032, some users reported small differences with previous results. One user reported a major problem. As a result, the eofunc documentation was modified to include a notice printed in red that recommended that users use the older eofcov or eofcor functions.

The new eofunc included in a033 uses a completely different program to calculate EOFs.

GRIB reader

In the last release (4.2.0.a032) of NCL, two new time variables were introduced for GRIB data being read in. Of these, the new variable "initial_time0_hours" (units: "hours since 1800-01-01 00:00") was found to be off by 48 hours. The other time related variables "initial_time0_encoded" (units "yyyymmddhh.hh_fraction") and "initial_time0" (units "mm/dd/yyyy (hh:mm)") are correct.

This "off by 48 hours" has been fixed for a033.

The a032 temporary work-around was as follows: for times after 1900-01-01 00:00, 48 hours had to be added to the values returned by NCL.

The second "fix" to the GRIB reader was not so much a fix as a removal of a hard-coded upper limit for the size of lat/lon arrays for thinned grids.

linmsg

This function was not correctly handling the case where a whole row of points was missing.

qsort

A problem was fixed in which the following short script was using up a bunch of memory:

begin 
 do i = 0,200 
  print((/i/)) 
  x1D = new((/4000000/),integer) 
  x1D = 1 
  qsort(x1D) 
  delete(x1D) 
 end do 
end 

solve_linsys

This function was not working correctly if the leftmost dimension of B was not the same as the rightmost dimension.

vcMapDirection

Fixed a bug where this resource was not taking effect when in curly vector mode.

Version 4.2.0.a032

6 December 2004

New and updated functionality

• Contouring non-uniform grids

  In recent years, many new non-uniform grids have become popular and these are being processed by new algorithms to reduce them to triangle meshes and to contour directly on these triangles, rather than interpolating to a uniform grid and contouring.

  For more information, see the short document on non-uniform grids that NCL can contour, and the following example sections: SEAM (HOMME) grids, Geodesic grids, and Adaptive grids.

• addfile/addfiles

  File suffixes recognized by these two functions are now case insensitive. For example, ".nc" and ".NC" are both recognized as representing netCDF files.

• OPeNDAP-enabled NCL

  NCL now has OPeNDAP (formerly known as "DODS") capabilities built into it, but only for systems that OPeNDAP is supported on (Linux, Solaris, AIX). What this means is that you can use functions like addfile and isfilepresent to access netCDF datasets served by an OPenDAP server.

  Here's an example and also a way to test if your version of NCL is OPeNDAP-enabled:

  begin
  ;
  ; The URL is so long, break it into two pieces.
  ;
    url      = "http://www.cdc.noaa.gov/cgi-bin/nph-nc/Datasets/"
    filename = "ncep.reanalysis.dailyavgs/pressure/air.1948.nc"
   
    exists = isfilepresent(url+filename)
    if(.not.exists) then 
      print("OPeNDAP test unsuccessful.")
      print("Either the file doesn't exist, or NCL does not have")
      print("OPeNDAP capabilities on this system")
    else
      f = addfile(url + filename,"r")
  ;
  ; "variables" should be equal to 
  ; (/"air","time","lon","lat","level"/)
  ;
      variables = getfilevarnames(f)
    end if
  
  end
  

• New special resources for contour lines: gsnContourZeroLineThicknessF, gsnContourLineThicknessesScale, and gsnContourNegLineDashPattern.

  Respectively, these resources allow you to specify the line thickness of the zero contour, specify a scale factor to apply to the current line thicknesses, and specify a dash pattern for negative contours. For some examples, see the contour effects examples.

• New EOF functions

  The eofunc* suite of three functions (eofunc, eofunc_ts, eofunc_varimax) implements a more efficient method for computing EOFs. The previous suite of EOF functions will be available but should be replaced by the eofunc* functions.

• get_ncl_version

  Returns the NCL version as a string.

• gsn_add_text, gsn_text, gsn_text_ndc

  The input X, Y, and text arrays are no longer restricted to be 1-dimensional. If they are multi-dimensional, they must be the same dimensions as each other. Any one of them can be a scalar.

• Any gsn_csm polar plotting script.

  The font for the longitude labels and gsnRightString, gsnLeftString, and gsnCenterString were all defaulting to "helvetica-bold," which is inconsistent with the rest of the gsn_csm plotting scripts, whose labels default to "helvetica".

  These fonts were changed to be just "helvetica", which means you may notice a difference when generating polar plots with this version of NCL.

  To keep the polar longitude labels and/or three top subtitles set to "helvetica-bold", you need to set:

    res@gsnPolarLabelFont = "helvetica-bold"
    res@gsnStringFont     = "helvetica-bold"
  

• New functions: gsn_csm_xy2, gsn_csm_x2y, and gsn_csm_x2y2

  These functions are similar to gsn_csm_xy, only they allow you to have a different axis system on one or both of the top X and bottom right axis.

• GRIB file work-around for reading GRIB files from the IPCC Data Distribution Center (http://cera-www.dkrz.de/IPCC_DDC/).

  Several unrecognized centers are used for these files. The work-around code is activated when an unrecognized center is encountered.

  User-defined parameter tables are still needed and NCL does not attempt to supply a name for the center.

• Three new ECMWF GRIB tables added

  132: Extreme forecast index
  162: Usage: ECMWF re-analysis, ERA40
  200: Usage: Differences between first guess and analysis
  

• Two additional time variables are provided when GRIB data are read.

  These new variables, which are of type "double", contain the same information as the current initial_time(n) variables which are of type "string". The two new variables are:

  1. initial_time(n)_hours: This has units of "hours since 1800-01-01 00:00".
  2. initial_time(n)_encoded: This has units of "yyyymmddhh.hh_frac".

• landsea_mask

  Returns a grid that contains a land sea mask given any (e.g. gaussian, fixed offset, curvilinear) latitude and longitude array. The result can then be applied to any array on the same grid using mask.

• simpeq

  Integrates a sequence of equally spaced points using Simpson's Rule.

• simpne

  Integrates a sequence of unequally spaced points using Simpson's three-point formula.

• triple2grid2d

  Places randomly-spaced data onto the nearest locations of a grid with two-dimensional latitude and longitude arrays.

• v5d_create

  Creates a Vis5D+ formatted file.

• v5d_write

  Writes compressed gridded data to a Vis5D+ formatted file.

• v5d_write_var

  Writes a single gridded variable to a Vis5D+ formatted file.

• v5d_setLowLev

  Sets the lowest vertical offset, per grid level, for each gridded variable in a Vis5D+ formatted file.

• v5d_setUnits

  Sets a name for physical units associated with a variable in a Vis5D+ formatted file.

• v5d_close

  Closes a Vis5D+ formatted file.

• wmbarbmap

  Uses the wind barb functions from the Wmap package to draw wind barbs over maps.

• New resources for zonal means plots

  If you are creating a zonal means plots using the gsnZonalMean resource, then you now have access to three new resources:

  • gsnZonalMeanXMinF - sets the minimum value of the X axis
  • gsnZonalMeanXMaxF - sets the maximum value of the X axis
  • gsnZonalMeanYRefLine - sets the value at which to draw the y reference line. The default is 0.0.
  If you are wondering what a zonal mean plot is, see example 7 in the list of color examples.

• asciiread bug

  A bug was fixed in asciiread which caused it to read in lone periods (".") as float values equal to "0". For example, if you had the string "The data file is called file.cdf", it would treat the period in "file.cdf" as the value 0.

• Coordinate subscripting bug

  If you subscripted an array using coordinate subscripting, and gave it a "finish" subscript and not a "start" subscript, then you may have gotten one extra coordinate value. For example, the simple script below demonstrates this:

  begin
    level = (/1.5,2.5,3.5,4.5,5.5/)
  
    lev   = (/level/)
    lev!0 = "lev"
    lev&lev = level
  
    lev1 = lev({:3}) 
    lev2 = lev({0:3})
  
    print(lev1)
    print(lev2)
  end
  
  

  The two arrays lev1 and lev2 should be identical and equal to (/1.5,2.5/). Before this bug fix, lev1 was incorrectly getting the values (/1.5,2.5,3.5/).

• Another coordinate subscripting bug

  If you tried to use coordinate subscripting without actually using a subscript value, as in:

      buf2 = buf({lev|:},{lon|:},{lat|30:50})
  

  it would sometimes cause a core dump.

• Problems reading netCDF files that had multi-dimensional variables with the same name as a dimension.

  NCL is now tolerant of netCDF files where a multi-dimensional variable has the same name as a dimension (in other words, something that NCL saw as a coordinate variable, and wanted it to be one-dimensional). NCL no longer assumes that a variable with the same name as a dimension is a coordinate variable unless the variable has a single dimension.

• And still another coordinate subscripting bug

  There was a problem with coordinate array subselection using double coordinate values: the coordinate values were only being compared to float precision.

  This fix allows the following code to execute correctly:

    coord = (/1234.5678901230d,1234.5678901231d,1234.5678901232d,\
              1234.5678901233d /)
  
    h   = (/ 4,5,6,7 /)
    h!0 = "coord"
    h&coord = coord
    printVarSummary(h)
    print(h&coord)
  
    v1 = 1234.56789012305d
    v2 = 1234.56789012311d
    v  = h({v1:v2})
    print(v)
  
    v  = h({1234.56789012305d:1234.56789012319d})
    print(v)
  

• Any gsn plotting routine that does a frame advance

  When you set the special resource gsnMaximize to True, this maximizes the size of the plot(s) in the current frame. For PostScript or PDF output, the maximization is done by computing something called device coordinates that tells PS/PDF how the output is supposed to appear on the page. Previously, if these device coordinates were not reset or recalculated after the frame was advanced, then subsequent plots may not have been drawn correctly in the frame.

  This bug was fixed by having the device coordinates set back to their original values, but only if the frame is advanced by the plotting routine (that is, if you set gsnFrame to False, then the device coordinates are not set back to their original values).

  You can reset the device coordinates yourself by calling the procedure:

      reset_device_coordinates(wks)
  

  This procedure should only be called after the frame is advance, and before any drawing has occurred on the new frame.

• Problems with reading HDF files.
  1. Variable names now have non-alphanumeric characters replaced with an underscore. Multiple underscores are collapsed to a single underscore. This brings the HDF code in line with what has always been documented.

  2. With respect to the above, each variable is now given an attribute called "hdf_name", whose value is the original HDF variable name. This may be a redundant piece of information, but it seems better to always have it so that the user code does not have to check whether it exists.

  3. Certain HDF files have SDS variables with identical names. They are distinguished in the HDF file by belonging to different hierarchically arranged "Vgroups", much like a directory structure in a file system. These are now distinguished by appending a double underscore followed by the Vgroup reference id to the variable name. In addition, a text representation of the Vgroup hierarchy (with '/' used as a separator) is added as an attribute called "hdf_group." The group reference id is stored as an integer attribute called "hdf_group_id." Here's an example fragment of calling "print" on a file variable:

           float Longwave_flux_minimum_value__316 ( day, region )
              valid_range :  
              _FillValue :   3.402823e+38
              long_name :    Daily, Total-sky Averages
              units :        Watts per square meter
              hdf_name :     Longwave flux minimum value
              hdf_group :    Daily Averages/Total-Sky
              hdf_group_id : 316
     

  4. Added caching for all HDF attributes, similar to the caching implemented for the NetCDF module. This improves the performance of printing the contents of large HDF files by several orders of magnitude.

Version 4.2.0.a031

2 January 2004

New and updated functionality

Contour line label density control

An internal parameter's value was changed to fix the occasional problem of getting no or very few contour line labels on a contour plot. This may cause the default behavior to change for some contour plots, if you are setting the resource cnLineLabelPlacementMode to "Computed" or "Randomized" (i.e. you might see more contour line labels). The "Constant" mode is unaffected by this change.

You also now have better control over the density of contour line labels using the new resource cnLineLabelDensityF. This resource allows a simple (though inexact) method for controlling the number of line labels on a ContourPlot for both the "Randomized" and "Computed" line label placement modes. It has no effect for the "Constant" mode, which depends on cnLineDashSegLenF to determine the spacing.

If cnLineLabelDensityF is set to its default value of 0.0, it has no effect, and the line label spacing can be controlled using the cnConpackParams resource as always. If cnLineLabelDensityF is set to 1.0, then the default settings of the appropriate Conpack parameters apply, overriding any that are set by cnConpackParams. As cnLineLabelDensityF is set to values greater than 1.0, the number of labels increases, while setting it to positive values less than 1.0 causes the number of labels to decrease.

eof2data

Uses the output of eofcov and eofcov_ts to construct a data array.

eofcor, eofcov, eofcor_pcmsg, eofcov_pcmsg

Added an attribute called eof_function to indicate which EOF function was used.

eofcor_pcmsg, eofcov_pcmsg

Updated to return pcrit as an attribute.

Any gsn_csm map script that can draw a Lambert Conformal plot.

The ability to mask out areas of a Lambert Conformal plot to produce a plot similar to example 5 in the suite of CSM polar examples has been added. For an example, click on the script lambert.ncl and its resource file, or see its output.

Any gsn_csm plotting script that uses the "long_name" attribute to label an axis.

In addition to the "long_name" attribute, if any other attributes with the name "standard_name", "description", or "DataFieldName" are present, they will be used in the labeling of gsn_csm plot templates. (If more than one of these attributes are present, then the first one encountered in the above list will be used.) Also, some more acceptable values for the "units" attribute were added, including "UNITS", "UNIT", and "unit".

Any gsn_csm script that doesn't have latitude or longitude values on the X axis.

If the coordinate array that represents the X or Y axis has a valid "long_name" type attribute, then the value of this attribute will be used to label the corresponding axis.

gsn_csm_xy

Added two new resources called gsnXYBarChartColors2 and gsnXYBarChartPatterns2. They behave similarly to gsnXYBarChartColors and gsnXYBarChartPatterns, except they assign colors and patterns of individual bars regardless of whether the bar is up or down. For an example, see examples 6 and 7 in the bar application examples.

sprintf

This function has been updated to allow double input.

Updates to GRIB reader

The GRIB reader in NCL has been updated to add support for NCEP GRIB tables 129, 130 and 131.

equiv_sample_size

Fixed a bug for the case where an entire input series was missing. This routine will return a missing value if any input series are all missing.

ezfftf, specx_anal

Fixed a bug that would cause a core dump on some systems if the input array had an odd number of elements.

GRIB reader bug fix

The GRIB reader was not recognizing all bits set in the lat/lon increment octets of the GDS as meaning "undefined", and thus Dj and Di were being calculated incorrectly. In this situation, Dj and Di were fixed to be calculated from the number of lats/lons and the endpoints.

idsfft

Fixed a serious bug that would cause incorrect output if your input array was non-square.

ut_inv_calendar

Fixed a bug that would cause this routine to core dump if invoked multiple times with the same specification string.

write_matrix

Data was being printed in column x row format instead of row x column format as advertised.

Version 4.2.0.a030

1 July 2003

This version was released shortly after the previous version to fix some bugs that were found in the dashline and stippling code. Also, some people were running into problems with cyclic data. If you have problems with this version, please send email to Mary Haley.

Version 4.2.0.a029

1 July 2003

New documentation

NCL mini reference manual

There's a new mini NCL reference manual that you can print out, courtesy of Dennis Shea and Sylvia Murphy of the Climate and Global Dynamics Division at NCAR. It contains information on language syntax, file I/O, attributes and coordinate variables, data processing, and how to access external codes. It's available in PDF format from the manuals page.

New way to create a double precision variable

You can now specify doubles on the fly without having to use the new function. The format is similar to Fortran, in which you use a 'D' or 'd' specification. The following are equivalent, and produce a NCL variable of type "double":

    d = 1d
    d = 1D
    d = 1D0
    d = 1d+0
    d = 1d-0

escovc

Calculates cross-covariance between two variables.

filwgts_normal

Calculates 1D filter weights based on the gaussian (normal) distribution.

fspan

This function has been updated to allow numeric input.

getfiledimsizes

Returns a list of dimension sizes of the given file variable.

getfilevardimsizes

Returns an array of integer dimension sizes for file variables. This function already existed as "filevardimsizes", but to stay consistent with the naming convention of other file retrieval functions (they all start with the word "get"), we decided to give it a new name. The old name will still work forever for backwards compatibility.

Any gsn_csm plotting script that recognizes the gsn*String resources.

The font height of the three subtitles at the top can now be set individually using the resources gsnLeftStringFontHeightF, gsnCenterStringFontHeightF, and gsnRightStringFontHeightF. You can also set all three font heights with the single resource gsnStringFontHeightF. The subtitle font heights can also still be set with txFontHeightF, but setting this resource may affect your lat/lon label sizes in a polar plot.

Any gsn_csm polar plotting script.

The font and font height of the latitude/longitude labels on a polar stereographic plot can now be controlled via the resources gsnPolarLabelFont and gsnPolarLabelFontHeightF.

isfilepresent

Checks for the existence of a file.

isunlimited

Checks if a named dimension in the file is defined as an unlimited dimension.

NhlNewDashPattern

Adds new dash patterns to the existing table of dash patterns. For an example click on the script dashlines.ncl, or see its output.

NhlNewMarker

Adds new markers to the existing table of markers. For an example, click on the script markers.ncl, or see its output.

Stipple dot size control

You can now control the size of stipple dots (pattern 17 in the fill pattern table) using the new resources cnFillDotSizeF, gsFillDotSizeF, lbFillDotSizeF, and mpFillDotSizeF.

For an example, click on the script stipple.ncl, or see its output (frame 1, frame 2, and frame 3).

ut_calendar, ut_inv_calendar

Converts from time values with specific units to UTC-referenced dates, and vice versa. These fuctions use routines in the Udunits library to do the conversions.

Fix for cases where you have constant X or Y data in an XY plot.

Previously, if you had an XY plot in which the data was constant in X or Y, you would get a warning message:

   warning:TransInitialize: Zero Y coordinate span: defaulting:[errno=1104]

and the axis representing the constant data would default to a minimum of 0 and a maximum of 1. This has been fixed so that the minimum and maximum are calculated based on the value of the constant data.

Changes to GRIB reader

The GRIB reader in NCL has been updated using the currently documented values at:

http://www.nco.ncep.noaa.gov/pmb/docs/on388/

with the exception that model index 84 was changed from "MESO ETA Model (currently 12 km)" to simply "MESO ETA Model", because we believe the same index has been used historically for a number of different model resolutions. Model indexes 83 and 85 are changed from "No longer used" to what they were previously: "ETA Model - 80 km version" and "ETA Model - 30 km version", on the assumption that any GRIB file with these model indexes would be an old one.

line thickness in PostScript files

With the addition of the PDF driver, the line thickness for the various output devices (NCGM, X11 window, PS, and PDF) were adjusted to try to get them all to look the same. This resulted in line thicknesses for PS files being noticeably thicker, so they were reduced back to what they looked like before version 4.2.0.a028.

markers

With the addition of the NhlNewMarker routine, the current existing markers in NCL have been adjusted to be more centered with respect to its position coordinates. These differences will probably not be noticeable for standard marker programs. However, if you are significantly increasing the size of your markers, you may notice a slight shift in the X and/or Y direction.

Version 4.2.0.a028

31 March 2003

• Changes and new capabilities in GRIB reader
• Sending output to a PDF file
• You can now write true scalars to an HDF or netCDF file
• Performance enhancement for array variable initialization and assignment
• New and updated functions
• Important bug fixes

Changes and new capabilities in GRIB reader

Some major additions have been added to NCL's GRIB file reader to make it much more robust and to fix some bugs.

For more information, please see the "supported data formats information" section in the NCL Reference Manual.

The ability to load GRIB parameters from a file has been added. This can be done by setting the environment variable NCL_GRIB_PTABLE_PATH to a file or directory path. Parameter tables read from a file have precedence over built-in tables that would otherwise apply to the same dataset. An interface for adjusting this precedence at run-time is on the enhancement request list.

Many new built-in parameter tables were added, including all tables supported by wgrib, three FSL tables, and a Navy Fleet Numerical Meteorology and Oceanography Center table.

Support was added for thinned "quasi-regular" grids.

The way NCL names certain GRIB variables has been changed. This may result in variable names that are incompatible with previous names. In particular, variables involving average, accumulation, and difference over specific periods of time. For example, the variable PRATE_GDS4_SFC_ave will now be PRATE_GDS4_SFC_ave6h. This was required because some GRIB files have averages for several differing periods on the same file.

A problem was fixed for parameters less than 128 in ECMWF files.

Sending output to a PDF file

A PDF driver was added to NCL, allowing you to direct your graphical output directly to PDF. To use this driver with the GSN* suite of scripts, simply change the first argument of your call to gsn_open_wks to "pdf". A file with the name "file.pdf" will be created, where file is the second argument to gsn_open_wks.

Otherwise, you can create a PDFWorkstation much like you do a PSWorkstation.

You can now write true scalars to an HDF or netCDF file

Previously, if you wrote an NCL scalar to an HDF or netCDF file and then did a dump on the file, you would see that the scalar was written out as a 1D array of length one, rather than as a true scalar. For example:

    netcdf test {
    dimensions:
            ncl_scalar = 1 ;
    variables:
            int c(ncl_scalar) ;
    data:
    
     c = 5 ;
    }

Now, you can write scalars to an HDF or netCDF file using one of two methods:

1. Use the filevardef procedure:

       f = addfile("test.nc","c")
       filevardef(f,"c","integer","ncl_scalar")
       c    = 5
       f->c = c
   

2. Create a scalar variable in NCL, assign it the dimension name "ncl_scalar", and then assign this variable to the file:

       f    = addfile("test.nc","c")
       c    = 5
       c!0  = "ncl_scalar"
       f->c = c
   

   Using one of the above methods results in a file as follows:

       netcdf test {
       variables:
               int c ;
       data:
       
        c = 5 ;
       }
   

3. Use a more efficient method to avoid the double copying of attributes to a file:

       c    = 5.123
       c@long_name = "sample constant"
       c@units     = "m"
   
       f = addfile("test.nc","c")
       filevardef(f,"c", typeof(c), "ncl_scalar")
       filevarattdef(f,"c", c)
       f->c = (/ c /)                    ; Use '(/' and '/)' to avoid
                                         ; copying of attributes.
   

   Using the above method results in a file as follows:

       netcdf test {
       variables:
               float c ;
                       c:units = "m" ;
                       c:long_name = "sample constant" ;
       }
   

You are no longer allowed to define the dimension "ncl_scalar" using filedimdef. If you do, a warning level message is returned:

    FileAddDim:"ncl_scalar" is a reserved file dimension name in NCL;
    it cannot be defined by the user

Note that there is no restriction on using the name "ncl_scalar" as a dimension name for ordinary variables: only for defining it as a file dimension.

Performance enhancement for array variable initialization and assignment

Whenever the new function is invoked, it fills the variable with missing values. This method has been improved to double the number of initializations taking place for each iteration.

Where possible, contiguous data are now copied used single invocations of memcpy, thus speeding up the intialization of various kinds of array assignments, including:

• unsubscripted assignment where the types differ
• unsubscripted = subscripted: t = u(1,:,:)
• subscripted = unsubscripted: t(1,:,:) = u
• subscripted = subscripted: t(1,:,:) = u(0,0:9,:)
• subscripted = scalar: t(1,:,:) = 10.0

The optimization is only possible when certain conditions are met:

• the stride is positive
• the dimension is not reversed
• the dimension is not reordered
• the dimension does not employ vector subsetting

New and updated functions

dspnt2s, dspnt2d, dspnt3s, dspnt3d.

These routines were updated to allow multiple dimensions.

gammainc

Evaluates the incomplete gamma function; often used to determine probabilities

getfilevartypes

Returns the types of the named variables in a given file.

Any gsn_csm script that recognizes the gsnAddCyclic resource.

The gsn_csm plotting scripts have been updated such that if 2D latitude/longitude coordinate variables are present (that is, the data has the special "lat2d" and "lon2d" attributes set to 2D arrays), then gsnAddCyclic will default to False.

This means that any NCL scripts that are setting the lat2d/lon2d attributes and expecting the cyclic point to be added, you will need to add a line setting gsnAddCyclic to True:

  res@gsnAddCyclic = True

gsn_csm_vector_map_ce and gsn_csm_vector_scalar_map_ce

These two plotting functions were modified so that if both a labelbar and a vector reference annotation are drawn, and you move the reference annotation up, then the labelbar will not get moved up into the tickmarks. If you were previously getting around this problem by setting the pmLabelBarOrthogonalPosF resource to readjust the position of the labelbar, then you may want to consider removing the setting of this resource altogether.

gsn_panel

Updated to add a new resource called gsnPanelFigureStringsFontHeightF. Use this resource to control the font height of the panel figure strings that you specify with the gsnPanelFigureStrings resource.

isdimnamed

Checks whether one or more of a variable's dimensions are named.

new

This function, which allocates space for a specified data type, has been improved by speeding up the initialization that takes place when you invoke it. In some of our timing tests on large allocations of data, we saw speed-ups of 2.5 times and greater.

triple2grid

Places randomly-spaced data onto the nearest locations of a grid with two-dimensional latitude and longitude arrays.

uv2vr_cfd

A term that accounts for the convergence of the meridions has been added to this routine. The effects should be small except possibly near the poles.

wgt_areaave2

Calculates the area average of a quantity using 2D weights.

wgt_areasum2

Calculates the area sum of a quantity using 2D weights.

wgt_arearmse2

Calculates the area root-mean-square-difference between two variables using 2D weights.

write_matrix

Prints nicely-formatted 2D arrays.

fbinrecwrite

This procedure was fixed so that it doesn't core dump if you try to write characters to a file. This bug is related to the typeof bug mentioned next.

typeof

This function now correctly returns the string "character" when you call it with a variable that is of type character. It was previously just returning "char". Make sure you fix any scripts that are calling this function and checking for "char".

Version 4.2.0.a027

30 December 2002

New and updated functions, and bug fixes

memory bug fix

A couple of memory bugs were fixed in NCL. One bug caused some large NCL scripts to core dump or to say a variable wasn't defined when it very clearly was. This bug was particularly noticeable if you had lots of do loops, or were creating lots of variables in your main program. The second bug occurred when NCL scripts erroneously referenced undefined variable attributes, and then tried to delete them.

filling high-resolution maps (bug fix)

A bug was fixed in which if you drew a low resolution map and filled the continents, and then drew a high resolution map and filled the continents, you would get some blocky holes in the filled areas.

Streamline bug

A streamline bug that was similar to the vector bug mentioned below was fixed. This bug caused coordinate arrays to be ignored when streamline plots were being overlaid on a map plot, and thus the streamlines were not appearing in the right location.

Vector bug

Fixed a vector bug that caused the reference length for normal line and fill vectors to not be calculated properly if the reference magnitude resource (vcRefMagnitudeF) was set, and the reference length resource had its default value of 0.0, thus indicating that NCL should determine the reference length itself.

dim_num

Counts the number of True values of the n-1 rightmost dimension for all dimensions 0...n-2

gsn_add_text, gsn_text, gsn_text_ndc

These routines have been updated to allow arrays of text strings to be drawn. To see some examples, go to the application text examples.

gsn_csm_vector_scalar_map, gsn_csm_vector_scalar_map_ce, and gsn_csm_vector_scalar_map_polar

These routines have been updated to use the scalar field's long_name and units attributes to label the top left and right of the plot, rather than the U/V field attributes.

histograms

New functionality has been added to gsn_histogram to allow you to specify ranges and discrete values together in one histogram. New histogram resources have been added to allow you to bin values that are outside the given range of class values (gsnHistogramMinMaxBinsOn), to make the histograms horizontal (gsnHistogramHorizontal), and to control how missing values are handled (gsnHistogramComputePercentagesNoMissing).

For an example, click on the script histogram.ncl, or see its output (frame 1, frame 2, frame 3, frame 4, and frame 5).

round

Rounds a float or double variable to the nearest whole number.

svd_lapack

Computes singular value decomposition (SVD) of a general rectangular matrix. Returned are the singular values and the left and right singular vectors.

Version 4.2.0.a026

24 September 2002

A vector bug was discovered in version 4.2.0.a025 that's serious enough to warrant releasing a bug fix right away (hence this version). This bug caused coordinate arrays to be ignored when vector plots were being overlaid on a map plot, and thus the vectors were not appearing in the right location.

Version 4.2.0.a025

16 September 2002

New capabilities in NCL

New capabilities with spherical 2D grids and
discrete rasterization capability

NCL can now handle 2D spherical grids; that is, grids that are represented by 2D coordinate arrays. This new capability can be used with both contour and vector plots. For an example, click on the script pop.ncl, or see its output (frame 1, frame 2, frame 3, frame 4, frame 5).

The above example also showcases the new discrete rasterization capability. If the lat/lon coordinate arrays have one more element along both dimensions than the data array, then in raster mode, this will cause the raster fill to treat the coordinate arrays as cell boundaries.

You can see some more examples in the pop applications page.

ictrans and med bugs

A bug was fixed in both ictrans and med that caused metafiles to not be appended properly on LINUX systems. The problem would surface when you tried to write multiple frames from one metafile to another metafile.

Running NCL scripts

You can now run an NCL script without using the "<" character:

ncl xy.ncl

or:

ncl < xy.ncl

New and updated functions

bar chart capability

You can now use multiple colors to fill the bars in a bar chart. See example 7 in the bar applications page.

ftcurv, ftcurvd, ftcurvi, ftcurvp, ftcurvpi, ftcurvps, ftcurvs, ftsurf

Updated to allow the input to be of type numeric (instead of just float), and to allow xi to be multi-dimensional.

ftkurv, ftkurvd, ftkurvp, ftkurvpd

Updated to allow the input to be of type numeric (instead of just float), and the output to be float or double.

getvardims

Returns a list of dimension names of the given variable.

gsn_draw_named_colors

Takes a list of named colors, and draws them in a grid with the color name and corresponding RGB triplet listed. For an example, click on the script gsn_draw_named_colors.ncl, or see its output.

gsn_reverse_colormap

Reverses the current color map keeping the foreground and background colors the same. You must have this version of NCL and load gsn_code.ncl in order to have access to this function. For an example, click on the script gsn_reverse_colormap.ncl, or see its original color map and then the reversed color map.

histograms

If you enter non-equally spaced values for the gsnHistogramClassIntervals or gsnHistogramBinIntervals resource, then gsn_histogram will now make them equally spaced on the axis.

See example 5 in the histogram application pages.

linint1, linint2, linint2_points

Updated to allow input arrays to be multi-dimensional.

nggetp, ngsetp

Sets and retrieves parameters for the nglogo, ngezlogo routines.

Version 4.2.0.a024

13 May 2002

New and updated functions

cdfbin_p, cdfbin_s, cdfbin_xn, cdfbin_pr

Calculates various parameters of the binomial distribution.

cdfchi_p, cdfchi_x

Calculates various parameters of the chi-square distribution.

cdfgam_p, cdfgam_x

Calculates various parameters of the gamma distribution.

cdfnor_p, cdfnor_x

Calculates various parameters of the normal distribution.

dtrend_quadratic

Estimates and removes the least squares quadratic trend at all grid points.

gsn_attach_plots

Updated so that you can now set the gsnMaximize resource to maximize the size of the attached plots.

MacOSX version of NCL available.

You can download the MacOSX NCL binaries by going to the download section and following instructions.

ngezlogo

Draws the NCAR logo in the lower right corner of the workstation. For an example, click on the script nglogo.ncl, or see its NCGM or PostScript output.

nglogo

Draws various NCAR and UCAR logos. For an example, click on the script nglogo.ncl, or see its NCGM or PostScript output.

sigma2hybrid

Interpolates a vertical column from sigma coordinates to hybrid coordinates.

Version 4.2.0.a023

14 February 2002