Example pages containing: tips | resources | functions/procedures
Various ways to do masking include:
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.
A Python version of this projection is available here.
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".
A Python version of this projection is available here.
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 "landsea.nc" file can be downloaded from http://www.ncl.ucar.edu/Applications/Data/#cdf
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,
"GSHHS_shp_2.2.0.zip", downloaded from:
http://www.ngdc.noaa.gov/mgg/shorelines/data/gshhs/oldversions/version2.2.0/
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.
mask_16.ncl /
mask_annotate_16.ncl:
This example, which uses dummy data, shows how to draw filled contours over gray land,
with the ocean filled in white to mask out the filled contours over ocean.
The dummy data was generated using generate_2d_array, with
random missing values added for illustrative purposes. For an example using real data
see examples mask_17.ncl / mask_annotate_17.ncl below.In order to draw filled land, followed by filled contours, followed by filled ocean, you have to create two plots.
The mask_16.ncl script creates and draws the contour/map plot twice: the first time with filled contours drawn over gray land and transparent ocean (the ocean color is arbitrary), and second time with the ocean filled in white, the land transparent, and the filled contours also transparent so you don't end up with filled contours over ocean again.
The mask_annotate_16.ncl script creates a contour/map plot with filled contours over gray land and transparent ocean and a map only plot of the exact same size with white ocean and transparent land. You then have two choices for drawing the two plots: you can simply draw both of them, or you can add one as an annotation of the other using gsn_add_annotation. Both methods are shown in this script, and they both produce the same image. The annotation method is generally the preferred method, because this will allow you to panel a series of these plots later with gsn_panel.
mask_17.ncl / mask_annotate_17.ncl:
This example is similar to mask_16.ncl, except it uses precipitation data read off a NetCDF file. See the description above for a description of how the map is being masked.
For more information about this particular dataset, see example gpm_1.ncl on the high-resolution precipitation page.
mask_18.ncl: This example
shows how to create a lat/lon polygon from the boundary of a lambert
conformal plot, and then use this polygon to mask data with
gc_inout. See the "get_latlon_bounding_polygon"
and "create_mask_array" functions.
The data being masked is a simple 2D array which has coordinate arrays. If you need to mask data that is not rectilinear, then you'll need to modify the "create_mask_array" function and change lat1d/lon1d to represent your lat/lon grid or mesh.
Both images contain the original data in the top plot, and the masked data in the bottom plot. The first image has primitives added (markers and lines) to show the location of the lambert conformal boundary, and the location of the missing and non-missing data.
