landsea_mask

Returns a grid that contains a land sea mask given any latitude and longitude array.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

	function landsea_mask (
		basemap [*][*] : byte,     
		lat            : numeric,  
		lon            : numeric   
	)

	return_val [*][*] :  integer

Arguments

A two-dimensional array of type byte that contains a 1 x 1 degree grid of baseline land sea mask. The user can modify this file if they so choose prior to its use. Note: A variable of type byte may readily be compared to values of type integer (see below).

A one or two-dimensional array of latitudes.

A one or two-dimensional array of longitudes. Acceptable values range from -180 to 359.99.

Return value

A two-dimensional array of type byte is returned. It contains five possible values: 0=ocean, 1=land, 2=lake, 3=small island, 4=ice shelf. The size will be the size of lat and lon. If the user inputs a scalar value for lat and lon, then the return value will be a single value.

Description

This function returns a grid that contains a land sea mask given any (e.g. gaussian, fixed offset, curvilinear) latitude and longitude array. The return value can then be applied to any array on the same grid using mask.

A 1x1 degree basemap is available for use as the first argument. The user may modify this file a priori if desired.

See Also

mask

Examples

In the examples below, it is assumed that array@_FillValue is set for use in mask.

Example 1

mask_5.ncl (view example)

Example 2

Values at land and small island points will be set to _FillValue in the array data after creating a new land/sea mask from one-dimensional lat/lon variables:

  
   a    = addfile("landsea.nc","r")
   lsdata = a->LSMASK
   lsm  = landsea_mask(lsdata,data&lat,data&lon)
   data = mask(data,lsm.eq.1,False)
   data = mask(data,lsm.eq.3,False)

All values, expect for ocean points, will be set to _FillValue in the array data after creating a new land/sea mask from one-dimensional lat/lon variables:

; assume data is 3D (time,lat,lon)
  a    = addfile("landsea.nc","r")
  lsdata = a->LSMASK
  lsm = landsea_mask(lsdata,data&lat,data&lon)

; lsm is a 2D array, in order to use it in mask, we must conform it
; to the size of the 3D array "data". 
  data = mask(data,conform(data,lsm,(/1,2/)).ge.1,False)

All values, expect for ocean points, will be set to _FillValue in the array data after creating a new land/sea mask from two-dimensional lat/lon variables:

; data is 2D w/ 2D lat long coordinate variables (TLAT,TLON).
  a = addfile("landsea.nc","r")
  lsdata = a->LSMASK
  lsm = landsea_mask(lsdata,TLAT,TLON)

; lsm is a 2D array that can be used directly in mask
  data = mask(data,lsm.ge.1,False)    

A sample script which will:

1. generate a user specified global mask
2. generate a netCDF file
3. plot the generated mask.

Keep in mind that the NCL provided mask is 1x1 so higher resolution make not be well accomodated.

;==========================================================
; User Specifications
;==========================================================
nlat = 128
mlon = 256
typeMask = "integer"     ; "byte" [default] or "integer"

grdType = 0              ; 0=gaussian , 1=regular , 2=regular offset
lonStrt = 0              ; 0 [GM] or -180 [Dateline]

diro = "./"
filo = "SampleLandSeaMask.nc"

PLOT = True              ; create a plot [ps]
;==========================================================
; End Required User Specifications
; Note: User may edit the mask below
;==========================================================

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_csm.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/contributed.ncl"
load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/shea_util.ncl"

function localByte2Int ( x:byte )
local dimx, X
begin
  delete(x@_FillValue)

  dimx = dimsizes(x)
  X    = new ( dimx, "integer", "No_FillValue")
  X    = x
  return(X)
end

begin

  if (grdType.eq.0) then      ; Gaussian [ S->N, GM eastward]
      lat  = latGau(nlat, "lat", "latitude", "degrees_north")
      lon  = lonGlobeF(mlon, "lon", "longitude", "degrees_east")
      gw   = latGauWgt(nlat, "lat", "gaussian weights", "")
  end if

  if (grdType.eq.1) then      ; Regular  [ 90S->90N, GM eastward]
      lat  = latGlobeF(nlat, "lat", "latitude", "degrees_north")
      lon  = lonGlobeF(mlon, "lon", "longitude", "degrees_east")
  end if

  if (grdType.eq.2) then      ; Regular offset from pole and GM
      lat  = latGlobeFo(nlat, "lat", "latitude", "degrees_north")
      lon  = lonGlobeFo(mlon, "lon", "longitude", "degrees_east")
  end if

  if (lonStrt.lt.0) then
      lon = (/ lon - 180. /)  ; subtract 180 from all values
      lon&lon = lon           ; update coordinates
  end if

                              ; read in land sea mask basemap file
  b    = addfile("landsea.nc","r")

; lsm: five possible values: 0=ocean, 1=land, 2=lake, 3=small island, 4=ice shelf

  if (isvar("typeMask") .and. typeMask.eq."integer") then
      lsm  = localByte2Int( landsea_mask(b->LSMASK,lat,lon) ) ; type is "integer"
  else
      lsm  = landsea_mask(b->LSMASK,lat,lon)                  ; type is "byte"
  end if
  lsm@long_name = "Land-Sea Mask"
  lsm@units     = "0=ocean, 1=land, 2=lake, 3=small island, 4=ice shelf"
  printVarSummary(lsm)

;=================== OPTIONAL =============================
; Manually edit lsm [type byte] to create a custom land mask. [range 0-7 if byte]
;==========================================================
 ;lsm  = where (lsm.eq.2, 0, lsm) ; make lakes "ocean"
 ;lsm  = where (lsm.eq.2, 1, lsm) ; make lakes "land"
 ;lsm  = where (lsm.eq.3, 1, lsm) ; make island "land"
 ;lsm  = where (lsm.eq.4, 1, lsm) ; make ice "land"
 ;lsm@units     = "change as required"

;==========================================================
; Create netCDF
;==========================================================
   system("/bin/rm -f "+diro+filo)
   ncdf = addfile (diro+filo , "c")

   ncdf@title = "Land-Sea Mask"
   ncdf@creation_date = systemfunc("date")
   ncdf->LSMASK = lsm

;==========================================================
; Create netCDF
;==========================================================
if (PLOT) then

   wks = gsn_open_wks("ps","lsmask")
   gsn_define_colormap(wks,"wh-bl-gr-ye-re")

   res = True
   res@mpFillOn         = False                ; do not color-fill the map
   res@gsnTickMarksOn   = False                ; turn off all tick marks
   res@mpPerimOn        = True                 ; turn the map perimeter on
   res@mpPerimDrawOrder = "PostDraw"           ; draw the map perimeter last
   res@cnLinesOn        = False                ; turn off the contour lines
   res@cnLineLabelsOn   = False                ; turn off the contour line labels
   res@cnLevelSelectionMode = "ExplicitLevels" ; explicitly set the levels via cnLevels
   res@cnLevels         = (/1.,2.,3.,4./)      ; set the levels
   res@cnFillOn         = True                 ; turn on color fill
   res@cnFillMode       = "RasterFill"         ; use raster fill
   res@cnFillColors     = (/60,100,20,140,5/)  ; set the colors that will be used to color fill
   res@lbLabelStrings   = ispan(0,4,1)         ; labels for the labelbar boxes
   res@lbLabelAlignment = "BoxCenters"         ; put the labels in the center of the label bar boxes
   res@lbTitleString    = "0=ocean, 1=land, 2=lake, 3=small island, 4=ice shelf"  ; labelbar title
   res@lbTitleFontHeightF = 0.0125             ; labelbar title font height

   plot = gsn_csm_contour_map_ce(wks,lsm,res)
end if
end