NCL > What's New
What's new in previous releases
4.3.1 | 4.3.0 | a034 | a033 | a032 | a031 | a030 | a029 | a028 | a027 | a026 | a025 | a024 | a023 | a022 | a021 | a020 | a019 | a018 | a017 | a016 | a015 | a014 | a013 | a012 | a011 | a010 | a009 | a008 | a007 | a006 | a005
Version 5.0.1
No scheduled date. See What's coming up in the next release of NCL.Version 5.0.0
Version 5.0.0 is the latest version of NCL. Go to the download page for information on downloading this version.
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
ARW WRF functions
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.
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 formatthen 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.
- 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".
- 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
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.
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.
- 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:
- 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:
- initial_time(n)_hours: This has units of "hours since 1800-01-01 00:00".
- 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.
- 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) endThe 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.
- 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.
- 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.
- 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 - 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.
- 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.
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:- 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 = cUsing 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" ; }
FileAddDim:"ncl_scalar" is a reserved file dimension name in NCL; it cannot be defined by the userNote 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. - Use the filevardef procedure:
- 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 stride is positive
- the dimension is not reversed
- the dimension is not reordered
- the dimension does not employ vector subsetting
- 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
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.
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
- 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.
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