TVMAP cheat sheet

---

GAMAP is now obsolete. We recommend using GCPy for analyzing output from recent GEOS-Chem versions. But we will preserve the GAMAP wiki documentation for reference.

---

This cheat sheet shows some of the most useful features of TVMAP that can be quickly tested at the command line (IDL prompt)... and used in your own programs.

Default behavior

Check:

DATA = DIST(30,20)
TVMAP, DATA
TVMAP, DATA, /SAMPLE, /CBAR

This is the same as (showing the implicit lon/lat range associated with the data):

DATA = DIST(30,20)
LON =-180. + findgen(30)*12 + 6. ; box center
LAT = -90. + findgen(20)* 9 + 4.5 ; box center
TVMAP, DATA, lon, lat

Zooming

To zoom, there is no need to cut the data to the window size, just use the LIMIT keyword. Compare:

TVMAP, DATA, LON, LAT, /GRID, /CONTINENTS
TVMAP, DATA, LON, LAT, /GRID, /CONTINENTS, LIMIT=[-10,0.,60.,25.]

Note that if you do not pass the LON and LAT associated to DATA, only the map is zoomed. Compare:

TVMAP, DATA, /GRID, /CONTINENTS, LIMIT=[-10,0.,60.,25.]
TVMAP, DATA, LON, LAT, /GRID, /CONTINENTS, LIMIT=[-10,0.,60.,25.]

It is strongly recommended to specify LON and LAT all the time.

LIMIT keyword tip

The following can be handy in a program, where you sometimes need to set the LIMIT. Setting LIMIT to 0 is the same as not setting it:

TVMAP, DATA, LIMIT=0

Out-Of-Range data and Colorbar

with a (default) white box

To indicate data below (above) a specific value, use MIN_VALID (MAX_VALID):

TVMAP, DATA, MIN_VALID=5., /SAMPLE, /CBAR

with a Triangle instead of a box

TVMAP, DATA, MIN_VALID=5., /TRIANGLE, /sample, /CBAR

with a non-white box

Use BotOutOfRange (TopOutOfRange) to specify the color for data below MIN_VALID (above MAX_VALID):

TVMAP, DATA, BOTOUTOFRANGE=!myct.gray50, MIN_VALID=5., /SAMPLE, /CBAR

with a non-white triangle

Combine Triangle and BotOutOfRange:

TVMAP, DATA, BOTOUTOFRANGE=2, MIN_VALID=5., /TRIANGLE, /CBAR

without any indication in the colorbar

Use a negative color index:

TVMAP, DATA, BOTOUTOFRANGE=-2, MIN_VALID=5., /SAMPLE, /CBAR

Tip: To denote out-of-range data with WHITE, but without a box or triangle in the colorbar, you must use the color index -17. White is available as index 0 and 17 with the standard set of colors of Gamap !MyCT.

TVMAP, DATA, BOTOUTOFRANGE=-17, MIN_VALID=5., /CBAR, /SAMPLE

Conditional insertion of triangles

Here is a wrapper that automatically add a triangle if, and only if, there is out of range data:

PRO WRAP_TVMAP, data, lon, lat, range, BOOR=BOORi, TOOR=TOORi, _extra=e

  ; Default values
  ; ---------------------------
  minvalid = range[0]  &   maxvalid = range[1]  &   triangle = 1
  BOOR = keyword_set( boori ) ? boori : !myct.bottom
  TOOR = keyword_set( toori ) ? toori : !myct.bottom+!myct.ncolors


  ; Check for out-of-range data
  ; ---------------------------
  cr  = range[sort(range)]
  nim = min(data, max=xam, /NaN)

  if ~ (nim lt cr[0] or xam gt cr[1]) then $
     UNDEFINE, minvalid, maxvalid, toor, boor, triangle
   

  ; Map plot
  ; ---------------------------
  TVMAP, data, LON,  LAT, /cbar, /continents, /sample,   $
         mindata=range[0],         maxdata=range[1],     $
         cbmin=range[0],           cbmax=range[1],       $
         
         ; denote out-of-range:
         BotOutOfRange = BOOR,   TopOutOfRange=TOOR,  Triangle=triangle, $
         min_valid=minvalid,     max_valid=maxvalid,     $
         
         _extra = e

  return
end

NaN data

To deal with NaN, you can set them to a very low or high value and use the MIN/MAX_VALID keywords. But you can also directly use the NAN_COLOR keyword (default to 0):

DATA[where(data gt 6)]=!values.f_nan

TVMAP, DATA, nan_color=!myct.orange

GRIDS

One or more GRID without DATA

If you just want to plot one grid, you can use the CTM_MAPGRID routine from GAMAP. For a more general approach, use MAP_GRID, like this (several tips at once!):

 ; no grid
 MAP_SET, /ORTHOGRAPHIC, 65., -15., 0., /isotropic, COLOR=!MYCT.BLACK
 
 ; 1st grid (not global)
 lats = -78  + findgen( 79 )*2
 lons = -180 + findgen( 121 )*3
 
 MAP_GRID, LATS=LATS, LONS=LONS, glinestyle=0, COLOR=!MYCT.black
 
 ; 2nd grid (automatic generation of LONS / LATS vectors from ranges
 ; and steps)
 lon=[-30, 30] & lat= [34, 70]
 dlon=1 & dlat=0.5
 
 lats = lat[0] + findgen( fix((lat[1]-lat[0])/dlat +1) )*dlat
 lons = lon[0] + findgen( (lon[1]-lon[0])/dlon +1 )*dlon
 
 MAP_GRID, LATS=LATS, LONS=LONS, glinestyle=1, COLOR=!MYCT.red, glinethick=2
 
 ; Continents
 MAP_CONTINENTS, /COAST, /COUNTRIES, COLOR=!myct.blue, MLINETHICK=2 

Control the GRID - (1) with /GRID

Setting /GRID, TVMAP will call MAP_GRID. Then you can pass keywords to MAP_GRID through the _EXTRA facility, like specifying the location of the grid lines (see MAP_GRID documentation for more on those keywords) or black/white box axes:

tvmap, data, /contin                                            ; no grid
tvmap, data, /contin, /grid                                     ; grid
tvmap, data, /contin, /grid, /BOX_AXES                          ; passsing MAP_GRID keywords
tvmap, data, /contin, /grid, LONS=-165., LATS=[-72.,-10,5,40]   ; passsing MAP_GRID keywords

But if the MAP_GRID keyword is also a MAP_SET keyword, then MAP_SET will trigger a second call to MAP_GRID, and you end up with two grids. So you cannot pass the following MAP_GRID keywords without having two grids (although the two grids may be identical, and you may not notice!). For example:

tvmap, data, /contin, /grid, glinestyle=2 ; two grids problem

; list of keywords common to MAP_SET and MAP_GRID (do not use them with TVMAP, /GRID):
 GLINESTYLE
 GLINETHICK
 LABEL
 LATALIGN
 LATDEL
 LATLAB
 LONALIGN
 LONDEL
 LONLAB

So, this method (grid keywords along /GRID) is useful but limited to keywords unknown to MAP_SET.

However, since v2.12 of GAMAP, you can use /GRID and specify the grid \emph{spacings} with DLON and DLAT keywords. The GXLABELS and GYLABELS can also be used to label every n-th gridlines (or none if zero). Compare the following to see how things work:

data=dist(40,40)
tvmap,data
tvmap,data, /grid
tvmap,data, /grid, dlat=8, dlon=10
tvmap,data, /grid, dlat=4, dlon=5, gxlabels=0, gylabels=0
tvmap,data, /grid, dlat=4, dlon=5, gxlabels=5, gylabels=4

Control the GRID - (2) with GRID=0

Not setting /GRID (or setting GRID=0), you can still trigger a call to MAP_GRID through MAP_SET, by using one of the grid keyword accepted by MAP_SET:

TVMAP, data, lon, lat, /contin, GLINESTYLE=0

To pass other grid keyword (those not accepted by MAP_SET), you must use the E_GRID keyword:

TVMAP, data, lon, lat, /contin, limit=[0,-160.,70,-30], latdel=8, londel=10, &
                       e_grid={box_axes:1}, nogxlabels=1, nogylabels=1

Note the use of NoGXLabel to leave control of the grid labels to MAP_GRID. This method gives you more control, since you can use all grid keywords, directly or with E_GRID.

Concrete example : plotting the GEOS-Chem grid box with TVMAP

You must pass the grid edges with LATS and LONS keywords to MAP_GRID. If the grid info structure associated with your data is called GridInfo, you will go with:

tvmap, data, xlon, ylat, /sample, &
       lats=gridinfo.yedge, lons=gridinfo.xedge, /grid

You can also improve the rendition with color:

tvmap, data, xlon, ylat, /sample, lats=gridinfo.yedge, lons=gridinfo.xedge, /grid, gcolor=!myct.gray15

However, if you want to modify other details of the grid, you must use the E_GRID keyword but not GRID. For example, the LINESTYLE of the grid:

tvmap, data, xlon, ylat, /sample, glinestyle=5, e_grid={lats:gridinfo.yedge, lons:gridinfo.xedge, color:=!myct.gray15}

What happens: there is no call to MAP_GRID in TVMAP (because we do not use /GRID), but instead a call to MAP_GRID triggered by MAP_SET (because we use GLINESTYLE).

FAQ : help, my plot has TWO grids!

   QUESTION: I try to modify some GRID features when calling TVMAP and end up with
   2 grids. What's happening?

   ANSWER: MAP_GRID can be triggered by :
    - TVMAP if /GRID is set
    - MAP_SET if grid related keywords accepted by MAP_SET are used.
     
   You used both /GRID and a grid keyword recognized by MAP_SET.
   Solution: do not use the /GRID keyword. See recommended method #2.

Control TVMAP settings from CTM_PLOT and/or GAMAP

Most of TVMAP keywords can be set when calling GAMAP or CTM_PLOT (thanks to the _extra facility of IDL):

gamap, file=ftest, 'anthsrce', dlon=2, dlat=2, lats=0.5, lons=-130.5,/usa, format='(f5.1)', &
       gylab=4,gxlab=10, min_valid=0.00000001

However, sometimes, a TVMAP keyword must be set with a different keyword in CTM_PLOT! For example, use YRANGE with CTM_PLOT to specify the MAXDATA passed to TVMAP:

YRANGE of CTM_PLOT <==> MAXDATA of TVMAP

Similarly, ON/OFF TVMAP keywords can be turn ON by default in CTM_PLOT or GAMAP, while they are OFF by default when calling TVMAP. You need to explicitly turn them OFF if you want them so. For example, by default, ISOTROPIC is off when calling TVMAP, but on when calling CTM_PLOT.

; unset default /isotropic 
CTM_PLOT, ....,  ISOTROPIC=0

Map projections

To get a list of ALL available map projections

Look into the IDL manual, or:

MAP_PROJ_INFO, PROJ_NAMES = NAMES
PRINT, TRANSPOSE(NAMES)

which opens programming possibilities.

Modifying TVMAP default map projection

You do not need to hack into TVMAP. Simply pass relevant MAP_SET keywords to TVMAP. You can overwrite MPARAM or/and LIMIT, or pass a new projection keyword like /LAMBERT.

DATA = DIST(30,20)
lon = -180. + findgen(30)*12 + 6.    ; box center
lat =  -90. + findgen(20)*9  + 4.5   ; box center
TVMAP, data, lon, lat, rectangle=0, GxLabels=0, /GOODES, /HORIZON

For a more elaborate projection, focusing on the USA,

Limit     = [40, -130, 45, -142, 40, -65, 24, -100]
ConUS_Y   = 37
ConUS_X   = -97
TVMAP, data, lon, lat, /CONTINENTS, MPARAM=[CONUS_Y, CONUS_X,0], LIMIT=LIMIT, /LAMBERT, /USA

or North America,

Limit     = [40, -140, 85, -142, 40, -50, 10, -100]
ConUS_Y   = 45
ConUS_X   = -97
TVMAP, data, lon, lat, MPARAM=[CONUS_Y, CONUS_X,0], LIMIT=LIMIT, /LAMBERT, /COUNTRIES, /CONTINENTS

or Europe:

Limit     = [40, -15, 75, 20, 40, 40, 30, 20]
ConUS_Y   = 57
ConUS_X   = 12
TVMAP, data, lon, lat, MPARAM=[CONUS_Y, CONUS_X,0], LIMIT=LIMIT, /LAMBERT, /COUNTRIES, /CONTINENTS

Using TVMAP and MULTIPANEL

simple way

Everything is handled automatically when only using TVMAP:

multipanel, 4
for k=0,3 do tvmap, data
multipanel,/off

But if it is combined with other type of plot, here is the procedure:

multipanel, 4

tvmap, data

multipanel, position=p
plot, findgen(12), color=!myct.black, position=p
multipanel, /advance, /noerase

tvmap,data
tvmap,data

multipanel,/off
   

advanced combination

Using /NOERASE and /ADVANCE in multiple calls to MULTIPANEL, let you arrange your plots however you like. Try something like this:

pro test

  data = dist(20,30)

  ; set a 2x2 panels
   multipanel, rows=2, cols=2

  ; set counterclockwise ordering
  !p.multi[4] = 1

  tvmap, data, title='plot 1'
  tvmap, data, title='plot 2'

  ; switch to 4x3 panels, and back to clockwise ordering
  multipanel, cols=4, rows=3,  /noerase
  !p.multi[4] = 0

  for k=3, 7, 2 do begin
     multipanel, /advance
     multipanel, /advance
     tvmap, data, title='plot ' + strtrim(k, 2)
     tvmap, data, title='plot ' + strtrim(k+1, 2)
  endfor

  ; reset
  multipanel, /off

  return
end

I let you figure out the unique colorbar (hint: use OMargin in the first call to MULTIPANEL).

Overplot lines or string

The active plot must be the last map projection, and not the next plot to come (which is the default). To stay on the map, use /NOADVANCE:

tvmap, dist(20, 20), /contin, /noadvance

LON=[-36., 54.] & LAT=[2., 74.]

plots, [LON[0], LON[1], LON[1], LON[0], LON[0]], &
       [LAT[0], LAT[0], LAT[1], LAT[1], LAT[0]], &
       color=!myct.black, thick=2,  _extra=e

Same story to use XYOutS for string.

About the SCALE keyword

Both MAP_SET and TVIMAGE accept the SCALE keyword. The IDL routine DEVICE (when using PS or PRINTER device) accepts the SCALE_FACTOR keyword. So be careful when using that _EXTRA facility! Note that TVMAP has two `scale' keyword for that purpose:

ScaleMapSet   to specify the MAP_SET SCALE keyword
ScaleMapImage to specify the TVIMAGE SCALE keyword

If you have any doubt try your keywords on this example, and add explicit keywords if needed:

pro my_routine, _extra=e

  open_device, _extra=e

  tvmap, dist(12,12), _extra=e

  close_device

end

Known Issue(s)

Bug with MAX_VALID

Try:

DATA = DIST(20,20)
Window,1 & TVMAP, DATA, MAX_VALID=20., /CBAR

This gives a wrong plot if X > MAX(DATA) and MAXDATA keyword is not used. The fix is to use both:

Window,2 & TVMAP, DATA, MAX_VALID=20., MAXDATA=20., /CBAR

--phs 13:14, 13 March 2012 (EDT)