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.
- New functions
- New features
- Backwards-incompatible changes
- Updated functions
- New resources
- New example pages
- New color table
- Bugs fixed
- Array Create, Manipulator, Query
- dim_maxind - Returns the index of the first occurrence of a maximum value within the specified dimension.
- dim_minind - Returns the index of the first occurrence of a minimum value within the specified dimension.
- isscalar - Determines if a variable is a scalar (True) or not (False).
- Venn Diagram -
A small suite of two-set Venn Diagram functions.
- 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.
- 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 /
- 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.
- 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.
- 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.
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") ;/
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:
"$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/csm/bootstrap.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/csm/extval.ncl" "$NCARG_ROOT/lib/ncarg/nclscripts/wrf/WRFUserARW.ncl"
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"
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.
- 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.
/ 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
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
page. See: regress_1a.ncl, regress_1b.ncl, regress_1c.ncl and
- 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.
- gsnHistogramBarColors - set individual
colors for bars in a histogram generated by
- gsnPanelMainString - set a main title for
paneled plots created from gsn_panel.
This resource replaces the awkwardly named "txString"
resource, which will still work for backwards compatibility.
Other resources were added to allow you to customize the panel title:
- gsnPanelMainFont - sets
the font for gsnPanelMainString.
This resource replaces the awkwardly named "txFont"
resource, which will still work for backwards compatibility.
- gsnPanelMainFontColor - sets
the font color for gsnPanelMainString.
This resource replaces the awkwardly named "txFontColor"
resource, which will still work for backwards compatibility.
- gsnPanelMainFontHeightF - sets
the font height for gsnPanelMainString.
This resource replaces the awkwardly named "txFontHeightF"
resource, which will still work for backwards compatibility.
- gsnPanelMainFont - sets the font for gsnPanelMainString. This resource replaces the awkwardly named "txFont" resource, which will still work for backwards compatibility.
- gsnPanelFigureStringsJust - set the
location of the figure strings in a set of paneled plots created
from gsn_panel. This resource
replaces the awkwardly named "amJust" resource, which will
still work for backwards compatibility.
gsnXRefLineDashThicknesses - these
resources are similar to their counterparts,
gsnYRefLineDashThicknesses. They allow
you to set the colors, dash patterns, and thicknesses for X reference
lines drawn with
- lbBoxEndCapStyle - controls
the shape of the two outer boxes of a labelbar, which
can either be rectangular or triangular/arrow shaped.
- lbFillOpacityF - Allows you to
set the fill opacity for labelbars. This is generally meant for
user-created labelbars, and not labelbars created by contour
or vector plots.
- lbOverrideFillOpacity - The
labelbar associated with filled contour plots will now reflect the
opacity of the fill colors. Set this resource to True if you do not
want this behavior.
New example pages
- ACCESS model
- Bootstrapping; Resampling
- Complex Demodulation
- Crop: Evapotranspiration; Penman-Monteith
- Eliassen-Palm flux (EP-flux); Brunt-Vaisala; Eady Growth rate; Gradient Richardson number
- Extended and Complete Empirical Mode Decomposition: EEMD and CEEMDAN
- Simple Extreme Value Statistics
- GFED: Global Fire Emissions Database
- Gradients: Meridional and Zonal
- Heat Index/Stress
- Plotting data on map
- Task Parallelism
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
- decimalPlaces -
Fixed the function. It was nor rounding correctly.
/ 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.
- "cape_2d" and "cape_3d" - fixed a bug in which the PSFC variable was not being converted to hPa as required by these routines.
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
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
- 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
- The labelbar associated with filled contour and color vector plots
will now reflect any transparency applied. See the section
changes in 6.4.0 for more information.
fixed a bug in which you'd get a warning:
warning:vcRefAnnoFontHeightF is not a valid resource in gsn_csm_vector_scalar_map_contour at this time
and the vector reference annotation may have been larger than expected.
- gsn_create_text - fixed a bug
which didn't allow for multiple text strings to be input, as
/ gsnAboveYRefLineColor /
- fixed a bug that didn't allow you to use a mix of scalar values or arrays for
these resoures, if you had multiple curves.
- pie_chart - fixed a bug that
caused an unnecessary fatal error:
fatal:fspan: number of elements parameter is less-than-or-equal-to one, can't continue
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
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)
The Colorado counties in NCL's map database were updated to include Broomfield, and the correct boundaries for existing counties.
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:
- gsnAboveYRefLineBarColors / gsnBelowYRefLineBarColors
- gsnAboveYRefLineColor / gsnBelowYRefLineColor
- gsnXYAboveFillColors / gsnXYBelowFillColors
- gsnXYLeftFillColors/ gsnXYRightFillColors
When sending NCL Graphics to an X11 window, the default size is now 1000x1000 (it was 512x512).