NCL Home > Documentation > Graphics

Overlaying data on a map

For some specific examples of plotting data on a map, see the "Plotting data on a map using gsn_csm_xxx functions" examples page. This page goes into more detail than what is covered below.

Plotting data on a map is also referred to as overlaying data on a map. In order for contour, vector, and streamline data to be correctly overlaid on a map projection using one of the gsn_csm_xxxx_map plot interfaces, one of the conditions below must be met.

Important note: It may be necessary to set the special gsnAddCyclic resource to False if your data is not global.

  1. The data is two-dimensional (lat x lon) and has one-dimensional latitude and longitude coordinate arrays attached to it. This is known as a rectilinear grid.

    In addition, the following conditions must be met:

    • The longitude coordinate array must have a "units" attribute of something like "degrees_east", "degrees-east", etc.
    • The latitude coordinate array must have a units of "degrees_north", "degrees-north", etc.

    For some examples, see these pages:

  2. The data is two-dimensional (lat x lon), and there are latitude and longitude arrays of the same size (or one element longer in the longitude dimension) that represent the locations of each data value. This is known as a curvilinear grid.

    When plotting with one of the gsn_csm_xxx_map plot interfaces, you can attach special "lat2d" and "lon2d" attributes to your data array, and set them equal to these two arrays.

    The special "lat2d" and "lon2d" attributes are for NCL gsn_csm_xxx_map graphics only. They shouldn't be used for writing data to a file.

    For some examples, see these pages:

    If you don't want to use the "lat2d" and "lon2d" attributes, then you can set the res@sfXArray and res@sfYArray resources (or for vector data, res@vfXArray and res@vfYArray) resources to the 2D longitude and latitude arrays respectively.

    For some examples, see these pages:

  3. The data is one-dimensional (like the number of cells), and there are latitude and longitude arrays of the same length that represent the locations of each data value. This is known as an unstructured mesh or grid or random data (like station points). You can only generate contours of unstructured data. Vectors on unstructured meshes are not supported yet.

    With NCL V6.4.0, you can attach special "lat1d" and "lon1d" attributes to your data array, and set them equal to the 1D lat/lon arrays. With older versions of NCL, you need to set the res@sfYArray and res@sfXArray resources to the 1D lat, lon arrays respectively.

    With unstructured or random data, a triangulation algorithm is used under the hood to generate the contours.

    For some examples, see these pages:

  4. If the data are already transformed onto a particular map projection, and you don't have any kind of latitude/longitude arrays associated with it, then the tfDoNDCOverlay resource must be set to True, and the map limits must be set appropriately.

    For some examples, see these pages:

  5. If none of the above conditions apply, then you will need to communicate the lat/lon information to the gsn_csm script in another way. For contour data, You can do this by setting the sfXArray and sfYArray resources to arrays of longitude/latitude values that represent the area your contours are to be overlaid on. Or, if your latitude and/or longitude values are equally spaced, you can just set sfXCStartV, sfXCEndV (for longitude) and sfYCStartV, sfYCEndV (for latitude).

    Likewise, for vector and streamline data, you can use the corresponding resources: vfXArray and vfYArray, or vfXCStartV, vfXCEndV, vfYCStartV, and vfYCEndV.