# 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.

- 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:

- Plotting data on a map
using gsn_csm_xxx functions

(see any example labeled as a rectilinear grid example) - cylindrical equidistant templates (all examples)
- polar stereographic (all examples)
- ice model (first two examples)
- vectors (all vector/map examples)
- streamlines (all streamline/map examples)
- NARR (example 3)

- 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:

- Plotting data on a map
using gsn_csm_xxx functions

(see any example labeled as a curvilinear grid example) - contours-on-contours (example 9)
- ice model (example 3)
- EASE (all examples)
- POP scalars (all examples)
- POP vectors (all examples)
- ROMS (all examples)

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:

- 2D vertical coordinates (all examples)

- Plotting data on a map
using gsn_csm_xxx functions
- 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:

- Plotting data on a
map using gsn_csm_xxx functions

(see any example labeled as a triangular mesh, random data, hexagonal mesh, etc) - adaptive grids (all examples)
- station data (example 1)
- triangular meshes (all examples)
- ORCA (all examples)
- ISCCP (all examples)

- Plotting data on a
map using gsn_csm_xxx functions
- If the data are already transformed onto a particular map
projection,
you don't have any kind of latitude/longitude arrays associated with it, then the*and**tfDoNDCOverlay*resource must be set to True, and the map limits must be set appropriately.For some examples, see these pages:

- native grid projections (all examples)
- NARR (first two examples)

- 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*.