What's coming in the next release of NCL

Visit the new color capabilities examples page for details.

This upgrade might result in some plots looking different. Please see the section on potential backwards-incompatibilites for more information.

If you think you've run across a real problem with this upgrade, please see our "Reporting NCL Bugs" page.

Changes to graphical defaults

With the introduction of the new color display model, we decided to change some long-standing graphical defaults NCL.

While these changes may cause some backwards-incompatibility in the look of your graphics, we think these changes are for the better. See this side-by-side comparison:

[Click on images for a larger version.]

NCL V6.0.0	NCL V6.1.0

Here are the changes you need to be aware of:

1. Default font is now helvetica

   The default font is now "helvetica" instead of "times-roman".

2. Default function code is now "~"

   The old default was a colon ":" which is a common character to use in titles.

3. Behavior of res@gsnSpreadColors = True is now the default

   gsnSpreadColors has been superceded by new resources cnSpanFillPalette, vcSpanLevelPalette, and stSpanLevelPalette, which all default to True. This means whenever you create filled contours, vectors, or streamlines, the default behavior is now that the current color map will be spanned.

   gsnSpreadColors will still work, but it will only have an effect if gsnSpreadColorStart and/or gsnSpreadColorEnd are set to something other than their default values of 2 and -1.

4. lbLabelAutoStride now defaults to True.

   This means labelbar labels are automatically "strided" if they overlap.

5. Default color table

   The default color table has been changed from the default one called "default" to a new color table called "ncl_default".

Here are some possible situations where you'll notice a different in your graphics:

• You are getting helvetica font instead of times-roman font

  If you really want times-roman font, then create a file called ".hluresfile" in your home directory and add this line to it:

  *Font : times-roman
  

  You can see a sample file here.

• You are suddenly seeing gray-filled land in your map plots.

  This is because the gsn_csm_xxx_map functions all fill the land in gray by default. In older (pre V6.1.0) versions of NCL, you had to have gray in your color map in order to see gray-filled land. This is no longer the case.

  If you don't want any map land fill, set:

    res@mpFillOn = False
  

• The colors in your plot (especially a filled contour or vector plot) are different.

  This could be due to one of two issues:

  1. If you are not calling gsn_define_colormap to change the color map, then the issue is likely that the new default color map is being used. To fix this, you can load the original default color map with:

       gsn_define_colormap(wks,"default")
     

  2. If you are setting your own color map, and you are creating a filled vector or contour plot, then the change may be due to the new resources cnSpanFillPalette or vcSpanLevelPalette defaulting to True. Try setting the appropriate resource to False:

       res@cnSpanFillPalette = False
       res@vcSpanLevelPalette = False
     

• The labelbar labels look different.

  This is likely due to lbLabelAutoStride now defaulting to True. Try setting it to False.

    res@lbLabelAutoStride = False
  

New regridding capabilities via ESMF software

We have incorporated the Earth System Modeling Framework (ESMF) regridding software into NCL. This software allows you to regrid rectilinear, curvilinear, and unstructured data, using three different interpolation methods.

Visit the ESMF regridding examples page for details.

New functions

• cd_convert - Converts a time variable from one set of units to another. This function is identical to ut_convert, except it uses cd_calendar and cd_inv_calendar internally. (Original routine contributed by Carl Schreck.)

• cd_string - Converts time values into nicely formatted strings. This function is identical to ut_string, except it uses cd_calendar internally. (Original routine contributed by Carl Schreck and Arindam Chakraborty.)

• depth_to_pres - Convert ocean depth to pressure.

• dim_min_n_Wrap / dim_max_n_Wrap - Computes the minimum/maximum of a variable's given dimensions at all other dimensions and retains metadata. The dim_min_n / dim_max_n functions have existed since version 5.1.1.

• dim_gamfit_n - Fits data to the two parameter gamma distribution.

• dim_numrun_n - Counts the number of "runs" (sequences) within a series containing zeros and ones.

• dim_spi_n - Calculate the standardized precipitation index (SPI).

• dtrend_quadratic_msg_n - Estimates and removes the least squares quadratic trend of the given dimension from all grid points. Missing values are allowed.

• ESMF functions:
  • curvilinear_to_SCRIP - Writes the description of a curvilinear grid to a SCRIP file.
  • latlon_to_SCRIP - Writes the description of a lat/lon grid to a SCRIP file.
  • rectilinear_to_SCRIP - Writes the description of a rectilinear grid to a SCRIP file.
  • unstructured_to_ESMF - Writes the description of an unstructured grid to an ESMF file.
  • ESMF_regrid - Regrids data from one grid to another, using ESMF software.
  • ESMF_regrid_gen_weights - Writes a weight file using the offline ESMF weight generator.
  • ESMF_regrid_with_weights - Using the provided weight file, regrids data from one grid to another.

• gamma - Evaluates the complete gamma function.

• get_cpu_time - Returns the CPU time used by NCL.

• gsn_add_shapefile_polygons - Attaches shapefile polygon data to the given plot using randomly filled polygons.

• gsn_add_shapefile_polylines - Attaches shapefile polyline or polygon data to the given plot using polylines.

• gsn_add_shapefile_polymarkers - Attaches shapefile point data to the given plot using markers.

• mixed_layer_depth - calculates a quantity derived from the Potential Density of significance.

• potmp_insitu_ocn - Calculate seawater potential temperature at an arbitrary reference pressure given insitu temperature, salinity and depth.

• read_colormap_file - Reads an NCL system colormap file or a user-defined colormap.

• reshape - Reshapes a multi-dimensional array to another multi-dimensional array.

• reshape_ind - Places values from a smaller one-dimensional array to a larger one-dimensional array, and reshapes it.

• rm_single_dims - Removes singleton (degenerate) dimensions from an array while preserving meta data.

• sparse_matrix_mult - Multiples a sparse matrix with a dense matrix.

• spcorr_n - Computes Spearman rank order correlation coefficient across the given dimension.

• str_split_csv - Splits strings into an array of strings using the given delimiter (usually a comma ',').

• wgt_area_smooth - performs a 5-point 2D area-weighted smoother.

• wind_component - Calculate zonal and meridional wind components from wind speed and wind direction.

• wind_direction - Calculate meteorological wind direction from zonal and meridional wind components.

New resources

This set of resources were added allowing you to have transparency in some graphical components:

• cnFillOpacityF - sets the opacity of all colors in a contour plot
• gsFillOpacityF - sets opacity for color-filled polygons
• gsLineOpacityF - sets opacity for boundaries of polygons, polylines, etc.
• gsMarkerOpacityF - sets opacity for marker-based graphics
• stLineOpacityF - sets the opacity of all streamlines in a streamline plot
• txFontOpacityF - sets opacity for textual graphics
• vcGlyphOpacityF - sets the opacity of all vector glyphs in a vector plot

This set of resources allows you to specify color palettes and behavior for each plot type.
They are are meant to replace the behavior of gsnSpreadColors:

• cnFillPalette / cnSpanFillPalette
• vcLevelPalette / vcSpanLevelPalette
• stLevelPalette / stSpanLevelPalette

New color tables

Matthew Long of NCAR/ASP contributed three new "cmp" color tables, and several other tables have been added by the NCL team.

You can download these tables now and use them. Click on the "download now" link of the desired table, and then go to the "Move file to appropriate directory" section of the "create your own color table" page for information on adding this new table to your current version of NCL.

amwg256 (download now)	cmp_b2r (download now)	cmp_flux (download now)	cmp_haxby nice for topography (download now)
GHRSST_anomaly nice for topography (download now)	ncl_default (new default for NCL)	seaice_1 (download now)	seaice_2 (download now)
matlab_hot (download now)	matlab_hsv (download now)	matlab_jet (download now)	matlab_lines (download now)

Updated functions

• cd_calendar / cd_inv_calendar - added recognition of the "none" calendar.

• day_of_week, day_of_year, days_in_month, isleapyear, monthday, jul2greg, greg2jul - these were updated to recognize missing values.

• fspan - updated to do calculations in double precision, giving it better precision.

• regCoef - now returns the y-intercepts.

• short2flt - now works with ushort.

• time_axis_labels - Updated to internally use cd_calendar instead of ut_calendar.

• wrf_user_getvar - added "sreh", which calculates helicity.

Changes to GRIB1/GRIB2 reader

• Added support for complex packing in GRIB1. (It's already available for GRIB2 files.)

• GRIB1 changes

  Time range indicator 10, which indicates that time parameter P1 occupies 2 bytes, is now treated the same as time range indicator 0 for the purposes of generating the forecast time dimension. This means that GRIB1 variable names that used to have '_10' appended no longer will. And, in a very small number of cases, two forecast time dimensions may be concatenated into a single dimension that is the union of the two.

• New GRIB2 tables added

  Details to be added soon.

Improvements and bug fixes to ncl_convert2nc and ncl_filedump

• ncl_convert2nc - wasn't working if the file was not in the current directory
• ncl_convert2nc - wasn't working if the file didn't have a file extension (i.e. ".grb")
• ncl_convert2nc - fixed bug with converting single string variables to netcdf character variables
• ncl_convert2nc - wasn't always creating unique names for the temporary NCL script it creates
• ncl_convert2nc - fixed a bug with trying to convert an HDF file with no scientific datasets.
• ncl_convert2nc - will now determine the name for an unlimited time-related dimension when given the option -u without a name parameter
• ncl_filedump - now works with OPeNDAP files.

Bugs fixed

File input/output bugs

• Fixed problem reading GRIB2 files larger than 2 GB.
• Fixed confusion over whether to start from "La1" or "La2" in a GRIB1 or GRIB2 file.
• Fixed a bug when you tried to open a GRIB file that didn't have a ".grb" extension.
• Fixed a bug in setfileoption in which it wouldn't work for HDF5 files if the first argument was a format string (like "h5"), rather than a file type variable.
• Fixed bug with writing NULL-valued attributes to an HDF-EOS2 file. They will now be assigned a missing value.
• Fixed bug in reading ZA data in an HDF-EOS5 file.
• Fixed a bug with strings not being read correctly in an HDF-EOS5 file
• Fixed a memory problem when deleting a global attribute from a file.
• Fixed a problem with reading files in "cat" mode where one of the variables doesn't have "true" coordinate arrays.
• Fixed a problem with accessing a variable when specifying a single file in a join type aggregation.
• Fix for problems reading files with single dimensions that exceed 2^31.
• Removed the limit of being able to write only 2048 variables to a NetCDF file.

Graphical bugs

• Fixed a problem in the contouring code that was causing some areas to be left blank if drawing a raster plot using a triangular mesh.
• Fixed a contour bug that caused a plot to be blank on one size of grid boundary. (?)
• gsn_csm_pres_hgt_streamline - fixed a bug in which the pressure values were not converted correctly for the u/v values, causing the streamlines not to show up.
• Fixed a bug in which colors in the labelbar and contour plot were sometimes not matching up. This involved changing the default value of cnFixFillBleed to True.

Analysis function bugs

• cd_calendar - was returning strange values if a bad "unit" was given. It now returns all missing values.
• dim_num_n - fixed a bug in the prototyping of this function.
• dpres_hybrid_ccm - fixed a memory issue that sometimes caused a segmentation fault.
• min and max - now returns the missing value of the input if input is all missing, rather than the missing value of the type of the input.
• reg_multlin - fixed a memory leak.
• str_capital - wasn't correctly capitalizing strings in all cases.
• str_match - didn't allow you to input an empty string as a delimiter.
• triple2grid - sometimes had a problem if "opt" was set to False.
• WRFUserARW.ncl - fixed a bug in calculating the cone factor.

Miscellaneous bugs

• idt - was failing under MacOS 10.7.
• NewList - wasn't letting you create a "cat" list directly.
• systemfunc - now returns a string missing value if there is no valid return information.
• Fixed bug with assigning logicals when a variable appeared on both sides of the "=" sign.
• Fixed a bug making a copy of a List variable.