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")

If you get a warning message:

warning:FileSetFileOption: invalid value supplied for option format

then your version of NCL does not have NetCDF 4 support. If your version does have NetCDF 4 support, then you can further control the level of compression with:

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

The third argument can be any value from 1 to 9, where 9 is the highest level of compression. See the setfileoption documentation for more information.

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.

Low-level three-dimensional visualization routines

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

New resources

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.

Bugs fixed

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

Prior to version 4.3.0, getFillValue would return the default _FillValue if a variable did not have _FillValue associated with it.

For example, in the line below:

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

if "w" is of type "float" and if "w" did not have a _FillValue, then getFillValue would return the _FillValue for a variable of type "float". Hence, q@_FillValue = -999. In some cases this result was not desired.

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)

if the variable has no _FillValue associated with it. The reason is the the string "No_FillValue" can not be assigned to "q" unless q is of type string.

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

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

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.

New functions

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:

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.

Important bug fixes

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.

Important bug fixes

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 and updated functionality

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.

Important bug fixes

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:

Use the filevardef procedure:

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

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 ;
    }

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.

Important bug fixes

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

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

labelbars and legends bug

Fixed a change in the way labelbars and legends were drawn that would cause some of the labels to disappear.

Automatic generation of map tickmarks (lat/lon labels)

You can have lat/lon labels automatically generated for several map projections. This feature has not been incorporated into the gsn_csm functions yet.

To generate map tickmarks automatically (if you are not using gsn_csm functions), set the pmTickMarkDisplayMode resource to "Always" when you are setting the map resources.

For an example, click on the script maptm.ncl, or see its output.

Access to RANGS/GSHHS high-resolution map database

You can access the multi-resolution coastline database RANGS (Regionally Accessible Nested Global Shorelines), developed by Rainer Feistel from Wessel and Smith's GSHHS (Global Self-consistent Hierarchical High-resolution Shoreline) database.

For information on how to download and install the RANGS/GSHHS, please click here.

Once you have the database installed, you can see an example by clicking on the script coast_2.ncl, or viewing its output.

New and updated functions

dewtemp_trh: Calculates the dew point temperature given temperature and relative humidity.
gsn_attach_plots: Starting with a base plot, this function attaches a series of plots to the right Y axis (or bottom X axis) of the previous plot. You must have at least this version of NCL and load gsn_code.ncl to have access to this function. For an example, see the script gsn_attach_plots.ncl and its output.
gsn_csm_y: This function is similar to gsn_csm_xy, except that only the Y values are passed in, and the X values will be index values going from 0 to npts-1, where npts is the number of points in the Y curve(s). You must load gsn_code.ncl and gsn_csm.ncl to have access to this function.
gsn_legend_ndc: This function draws a legend anywhere in the viewport. You must load gsn_code.ncl to have access to this function.
gsn_y: This function is similar to gsn_xy, except that only the Y values are passed in, and the X values will be index values going from 0 to npts-1, where npts is the number of points in the Y curve(s). You must load gsn_code.ncl to have access to this function. For an example, see the script gsn_y.ncl and its output.
ind_resolve: Takes a list of indices returned by ind and resolves them to their multi-dimensional representation.
lclvl: Calculates the pressure of the lifting condensation level.
mixhum_ptrh: Calculates the mixing ratio or specific humidity given pressure, temperature and relative humidity.
rcm2points: Interpolates from a grid produced by the Regional Climate Model (where grid points are represented by 2D lat/lon arrays), to user-specified locations.
wmstnm: This procedure uses the low-level WMSTNM routine from the Wmap package to plot station model data.
dv2uvF, dv2uvG uv2sfvpF, uv2sfvpG uv2vrdvF, uv2vrdvG vr2uvF, vr2uvG, vrdv2uvF, vrdv2uvG: These are functional versions of the existing procedures: dv2uvf, dv2uvg, uv2sfvpf, uv2sfvpg, uv2vrdvf, uv2vrdvg, vr2uvf, vr2uvg, vrdv2uvf, vrdv2uvg

Version 4.2.0.a022

28 November 2001

pres_hybrid_ccm, dpres_hybrid_ccm: Fixed a bug that caused these functions not to work if ps was more than 2 dimensions.
conform: Updated to allow a multi-dimensional array to conform to the shape of another multi-dimensional array
Curly vectors: A resource was updated to allow the specification of curly vectors. This functionality has actually been in NCL since version 4.2.0.a019, but I forgot to mention it then. For more information, see the vcGlyphStyle resource or see example 2 in the vector application pages.
ezfftb, ezfftf: Updated to check for missing values.
filwgts_lancos: Updated to allow nsigma to be numeric.
linint1 Updated to allow the input or output X coordinates to be increasing OR decreasing.
linint2: Updated to allow the input or output X/Y coordinates to be increasing OR decreasing.
random_chi: Generates random values of chi-square va