NCL > What's New | previous releases | current release

What's coming in the next release of NCL

The next release of NCL will be version 6.4.0, with a scheduled release date of Feb 2017.

If you see a new feature or bug fix that you would like to test now, then either try a test version of NCL under conda or email (you must subscribe first).

New functions

  • Array Create, Manipulator, Query

  • Bootstrap functions - Application of the bootstrap method.

    • bootstrap_correl - Bootstrap estimates of sample cross correlations (ie, Pearson's correlation coefficient) between two variables.
    • bootstrap_diff - Bootstrap mean differences from two samples.
    • bootstrap_estimate -Extract the user specified element from the bootstrapped values.
    • bootstrap_regcoef - Bootstrap estimates of the linear regression coefficient.
    • bootstrap_stat - Bootstrap estimates of basic statistics derived from a variable.

  • CESM

    • albedo_ccm - Calculates the albedo given a pair of model radiation variables.
    • time_reassign - Reassign (replace) a Cf-conforming "time" variable by calculating the mid-time values using the "bounds" attribute.
    • time_reassign_cv2var - Reassign (replace) a Cf-conforming "time" coordinate variable associated with a variable by calculating the mid-time values using the "bounds" attribute.

  • Crop & Evapotranspiration - A suite of functions for computing crop water requirements based upon the FAO Irrigation and drainage paper 56 including Penman-Monteith estimates (FAO 56) of reference evapotranspiration.

  • Date, String

    • cd_inv_string - Converts string time values to numeric values, using the given format string.
    • cla_sq - Create a string that uses single quotes (') to enclose command line assignment statements (CLAs) for later use by NCL's system procedure.

  • Extreme Value Statistics - A small suite of functions focused on extreme value distributions.

    • extval_frechet - Calculates the probability (PDF) and cumulative (CDF) distribution functions of the Frechet Type II distribution given the shape, scale and location parameters.
    • extval_gev - Calculates the probability (PDF) and cumulative (CDF) distribution functions of the of the Generalized Extreme Value (GEV) distribution given the shape, scale and location parameters.
    • extval_gumbel - Calculates the probability (PDF) and cumulative (CDF) distribution functions of the Gumbel (Type I) distribution function given the scale and location parameters.
    • extval_mlegam - Estimates the shape, scale, location other parameters for the Gamma distribution using Maximum-Likelihood Estimation.
    • extval_mlegev - Estimates the shape, scale and location parameters for the Generalized Extreme-Value (GEV) distribution using Maximum-Likelihood Estimation.
    • extval_pareto - Calculates the probability (PDF) and cumulative (CDF) distribution functions of the Pareto distributions (Generalized, Type I, TYpe II) given the shape, scale and location parameters.
    • extval_recurrence_table - Calculates the recurrence interval (return period), cumulative and exceedence probabilities based upon a time series.
    • extval_return_period - Calculates the period of an event (eg, flood, heat wave, drought) occurring given an average event recurrence interval and specified probability level.
    • extval_return_prob - Calculates the probability of an event (eg, flood, heat wave, drought) given an average event interval and a specified exceedance period.
    • extval_weibull - Calculates the probability (PDF) and cumulative (CDF) distribution functions of the Weibull Type III distribution given the shape, scale and location parameters.

  • General Applied Math

    • calculate_daily_values - Calculate daily values [avg, sum, min, max] from high frequency temporal values.
    • calculate_segment_values - Calculate segment (eg, pentad [5-day], weekly [7-day]) values from high frequency temporal values.
    • ceemdan - Complete ensemble empirical mode decomposition with adaptive noise. [NOTE: the function interface may change.]
    • cohsq_p2c - Calculate the value(s) of coherence-squared required for a specified significance level and effective degrees-of-freedom.
    • cohsq_c2p - Given coherence-squared and the effective degrees-of-freedom, calculate the associated probability.
    • demod_cmplx - Perform a complex demodulation on one or more time series.
    • eemd - Perform ensemble empirical mode decomposition. [NOTE: the function interface may change.]

    • eofunc_n / eofunc_ts_n / eofunc_n_Wrap / eofunc_ts_n_Wrap / eof2data_n

      These are identical to eofunc / eofunc_ts / eofunc_Wrap / eofunc_ts_Wrap eof2data, except you no longer need to reorder the input array so that 'time' is the rightmost dimension.

    • get_d2r - Return a constant that converts degrees to radians.
    • get_pi - Return pi as a type float or double.
    • get_r2d - Return a constant that converts radians to degrees.

  • Heat-Stress functions

    • fire_index_haines - Calculates the Haines fire index for a sounding.
    • heat_apptemp - Compute apparent temperature.
    • heat_discoi - Compute a simplified human discomfort index.
    • heat_discoi_stull - Compute the human discomfort index due to excessive heat and humidity using the Stull wet bulb temperature (wetbulb_stull).
    • heat_esidx_moran - Compute an environmental stress index (ESI) which is an alternative to the wet bulb globe temperature (WBGT).
    • heat_humidex - Compute the 'feels-like' temperature for humans.
    • heat_index_nws - Computes the 'heat index' as calculated by the National Weather Service.
    • heat_swamp_cooleff - Compute the swamp cooler temperatures at 65% amd 80% efficiency.
    • heat_thic_thip - Compute the thermal humidity comfort index (thic) and the thermal humidity physiology index (thip).
    • heat_wbgt_inout - Compute the composite Wet-Bulb Globe Temperature (WBGT) index with options for indoor or outdoor formulations.
    • heat_wbgt_simplified - Simplified WBGT index.

  • Legends

    • simple_legend - Creates a legend based on user supplied resources. simple_legend 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.

  • Meteorology

    • brunt_vaisala_atm - Compute the Brunt-Vaisala frequency which is a measure of bouyancy in a continuously stratified atmosphere.
    • coriolis_param - Compute Coriolis parameter.
    • eady_growth_rate - Compute the Eady maximum baroclinic growth rate.
    • epflux - Compute quasi-geostrophic Eliassen-Palm fluxes at isobaric levels.
    • grad_latlon_cfd - Compute the meridional and zonal gradients of a variable on a global or limited area rectilinear grid.
    • latent_heat_water - Estimate latent heat flux for water: evaporization (condensation), melting (freezing) or sublimation (deposition).
    • pot_temp_equiv - Compute equivalent potential temperature..
    • pres_hybrid_jra55 - Calculates the "full" hybrid levels for the 60-level Japanese ReAnalysis.
    • relhum_ice / relhum_water - Calculates relative humidity with respect to ice/water, given temperature, mixing ratio, and pressure.
    • rigrad_bruntv_atm - Compute the atmospheric gradient Richardson number and, optionally, the Brunt-Vaisala, buoyancy and shear.
    • satvpr_water_bolton - Estimate the saturation vapor pressure over water using Bolton's equation 10.
    • satvpr_water_stipanuk - Estimate the saturation vapor pressure over water using the Stipanuk approximation.
    • wetbulb - Compute wetbulb temperature.
    • wgt_vertical_n - Calculate a weighted vertical average and/or sum (integral).
    • wind_speed - Calculate wind speed from zonal and meridional wind components and return associated meta data.
    • wind_stats - Given a sequence of wind speeds and directions, compute assorted wind-related statistics including the standard deviation of the wind direction.

New features

Block style comments

You can now do "block style" comments in NCL, using /; and ;/ to start and end a block:

    This is inside an NCL block style comment,
    available in NCL V6.4.0.

  print("A demonstration of block comments")

  print("This line should not be printed")
  print("...nor this one")
  print("...or this one")

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:


Backwards-incompatible changes

The "MediumRes" map database will be the default in some cases

This involves a change to the default value of the mpDataBaseVersion resource

This resource has a new default value of "Dynamic". This means that the "LowRes" database (the default in older versions of NCL) will be used, unless either of the boundary-set resources mpFillBoundarySets or mpOutlineBoundarySets are set to anything other than "Geophysical", in which case the "MediumRes" database will be used.

This behavior represents a balance between performance and accuracy for common use-cases. For global-scale maps depicting just the continents and oceans, the LowRes database is more than sufficient, whereas the more detailed MediumRes database would incur additional compute overhead. However, the political boundaries of the MediumRes database are more up-to-date, and are thus favored if any political boundaries are to be drawn.

Click on the images below for a comparison with the previous version of NCL, and note the differences in the righmost panel. The left plot of both versions shows the default "LowRes" database. The right panel of NCL V6.3.0 still shows the "LowRes" database, wheresae the right plot of NCL V6.4.0 automatically defaulted to "MediumRes"

Labelbar colors will now reflect opacity used in plot

The labelbar associated with filled contour and color vector plots will now reflect any opacity applied. We decided to consider this a bug rather than a new feature.

If this behavior is not desired, then set the new resource lbOverrideFillOpacity to True.

Click on the images below for a comparison with the previous version of NCL, and note the differences in the bottom labelbar.

Updated functions

  • calculate_monthly_values - This function no longer requires that the time dimension name be 'time'. Also, (i) the algorithm no longer assumes that the values are equally spaced in time; and (ii) the user may specify that a minimum number of observation be used for deriving a statistic.

  • cd_inv_calendar / ut_inv_calendar - These functions were enhanced to allow different numeric types for the input parameters and the return array. The return array will still default to type "double" unless the special attribute "return_type" is set to "float", "long", or "int". Read the function documentation for more details.

  • gsn_csm_xy - This function underwent a major overhaul to allow for horizontal curves and bars to be filled when gsnXRefLine is set. This is the same behavior that already existed for gsnYRefLine.

    Many new resources were added to allow customized horizontal bars.

  • printMinMax - The "units" attribute, if present, will be added to the print output.

  • regline_stats - Added several new attributes related to 95% confidence limits of the slope and y-intercept, the mean responses, and the prediction limits. Examples of use were added to the regress/trend page. See: regress_1a.ncl, regress_1b.ncl, regress_1c.ncl and regress_3.ncl.

  • skewt_func - Added ability to change the thickness of the wind barbs.

  • trend_manken - Added recognition of the opt argument: if opt is set to True, then the trend is not calculated.

New resources

New example pages

New color table

The new default color table for matplotlib, MPL_viridis, was added, thanks to Brian Medeiros of NCAR.

Bugs fixed in functions and procedures

  • advect_var - this function was incorrectly named in NCL V6.3.0. The correct name is advect_variable.

  • decimalPlaces - Fixed the function. It was nor rounding correctly.

  • f2foshv_Wrap / fo2fshv_Wrap - fixed a bug remove incorrect syntax that subtracted or added one to the size of the latitude arrays of uNew and vNew and prevented the functions from working at all.

  • generate_sample_indices - replaced the method used with a similar but more robust method.

  • int2p, int2p_n - fixed a bug which occurred when the input and output pressure levels were not monotonically decreasing. The functions now work regardless of the input or output pressure level ordering.

  • kolsm2_n - fixed bug in which using multiple dimensions (for example, in the time dimension) would cause the results to be wrong.

    You can work around this by using loops, which will be slower:

    ; Assume:
    ;   TS_2 is dimensioned nyears1 x nlat x nlon 
    ;   TS_3 is dimensioned nyears2 x nlat x nlon 
      dims = dimsizes(TS_2)
      nlat = dims(1)
      nlon = dims(2)
      ks   = new((/nlat,nlon/),typeof(TS_2))
      ds   = new((/nlat,nlon/),typeof(TS_2))
      zs   = new((/nlat,nlon/),typeof(TS_2))
      do ilat = 0, nlat-1
        do ilon = 0, nlon-1
          ks_single     = kolsm2_n(TS_2(:,ilat,ilon),TS_3(:,ilat,ilon),0)
          ks(ilat,ilon) = ks_single
          ds(ilat,ilon) = ks_single@dstat
          zs(ilat,ilon) = ks_single@zstat
        end do
      end do

  • pot_vort_isobaric - Andy Show (12/15) reported that the term [ R/(s*p) ] should be [ 1/s ].

  • stat_dispersion - David Ahijevych (12/29) reported that setting the opt=True but not associating any attributes resulted in a fatal error.

  • table_attach_rows - Dave Allured (5/27) reported that this function was printing intermediate information used for debugging. The print statements have been removed.

  • trend_manken - fixed bug in which passing a really large array (i.e. 400 MB) would cause this routine to hang and/or produce a segmentation fault. The issue was with the internal sorting algorithm used, which is required to calculate the trend. A new sorting algorithm was implemented, and also the option to not calculate the trend was added.

  • wrf_user_getvar - fixed the following bugs:

    • "cape_2d" and "cape_3d" - fixed a bug in which the PSFC variable was not being converted to hPa as required by these routines.

    • "ctt" (cloud top temperature)

      • This function now returns its values in degrees Celsius (it was previously returning them in degrees Kelvin). This is to stay consistent with other diagnostics that are returned in Celsius.
      • Fixed a bug where the pressure values were not being converted properly.
      • Fixed the interface to allow "ctt" to be calculated for multiple timesteps when used with addfiles.

    • "helicity" - fixed the interface to allow helicity to be calculated for multiple timesteps.

    • "omg" (omega) - fixed a bug in which the calculation was incorrectly using the temperature values for the water vapor mixing ratio, making the output results nonsensical.

Bugs fixed in file I/O

  • Fixed a bug where you couldn't read a NetCDF-4 variable that contains a '.' character; for example, "conc.instant_Cs137".

  • Fixed a bug in which opening some HDF5 files with "new" file features (like groups, compound data, enum, etc) would cause a segmentation fault.

    A work-around for V6.3.0 is to call the following before you open the file:

      setfileoption("h5", "FileStructure", "Advanced") 

    or to use the "-f" option when running ncl:

      ncl -f myscript.ncl

  • Fixed a bug where deleting a group would delete parts of the file variable structure.

  • Fixed a bug that led to a segmentation fault when trying to read a variable from a NetCDF4 file opened in "w" mode.

  • Fixed a bug that resulted in a segmentation fault when re-writing string attributes to a NetCDF4 file, even if the attribute values were unmodified from their previous values in the file.

  • Fixed a segmentation fault that occurred when using fileattdef to create global attributes in a NetCDF4 file.

  • Fixed a problem using the list style delete syntax for deleting file variables and coordinate variables.

Graphics bugs fixed


Plotting unstructured or "random" data

When using one of the gsn_csm_xxxx_map functions to plot unstructured or "random" data represented by one-dimensional lat/lon arrays, you can now attach these arrays as special attributes called "lat1d" and "lon1d" attributes to your data array, instead of having to set the sfXArray and sfYArray resources. This is similar to how the "lat2d" and "lon2d" attributes work for curvilinear data.

For some examples, see the Plotting data on a map examples page.

Plotting WRF data

  • If you plot WRF-ARW data using the gsn_csm_xxx scripts, you will no longer get these warning messages:

      warning:start_lat is not a valid resource in wrf_gsn_contour at this time
      warning:start_lon is not a valid resource in wrf_gsn_contour at this time
      warning:end_lat is not a valid resource in wrf_gsn_contour at this time
      warning:end_lon is not a valid resource in wrf_gsn_contour at this time
      warning:mpNestTime is not a valid resource in map at this time

    Note: you can safely ignore these warnings with older versions of NCL.

  • You can now use cnFillPalette with wrf_contour without getting the following error:

    warning:ContourPlotSetValues: color index (255) exceeds size of palette,
            defaulting to foreground color for entry (11) 

Graphics improvements

  • Colorado counties improved

    The Colorado counties in NCL's map database were updated to include Broomfield, and the correct boundaries for existing counties.

  • Overhauled special "gsn" Color resources to allow RGB/A entries

    Many of the special"gsn" Color resources now allow all types of color entries, including color index values, named colors ("red"), RGB values, and RGBA values. Use of RGBA allows you to make filled areas partially transparent.

    The updated resources include:

  • Default X11 window now larger

    When sending NCL Graphics to an X11 window, the default size is now 1000x1000 (it was 512x512).