NCL Website header
NCL Home> Application examples> Plot techniques || Data files for some examples

Example pages containing: tips | resources | functions/procedures


Masking refers to the technique of not drawing certain portions of your data over areas you are not interested in.

Various ways to do masking include:

  • using the mask function to change certain values in your data to missing,
  • using gc_inout to change certain values in your data to missing,
  • using graphical resources to control masking,
  • changing the drawing order of certain plot elements to control what gets drawn when.

You may also want to see the draw order applications page to see examples of controlling graphical masking by changing the draw order of certain plot elements.

mask_1.ncl: Demonstrates the use of the mask function and a masking array to mask out land or ocean.

The NCL mask function can be a bit confusing. It sets all values to missing that DO NOT equal the mask array. To mask out the ocean, you put in the land value and vice versa.

mask_2.ncl: Uses resources to draw land on top of the contours.

cnFillDrawOrder = "Predraw" draws the contours first. If necessary, you can also specify that the contour lines be drawn first as well by setting cnLineDrawOrder = "Predraw".

mask_3.ncl: Uses the mask function to leave only a range of the data.
mask_4.ncl: Uses the mpFillAreaSpecifiers and mpMaskAreaSpecifiers resources to indicate which map areas to fill and mask.
mask_5.ncl: The shea_util function landsea_mask can be used to create a landsea mask when one is not available for your particular dataset. This example demonstrates how to use landsea_mask to calculate a mask based on a particular resolution (in this case t85), and how to apply that mask to mask out all the ocean points from the data array.

The top plot shows the calculated T85 land sea mask. Note that at this resolution some islands (notably Hawaii) are not labeled as land or as small islands. This can be due to a variety of reasons, including the resolution of the data, the resolution of the 1x1 basemap, or whether the centers of the grid boxes are over the islands themselves. Note that the file that is returned by landsea_mask can be easily modified, as can the basemap that is downloadable off of the landsea_mask documentation page.

The bottom plot shows a surface temperature field at T85 resolution that has had the ocean points masked out by using the land sea mask shown in the top plot.

mask_6.ncl: This example shows how to mask out areas of your data based on a mask shape (a circle in this case).

This example also shows how to annotate the map with lines, markers, and text, using gsn_add_polyline, gsn_add_polymarker, and gsn_add_text.

mask_7.ncl: This example shows how to mask out areas of a contour plot that are below a certain threshold, in this case topography.

The first frame shows the unmasked data array.

The second frame shows the data array masked by the topography, with the missing areas filled via cnMissingValFillColor. Note that to use cnMissingValFillColor, one also has to set cnFillOn to True. As we do not wish to color fill the contour field in this case, we simply set cnFillColor to the background color (white in this case).

The third frame shows the data array masked by the topography, with the missing areas outlined. cnMissingValPerimOn needs to be set to True to outline the missing areas.

mask_8.ncl / mask_dummy_8.ncl: This example shows how to using masking resources to draw only the counties of Wisconsin, United States and to mask other areas. It uses the mpFillAreaSpecifiers and mpMaskAreaSpecifiers resources to indicate which map areas to fill and mask.

The "mask_8.ncl" script is the original script that reads the data from a NetCDF file. The "mask_dummy_8.ncl" script uses dummy data. The "" file can be downloaded from

To get the counties of Wisconsin, mpDataSetName must be set to "Earth..2" and mpDataBaseVersion to "MediumRes". The counties are drawn and filled by setting mpOutlineSpecifiers and mpFillAreaSpecifiers to "Wisconsin:counties".

This script was contributed by Dr. Michael Notaro, a scientist at the Center for Climatic Research, University of Wisconsin-Madison.

mask_9.ncl: Demonstrates using gc_inout to mask an area in your data array using a geographical outline.

This particular example reads a shapefile to get an outline of the Mississippi River Basin. You then have the option of masking out all areas inside or outside this outline.

mask_10.ncl: Demonstrates how to overlay a cell fill plot on a raster plot, filling the missing value areas of the cell fill plot with transparency so you can see the first contour plot underneath.

The cnMissingValFillColor resource is set to -1 to get the transparency. You have to use a cnFillMode of "CellFill" for the second plot, because transparency isn't available for "RasterFill". ("AreaFill", the default, would also work.)

mask_11.ncl: Similar to example 8, this script shows how to show a color filled contour field only over those areas specified in mpFillAreaSpecifiers.

In this example the Earth..4 database is used by setting the mpDataSetName resource. This database has many areas, and all can be specified in mpFillAreaSpecifiers. Note that under the Area Name column in the table on the Earth..4 page there are a number of words bolded. The bolded part of the area name is unique, and can be used to specify a specific area.

The following areas were specified: (/"Arizona","New Mexico","Conterminous US: Utah", "Conterminous US: Colorado", "Great Salt Lake"/). The reason "Conterminous US" was needed before Colorado and Utah is because there are other areas in the Earth..4 database named Utah and Colorado, namely Utah county in Utah and Colorado county in Texas. As these areas are being specified in mpOutlineSpecifiers and mpFillAreaSpecifiers, these areas would also be outlined and filled if "Conterminous US" was not present. The reason Great Salt Lake was specified is because all inland water areas were being map color filled white, and by specifying Great Salt Lake in mpOutlineSpecifiers and mpFillAreaSpecifiers NCL will not color fill the lake white.

mask_12.ncl: This example shows how to use a shapefile that contains polygon outlines to create a data mask for a variable with 1D coordinate arrays. The mask array is then written to a copy of the input file.

In this case, the shapefile contains coastal outlines, which a land mask is created from. See the function "create_mask_from_shapefile" in the "mask_12.ncl" script. This function only works for data that contains coordinate arrays. You will need to modify it to work with curvilinear or unstructured data.

You should be able to use any shapefile that contains polygon data (point and polyline data won't work) to create the desired mask.

The shapefile used in this example was part of a compressed file, "", downloaded from:

You need to uncompress it with the "unzip" command. You can use any of the other shapefiles that are included with this file, but they are potentially a higher resolution, and hence creating the mask will take longer.

mask_13.ncl: This example uses the same "create_mask_from_shapefile" function as the previous example, to compare the mask with the "ORO" mask already on the file (same data used in example mask_1.ncl).
overlay_11.ncl: This example shows how to overlay vectors on top of a filled contour plot, where the contours are masked by a geographical area and the vectors are not. The masking is accomplished by setting:

  mpres@mpDataBaseVersion   = "MediumRes"
  mpres@mpMaskAreaSpecifiers = (/"China:states","Taiwan"/)

The mask area specifier names are part of the predefined group names available in the "MediumRes" map database.

This script was written by Yang Zhao (CAMS) (Chinese Academy of Meteorological Sciences).

mask_14.ncl: This example shows how to mask data based on terrain data read from a separate file. The terrain data is regridded to the data to be masked using area_hi2lores_Wrap.

This script was written by Yang Zhao (CAMS) (Chinese Academy of Meteorological Sciences).

mask_15.ncl: This example shows how to draw two filled contour plots on top of one another. The top plot has a rectangular "hole" of missing data, allowing you to see part of the base plot underneath.

The original version of this script was written by Yang Zhao and Yuhong Wang (CAMS) (Chinese Academy of Meteorological Sciences).

Katrina_circle.ncl: This script plots the 5-day running average of precipitation for an entire year (2005). It shows a unique way of displaying filled contours in a circle, by using nggcog in conjunction with gc_inout to mask data inside a great circle.

See the Unique examples page for another version of this script that generates a histogram of the values, and for an animation of both scripts.

This code was contributed by Jake Huff, a Masters student in the Climate Extremes Modeling Group at Stony Brook University.