NCL > What's New

What's new in the current release

[previous releases | next release]

Version 6.5.0 - July 16, 2018 - [download and install]

New functions for task parallelism

This version contains two new functions that enable NCL scripts to execute multiple independent tasks in parallel. The tasks can be any operation that can be invoked from a UNIX command line. One example might be using an NCL driver script to execute a series of other NCL scripts in parallel.

  • subprocess - this is the main function which takes as input the shell command to execute.
  • subprocess_wait - checks the finish status of a concurrent process launched by subprocess.

For examples of using these functions, see the task parallelism examples page.

New Functions

  • dim_pad_extend - extends (i.e., expand, append, pad) an existing array along the 'record dimension' to a user specified size.

  • dim_pad_modulo - pads (i.e., expand, append, extend) an existing array such that the size of a specified dimension is a user specified 'modulo' length.

  • enthalpy - computes atmospheric enthalpy.

  • esacr_n - computes sample auto-correlations on the given dimension.

  • exponential_curve_fit - calculates the coefficients for a simple exponential curve fit of the form ' y = A*exp(B*x)' using least squares.

  • geolocation_circle - creates latitudes and longitudes that define concentric circles at user specified distances from a central location.

  • get_bitfield - unpacks bit fields from an array.

  • Several new file I/O query functions were added for consistency purposes and more meaningful names:

  • isconform - checks two variables for array conformance (same shape and size).

  • keyword_values - reads a text file that contains keywords and associated values (similar to fortran NAMELIST).

  • tlcl_evp_bolton - computes the lifting condensation level temperature using water vapor pressure.

  • tlcl_mixr_bolton - computes the lifting condensation level temperature using mixing ratio and pressure.

  • tlcl_rh_bolton - computes the lifting condensation level temperature using relative humidity.

  • tlcl_td_bolton - computes the lifting condensation level temperature using dew point temperature.

  • mixhum_convert - converts mixing ratio to specific humidity or vice-versa.

  • pot_temp_equiv_tlcl - computes equivalent potential temperature using the lifting condensation temperature.

  • regline_weight - calculates the linear regression coefficient between two series where the dependent (y) variable's values are weighted by some measure of uncertainty (typically, standard deviations) such that the Chi-square goodness-of-fit is minimized.

  • refevt_hamon - uses the Hamon formulation to derive reference evapotranspiration.

  • str_match_bool / str_match_bool_ic - returns a logical array of True/False/Missing indicating where the input array of strings contain the given substring.

  • simple_legend_ndc - creates a legend in NDC space based on user supplied resources. Similarly to simple_legend, simple_legend_ndc gives the user complete control over the design and placement of the legend, and can be seen as an easier way to create legends in NCL.

  • static_energy_atm - computes the atmospheric moist and dry static energy.

  • temp_virtual - computes atmospheric virtual temperature.

  • unwrap_phase - unwraps (correct) phase angles to produce smoother phase plots.

  • zscore - computes the zscore of a variable's given dimensions at all other dimensions and retains metadata.

New "elseif" statement

This version will have the long-requested "elseif" statement!

The old way of using "else if" required you to have an "end if" for every "else if" statement:

  a = 5
  if (a.eq.1) then
    a = a + 1
  else if (a.eq.2) then
    a = a + 2
  else if (a.eq.3) then
    a = a + 3
  else if (a.eq.5) then
    a = a + 5
    a = -1
  end if
  end if
  end if
  end if
  print("a = " + a)

The new way, with the use of "elseif" (no spaces) looks like this:

  a = 5
  if (a.eq.1) then
    a = a + 1
  elseif (a.eq.2) then
    a = a + 2
  elseif (a.eq.3) then
    a = a + 3
  elseif (a.eq.5) then
    a = a + 5
    a = -1
  end if
  print("a = " + a)

The old way will still work, and both codes above should return:

   a = 10

New profiler command line option Examples coming soon. Stay tuned...

Preloaded NCL scripts

Several NCL scripts are now preloaded, and you no longer need to explicitly load them at the top of your own scripts. Here's a full list of the preloaded scripts:


It's perfectly fine to continue loading one or more of these scripts, even if NCL is preloading them.

In most cases you will not notice but loading these scripts does take a few tenths of a second. In certain situations where you want to run many very short scripts the resulting overhead may cause a significant slowdown of your work flow. For this case, a new command line option, '-s', allows you to start NCL without preloading any scripts.

New resources

New color tables

NCL V6.5.0 has 29 new color maps added.

The table below contains a suite of color maps for vegetation.

NEO_div_vegetation_a NEO_div_vegetation_b
NEO_div_vegetation_c NEO_modis_ndvi
NOC_ndvi vegetation_ClarkU
vegetation_modis Click on color map name or color bar for more information or larger image.

The table below contains a matplotlib suite of color maps for oceanography. Thanks to Sam McClatchie of NOAA for the suggestion.

cmocean_algae cmocean_amp
cmocean_balance cmocean_curl
cmocean_deep cmocean_delta
cmocean_dense cmocean_gray
cmocean_haline cmocean_ice
cmocean_matter cmocean_oxy
cmocean_phase cmocean_solar
cmocean_speed cmocean_tempo
cmocean_thermal cmocean_turbid
Click on color map name or color bar for more information or larger image.

The table below contains four random color maps:

  • srip_reanalysis - selected by the SPARC reanalysis intercomparison project group for reanalysis comparisons. This group carefully selected colors so that groups of reanalyses worked well and so colorblind people could use it. The idea is that papers will have these colors for time-series comparisons. Thanks to Cathy Smith (NOAA/ESRL PSD and CU CIRES) for bringing it to our attention.

  • UKM_hadcrut - from the UK Met Office

  • GSFC_landsat_udf_density - from NASA's Landsat Science "undisturbed forests"

  • drought_severity - a drought severity color map

srip_reanalysis UKM_hadcrut
GSFC_landsat_udf_density drought_severity
Click on color map name or color bar for more information or larger image.

Graphics enhancements

  • get_color_index / get_color_rgba - these functions were enhanced to allow the third argument to be an array of values. This can signficantly speed up the routines if you have a lot of calls to these functions.

    See example table_8.ncl.

Function enhancements

  • cd_inv_string - new formatting options added for month names, and changed 'f' option to 'r' to match cd_string.

  • nggcog - this procedure was updated to allow numeric input and/or float and double output. See example polyg_27.ncl for an example.

Other enhancements

  • ncl_convert2nc - an "-nc4" option was added to allow the conversion of files to NetCDF 4.

Function and procedure bugs fixed

  • bin_avg - this function expects equal grid spacing for the destination grid. The internal test required exact spacing. However, some grid spacing led to round-off errors which caused the test to fail. More robust testing was used to address this issue.

  • calculate_daily_values / calculate_monthly_values / calculate_segment_values - the documentation for each function was updated to clarify the supported `data structures. The calculate_daily_values and calculate_monthly_values functions now support 5-dimensional structures of the form: (ncase,time,level,lat,lon) and (time,ncase,level,lat,lon).

  • calendar_decode2 - no longer exits with an error if the "calendar" attribute is set to "proleptic_gregorian".

  • cd_calendar / cd_string - the "calendar" attribute can now be any case ("julian", "JULIAN", "Julian", etc).

  • clmDayTLLL - fixed a bug where it wasn't handling the 360-day calendar properly.

  • daylight_fao56 - fixed an issue which arose when two-dimensional latitude/longitude coordinates were encountered.

  • dim_acumrun_n - fixed a bug that would cause this function to crash if you passed in an "lrun" that was greater than the number of elements of the input array.

  • dim_pqsort / dim_pqsort_n - these functions would fail if you tried to sort an array with more than two gigabyte values.

  • fbinread / fbinwrite / fbindirread /fbindirwrite - these functions can now read and write > 2 GB variables.

  • get_isolines - was not correctly checking for out-of-bounds conditions and sometimes returned non-sensical values. See the isolines examples page for NCL graphical scripts that use this function.

  • lspoly / lspoly_n - these functions were potentially returning the wrong coefficients if multiple least-squares polynominals were input at once.

  • natgrid_Wrap - was not correctly attaching the coordinate arrays to the return variable (it had the rightmost two dimensions swapped).

  • paleo_outline - fixed a bug that was restricting the string length of the base name of the map files to 512 characters.

  • pot_vort_isobaric - when opt=1, this function returned seven variables as elements of a list variable. It was supposed to return three variables.

  • product - now allows types int64, uint, and uint64 to be input.

  • stat_medrng - now allows the output arguments to be scalars as advertised.

  • trop_wmo - was returning -999 for missing values, but no _FillValue attribute was being set.

  • ut_string_fix - was not calling ut_calendar_fix under the hood, and thus it still had the infamous "60 second" bug.

  • wgt_volrmse - was returning the wrong values due to a value being squared twice.

  • wrf_user_intrp2d / wrf_user_intrp3d - these two vertical cross section routines weren't including the 0th grid point when setting up the output domain, causing the output array to be missing a grid point in the rightmost dimension. In the figures below, you can see the error by comparing the right edge of each plot. (Click on color map name or color bar for more information or larger image.)

Graphics bugs fixed

  • cnLineLabelFormat - this resource is now recognized by the gsn_csm contouring routines.

  • cnLowLabelFontColor / cnHighLabelFontColor - these resources are now recognized by the wrf_contour function.

  • cnLineLabelFontThicknessF / cnHighLabelFontThicknessF / cnLowLabelFontThicknessF / cnInfoLabelFontThicknessF - these contour font thickness resources are no longer ignored.

  • gsn_add_text / gsn_create_text / gsn_text / gsn_text_ndc - fixed a bug in which missing text strings would show up on the plot as whatever the missing value was for that string. (Click on images for a larger view.)

  • gsn_csm_streamline_scalar_map_polar - fixed a bug where this function would fail if you tried to turn off the labelbar by setting lbLabelBarOn to False.

  • gsnYRefLine / gsnXRefLine

    • Fixed a bug where drawing your curves with markers or markers and lines (xyMarkLineMode = "markers" or "marklines") would cause extra markers to show up at locations where the X or Y reference line crossed your curve(s). (Click on images for a larger view.)

    • Fixed a bug where if you are adding a different number of X and Y reference lines to a plot via these two resources, then you may get a fatal error:

      fatal:Number of dimensions on right hand side do not match number of dimension in left hand side
      fatal:["Execute.c":8640]:Execute: Error occurred at or near line 6014 in file 

      If you have NCL V6.4.0 and need a fix for this problem now, download this gsn_csm_640_fix.ncl file and load it from your own script after any other load commands.

  • gsn_add_polyline / gsn_polyline

    • Fixed a bug in which NCL was not always drawing the shortest path between two points on a map. (Click on images for a larger view.)

    • Fixed a bug in which the lines wouldn't be drawn correctly if the precision exceeded that which could be represented by a float.

  • Fixed a bug where if you were drawing filled contours or vectors with transparency applied (for example, via resources like cnFillOpacityF or vcGlyphOpacityF), the opacity was also being applied to the map outlines. The map outlines have been fixed to be fully opaque. (Click on images for a larger view.)

  • gsn_csm_xxxx_map functions - Fixed a bug where if mpCenterLonF was set to something less than 0 (and pmTickMarkDisplayMode was not set to "Always"), the longitude labels in the eastern hemisphere were continuing to be labeled with "W".

  • gsn_panel / gsnPanelLabelBar - Fixed a bug where if you are running a script that calls gsn_panel to panel XY plots and setting gsnPanelLabelBar to True, then you would get a fatal error:

    fatal:Variable (mono_fill_scl) is undefined
    fatal:["Execute.c":8640]:Execute: Error occurred at or near line 6100 \
       in file $NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl

    The gsnPanelLabelBar resource cannot be applied to XY plots anyway, so the solution is to simply not set this resource. In the next release, NCL will produce a warning instead of exiting with an error.

  • tfDoNDCOverlay - This resource used to only be settable to True / False. As of several versions ago, this resource can now be set with strings. The gsn_csm functions, however, were still only allowing True/False values. You can now set this resource either way.

    The following settings show the new values and their allowable equivalents:

    res@tfDoNDCOverlay = 0 
    res@tfDoNDCOverlay = False 
    res@tfDoNDCOverlay = "DataTransform" 
    res@tfDoNDCOverlay = 1 
    res@tfDoNDCOverlay = True 
    res@tfDoNDCOverlay = "NDCViewport" 
    res@tfDoNDCOverlay = 2 
    res@tfDoNDCOverlay = "NDCDataExtent" 

    The string settings are case insensitive, so "DataTransform" is the same as "datatransform" which is the same as "DaTaTranSfORM".

    To see an example of what the three values mean, see example dataonmap_14.ncl on the Plotting data on a map examples page.

Other bugs fixed

  • GRIB2 - fixed issues with reading files containing aerosol data.

  • ncl_convert2nc - fixed a bug where this script would not work properly if you give it more than two files.