0

UUssiinngg II DDLL iinn MM eetteeoorr oollooggyy VVeerr ssiioonn 55

Andy Heaps a.j.heaps@reading.ac.uk ©NCAS 2010

Acknowledgements Special thanks are due to the NCAS and Reading University Meteorology department IDL users for all their help and suggestions in improving this guide. In particular I would like to thanks Chris Bell, Paul Berrisford, Charles Boschetto, Roger Brugge, Ralph Burton, Jonny Day, Dan Hodson, Ricardo Fonseca, Chris Holloway, Pete Irvine, Dan Kirchbaum, Nick Klingaman, Deepthi Marathayil, Pratap Mohanty, Scott Osprey, Jonathan Robson, Sarah Sparrow, Andy Turner, Evangelos Tyrlis, Laura Wilcox and Ma Yin for their ideas, providing data and example plots for the guide. I am very grateful to Roger Brugge for permission to include his tephigram plotting code. I am also much indebted to the pvwave-idl newsgroup and ITT-VIS support for many interesting discussions and for answering the really difficult questions. The cover picture is of a snowmobile group heading towards the schooner Noorderlicht in Tempelfjorden, Spitsbergen.

1

At the core of this guide are a small set of routines that allow IDL users to quickly and easily make publication quality plots that are commonly used in meteorology. Data and postscript operators NCREAD - read a netCDF file. PSOPEN, PSCLOSE - open and close a postscript file. POS - select the plot position in the postscript page. SF - select a field for a contour or vector plot. Contour plots LEVS - select contour levels. CON - draw a contour plot. COLBAR - draw a colour bar. GFILL - fill patterns on a contour plot. Vector plots VECT - plot vectors. Graph plots GPLOT - draw lines, text and symbols on plots. GSYM - a selection of plotting symbols. EBAR - draw error bars. HIST - plot histograms. TEPHI - plot tephigrams. General AXES - label axes CS - select and manipulate colour scales. FEATURES - select features in a field. GLEGEND - make a legend for the plot. GSET - set up the plotting area. MAP - select a map projection. PCON - convert pressure to height in km and vice-versa. REGRID - regrid data using bi-linear interpolation. SCROP - convert input to a character string. Rotated grids RGAXES - draw rotated axes. RGROT, RGUNROT - move points between rotated grid and normal coordinates. Shape files COUNTRY - select countries from a shape file for plotting.

Setting up access to the guide routines Meteorology department at the University of Reading users: add setup idl idl_guide5 to your .kshrc file and open a new terminal window. All other users: See Appendix A for Unix, Mac and PC setup instructions.

2

Running the examples To start up IDL and to compile and run the first example in this guide type the following commands at the UNIX command prompt: idl ex1 Typing q or pressing escape in the graphic window will quit the viewing of the plot and return to the IDL command prompt.

PRO ex1 PSOPEN CS, SCALE=1 MAP LEVS, MIN=-32, MAX=32, STEP=4 CON, F=SF('gdata.nc', 'temp', p=1000), TITLE='Jan 1987', CB_TITLE='Temperature (Celsius)' PSCLOSE END In the first example we plot the temperature at 1000mb.

3

The program ex1.pro is made up from the following components: PRO ex1 – name the procedure. PSOPEN - open a postscript file. CS, SCALE=1 - set the colour scale to scale number 1. MAP - set the cylindrical map projection. LEVS, MIN=-32, MAX=32, STEP=4 - specify the contour levels. In this case we select a minimum of –32, maximum of 32 and a step of 4. CON, F=SF('gdata.nc', 'temp', p=1000), TITLE='Jan 1987', CB_TITLE='Temperature (Celsius)' This makes the contour plot. To the CON command we pass the temperature field at 1000mb from the netCDF file gdata.nc. PSCLOSE - close and view the postscript file. END - end the procedure. We could also select and contour the data using d=NCREAD('gdata.nc') CON, F=d.temp(*,*,0), X=d.lon, Y=d.lat,, TITLE='Jan 1987', CB_TITLE='Temperature (Celsius)' We know that level number 0 in the temperature field is 1000mb as: PRINT, d.p(0) 1000.00 The program examples, data and library can be accessed by typing gex, gdata or glib at the UNIX command prompt. Start off by copying the example that most closely matches the plot you’d like to make to your home directory. Then modify the code to try and inset your data and parameters into the code. i.e. gex cp ex1.pro ~ cd ~ nedit ex1.pro & Then edit the code as required in ex1.pro. This new version of ex1.pro takes precedence over the examples directory ex1.pro as it is in the current directory. If you are making changes to the ex1.pro program then a recompilation of the ex1.pro file is required: idl .compile ex1 ex1 As you become more familiar with the plotting routines you’ll be able to write plotting code without reference to the example code.

4

PRO ex2 PSOPEN MAP, LONMIN=-20, LONMAX=40, LATMIN=30, LATMAX=70 LEVS, MIN=-20, MAX=20, STEP=2.5, NDECS=1 CON, F=SF('gdata.nc', 'temp', P=1000) PSCLOSE END In the second example, we have zoomed into a region by setting the mapping using MAP, LONMIN=-20, LONMAX=40, LATMIN=30, LATMAX=70 The levels were also changed to better fit the temperature range over the plotted region. Notice that the levels were selected so that all the negative temperatures were shaded blue. In the LEVS command NDECS=1 was used to limit the number of decimal places of the levels to one.

5

PRO ex3 PSOPEN CS, SCALE=33, NCOLS=12 MAP, /NH LEVS, MIN=15150, MAX=16650, STEP=150 CON, F=SF('gdata.nc', 'ht', p=100), CB_TITLE='Height (m)', $ TITLE='Jan 1987 - 100mb Geopotential Height' PSCLOSE END Here we selected the 100mb geopotential height field and made a northern hemisphere polar plot using the /NH flag to the MAP command. CS, SCALE=4 - We also used colour scale number four which fits in better with the selected levels. Colour scale 4 is a sequential colour scale which indicates an increase of the field value. The CON command was a little long to fit on one line so the IDL continuation symbol $ was used.

6

PRO ex4 PSOPEN CS, SCALE=1 MAP LEVS, MIN=-32, MAX=32, STEP=4 CON, F=SF('gdata.nc', 'temp', p=1000), TITLE='Jan 1987', /NOFILL PSCLOSE END To create an unfilled contour plot add the /NOFILL option to the CON command.

7

PRO ex5 d=NCREAD('strf_anom.nc') PSOPEN, XSIZE=20000, YSIZE=5000, CCOLOUR=7 CS, SCALE=7 MAP, LATMIN=0, /ISOTROPIC LEVS, MIN=-6, MAX=5, STEP=1 CON, F=d.strf/1e6, X=d.x, Y=d.y, TITLE='Streamfunction anomaly*1e6 s!E-1!N', $ NEGATIVE_STYLE=2, ZERO_THICK=200, /NOFILL PSCLOSE END In example 5 we modified: PSOPEN, CCOLOUR=7 - coastlines were changed to colour 7 on SCALE=7, grey. MAP, LATMIN=0, /ISOTROPIC - plot only the northern hemisphere and make the scaling between longitude and latitude degrees equal. CON options: NEGATIVE_STYLE=2 - negative contour lines to be dashed. ZERO_THICK=200 - set zero line to be twice as thick as normal. The character string s!E-1!N was used to make s-1 in the title. There is more on text formatting in section 11 of the brief introduction to IDL in appendix C. The field was read in using NCREAD here as when it is divided the field by 1e6 the contour levels are easier to read.

8

PRO ex6 PSOPEN MAP, LONMIN=-20, LONMAX=40, LATMIN=30, LATMAX=70 LEVS, MIN=-20, MAX=20, STEP=2.5, NDECS=1 CON, FIELD=SF('gdata.nc', 'temp', p=1000), TITLE=’Jan 1987’, /BLOCK PSCLOSE END A block plot is where the individual cells of data are shaded according to their value. To make a block fill plot use the /BLOCK option to the CON command.

9

PRO ex7 PSOPEN, XPLOTS=2, YPLOTS=2 LEVS, MIN=-32, MAX=32, STEP=4 f=SF('gdata.nc', 'temp', p=1000) MAP CON, F=f, TITLE='Jan 1987' POS, XPOS=1, YPOS=2 MAP, /MOLLWEIDE CON, F=f, TITLE='Jan 1987' POS, XPOS=2, YPOS=1 MAP, /ROBINSON, LONMIN=0, LONMAX=360 CON, F=f, TITLE='Jan 1987' POS, XPOS=2, YPOS=2 MAP, SATELLITE=[0, 50] CON, F=f, TITLE='Jan 1987' PSCLOSE END In example 7 four different map projections are plotted on a page and the POS command is used to specify each position. The default position for a plot is POS, XPOS=1, YPOS=1 so it is not necessary to set it for the first plot made.

10

PRO ex8 PSOPEN, TICKLEN=-200, FONT=6, TFONT=6, TCHARSIZE=200, SPACE1=300, $ CB_WIDTH=75, CB_HEIGHT=200 CS, SCALE=1 MAP LEVS, MIN=-32, MAX=32, STEP=4 CON, F=SF('gdata.nc', 'temp', p=1000), TITLE=’Jan 1987’ PSCLOSE END In example 8 the following options to PSOPEN were changed: TICKLEN=-200 - set the tick length to be -200 pixels i.e. into the plot. FONT=6 - changed the general and title font to be Schoolbook. TCHARSIZE=200 - set title font to be twice normal size. SPACE1=300 - set the general spacing of text and lines to be 300 pixels. CB_WIDTH=75, CB_HEIGHT=200 - changed the colour bar to be 75% of the width of the plot and to be twice the normal height. See the reference section entry for PSOPEN for a full listing of all the options to PSOPEN.

11

PRO ex9 PSOPEN CS, COLS=[95, 125, 93, 269, 274, 369, 411, 421, 409] MAP, LONMIN=110, LONMAX=300, LATMIN=-50, LATMAX=40 LEVS, MANUAL=['-1', '-0.5', '0.5', '1', '1.5', '2', '2.5', '3'] CON, FIELD=SF('elnino.nc', 'sst'), TITLE='October SST Anomaly', $ CB_TITLE='Temperature (Celsius)' AXES, STEP=10 PSCLOSE END In this plot we defined a simple colour scale to fit the temperature anomaly by selecting the colours by name. In addition the /NOAXES keyword was passed to the CON command and a separate call was made to the AXES command to specify an axis label every ten degrees. This was done because the longitude extent of 190 degrees would have produced a strange set of longitude and latitude labels. The levels were placed inside quotes as the levels contained both integer and floating point numbers. If this had not been done IDL would have translated the levels into a set of floating point numbers and the formatting would have been lost. CS, COLS=[93, 123, 91, 267, 272, 367, 409, 419, 407] was used to manually select a colour scale from a table of colours.

12

PRO ex10 PSOPEN POS, XSIZE=10000, YSIZE=8000, XOFFSET=2000, YOFFSET=6000 CS, SCALE=30 MAP, LONMIN=50, LONMAX=150, LATMIN=0, LATMAX=60 LEVS, MIN=250, MAX=6000, STEP=250, /EXACT CON, F=SF('orog_lr.nc', 'ht'), TITLE='Low resolution orogra phy',$ /BLOCK, /NOLINES, /NOCOLBAR, /NOAXES AXES, XSTEP=20, YSTEP=10 POS, XSIZE=10000, YSIZE=8000, XOFFSET=14000, YOFFSET=6000 MAP, LONMIN=50, LONMAX=150, LATMIN=0, LATMAX=60 CON, F=SF('orog_hr.nc', 'ht'), TITLE='High resolution orography',$ /BLOCK, /NOLINES, /NOCOLBAR, /NOAXES AXES, XSTEP=20, YSTEP=10 COLBAR, COORDS=[3000, 3000, 23000, 3700], TITLE='Height (m)', /ALT PSCLOSE END Here we plotted low and high resolution block fill orography over India and the Himalaya region. The individual colour bars were turned off with the /NOCOLBAR option to CON. A separate call to COLBAR was made to produce a colour bar for both plots. The /ALT option to COLBAR alternated the text top and bottom on the colour bar or the text would overlap. When making separate calls to COLBAR the /EXACT keywords to LEVS must be used or a mismatch between plot colours and the colour bar can occur. POS was used to manually place the plots using the supplied sizes and offsets. IDL uses 1000 pixels per centimetre in postscript plots. To see where your plot is being positioned just divide the POS options by 1000 to get centimetres.

13

PRO ex11 d=NCREAD('lc1.nc') PSOPEN CS, SCALE=1, NCOLS=19 MAP, LONMIN=0, LONMAX=110, LATMIN=20, LATMAX=75, /SECTOR LEVS, MIN=-20, MAX=20, STEP=2, /EXACT CON, F=SF('lc1.nc', 'temp'), COL=INDGEN(21)+2, /NOFILL, /NOMAP, /NOAXES, TITLE='' LEVS, MANUAL=['-1.0', '-0.8', '-0.6', '-0.4', '-0.2', '0.2' , '0.4', '0.6', '0.8', '1.0'] CON, F=SF('lc1.nc', 'mslp'), NEGATIVE_STYLE=2, /NOFILL , /NOMAP, /NOAXES, TITLE='' AXES, STEP=20 PSCLOSE END In example 11 some LC1 experiment data was plotted. The individual temperature contour colours were specified with the COL option to CON. A further plot of mean sea level pressure anomaly was then overlaid on this with another call to CON.

14

PRO ex12 d=NCREAD('orca2.nc') PSOPEN, YPLOTS=2, /PORTRAIT CS, SCALE=1 MAP LEVS, MIN=-2, MAX=30, STEP=2 CON, FIELD=d.sst, X=d.longitude, Y=d.latitude, CB_TITLE='Temperature (Celsius)' POS, YPOS=2 MAP, LAND=12, OCEAN=8, /DRAW GPLOT, X=d.longitude, Y=d.latitude, SYM=1, /NOLINES, SIZE=10 AXES PSCLOSE END The top plot shows the Orca2 grid point locations with two northern poles and one southern pole. The bottom plot shows the sea surface temperature on this grid being contoured and plotted in the usual manner. Further discussion of contouring irregular grids can be found in the guide routines discussion section after these example plots.

15

PRO ex13 PSOPEN, SPACE2=800 LEVS, MIN=-32, MAX=32, STEP=4 CS, SCALE=1 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0 CON, F=SF('gdata.nc', 'u', MEAN='lon'), TITLE='Jan 1987 - Zonal Mean Zonal Wind', $ NEGATIVE_STYLE=2, ZERO_THICK=200,CB_TITLE=' ms!E-1!N' AXES, XSTEP=30, XTITLE='Latitude', YSTEP=-250, YTITLE='Pressure (mb)' PSCLOSE END The plotting region was set using GSET before contouring the data with negative contours dashed and a thicker zero contour line. The data was averaged over the longitudes with SF('gdata.nc', 'u', MEAN='lon') to get the zonal mean zonal wind. The plot to colour bar spacing was increased to 800 pixels with PSOPEN, SPACE2=800 so that the colour bar didn’t overwrite the x-axis title of ‘Latitude’. A separate call was made to AXES to label them with the specified axis labels. Note that a YSTEP= -250 was used as this is a pressure axis with YMIN=1000 and YMAX=0 . To zonally average the zonal wind we could also have used d=NCREAD('gdata.nc') TOTAL(d.u,1)/N_ELEMENTS(d.lon) Thhis sums the array over the first dimension of longitude and then divides by the number of longitudes to get the zonal mean zonal wind.

16

PRO ex14 d=NCREAD('gdata.nc') zonalu=SF('gdata.nc', 'u', MEAN='lon') PSOPEN CS, COLS=[464] LEVS, MANUAL=[-200, 0], /EXACT GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0.3, /YLOG CON, FIELD=zonalu, TITLE='Jan 1987 - Zonal Mean Zonal Wind', $ CB_TITLE='ms!E-1!N', /NOLINES, /NOCOLBAR LEVS, MIN=-100, MAX=35, STEP=5 CON, FIELD=zonalu, NEGATIVE_STYLE=2, ZERO_THICK=200, /NOF ILL AXES, XSTEP=30, XTITLE='Latitude', YVALS=['1000', '300', '100', '30', '10', '3', '1', '0.3'], $ YTITLE='Pressure (mb)', /NORIGHT ylabels=[0, 10, 20, 30, 40, 50, 56] yvals=PCON(ylabels, /TO_MB) AXES, /ONLYRIGHT, YVALS=yvals, YLABELS=ylabels, YTITLE ='Height (km)' PSCLOSE END Here we made a logarithmic y-axis by adding the /YLOG keyword to GSET. In this plot we used a single shade of grey for the negative values. A second call to CON was made to overlay the contour levels. Shading with grey is a common way of avoiding paying journal colour page charges. The right y-axis was labelled by height rather than pressure by using the PCON function to convert pressure to height. Be careful to not do the same for troposphere plots as the pressure height relation is only reliable for the stratosphere. The /NORIGHT and /ONLYRIGHT keywords to the AXES routine were used to plot the right y-axis in the correct way.

17

PRO ex15 d=NCREAD('stipple.nc') PSOPEN CS, SCALE=11, NCOLS=14 MAP, /ROBINSON LEVS, MIN=-30, MAX=30, STEP=5 CON, FIELD=d.climatology, X=d.longitude, Y=d.latitude, CB_TITLE='Temperature [Celcius]' PFILL, FIELD=d.climatology-d.jan1963, X=d.longitude, Y=d.lati tude, MIN=1, MAX=20 PSCLOSE END In example 15 the PFILL procedure is used to show and anomaly field on top of a contour plot. The contour plot is that of the 1957-2002 January climatology. The stippled field is that where the January 1963 temperature is one degree or less below this climatology. Stippling is commonly used to indicate anomalies and deviations. [PFILL has replaced the STIPPLE routine in the guide 4 routine library.]

18

PRO ex16 PSOPEN, SPACE2=800 f=SF('gdata.nc', 'u', MEAN='lon') LEVS, MIN=-32, MAX=32, STEP=4 CS, SCALE=1 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0 CON, F=f, TITLE='Jan 1987 - Zonal Mean Zonal Wind', $ NEGATIVE_STYLE=2, ZERO_THICK=200,CB_TITLE='ms!E-1!N ', /NOFILL PFILL, FIELD=f.data, X=f.lat, Y=f.p, MIN=28, MAX=100, S TYLE=6 AXES, XSTEP=30, XTITLE='Latitude', YSTEP=-250, YTITLE='P ressure (mb)' PSCLOSE END In example 16 a cross hatch pattern was used to indicate the areas where the zonal wind was above 28m/s.

19

PRO ex17 PSOPEN, SPACE2=800 CS, SCALE=1 LEVS, MIN=-40, MAX=15, STEP=5 GSET, XMIN=90.5, XMAX=1169.5, YMIN=1000, YMAX=10, /YLOG CON, F=SF('qbo.nc', 'zonalu'), TITLE='Zonal Mean Zonal Win d', $ CB_TITLE='ms!E-1!N', ZERO_THICK=200 yvals=[1000, 700, 500, 300, 200, 100, 70, 50, 30, 20, 10] xvals=[90.5, 480.5, 840.5, 1169.5] xlabels=['01/12/1978:12z', '01/01/1980:12z', '01/01/1981:12z', '01/12/1981:12z'] AXES, XVALS=xvals, XLABELS=xlabels, XTITLE='Time', $ YVALS=yvals, YLABELS=yvals, YTITLE='Pressure [hPa]' PSCLOSE END In this plot XVALS was associated with XLABELS to produce different labels on the x-axis other than the value at that point. We also set YVALS to be a string array so that we both set the YVALS and label them with the same array. A logarithmic y-axis was made and labelled with the pressure.

20

PRO ex18 PSOPEN CS, SCALE=1 GSET, XMIN=120, XMAX=240, YMIN=0, YMAX=199 LEVS, MIN=-8, MAX=5, STEP=1 CON, F=SF('u2.nc', 'u'), TITLE='Zonal wind',CB_TITLE=' ms!E-1!N', $ /NOLINES LEVS, MANUAL=[-1000, 0] CON, F=SF('u2.nc', 'u'), /NOLINELABELS, /NOFILL, TIT LE='' AXES, XVALS=[120,150,180,210,240], $ XLABELS=['120E', '150E','180','150W', '120W'], $ YVALS=[12,43,74,102,133,163,194], $ YLABELS=['Jan 1995','Feb 1995','Mar 1995','Apr 1995', $ 'May 1995','Jun 1995','Jul 1995'] PSCLOSE END

Here we made a longitude-time plot. A separate call to CON was made draw a single zero contour line. The individual contour lines weren’t drawn as this would have made seeing the structure within the data very difficult.

21

Data from http://www.cate.mmu.ac.uk

PRO ex19 PSOPEN CS, SCALE=26, NCOLS=9 MAP LEVS, MANUAL=['1E6', '5E6', '1E7', '5E7', '1E8', '5E8', '1E9' , '5E9', '1E10', '5E10'], /EXACT CON, F=SF('vapour.nc', 'vapour'), TITLE='Total Emission s - January',$ CB_TITLE='H!I2!NO vapour(g)', /NOLINES PSCLOSE END Example 19 shows a plot of some AERO2k aircraft water emission vapour total column data for January. LEVS is used with the MANUAL keyword and the levels are preserved by using quotes to be used in the colour bar. If the quotes weren’t used then the levels would have been labelled as floating point numbers.

22

In this Mollweide plot the ice, land and ocean temperatures and cloud amounts were all plotted sequentially with different colour scales. Each associated colour bar was placed underneath the plot so that there were no gaps between them. The code for this is too long to fit on the page so if you are interested in the details of this then please type glib nedit ex20.pro &

23

PRO ex21 PSOPEN CS, SCALE=24, NCOLS=12, /REV, SAVE=1 CS, SCALE=29, NCOLS=23, SAVE=2 CS, /MERGE MAP LEVS, MANUAL=[-5000, -4000, -3000, -2000, -1000, -800, -600, -400, -200, -100, -50, $ 0, 50, 100, 200, 400, 600, 800, 1000, 1250, 1500, 1750, 2000, 2250, 2500, $ 2750, 3000, 3500, 4000, 4500, 5000, 5500, 6000] CON, F=SF('ETOPO2v2c_f4.nc', 'z'), /NOLINES, /CB_ALT, /IMG, /NOMAP, TITLE='' PSCLOSE END

In this example colour scales 24 and 29 were merged together to make a combined colour scale suitable for orography and bathymetry. The data in this dataset is of size 10800x5400 points and so plotting it takes rather a long time. On a 2.9GHz Xeon server contouring this data took six minutes and produced a 3GB postscript file which is too unwieldy to use. When the /IMG flag was used to the CON routine to select an image for the colour filled contours rather than postscript polygons this was reduced to three minutes and 4MB. The data set ETOPO2v2c_f4.nc is available locally within the department of Meteorology at the University of Reading. If you are an external user please download it from http://www.ngdc.noaa.gov/mgg/fliers/01mgg04.html by clicking on the data link in the web page.

24

PRO ex22 PSOPEN, /PORTRAIT CS, SCALE=24, NCOLS=12, /REV, SAVE=1 CS, SCALE=29, NCOLS=23, SAVE=2 CS, /MERGE MAP, LONMIN=-15, LONMAX=10, LATMIN=40, LATMAX=70, /ISOTR OPIC LEVS, MANUAL=INDGEN(26)*100-1100 CON, F=SF('ETOPO2v2c_f4.nc', 'z'), /NOLINES, /CB_ALT, /IMG, /NOMAP, TITLE='' PSCLOSE END In example 22 the /ISOTROPIC keyword is used in a plot of the orography and bathymetry of the UK and surrounding countries. The data set ETOPO2v2c_f4.nc is available locally within the department of Meteorology at the University of Reading. If you are an external user please download it from http://www.ngdc.noaa.gov/mgg/fliers/01mgg04.html by clicking on the data link in the web page.

25

PRO ex23 PSOPEN, /PORTRAIT, XSIZE=15000, YSIZE=15000;, YOFFSET=9000 MAP, LONMIN=-6, LONMAX=2, LATMIN=50, LATMAX=56, /HIRES , /ISOTROPIC CS, COLS=[453, 534], NCOLS=10 LEVS, MIN=200, MAX=1400, STEP=200 d=NCREAD('ukterrain.nc') CON, F=d.hgt, X=d.lon, Y=d.lat, /NOLINES, /NOAXES, /NOCOLBAR CS, COLS=[98, 174, 224, 252, 329, 370, 27, 453] LEVS, MANUAL=['0.25','0.5','1','2','4','8','16','32'], /UPPER CON, F=SF('rainfall_rate.nc', 'rrate'), /NOLINES, $ /CB_RIGHT, CB_TITLE='mm/hr', TITLE='15/06/2009-1500' GPLOT, X=-1.92, Y=52.5, SYM=13, SIZE=100,COL=1 GPLOT, X=-1.77, Y=52.5, TEXT="Birmingham", ALIGN=0.0, VAL IGN=0.5 GPLOT, X=0.17, Y=51.5, SYM=13, SIZE=100, COL=1 GPLOT, X=0.0, Y=51.5, TEXT="London", ALIGN=1.0, VALIGN=0. 5 GPLOT, X=-2.24, Y=53.48, SYM=13, SIZE=100, COL=1 GPLOT, X=-2.09, Y=53.48, TEXT="Manchester", ALIGN=0.0, VAL IGN=0.5 GPLOT, X=-3.0, Y=53.25, SYM=13, SIZE=100, COL=1 GPLOT, X=-2.85, Y=53.25, TEXT="Liverpool", ALIGN=0.0, VALIGN =0.5 PSCLOSE END In this plot the orography is initially plotted in greyscale. Over the top of this a radar indication of the rainfall rate is plotted with a new colour scale.

26

PRO ex24 d=NCREAD('eddies.nc') PSOPEN LEVS, MIN=-4, MAX=28, STEP=1 CS, SCALE=26, NCOLS=36 MAP, LONMIN=-100, LONMAX=10, LATMIN=0, LATMAX=70, /HIRES , /ISOTROPIC CON, F=d.temperature(*,*), X=d.longitude, Y=d.latitude, /NOLINES PSCLOSE END In this example we have high resolution data with eddies in the ocean temperature. Normally using 36 colours is too many for the eye to pick up but in this case the ocean eddies are readily identifiable. Generally between 12 and 18 colours are ideal for a contour plot.

If you need more colours than this then the colour scale text will overwrite adjacent labels. In this case the CB_LABELS=cb_labels option to CON will label just the levels specified.

27

PRO ex25 d=NCREAD('gdata.nc') PSOPEN CS, SCALE=1, NCOLS=14 LEVS, MIN=-300, MAX=300, STEP=50 MAP CON, FIELD=d.ht(*,*,0), X=d.lon, Y=d.lat, /NOCOLBAR f=FEATURES(FIELD=d.ht(*,*,0), MIN=-100, MAX=200, X=d.lon, Y= d.lat, $ THRESHOLD=10, LABEL=0, CHARSIZE=300, COL=1) PSCLOSE END

Here a contour field of geopotential height is plotted and then the FEATURES routine is used to overlay high and low labels on the plot for lows less than 100 and highs greater than 200.

28

PRO ex26 PSOPEN MAP, /DRAW COUNTRY, ISO=['RUS', 'GRL'], FILLCOL=[16, 5] MAP, /DRAW AXES PSCLOSE END In example 26 a map is drawn and then Greenland and Russia are shown using the COUNTRY procedure.

29

PRO ex27 d=NCREAD('stations_china.nc') PSOPEN, AXISTYPE=2, XSIZE=21000, YSIZE=12000, YOFFSET=2000, SPACE2=1400 CS, SCALE=1, NCOLS=14, /REV LEVS, MIN=-120, MAX=120, STEP=20 f=GRIDDATA(d.longitude, d.latitude, d.precip_anom, /KRIGING, START=[73, 19], $ DELTA=1, DIMEN=[63,37], MISSING=-999) MAP, LONMIN=70, LONMAX=140, LATMIN=15, LATMAX=55, /HIRES, /I SOTROPIC, /SET COUNTRY, ISO=['CHN', 'TWN'], FILLCOL=[16, 5], COL=[1,1], MASK='mask_china' CON, F=f, X=INDGEN(63)+73, Y=INDGEN(37)+19, CB_TITLE='Precipitation Anomaly (mm)', $ /NOLINES, MASK='mask_china', /NOMAP COUNTRY, ISO=['CHN', 'TWN'] AXES PSCLOSE END In example 27 some station data is read in and converted to a regularly gridded data set using the IDL routine GRIDDATA . The COUNTRY routine is used to make a mask for China and Taiwan and this is stored in the file mask_china. This mask is the passed to the CON routine and used for masking out regions of the contour plot outside of these countries.

30

PRO ex28 PSOPEN CS, SCALE=26 MAP, OCEAN=2, LAND=14, /DRAW GPLOT, X=-120, Y=8, TEXT='Nino3 region', FONT=7 xpts=[-150, -150, -90, -90, -150] ypts=[-5, 5, 5, -5, -5] GPLOT, X=xpts, Y=ypts, FILLCOL=17, THICK=400 GPLOT, X=43, Y=55, TEXT='Moscow', ALIGN=0.0, VALIGN=0.5 GPLOT, X=37, Y=55 , SYM=3, SIZE=200, COL=25 GPLOT, X=103, Y=-30, TEXT='Australia', CHARSIZE=200, ORIENTA TION=-90, COL=22 GPLOT, X=3000, Y=19000, TEXT='Text above plot and left justified', FONT=2, $ ALIGN=0.0, SIZE=150, /BOLD, /ITALIC, /DEVICE GPLOT, X=26700, Y=19000, TEXT='Text above plot and right justified', FONT=2, $ ALIGN=1.0, SIZE=150, /DEVICE AXES PSCLOSE END Example 28 shows how to draw lines, text and symbols on plots. The locations of these are in data units which are specified by MAP (degrees) or GSET. If the keyword /DEVICE is used then the locations are in device or pixel coordinates. Using device coordinates means the bottom left corner is (0,0) and the size of the default A4 paper size is 29700x21600 pixels.

31

PRO ex29 d=NCREAD('katrina.nc') cats=['EXTRATROPICAL-DEPRESSION', 'TROPICAL-DEPRESSI ON', 'TROPICAL-STORM',$ 'HURRICANE-1','HURRICANE-2','HURRICANE-3','H URRICANE-4','HURRICANE-5'] PSOPEN CS, SCALE=1 MAP, LONMIN=-100, LONMAX=-60, LATMIN=10, LATMAX=50, OCEAN= 10, LAND=11, /HIRES, /DRAW CS, COLS=[425, 122, 230, 252, 288, 358, 43, 399] FOR ix=0, N_ELEMENTS(d.lon)-2 DO BEGIN cat=WHERE(STRING(BYTE(d.status(*,ix))) EQ cats) mycat=cat(0) GPLOT, X=[d.lon(ix), d.lon(ix+1)], Y=[d.lat(ix), d. lat(ix+1)] , THICK=300, $ SIZE=60, SYM=3, COL=mycat+2 ENDFOR GLEGEND, LEGPOS=9, LABELS=cats, COL=INDGEN(8)+2, FILL COL=0, TYPE=1 GPLOT, X=14750, Y=19000, CHARSIZE=200, /DEVICE, $ TEXT='Hurricane Katrina - dots are six hours apart' AXES, STEP=10 PSCLOSE END

In example 29 the path and intensity of hurricane Katrina are plotted on a map using the GPLOT routine. The GLEGEND routine is used to make a legend indicating the relationship of the colour of the track to the hurricane intensity.

32

PRO ex30 d=NCREAD('ukmo_test.nc', VAR='p') PSOPEN, XSIZE=20000 MAP, /DRAW CS, SCALE=2, NCOLS=12 f=FEATURES(FIELD= d.p(*,*, 0, 0)/100.0, MAX=1010, X=d.longitude, Y=d.latitude, $ THRESHOLD=10, /DRAW, /V) MAP, /DRAW AXES GLEGEND, COL=INDGEN(MAX(f.max)+1)+2, LABELS=SCROP(f.maxp ts), LEGPOS=15, TYPE=1 PSCLOSE END

In this example the FEATURES routine is used to find the features where the surface pressure is greater than 1010mb. The /DRAW option to features draws the locations of the features on a map. The /V option to FEATURES prints on the command line the number of points in each feature.

33

PRO ex31 PSOPEN CS, SCALE=1 MAP, LONMIN=10, LONMAX=120, LATMIN=-30, LATMAX=30 VECT, F=SF('gwinds.nc', ['u','v'], HYBRID_P_X1000=869.832), $ LENGTH=200, MAG=10, MUNITS='ms!E-1!N' AXES, STEP=10 PSCLOSE END In example 31 the u and v components of the wind were selected at 870mb and were passed to the VECT routine for plotting. The mapping was set and drawn by adding the /DRAW option to MAP .

We could also have passed the winds into the VECT routine as individual u and v fields using d=NCREAD('gwinds.nc') VECT, U=d.u(*,*,3), V=d.v(*,*,3), X=d.longitude, Y=d.latit ude, $ LENGTH=200, MAG=10, MUNITS='ms!E-1!N'

34

PRO ex32 d=NCREAD('gwinds.nc') uv=SF('gwinds.nc', ['u', 'v'], hybrid_p_x1000=99.2468) PSOPEN, XPLOTS=2 CS, SCALE=1 MAP, /NH VECT, F=uv, MAG=10, MUNITS='ms!E-1!N' AXES, STEP=30 POS, XPOS=2 MAP, /NH VECT, F=uv, MAG=10, MUNITS='ms!E-1!N', PTS=40 AXES, STEP=30 PSCLOSE END

With polar vectors, the regular latitudes contract to give a ‘bulls eye’ effect as seen in the left plot. When the PTS=40 option is added to the VECT routine for polar plots the data is interpolated using bi-linear interpolation to 40 regularly spaced points in both the x and y directions. With the data interpolated in this manner it is much easier to see the wind direction than in the regularly plotted vectors at their original longitudes and latitudes.

35

PRO ex33 d=NCREAD('epflux.nc') PSOPEN CS, SCALE=6, NCOLS=10 LEVS, MIN=-2, MAX=2, STEP=0.5, NDECS=1 GSET, XMIN=0, XMAX=90, YMIN=1000, YMAX=0, TITLE='EP Flux and Zonal Wind Anomalies' CON, X=d.latitude, Y=d.plev, FIELD=d.u, ZERO_STYLE=2, /NOCOLBAR VECT, X=d.latitude, Y=d.plev, U=d.epfu, V=d.epfv, $ MAG=['1E14', '1E19'], LENGTH=[100, 200], MUNITS=['m!E2!Ns!E-2!N', 'ms!E-2!NPa'] AXES, XSTEP=15, YSTEP=-200, YMINOR=-50, XTITLE='Latitude (N)', YTITLE='Pressure (hPa)' PSCLOSE END Some plots have widely differing scales for the u and v components as in this example of the Elliasen-Palm flux. If your plot requires a precise angle for the vector then:

1) PSOPEN, XSIZE=xsize, YSIZE=ysize will set your plot size in pixels. 1cm=1000 pixels. 2) Use the LENGTH=length option to VECT to set your vector lengths in the x and y-directions. These

are by default 100 (%) which is 300 pixels (0.3cm). 3) Use MAG=mag option to VECT to set the magnitudes of the u and v-components.

36

PRO ex34 xpts=FINDGEN(361) PSOPEN CS, SCALE=1 GSET, XMIN=0, XMAX=360, YMIN=-1, YMAX=1 GPLOT, X=xpts, Y=SIN(xpts*!DTOR) AXES PSCLOSE END In example 34 a plot of a sine curve is made. To convert from degrees to radians the degrees to radians conversion factor !DTOR is used. Calling AXES without any user supplied values gives default axis values that can be improved on by specifying some extra keywords, as shown in the next example.

37

PRO ex35 xpts=FINDGEN(361) ypts=[[SIN(xpts*!DTOR)], [COS(xpts*!DTOR)]] PSOPEN, THICK=200, CHARSIZE=150, XOFFSET=2000 CS, SCALE=1 GSET, XMIN=0, XMAX=360, YMIN=-1, YMAX=1 AXES, XSTEP=30, XTITLE='Degrees', YTITLE='Amplitude', YSTEP=0.25, NDECS=2 GPLOT, X=xpts, Y=ypts, /LEGEND, LEGPOS=3, COL=[3, 18], LABELS=['Sine', 'Cosine'] PSCLOSE END In example 35 sine and cosine curves are plotted and a legend was made. The axes were better labelled by specifying different steps and labels for the x and y-axes. To make the plot easier to see the lines were made thicker and the text larger with the options THICK=200, CHARSIZE=120 to PSOPEN. The plot was shifted slightly to the right with XOFFSET=2000 so that there was space for the y-axis title of ‘Amplitude’.

38

PRO ex36 d=NCREAD('fieldsite.nc') PSOPEN, THICK=200, CHARSIZE=140 CS, SCALE=1 GSET, XMIN=7, XMAX=25, YMIN=-5, YMAX=15, TITLE='Reading field site temperatures' labels=['Maximum', 'Minimum'] GPLOT, X=d.day, Y=d.temperature, /LEGEND, LEGPOS=7, SYM=[1, 2], $ COL=[18, 3], LABELS=labels xvals=INDGEN(10)*2+7 xlabels=SCROP(xvals)+' Feb' AXES, XVALS=xvals, XLABELS=xlabels, YSTEP=5, YTITLE='Te mp [Deg C]', MINOR=1 PSCLOSE END

Example 36 shows the minimum and maximum at the University of Reading field site. The data points have markers associated with them by using the SYM keyword to GPLOT .

39

(Temperature data from http://www.engr.udayton.edu/weather/citylist/World.htm) PRO ex37 d=NCREAD('dailyt.nc') PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=28 GSET, XMIN=1, XMAX=365, YMIN=-30, YMAX=40, TITLE='Daily tem perature' xvals=[1,31,59,90,120,151,181,212,243,273,304,334] months=['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug',' Sep','Oct','Nov','Dec'] cities=['Beijing', 'Mumbai', 'Moscow', 'Sydney', 'Winnipeg' , 'Brasilia'] cols=INDGEN(6)+2 GPLOT, X=d.day, Y=d.temp, /LEGEND, LEGPOS=6, COL=cols, LABELS=cities AXES, XVALS=xvals, XLABELS=months, XTITLE='Month', YST EP=10, YTITLE='Degrees Celsius' PSCLOSE END In example 37 the x-values in days were translated into months and plotted using the AXES procedure. The legend position was also moved using the LEGPOS keyword to GPLOT to a central position as there was space there where no lines from the graph were drawn.

40

(Data from http://www.esrl.noaa.gov/gmd/webdata/ccgg/trends/co2_mm_mlo.dat) PRO ex38 d=NCREAD('maunaloa.nc') PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=1 GSET, XMIN=1958, XMAX=2010, YMIN=310, YMAX=390, $ TITLE='Atmospheric CO!I2!N at Mauna Loa Observatory' GPLOT, X=d.time(0:186), Y=d.co2(0:186), COL=3 GPLOT, X=d.time(186:N_ELEMENTS(d.time)-1), Y=d.co2(186:N_ELEMENTS(d.time)-1), COL=18 GLEGEND, LEGPOS=1, COL=[3, 18], LABELS=['SIO', 'CDIAC' ] AXES, XVALS=INDGEN(6)*10+1960, XTITLE='Year', YSTEP=10, YTITL E='Concentration (ppm)' PSCLOSE END In this plot the CO2 concentration at Mauna Loa was plotted for two different stations. As the data came from two different stations this was differentiated by making into two curves. The crossover point (pt=186) is the date the monitoring station used was changed, February 1974. A separate call to the GLEGEND procedure was made to form a legend for the two lines.

41

PRO ex39 d=NCREAD('gdata.nc') zonalt=TOTAL(d.temp,1)/N_ELEMENTS(d.lon) zonalu=TOTAL(d.u,1)/N_ELEMENTS(d.lon) PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=28 GSET, XMIN=-90, XMAX=90, YMIN=-30, YMAX=30, $ TITLE='Zonal Mean Temperature and Zonal Mean Zonal Wind' GPLOT, X=d.lat, Y=zonalt(*,0), COL=4 AXES, YSTEP=10, YTITLE='Temperature (Celsius)', /ONLYLEFT AXES, XSTEP=30, XTITLE='Latitude', /NOLEFT, /NORIGHT GSET, XMIN=-90, XMAX=90, YMIN=-15, YMAX=15 GPLOT, X=d.lat, Y=zonalu(*,0), COL=7 AXES, STEP=5, YTITLE='Zonal Wind ms!E-1!N', /ONLYRIGHT GLEGEND, LEGPOS=9, COL=[7, 4], LABELS=['Zonal Wind', 'Te mperature'] PSCLOSE END In example 39 a graph with two independent y-axes is plotted. The /NORIGHT was used to omit the right y-axis. A second call was then made to GSET to reset the plotting limits. Finally another call to AXES was made with the /ONLYRIGHT keyword to draw the right y-axis.

42

PRO ex40 d=NCREAD('amo.nc') PSOPEN, THICK=300, CHARSIZE=150 CS,SCALE=28 GSET, XMIN=1870, XMAX=2003, YMIN=-0.3, YMAX=0.3, TITLE='AMO I ndex' GPLOT, X=d.year, Y=d.index, BELOW=4, ABOVE=2 AXES, XSTEP=10, YSTEP=0.1, NDECS=1 PSCLOSE END In example 40 the ABOVE and BELOW keywords to GPLOT were used to fill the curve above and below the zero line with different colours.

43

PRO ex41 d=NCREAD('gdata.nc') zonalu=TOTAL(d.temp,1)/N_ELEMENTS(d.lon) profiles=TRANSPOSE([zonalu(12, *), zonalu(36, *), zonalu(60, *)]) labels=['60S', 'Equator', '60N'] PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=28 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0.3, /YLOG, $ TITLE='Zonal Mean Zonal Wind (ms!E-1!N)' GPLOT, X=profiles, Y=d.p, /LEGEND, LEGPOS=9, COL=[2, 3, 4], LABELS=labels AXES, XSTEP=30, XTITLE='Latitude', YTITLE='Pressure ( mb)', /NORIGHT, $ YVALS=['1000', '300', '100', '30', '10', '3', '1', '0.3'] ylabels=[0, 10, 20, 30, 40, 50, 56] yvals=PCON(ylabels, /TO_MB) AXES, /ONLYRIGHT, YVALS=yvals, YLABELS=ylabels, YTITLE ='Height (km)' PSCLOSE END Here we plot the zonal mean zonal winds at three latitudes on a logarithmic vertical y-axis. The IDL routine TRANSPOSE was used to rotate the profiles array so that the three lines were plotted vertically rather than horizontally.

44

PRO ex42 d=NCREAD('three_axes.nc') PSOPEN, YOFFSET=6000, /PORTRAIT CS, SCALE=28 GSET, XMIN=-2.0, XMAX=0.0, YMIN=2200, YMAX=0 GPLOT, X=d.temperature, Y=d.pressure AXES, YTITLE='Pressure (decibar)', XTITLE='Temperatu re (Celsius)', $ YSTEP=-200, NDECS=1 GSET, XMIN=34.5, XMAX=35, YMIN=2200, YMAX=0 GPLOT, X=d.psal, Y=d.pressure, COL=2 AXES, /ONLYLOWER, OFFSET=2000, STEP=0.1, NDECS=1, COL=2, XTITLE='Salinity (psu)' GSET, XMIN=27, XMAX=38, YMIN=2200, YMAX=0 GPLOT, X=d.density, Y=d.pressure, COL=4 AXES, /ONLYLOWER, STEP=1, OFFSET=4000, COL=4, XTITLE='Density' GLEGEND, LEGPOS=3, LABELS=['Temperature', 'Salinity' , 'Density'],$ COL=[1,2,4] PSCLOSE END

In example 42 three variables with their corresponding axes are plotted on the same graph. A call to GSET is needed for each variable and the corresponding axes are offset using the OFFSET option to the AXES command.

45

PRO ex43 PSOPEN, XPLOTS=2, THICK=200, CHARSIZE=150 CS, SCALE=7 xpts=INDGEN(12)+1 ypts=[10, 21, 26, 33, 35, 37, 38, 35, 33, 26, 21, 10] GSET, XMIN=1, XMAX=12, YMIN=0, YMAX=40 AXES, XSTEP=1, YSTEP=5, /GRID, GCOL=4 GPLOT, X=xpts, Y=ypts, SYM=2 POS, XPOS=2 GSET, XMIN=1, XMAX=12, YMIN=0, YMAX=40 newx=FINDGEN(111)/10+1 newy=SPLINE(xpts, ypts, newx) AXES, XSTEP=1, YSTEP=5, /GRID, GCOL=4 GPLOT, X=xpts, Y=ypts, SYM=2, /NOLINES GPLOT, X=newx, Y=newy PSCLOSE END

In example 43 the IDL routine SPLINE to make a smooth curve through a set of points using cubic spline interpolation. The FINDGEN routine was used to make a new set of x-points (newx) for passing to SPLINE and for plotting the new curve.

46

PRO ex44 PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=7 xpts=FINDGEN(41)/10 ypts=xpts*2+RANDOMN(0.0, 41) GSET, XMIN=0, XMAX=4, YMIN=-1, YMAX=10 GPLOT, X=xpts, Y=ypts, SYM=2, /NOLINES coefficients=LINFIT(xpts, ypts, yfit=yfit) GPLOT, X=xpts, Y=yfit AXES, STEP=1 PSCLOSE END Here we used the IDL function LINFIT . This fits the data (xpts, ypts) to the linear model, y = A + Bx, by minimizing the chi-square error statistic. The IDL routine RANDOMN was used to generate the random data for plotting.

47

PRO ex45 d=NCREAD('errorplot.nc') PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=27 GSET, XMIN=1900, XMAX=2010, YMIN=-3, YMAX=2 AXES, XSTEP=20, YSTEP=0.5, NDECS=1, /HGRID, GCOL=34, $ YTITLE='Temperature Anomaly [deg.C]', XTI TLE='Year' GPLOT, X=d.years, Y=d.temp_anom, SYM=2, SIZE=150 FOR ix=0, N_ELEMENTS(d.years)-1 DO BEGIN EBAR, X=d.years(ix), Y=d.temp_anom(ix), ERROR_Y=d.errors(ix) ENDFOR PSCLOSE END

In this example a simple error bar plot is made. A line is drawn between the temperature points and a diamond marker at the point value. The error bars for each point are then plotted within a loop by calling the EBAR routine with the error bar at that point. More information on the other EBAR options is available at the end of the guide.

48

PRO ex46 d=NCREAD('rainhist.nc') PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=7 GSET, XMIN=1970, XMAX=2008, YMIN=-600, YMAX=300 AXES, XSTEP=5, XTITLE='Year', YSTEP=100, YTITLE='Rainf all Surplus/Deficit (mm)', /HGRID HIST, X=d.years, Y=d.rainfall, FILLCOL=6 PSCLOSE END

Example 46 is a simple bar chart of rainfall surplus/deficit. The bars are filled with grey by specifying FILLCOL=6 .

49

PRO ex47 d=NCREAD('gprobability.nc') PSOPEN, THICK=200, CHARSIZE=140 CS, SCALE=1 GSET, XMIN=350, XMAX=1000, YMIN=0.0, YMAX=0.3 AXES, XSTEP=50, YSTEP=0.1, YMINOR=0.025, NDECS=1, $ XTITLE='Seasonal Total (mm)', YTITLE='Probability' HIST, X=d.seasonal_total, Y=d.probablity1, WIDTH=150, FILLCOL=1 HIST, X=d.seasonal_total+18, Y=d.probablity2, WIDTH=150, FILLCOL=18 GLEGEND, LEGPOS=9, LABELS=['1xCO!I2!N', '2xCO!I2!N'], C OL=[1, 18], TYPE=1 PSCLOSE END Example 47 shows placing two bar charts side by side to allow a direct comparison between the two scenarios.

50

PRO ex48 d=NCREAD('hurricane_cat.nc') PSOPEN, THICK=200, CHARSIZE=150 CS, SCALE=11 GSET, XMIN=1850, XMAX=2007, YMIN=0, YMAX=85 col=[13, 2, 4, 6, 9, 8] HIST, X=d.year+1.5, Y=REVERSE(d.category, 2), /TOWER, FILLCOL=col AXES, XSTEP=50, XTITLE='Year', YSTEP=10, YTITLE='Number of Storms' cats=['Category 5', 'Category 4','Category 3','Category 2','Category 1', 'Tropical Storm'] GLEGEND, LEGPOS=1, LABELS=cats, COL=col, TYPE=1 PSCLOSE END In example 48 the /TOWER keyword to the HIST routine was used to build a combined bar chart showing the total number of storms from 1850 to 2000.

51

Example 49 shows using the GPLOT command to show the range of values for two model runs between April and December. Choosing the width of the plotted lines so that they don’t overlap gives a good comparison of the range of values between the two runs. The code isn’t shown here as it is just a little too long to fit on one page.

52

Tephigrams

guide_data=GETENV('GUIDE_DATA') IDL> tephi, FILE=guide_data+'/tephi.dat' CP FLOAT = 1005.46 ALV FLOAT = 2500.00 RDCP FLOAT = 0.285491 Do you wish to redefine any of CP, ALV or RDCP? Enter 1 FOR yes, or 0 for no. : 0 Type 1 for dew point sounding, or 2 FOR moisture sounding : 2 Enter 3 if sounding data uses DEG C, else 4 FOR DEG K : 4 Enter 5 if sounding data uses temperature, else 6 if data uses potential temperature : 6 Type 1 if wind data to be input, else 0 : 0 The TEPHI routine provided here is Roger Brugge’s tephigram plotting procedure. It is a command line driven routine with clear questions as to what input is expected.

53

Rotated Grids Rotated grids can be plotted using the RGAXES, RGROT and RGUNROT routines. RGAXES - Draw axes on rotated grids. RGROT - translate from normal to rotated grid space. RGUNROT - translate from rotated grid space to normal grid. RGROT and RGUNROT can be used for plotting of rotated grids but if you need to do some scientific calculations the using the eqtoll.f and lltoeq.f Fortran routines is recommended. When plotting rotated grids it is more normal to plot them in their native rotated state as in the example below.

PRO ex50 d=NCREAD('rgp.nc') PSOPEN GSET, XMIN=0, XMAX=N_ELEMENTS(d.x)-1, YMIN=0, YMAX=N_ELE MENTS(d.y)-1 RGAXES, XIN=d.x, YIN=d.y, XPOLE=160, YPOLE=30, /CONTINENTS PSCLOSE END GSET is used to set up a normal plotting region based on the sizes of the rotated grid longitude and latitude arrays. RGAXES is then used to overlay the gridlines and continents over this region.

54

PRO ex51 d=NCREAD('rgsa.nc', /ATT) xpole=d.rotated_pole.GRID_NORTH_POLE_LONGITUDE ypole=d.rotated_pole.GRID_NORTH_POLE_LATITUDE xin=d.grid_lon.data yin=d.grid_lat.data PSOPEN, XPLOTS=2, YSIZE=10000 GSET, XMIN=0, XMAX=N_ELEMENTS(xin)-1, YMIN=0, YMAX=N_ELE MENTS(yin)-1 RGAXES, XIN=xin, YIN=yin, XPOLE=xpole, YPOLE=ypole, /COUNTRIES, XLAB=3, YLAB=3 POS, XPOS=2 RGUNROT, XIN=xin, YIN=yin, XPOLE=300, YPOLE=55, XOUT=xout, YOUT=yout MAP, LATMAX=0.0, LONMIN=-120, LONMAX=0, /DRAW GPLOT, X=xout, Y=yout, /NOLINES, SYM=3, SIZE=5 AXES PSCLOSE END This example is of a rotated pole grid over South America. It was made using the BADC rotated grid utilities at http://badc.nerc.ac.uk/community/ancillary/badc_grid_utils/doc/index.html We need the /ATT parameter on NCREAD to get all the netCDF attributes, including the rotated pole coordinates, from the netCDF file. A second plot on the right hand side is of the grid point locations in normal coordinates which were obtained using the UNROT command.

55

PRO ex52 d=NCREAD('rgp.nc') PSOPEN CS, SCALE=1, NCOLS=24 GSET, XMIN=0, XMAX=N_ELEMENTS(d.x)-1, YMIN=0, YMAX=N_ELE MENTS(d.y)-1 LEVS, MIN=980, MAX=1035, STEP=2.5, NDECS=1 CON, X=FINDGEN(N_ELEMENTS(d.x))+0.5, Y=FINDGEN(N_ELEMEN TS(d.y))+0.5, $ FIELD=REVERSE(d.p, 2), /CB_ALT, CB_TITLE='Surface Pressure (mb)' RGAXES, XIN=d.x, YIN=d.y, XPOLE=160, YPOLE=30 PSCLOSE END

Here we plot a pressure field on a rotated grid as a normal contour field and then use RGAXES to place the grid annotation over the top. The continents weren’t drawn as the field contours show these quite effectively already.

56

PRO ex53 d=NCREAD('af4km.nc') PSOPEN CS, SCALE=1, NCOLS=22 GSET, XMIN=0, XMAX=N_ELEMENTS(d.x)-1, YMIN=0, YMAX=N_ELE MENTS(d.y)-1 LEVS, MIN=120, MAX=320, STEP=10 CON, FIELD=d.olr, X=INDGEN(N_ELEMENTS(d.x)), Y=INDGE N(N_ELEMENTS(d.y)),$ CB_TITLE='OLR (wm-2)', /IMG, /NOLINES RGAXES, XIN=d.x, YIN=d.y, XPOLE=180, YPOLE=79, /COUNTRIES PSCLOSE END In this example the data is on a high resolution 4000x2888 grid. The CON command for this grid takes 41 seconds on a fast Linux box and the output postscript file is 433MB in size which is rather unwieldy in terms of disk space and for printing. To effectively handle high resolution data use the /IMG option to the CON command. This takes around 23 seconds to run on the same Linux machine and the output postscript is 4MB in size. The /IMG option to CON makes a contour plot in the IDL Z-buffer and then places the image into the postscript file. The /IMG option to CON only works in the cylindrical projection or when the GSET command has been used to set the plotting coordinates. Spotty fields such as precipitation can be visualised in detail on the on the screen using the pan icon in the ImageMagick display command. i.e. display -density 600 -rotate -90 +antialias idl.ps

57

In example 48 we used RGUNROT to from rotated to normal longitude-latitude coordinates to make a plot of the data point positions. Here we use RGROT to do the reverse and place a blue dot over London in rotated coordinates.

PRO ex54 d=NCREAD('rgp.nc') PSOPEN GSET, XMIN=0, XMAX=N_ELEMENTS(d.x)-1, YMIN=0, YMAX=N_ELE MENTS(d.y)-1 RGAXES, XIN=d.x, YIN=d.y, XPOLE=160, YPOLE=30, /CONTINENTS RGROT, XIN=0.0, YIN=51.5, XPOLE=160, YPOLE=30, XOUT=xout, YOUT=yout lons=((d.x + 180) MOD 360)-180 xpt=MAX(WHERE(xout GE lons)) xval=xpt+(xout-lons(xpt))/(lons(xpt+1)-lons(xpt)) lats=REVERSE(d.y) ypt=MIN(WHERE(yout GE lats)) yval=ypt+(yout-lats(ypt))/(lats(ypt+1)-lats(ypt)) GPLOT, X=xval, Y=yval, SYM=1, COL=6 PSCLOSE END In this example the longitude and latitude for London is passed into the ROT routine: ROT, XIN=0.0, YIN=51.5, XPOLE=160, YPOLE=30, XOUT=xout, YOUT=yout The longitudes are then converted to the range -180 to 180: lons=((d.x + 180) MOD 360)-180 The location of the point in the lons array is then found with: xpt=MAX(WHERE(xout GE lons)) xval=xpt+(xout-lons(xpt))/(lons(xpt+1)-lons(xpt)) A similar process is used to work out the y location in the latitude grid.

58

WRF Grids In the wrf_test.nc data file the grids are regularly spaced in longitude and latitude. The grids have a surfeit of information though with the xlong array having 455x369 points. When plotting the data we just need CON, F=d.tmn(*,*), X=d.xlong(*,0), Y=REFORM(d.xlat(0,*)) as the data is regular in the X and Y directions.

PRO ex55 d=NCREAD('wrf_test.nc') PSOPEN MAP, LONMIN=-60, LONMAX=20, LATMIN=30, LATMAX=70, /DRAW FOR iy=0, 368, 5 DO BEGIN FOR ix=0, 454, 5 DO BEGIN GPLOT, X=d.xlong(ix,iy,0), Y=d.xlat(ix,iy,0), SYM=3, SIZE=10 ENDFOR ENDFOR AXES PSCLOSE END

Here we plot the locations of the X and Y points from a WRF run on a map. The data is regular in the X and Y directions.

59

PRO ex56 d=NCREAD('wrf_test.nc') PSOPEN MAP, LONMIN=-60, LONMAX=20, LATMIN=30, LATMAX=70 GSET, XMIN=-60, XMAX=20, YMIN=30, YMAX=70 LEVS, MIN=250, MAX=290, STEP=2 CS, SCALE=1, NCOLS=28 CON, F=d.tmn(*,*), X=d.xlong(*,0), Y=REFORM(d.xlat(0,*)) , $ TITLE='SOIL TEMPERATURE AT LOWER BOUNDARY ' AXES PSCLOSE END In example 56 the soil temperature at the lower boundary was plotted.

60

PRO ex57 d=NCREAD('wrf_test.nc') PSOPEN MAP, LONMIN=-60, LONMAX=20, LATMIN=30, LATMAX=70, /DRAW newv=REGRID(d.v(*,*, 0, 0), d.xlong_v(*,0,0), d.xlat_v(0,*,0), d.xlong_u(*,0,0), d.xlat_u(0,*,0)) VECT, U=d.u(*,*, 0, 0), V=newv, X=d.xlong_u(*,0,0), Y=REFORM(d.xlat_u(0,*,0)), STRIDE=10, MAG=10 AXES PSCLOSE END In this example the meridional wind was interpolated onto the zonal wind grid using REGRID . Every tenth wind vector was plotted as otherwise there are too many data points to make a meaningful vector plot.

61

PRO ex58 d=NCREAD('wrf_test.nc') PSOPEN, SPACE2=800 CS, SCALE=1, NCOLS=20 LEVS, MIN=-72, MAX=72, STEP=8 GSET, XMIN=35, XMAX=70, YMIN=1, YMAX=50 CON, F=REFORM(d.u(0, *, *)), X=REFORM(d.xlat_u(0,*,0)), Y=d.bottom_top AXES, XTITLE='Latitude', YTITLE='Height' PSCLOSE END In example 58 the zonal wind is plotted as a function of latitude and height.

62

Discussion of Guide routines The guide routines are very easy to use but sometimes when fine tuning a plot a deeper insight into what the routines do is needed. In this section some of the more technical aspects of making a plot are discussed.

Plot positioning and attributes The positioning of plots on the postscript page is done using the POSPEN and POS commands. PSOPEN is used to specify the paper size of the postscript file which by default is A4 in landscape mode. Using the options /LETTER or /A5 will give you a Letter or A5 sized postscript file for plotting on. Use /PORTRAIT to get a portrait orientation plot. The paper sizes in pixels are: A4 - landscape = 29,700 x 21,000 pixels

- portrait = 21,000 x 29,700 pixels Letter - landscape = 27,900 x 21,600 pixels

- portrait = 21,600 x 27,900 pixels A5 - landscape = 21,000 x 14,800 pixels - portrait = 14,800 x 21,000 pixels You can see from these dimensions that the postscript files have a density of 1000 pixels per centimetre. Options to PSOPEN to change the plot position are: XOFFSET=xoffset - offset in x direction, default=0 pixels. YOFFSET=yoffset - offset in y direction, default=0 pixels. XSIZE=xsize - x size in pixels. YSIZE=ysize - y size in pixels. MARGIN=margin - margin around paper edges, default=3000 pixels. In addition to the /LETTER , /A4 and /PORTRAIT options to PSOPEN you can also specify the exact size of your postscript file using the SIZE parameter. The units of SIZE are pixels so PSOPEN, SIZE=[20000, 15000] will give you a postscript plotting area of 20cm x 15cm. Plots are sized so as to fit on the page with a 3000 pixel (3cm) margin with the axes for the plots are then drawn around this plotting region. The plot below shows example 1 and the page plotting boundaries.

The plot can be moved around the page using the XOFFSET and YOFFSET keywords to PSOPEN. These are in pixels and the below plot was produced using PSOPEN, XOFFSET=4000 showing the left hand boundary of the plot moved 4 cm to the right. The other boundaries are left unchanged.

63

When a colour bar is selected the plot is resized vertically as shown below so that the margin of 3000 pixels is retained.

Resizing isn’t performed when the XSIZE and YSIZE options to PSOPEN are selected. If your axes don’t entirely fit on the page then the XOFFSET, YOFFSET XSIZE , YSIZE and MARGIN parameters can be used to adjust the plot position. Making multiple plots on a page To select multiple plots on a page use the following commands. XPLOTS=xplots - number of plots in the x direction. YPLOTS=yplots - number of plots in the y direction. The following are also commonly used to modify the spacing and margin surrounding the plots. MARGIN=margin - margin around paper edges, default=3000 pixels. SPACING=spacing - spacing between plots, default=3000 pixels. XSPACING=xspacing - x spacing between plots. YSPACING=yspacing - y spacing between plots. Use POS, XPOS=xpos, YPOS=ypos to select the plot position. The default plot position is POS, XPOS=1, YPOS=1 i.e. the bottom left hand corner plot. The following example should illustrate use of these options.

64

PRO gd1 d=NCREAD('climatology_t.nc') PSOPEN, XPLOTS=2, YPLOTS=2, YOFFSET=2000, SPACING=1800, SPACE3=400 CS, SCALE=1 LEVS, MIN=-32, MAX=32, STEP=4 POS, XPOS=1, YPOS=2 MAP CON, FIELD=d.djf, X=d.lon, Y=d.lat, TITLE='DJF', /NOC OLBAR POS, XPOS=2, YPOS=2 MAP CON, FIELD=d.mam, X=d.lon, Y=d.lat, TITLE='MAM', /NOC OLBAR POS, XPOS=1, YPOS=1 MAP CON, FIELD=d.jja, X=d.lon, Y=d.lat, TITLE='JJA', /NOCO LBAR POS, XPOS=2, YPOS=1 MAP CON, FIELD=d.son, X=d.lon, Y=d.lat, TITLE='SON', /NOC OLBAR COLBAR, COORDS=[6850, 3000, 22850, 3500], TITLE='Temperature (C)' PSCLOSE The POS command also takes the following options: XOFFSET=xoffset - offset in the x direction. YOFFSET=yoffset - offset in the y direction. XSIZE=xsize - x size in pixels. YSIZE=ysize - y size in pixels. /NP - new page - move onto the next page in the postscript file. These options can be used to individually position a third plot below two plots that were made using the XPOS=xpos and YPOS=ypos keywords..

65

PRO gd2 d=NCREAD('gdata.nc') PSOPEN, XPLOTS=2, YPLOTS=2, MARGIN=2000 CS, SCALE=1 POS, YPOS=2 LEVS, MIN=-32, MAX=32, STEP=4 MAP CON, FIELD=d.temp(*,*,0), X=d.lon, Y=d.lat, TITLE='Jan 1987' , $ CB_TITLE='Temperature (Celsius)', /NOLINES POS, XPOS=2, YPOS=2 LEVS, MIN=-16, MAX=16, STEP=2 MAP CON, FIELD=d.u(*,*,0), X=d.lon, Y=d.lat, TITLE='Jan 1987', $ CB_TITLE='Zonal Wind (m/s)', /NOLINES POS, XOFFSET=8600, YOFFSET=2000, XSIZE=11800, YSIZE=6900 LEVS, MIN=-8, MAX=8, STEP=1 MAP CON, FIELD=d.v(*,*,0), X=d.lon, Y=d.lat, TITLE='Jan 1987', $ CB_TITLE='Meridional Wind (m/s)', /NOLINES PSCLOSE END

66

Changing plot attributes Plot attributes are generally changed via the PSOPEN command options: SPACE1=200 ;Space between text (pixels). SPACE2=400 ;Space between colour bar and plot (pixels). SPACE3=800 ;Space between the title and the plot (pixels). TICKLEN=200 ;Tick length (positive is away from plot) (pixels). THICK=100 ;Thickness of lines (%). CTHICK=100 ;Thickness of continents (%). CSTYLE=0 ;Line style of continents. CCOLOUR=1 ;Colour of the continents. CB_WIDTH=100 ;Width of colour bar (%). CB_HEIGHT=100 ;Height of colour bar (%). BORDER_THICK=100 ;Thickness of the line around the plot (%). FONT=1 ;Font to use for text except titles (values=1-7). CHARSIZE=100 ;Size of text except for titles (%). /BOLD ;Use bold text. /ITALIC ;Use italic text. CFONT=1 ;Font to use for contours (values=1-7) CCHARSIZE=100 ;Size of text for contours (%) /CBOLD ;Use bold contours /CITALIC ;Use italic contours TFONT=1 ;Font to use for titles (values=1-7). TCHARSIZE=100 ;Size of text for titles (%). /TBOLD ;Use bold titles. /TITALIC ;Use italic titles. AXISTYPE=0 ;Type of axis The following is a listing of the fonts that can be used with this guide. FONT FONT NAME NO OPTIONS /BOLD /ITALIC /BOLD, /ITALIC

Note that there are no bold typefaces available for FONT=5 or FONT=7. The /ITALIC keyword gives italic fonts for FONT=2, 3, 6 and 7 and oblique typefaces for FONT=1, 4 or 5. The axis types are as follows: 0=90W, 0, 90E. 1=-90, 0, 90. 2 = as 0 with degree symbol. 3 = as 1 with degree symbol.

67

The hierarchy of setting the plot attributes is: 1) The system file $IDL_GUIDE/lib/idl_guide5.def 2) The users definition file $HOME/.idl_guide5.def (if it exists) 3) A definition file attached to the PSOPEN command: PSOPEN, DEF=’graph.def’ 4) Individual definitions to the PSOPEN command: PSOPEN, SPACE2=400

If you choose to have your own definition files as in options 2 or 3 then copy the system file: glib cp idl_guide5.def ~/.idl_guide5.def and then use this as your starting point.

PRO gd3 PSOPEN, AXISTYPE=2, FONT=7, CHARSIZE=130, TFONT=7, TCHARSIZE=180, $ CFONT=7, CCHARSIZE=120 CS, SCALE=1 MAP LEVS, MIN=-64, MAX=64, STEP=8 CON, F=SF('gdata.nc', 'u', p=1), TITLE='Zonal Wind at 1mb' PSCLOSE END In example gd3 the following options to PSOPEN were changed: AXISTYPE=2 - add the degree symbol to the axis labels. FONT=7, TFONT=7, CFONT=7 - set the general, contour label and title text to be bookman. CHARSIZE=130 - Set the general text size to be 1.3 times bigger. TCHARSIZE=180 - Set the title text size to be 1.8 times bigger. CCHARSIZE=120 - Set the contour text size to be 1.2 times bigger.

68

Using Colours Colour tables are selected using the CS command. The following are the default set of colour scales to select from using the notation CS, SCALE=scale

69

A diverging colour scheme such as SCALE=1, 15 or 16 is used to colour a dataset that has a critical midpoint such as a zero value. Examples of these are temperature, zonal wind or an anomaly. A sequential colour scheme such as SCALE=3, 24 or 30 is used to colour a dataset that has no significant midpoint. Examples of these are height, albedo or a percentage of mean. Other keywords to CS are: COLS=[cols] - select colours by number. MIN=min - start colour (0-255). MAX=max - end colour (0-255). NCOLS=ncols - number of colours. /REV - reverse the colour scale. REV=rev - reverse the colours from colour 2 to this colour. WHITE=white - make this/these colour(s) white. This is applied after REVERSE if it is specified. /DRAW - draw this colour scale on the screen. This is a useful check of your colour scale before using it. FILE=file - read the colours from this file. OUTFILE=outfile - write colours to this file. SAVE=save - save the colours in this temporary scale. Values are 1 to 5. /MERGE - merge the saved colour scales in sequential order. /CLEAR - clear the temporary colour scales. If your levels don’t fit into one of the previous number of levels then you can interpolate the scales to a new number of colours. The default SCALE=4 has twelve colours. CS, SCALE=4

This can be changed by the addition of the NCOLS parameter. CS, SCALE=4, NCOLS=8

The colour scales can be viewed interactively using the /DRAW option to CS. CS, SCALE=4, NCOLS=254, /DRAW

70

The first two colours in the colour map are reserved colours for the background and default line and text colours respectively. Colours that the user has control over range from 2 to 255. Generally plots with less than twenty colours are best as the eye has difficulty differentiating the different colours on a contour plot. If we used all 256 colours from the above colour scale then the variation between the second and fifteenth colours, for instance, are too subtle to notice. When a colour scale is interpolated to a new number of colours it is first expanded by interpolation to 254 colours. If only the NCOLS parameter is set then the scale is then stepped though at equal intervals to get a new colour scale. If the MIN=min and MAX=max parameters are included then these are used in the 254 colours as the starting and finishing point for the stepping. Colour scales can be reversed by using the REV keyword.

CS, SCALE=16, /DRAW

CS, SCALE=16, /REV, /DRAW With some anomaly plots white is sometimes needed in the middle so that you don’t colour those regions. This can be done with the WHITE keyword.

CS, SCALE=16, WHITE=6, /DRAW Another way to make a colour scale is to specify numbered colours in the desired sequence as in example 9. CS, COLS=[93, 123, 91, 267, 272, 367, 409, 419, 407]

The numbered colours are shown in the table below.

71

Colour RGB values are from http://cloford.com/resources/colours/500col.htm

72

The colours used in the guide are based on red, green, blue triplets, more commonly called an RGB scale. In this colour scheme the intensities of the red, green and blue components of colour are on a scale of zero to 255. To represent white in this colour scheme the red, green and blue components are set to their maximum intensity of 255. To represent black in this colour scheme the components are all set to be zero. The first six lines of SCALE=6 show how this works in practice. 255 255 255 0 0 0 0 0 255 255 255 255 255 0 0 255 255 255 These correspond to the colours below when displayed on the screen using CS, SCALE=6, /DRAW

Here the first six colours only are shown and the rest are all white. You may occasionally need to manually edit a colour scale to add new colours or if you wish to import a colour scale from another graphics package.

CS, COLS= [224, 232, 331, 419], /DRAW

CS, COLS=[224, 232, 331, 419], NCOLS=12, /DRAW You can save and merge up to five colour scales. Here we merge two colour scales as is done in example 22. CS, SCALE=24, NCOLS=12, /REV, SAVE=1 CS, SCALE=29, NCOLS=23, SAVE=2 CS, /MERGE

73

Around 10% of men have some form of colour deficiency. The most common form of this is Deuteranope, a red-green colour deficit. See http://www.vischeck.com for more information and an upload page to see how your colour plot will probably look to around 10% of men. Here are two colour schemes that have been run though the Vischeck colour vision simulator at http://www.vischeck.com. The top left is a spectral colour scheme which gives a confusing simulation. Both the high and low temperatures have blue colours and so are hard to distinguish. The lower plots of a blue-red colour scheme fares much better and the high and low values are easy to tell apart.

Spectral (top, CS, SCALE=1) and How these schemes look to someone with blue-red (bottom, CS, SCALE=2) colour schemes. red/green color deficit (deuteranopia).

74

AXES Axes on longitude-latitude plots are drawn automatically from the contouring procedure CON. The CON procedure looks at the limits of the plotting region and selects an appropriate spacing for the longitude and latitude labels. If these don’t look good for your plot then turn off the automatic axis drawing in CON with the /NOAXES keyword and then afterward add the axes on by hand with AXES, XSTEP=xstep, YSTEP=ystep. Axes on all other type of plots must be added by using the AXES command. Use NDECS=ndecs to specify the number of decimal places for the X and Y axes. If you need different number of decimal places for the X and Y axes then use NDECS=[nxdecs, nydecs] to set the x and y axes decimal paces separately. In the example plot below we set the X-axis to go from 0 to 1.0 and the Y-axis to go from 0.05 to 0.15. On the left hand side we use AXIS with no options and produce a poorly labelled plot. On the right hand side we use AXES, XSTEP=0.1, YSTEP=0.01, NDECS=[1, 2] and produce a much better set of labels.

When making some plots a non-uniform or non-numeric axis is needed as is shown in the below examples. Here use of the XVALS=xvals, XLABELS=xlabels, YVALS=yvals, YLABELS=ylabels

75

Top picture GSET, XMIN=0, XMAX=11, YMIN=0, YMAX=10 months=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul' , 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] AXES, XVALS=INDGEN(12), XLABELS=months, YSTEP=1 Bottom picture GSET, XMIN=0, XMAX=11, YMIN=0, YMAX=10 months=['January', 'February', 'March', 'April', 'May', ' June', 'July', 'August', 'September',$ 'October', 'November', 'December'] AXES, XVALS=INDGEN(12), XLABELS=months, YSTEP=1, ORIENTATION=45 When mixing integers and floats use quotes to make the values a string variable. yvals=[1000, 464, 100, 46.4, 10, 4,64, 1] IDL> PRINT, yvals 1000.00 464.000 100.000 46.4000 10.0000 4.00000 64.0000 1.00000 yvals=['1000', '464', '100', '46.4', '10', '4,64', '1'] IDL> PRINT, yvals 1000 464 100 46.4 10 4,64 1

76

PRO gd4 PSOPEN, XPLOTS=2, /BOLD, CHARSIZE=130 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=1, /YLOG yminor=[INDGEN(9)+1, INDGEN(10)*10+10, INDGEN(10)*100+100] AXES, XSTEP=30, XTITLE='Latitude', YVALS=[1000, 100, 10, 1], $ YMINOR=yminor, YTITLE='Pressure (mb)' POS, xpos=2 ymticks=[2,3,4,5,6,7,8,9,20,30,40,50,60,70,80,90,200,300,400,500,600,700,800,900] xmticks=[-80,-70,-50,-40,-20,-10,10,20,40,50,70,80] GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=1, /YLOG AXES, XSTEP=30, XMINOR=xmticks, YVALS=[1, 10, 100, 1000], YMINOR=ymticks, $ YMLABELS=ymticks, XMLABELS=xmticks, XTIT LE='Latitude', YTITLE='Pressure (mb)' PSCLOSE END In this example we use XMLABELS and YMLABELS to label the minor X and Y label points.

77

PRO gd5 PSOPEN, XSIZE=25000, YSIZE=17000 CS, COLS=[199] GSET, XMIN=0, XMAX=25, YMIN=0, YMAX=17 AXES, XSTEP=0.2, YSTEP=0.2, GCOL=2, /GRID, GTHICK=40, /NOTICKS, /NOLABELS AXES, XSTEP=1, YSTEP=1, GCOL=2, /GRID, GTHICK=140, COL=2 PSCLOSE END In this example a graph paper plot was made using two calls to the AXES command.

78

PRO gd6 PSOPEN GSET, XMIN=1959, XMAX=2005, YMIN=0, YMAX=240 AXES, XSTEP=1, ORIENTATION=90, YSTEP=30, /NORIGHT, YTIT LE='Snow Depth (cm)' GSET, XMIN=1959, XMAX=2005, YMIN=-0.8, YMAX=0.8 AXES, /ONLYRIGHT, STEP=0.2, NDECS=1, YTITLE='NAO' PSCLOSE END When making plots with more than two axes use the /NOLOWER , /NOUPPER , /NOLEFT, /NORIGHT keywords to turn off various axes. The /ONLYLOWER , /ONLYUPPER , /ONLYLEFT , /ONLYRIGHT keywords can be used to draw individual axes as below. Also see example 42 where the OFFSET option to AXES is used to make a supplementary offset axis.

79

Selecting data for contour and vector plots If we wanted to make a contour plot of the zonal wind at 299mb from the file ukmo_test.nc then we could select the data in two ways: f=SF('ukmo_test.nc', 'u', HYBRID_P_X1000=299.752) This produces a structure with the required data for making a contour plot. The data we have selected is two dimensional and so can be passed to the CON procedure with CON, FIELD=f or CON, F=f in shortened notation. If the returned array isn’t two dimensional SF will produce a list of the dimensions available and exit. This method doesn’t work for irregular grids – use method 2 as below. The second way is to read the data directly with NCREAD and then select the data required. This was the method used in the guide4 release. d=NCREAD('ukmo_test.nc', VARS='u') HELP, d, /STR ** Structure <8155dcc>, 5 tags, length=526064, data length=526064, refs=1: U FLOAT Array[96, 72, 19] LONGITUDE_1 FLOAT Array[96] LATITUDE_1 FLOAT Array[72] HYBRID_P_X1000 FLOAT Array[19] T FLOAT 0.00000 This shows that we have a three dimensional array containing the longitude, latitude and pressure coordinates. To see the pressure coordinates we use: PRINT, d.hybrid_p_x1000 996.999 974.956 930.417 869.832 792.228 699.574 599.503 504.522 422.103 354.698 299.752 249.702 199.627 149.501 99.2468 56.8542 29.5943 14.7972 4.60588 The 299mb level is the 11th element into this vector. IDL starts numbering the elements of a dimension at 0 rather than 1 so this is element 10 in IDL notation. We can check this is correct with PRINT, d.hybrid_p_x1000(10) 299.752 We can select the zonal wind data with field=d.u(*,*,10) The CON command would then be CON, FIELD= field=d.u(*,*,10), X=d.longitude_1, Y=d.latitude_1

80

Selecting Levels for contour plots Selecting levels for contour plots using the LEVS command is normally a straight forward process. LEVS accepts the following keywords: MIN=min - the minimum level. MAX=max - the maximum level. STEP=step - the step for the levels. /EXACT - keep levels to those specified. /LOWER - extend lower level limit. /UPPER - extend upper level limit. /NDECS - the number of decimal places. MANUAL=manual - supply your own levels. /NOZERO - remove the zero contour. /V - print the levels generated. A few examples will help show some of the features of LEVS that might not be immediately apparent. LEVS, MIN=0, MAX=9, STEP=1, /V Levels are: -2147483648 0 1 2 3 4 5 6 7 8 9 2147483647 This gives the colour bar the 0 to 9 range as expected but with a minimum of -2147483648 and a maximum of 2147483647. These large numbers relate to the lower and upper limit extensions on the colour bar and are the minimum and maximum allowed 32 bit integers. In this case all data between -2147483648 and 0 is shaded red and all data from 9 to 2147483647 is shaded blue. The corresponding colour bar would look as below.

This default behaviour can be modified using the /LOWER , /UPPER and /EXACT keywords: LEVS, MIN=0, MAX=9, STEP=1, /LOWER, /V Levels are: -2147483648 0 1 2 3 4 5 6 7 8 9

LEVS, MIN=0, MAX=9, STEP=1, /UPPER, /V Levels are: 0 1 2 3 4 5 6 7 8 9 2147483647

LEVS, MIN=0, MAX=9, STEP=1, /EXACT, /V Levels are: 0 1 2 3 4 5 6 7 8 9

When using floating point numbers the minimum/maximum values for the limit extensions are set to -1E38/1E38. When using floating point numbers the NDECS keyword is very useful for removing extra decimal places that will otherwise occur in your colour bar and contour line labels:

81

LEVS, MIN=-7.5, MAX=7.5, STEP=2.5, /EXACT, /V Levels are: -7.50000 -5.00000 -2.50000 0.00000 2.50000 5.00000 7.50000 LEVS, MIN=-7.5, MAX=7.5, STEP=2.5, /EXACT, NDECS=1, /V Levels are: -7.5 -5.0 -2.5 0.0 2.5 5.0 7.5 You can also specify your levels manually using the MANUAL=manual option to LEVS. Here we specify a non-linear set of levels for use in an anomaly plot. Quotes were used to protect the numbers or as some are floating point numbers and some are integers IDL would translate all the numbers into floating point numbers.

CS, SCALE=26, NCOLS=33 LEVS, MANUAL=['0','0.1', '0.2', '0.3',' 0.4', '0.5', '0.6' , '0.7', '0.8', '0.9', $ '1', '2' ,'3', '4', '5','6', '7', '8', '9',$ '10', '20', '30', '40', '50', '60', '70', '80', '90', '100', '200', '300'] When making plots with a lot of contours the LABELS option to COLBAR aids the readability of the colour bar.

CS, SCALE=26, NCOLS=50 LEVS, MANUAL=[INDGEN(9)+1, INDGEN(9)*10+10, INDGEN(9)*100+100, $ INDGEN(9)*1000+1000, LINDGEN(10)*10000+10000] COLBAR, COORDS=[1000, 7000, 26000, 7700], /NOLINES, $ LABELS=['1', '10', '100', '1000', '10000', '100000']

82

Making Contour plots Contours are plotted with the CON command. The basic use of CON is CON, FIELD=field, X=x, Y=y where the FIELD is a two dimensional array with its values in the positions defined by the values in X and Y. In the case of regular grids X and Y are vectors whereas in the case of irregular grids they are two dimensional arrays of the same size as FIELD . If a map projection plot is needed then use the MAP command before calling CON. If a normal contour plot is required then set the plotting coordinates with the GSET command. Commonly used options to CON are: /AUTOLEVS - use the field min/max to make the levels. /NOCOLBAR - don't put a colour bar on the plot. /NOFILL - don't fill with colour. /NOLINES - don't put labelled lines on the plot. /BLOCK - make a blockfill plot. TRI=tri - the triangulation to use with irregular grids. /NOLINELABELS - don't put labels on the lines. /QP – make a quick plot. CON, FIELD=SF('gdata.nc', 'temp', p=1000), /QP and CON, FIELD=SF('gdata.nc', 'temp', mean='lon'), /QP Are examples of making quick plots. THICK=thick - thicknesses for the lines, default=100 (%). Titling and annotation options to CON are: /NOAXES - don't put axes on the plot if a MAP plot. TITLE=title - use this as the title above the plot. LEFT -TITLE = left _title - use this title on the left above the plot. RIGHT_TITLE = right _title - use this title on the right above the plot. /NOMAP - don't draw a map after drawing contours. Line style options to CON are: NEGATIVE_STYLE=negative_style - style for negative lines. As for STYLE below. POSITIVE_STYLE=positive_style - style for positive lines. As for STYLE below. ZERO_STYLE=zero_style - style for zero line. As for STYLE below. NEGATIVE_THICK=negative_thick - thickness for negative lines, default=100 (%). POSITIVE_THICK=positive_thick - thickness for positive lines, default=100 (%). ZERO_THICK=zero_thick - thickness for zero lines, default=100 (%). NEGATIVE_COL=negative_col - colour for the negative lines. POSITIVE_COL=positive_col - colour for the positive lines. ZERO_COL=zero_col - colour for the zero line. Line drawing options to CON (all taking multiple values) are: STYLE=style - Changes the linestyle: 0=solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. Colour bar options to CON are: CB_TITLE=cb_title - title for colour bar. /CB_LEFT - place colour bar to the left of the plot. /CB_RIGHT - place colour bar to the right of the plot. /CB_UNDER - place colour bar under the plot. /CB_ALT - alternate text position (bottom to top) for horizontal colour bar. CB_WIDTH=cb_width - scaling factor for width of colour bar, default=100 (%).

83

CB_HEIGHT=cb_height - scaling factor for height of colour bar, default=100 (%). CB_NTH=cb_nth - label every cb_nth level on the colour bar rather than all the levels. Used when the contour plot has a lot of colours in to show structure within a field. /CB_NOLINES – draw an internal colour bar level division only at the label points rather than every level. There are many contour plot illustrations in the examples section at the front of the guide. Most of these options are self explanatory but one or two will need a little explanation for you to use them properly. TRI=tri – see the section below on contouring irregular grids for a discussion of this keyword. NEGATIVE_XXX , POSITIVE_XXX and ZERO_XXX all take just one value. This value applies to all the lines in that class. See example 5 for an example. STYLE, COL and THICK all take a series of values, one for each line defined by the LEVS command. See example 11 for an example. If a map is set then MAP and AXES are applied after a call to CON. There will be occasions where this isn’t required and the /NOMAP and /NOAXES keywords suppress this default behaviour. The default call to CON produces a colour filled plots with labelled lines drawn over and a colour bar in a default position. /NOFILL produces a simple unfilled contour plot with no colour bar. /NOCOLBAR suppresses the drawing of a colour bar on the plot even if colour filled contours are present. Contouring irregular grids Example 12 shows contouring an irregular grid. If you are plotting complicated grids all the time then make use of the CON option TRI=tri to pick up a pre-computed triangulation as below. On a 2.6GHz Linux PC the triangulation calculation of an Orca2 grid takes 0.96 seconds whereas an Orca05 grid takes 18 seconds. Depending on the complexity of your grid you can save a considerable amount of time by using a pre-computed triangulation. If your grid longitudes and latitudes are in the arrays lons, lats then calculate the triangulation with: QHULL, lons, lats, tri, SPHERE=s Save this to a file. OPENW, lun, ‘triangulation.dat’, /GET_LUN WRITEU, lun, tri FREE_LUN, lun Make a note of your array size by typing HELP, tri . Lets say this is 3*53064 for this example. When making your complicated grid plots read the data back in again: tri=FLTARR(3, 53064) OPENR, lun, ‘triangulation.dat’, /GET_LUN READU, lun, tri FREE_LUN, lun Then pass this triangulation to the CON command with the TRI=tri keyword. When making plots of high resolution data the /IMG option to CON is recommended. This makes an image contour plot in memory and places this in the contour plotting region. When plotting high resolution data this can make a significant reduction in the size of the output postscript file. This option only works for the cylindrical map projection and for plots made when using GSET. The default image resolution is 100 dots per centimetre. To change this use IMG=img. So for example IMG=400 would give 400 dots per centimetre.

84

Vectors Vectors are plotted using the VECT routine. The routine needs a minimum of four parameters to make a vector plot: U=u - X location of the vector(s) to be plotted. V=v - Y location of the vector(s) to be plotted. X=x - X component of the vector(s) to be plotted. Y=y - X component of the vector(s) to be plotted.

VECT, F=SF('ukmo_test.nc', ['u', 'v'], HYBRID_P_X1000=996.999), MAG=10, /QP When working with higher resolution grids some method of data thinning is needed or it isn’t possible to see the individual vectors. STRIDE=stride - pick every nth in the x and y directions for plotting. This is a good method when you need to see the vectors on the original grid. PTS=pts - the number of equally spaced points to interpolate to across the diameter of a cylindrical or polar polar plot. When plotting in the cylindrical mode this can take two elements, one for the x-direction and one for the y-direction. The length of the default vector can be changed with LENGTH=length - length of the vector, default=100 (%), 300 pixels (0.3cm). to give you the a plot where the vector directions are clearly visible. When selecting a decimal magnitude use MAG='10.5' rather than MAG=10.5 so that the magnitude label is properly formed as below.

85

MAG='10.5' and MAG=10.5

PRO gd7 d=NCREAD('ukmo_test.nc', VARS=['u', 'v']) PSOPEN, YPLOTS=2 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0 VECT, X=d.latitude_1, Y=d.hybrid_p_x1000, U=REFORM(d.u(0, *,*)), $ V=REFORM(d.v(0,*,*)), MAG=30 AXES, XSTEP=30, YSTEP=-200 POS, YPOS=2 GSET, XMIN=-90, XMAX=90, YMIN=1000, YMAX=0 VECT, X=d.latitude_1, Y=d.hybrid_p_x1000, U=REFORM(d.u(0, *,*)), $ V=REFORM(d.v(0,*,*)), SIZE=100, /NOLEGEND AXES, XSTEP=30, YSTEP=-200 PSCLOSE END When the length of the vector is small it is sometimes difficult to see which direction it is pointing in. Using the SIZE=size option to VECT draws a uniformly sized vector head for each vector.

86

PRO gd8 PSOPEN d=NCREAD('ukmo_test.nc', VARS=['u', 'v', 'temp']) tnew=REGRID(d.temp, d.longitude, d.latitude, d.longitude_1, d.latitude_1) col=FLTARR(96, 72)+2 icol=2 FOR i=-32, 32,4 DO BEGIN pts=WHERE(tnew-273.15 GT i, count) IF (count GT 1 ) THEN col(pts)=icol icol=icol+1 ENDFOR MAP VECT, X=d.longitude_1, Y=d.latitude_1, U=d.u(*,*, 0), V=d.v(*,*,0), MAG=10, COL=col AXES LEVS, MIN=-32, MAX=32, STEP=4 COLBAR, COORDS=[3000, 1000, 26700, 1500] PSCLOSE END

87

On cylindrical projection plots the default is to draw a vector of u=v=10 such that it’s angle is 45o to the horizontal. Using the cylindrical projection with the /MAP option will rotate the vector as the latitude approaches the poles such that it will point to the North West in projection space.

Without /MAP With /MAP PRO gd9 PSOPEN, XPLOTS=2, YPLOTS=2 u=FLTARR(31, 21)+10 v=FLTARR(31, 21)+10 x=FINDGEN(31)*12-180 y=FINDGEN(21)*9-90 MAP VECT, X=x, Y=y, U=u, V=v, MAG=10, MUNITS='ms!E-1!N' AXES POS, XPOS=2 MAP VECT, X=x, Y=y, U=u, V=v, MAG=10, MUNITS='ms!E-1!N', /M AP AXES PSCLOSE END In the plot below the /AXES keyword to VECT changes the orientation of a u=v=1 vector from the default angle of 45o to the horizontal to take into account the axis scales.

Example 33 shows the use of different vector magnitudes in the X and Y directions on an E-P flux vector plot.

88

Data Interpolation It is usually best to plot data on the input grid if possible but there are instances of where this isn’t desirable or possible. If you wish to plot vectors and the u and v components are on different grids then this will need the components on a common grid which can only be achieved by interpolation. The interpolation routine, REGRID , provided in this guide is a bi-linear interpolation routine. See http://en.wikipedia.org/wiki/Bilinear_interpolation for details on bilinear interpolation. In the following example we will use REGRID to find what the temperature is in Sydney (151o0’E 34o0’ S).

PRO gd10 PSOPEN d=NCREAD('gdata.nc') sydneyt=REGRID(d.temp(*,*,0), d.lon, d.lat, 151.0, -34.0) title='Sydney temperature is '+SCROP(sydneyt) CS, SCALE=1, NCOLS=22 MAP, LONMIN=110, LONMAX=160, LATMIN=-40, LATMAX=-10 LEVS, MIN=12, MAX=32, STEP=1 CON, F=d.temp(*,*,0), X=d.lon, Y=d.lat, TITLE=title GPLOT, X=151.0, Y=-34.0, SYM=3, COL=16 GPLOT, X=152.0, Y=-34.0, TEXT='Sydney', ALIGN=0.0, VALIGN=0.5 PSCLOSE END It is always advisable to do a visual check of the regridded data to see that the values look consistent. In this example we see that Sydney is between the 19 and 20 Celsius contour lines and the temperature from the REGRID procedure gives 19.62 Celsius.

89

In the next example we will regrid the temperature data from a 2.5 degree grid to a 1.0 degree grid. A contour plot shows that the data is consistent between the two grids.

PRO gd11 PSOPEN, XPLOTS=2, YPLOTS=2 d=NCREAD('gdata.nc') lons_new=INDGEN(361)-180 lats_new=INDGEN(181)-90 temp_new=REGRID(d.temp(*,*,0), d.lon, d.lat, lons_new, lats_new) CS, SCALE=1, NCOLS=22 LEVS, MIN=12, MAX=32, STEP=1 MAP, LONMIN=110, LONMAX=160, LATMIN=-40, LATMAX=-10 CON, F=d.temp(*,*,0), X=d.lon, Y=d.lat, TITLE='Grid spa cing=2.5 degree' POS, XPOS=2 MAP, LONMIN=110, LONMAX=160, LATMIN=-40, LATMAX=-10 CON, F=temp_new, X=lons_new, Y=lats_new, TITLE='Grid spacing=1.0 degree' PSCLOSE END

Pressure level interpolation If the 900mb temperature from gdata.nc was required a look at the pressure levels gives: 1000.00 700.000 500.000 320.000 215.000 150.000 100.000 70.0000 50.0000 32.0000 20.0000 15.0000 10.0000 7.00000 5.00000 3.20000 2.00000 1.50000 1.00000 0.700000 0.500000 0.300000 The location of 900mb is one third of the way between the first and second pressure points. The temperature field at 900mb would be a linear combination of the temperatures at the first and second levels of 1000mb and 700mb. t900=d.temp(*,*,0)*2/3+d.temp(*,*,1)*1/3 There is plenty of scope for getting the interpolation wrong when doing this manually but it does have the advantage that you fully understand what has happened with the data. Climate Data Operators (CDO) has a series of routines for interpolation, extrapolation and quantity conserving interpolation. In CDO this interpolation can be done with cdo intlevel,900 gdata.nc nest.nc CDO is available locally using the setup cdo command when on a 64 bit Linux server. For external users CDO is available from https://code.zmaw.de/projects/cdo

90

Graphs and other plots Graphs are made using GSET to set the plotting region in data coordinates, AXES to draw the axes and GPLOT to plot lines and symbols. There are plenty of examples at the front of the guide to show you the commonly made plots needed when viewing data. Using the GPLOT command it is very easy to draw lines, symbols and text on graphs and the two examples below illustrate this well. The first is from Charles Boschetto and shows normal years, drought and flood monsoon year, as well as El Niño and La Niña events (circles on top).

The second plot was made by Nick Klingaman and shows combining a colour bar with a fractional frequency plot.

91

Quick Plots It is often useful to make quick plots for looking at data quickly. The contouring and vector plotting routines CON and VECT take the /QP option to allow this.

CON, F=SF('ukmo_test.nc', 'soiltemp', level6_1=0.930417), /QP If data has lon and lat in as the first three characters of the coordinate names then the CON routine does a cylindrical projection plot. If not it will do a normal contour plot with no map.

92

CON, F=SF('gdata.nc', 'temp', MEAN='lon'), /QP

VECT, F=SF('gdata.nc', ['u','v'], p=10), MAG=20, PTS=40, /QP

93

Appendix A - Setting up access to the guide library and examples

A-1 - Unix Download Sample Datasets and code for IDL in Meteorology Guide from http://ncas-climate.nerc.ac.uk/ajh/idl_guide5.tgz In the download directory type: gzip –dc idl_guide5.tgz | tar xvf - Move the idl_guide5 directory to its final place. This can be in /usr/local or /opt/local for a system wide installation or your home directory for a personal installation. Bash or Korn shell: Edit the idl_guide5/guide5.sh file and change the path as indicated. In your .bashrc or .kshrc file source the setup file. i.e. or my personal installation in /home/andy I'd add the line . /home/andy/idl_guide5/guide5.sh to my .kshrc file. For a system wide installation in /usr/local installation I'd add the line . /usr/local/idl_guide5/guide5.sh to my .kshrc file. For the C-shell edit the idl_guide5/guide5.csh file as indicated in the file. In your .cshrc file use source /usr/local/idl_guide5/guide5.csh Then open a new command window and you should be able to use the examples as shown in the guide. Problems 1) If you cannot see STRSPLIT as below gvars=STRSPLIT(data.guide_vars(0), /EXTRACT) ^ % Syntax error. Then your IDL_PATH isn’t correct. Your IDL_PATH should include the guide and IDL libraries. On our system the IDL_PATH is set to be +/opt/graphics/idl/idl_guide5:/opt/graphics/idl_7.1.1/idl/lib 2) If you see grey squares in the background on the displayed plots as below then the ImageMagick delegates.xml file needs to be modified.

To give you an idea where this might be on OpenSuSe 11.1 64 bit server this is in /usr/lib64/ImageMagick-6.3.5/config/delegates.xml. Edit this file and go to the line with <delegate decode="ps:color" at the start. Replace -sDEVICE=pngalpha with -sDEVICE=pnmraw on this line and the grey squares should be replaced by a white background the next time you make a plot

94

A-2 – Macs Download and install ghostscript from http://pages.cs.wisc.edu/~ghost. Download and install ImageMagick from http://www.imagemagick.org/script/binary-releases.php. Download and install the Unix version of IDL. Select the default location of /usr/local/itt. Finally download the guide routines from http://ncas-climate.nerc.ac.uk/ajh/idl_guide5.tgz. Install these in either a system directory or in your home directory. Edit the guide5.sh file as in the Linux notes and change the install directory as indicated. You may need to add export IDL_PATH=+/usr/local/itt to your .bashrc file before sourcing the guide5.sh file.

A-3 - Windows Install gsview from http://pages.cs.wisc.edu/~ghost/gsview so that you can view the output postscript files. Then download the guide routines from http://ncas-climate.nerc.ac.uk/ajh/idl_guide5.zip Unzip the routines and move them to their final place which is C:\idl_guide5. To import all the idl_guide5 files: File -> Import -> General -> File system and Next Browse to the C: directory and select idl_guide5. Click to highlight the tick next to idl_guide5 Into folder -> browse to idl_guide5 Click on Create complete folder structure and then Finish. In the guide notes example programs reference is made to a routine called CON. In Windows CON is a reserved command and so the Windows guide routines have been changed to use the routine name GCON instead. Note: 1) If your change the default location of the library from C:\idl_guide5 then you need to edit the idl_guide5\lib\psopen.pro and modify the definition of windows_lib as appropriate. 2) If your change the default postscript viewer then you need to change the definition of the windows_viewer variable as appropriate in C:\idl_guide5\lib\psopen.pro. To run example 1 from the examples section browse to idl_guide5 -> examples. Double click on ex1 and then click on the compile and run buttons at the top of the IDL window.

95

Appendix B - Routines in the Guide Library AXES AXES is a procedure for drawing axes on plots. Allowed options are: XSTEP=xstep - use this x step. YSTEP=ystep - use this y step. XVALS=xvals - draw major tickmarks at these x locations. XLABELS=xlabels - labels the above with these x labels. YVALS=yvals - draw major tickmarks at these y locations. YLABELS=ylabels - labels the above with these y labels. STEP=step - use this step in the x and y directions. MINOR=minor - use this step or these points for the minor tickmarks. XMINOR=xminor , YMINOR=yminor - use xminor and yminor steps or points for minor tick marks. XTITLE=xtitle - label for x-axis. YTITLE=ytitle - label for y-axis. NDECS=ndecs - trim axis labels to ndecs decimal places. /GRID, /HGRID, /VGRID - draw a grid, horizontal only grid or vertical only grid. GSTYLE=gstyle - draw a grid, 0=solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. GTHICK=gthick - grid thickness, default=100 (%). GCOL=gcol - grid colour. Additional less used options: /NOUPPER, /NOLOWER, /NOLEFT, /NORIGHT - omit drawing these axes. /ONLYUPPER, /ONLYLOWER, /ONLYLEFT, /ONLYRIGHT - only draw these axes. ORIENTATION=orientation - orientation in degrees of the lower x-axis labels. OFFSET=offset - offset axes by this number of pixels. A positive offset draws the axis away from the centre of the plot. COL=col - use this colour for the axis and labels. NOTICKS=noticks - don’t draw the ticks for this axis. NOLABELS=nolabels - don’t draw the labels for this axis. When a longitude-latitude contour plot is made a call is made to AXES within the CON routine. This default behaviour can be switched off using the /NOAXES parameter to the CON command. When using GSET to set the plotting area an extra call to AXES needs to be made. When an integer STEP, XSTEP, YSTEP interval is selected the axes will be labelled with the appropriate integer values. AXES, STEP=1 on an x-axis of 0 to 10 gives

When a floating point interval is selected the NDECS command can be used to trim the labels for the axes as below.

AXES, STEP=0.1 on an x-axis of 0 to 0.8 gives

96

AXES, STEP=0.1, NDECS=1 on the same x-axis range gives a cleaner axis as below.

Labelling the axes with different text is done by specifying the XVALS and a corresponding list of XLABELS to the AXES routine: GSET, XMIN=0, XMAX=12 xlabels=['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul' , 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] xvals=INDGEN(12)+0.5 AXES, XVALS=xvals, XLABELS=xlabels

This is fine for certain plots where the mean value for each month is placed at the axis label as in a histogram plot. If you are plotting daily values then you’ll need to specify the month as a day number as in example 36. Plots that have long labels on the x-axis might need to rotate the text on the lower x-axis. This can be done by adding the ORIENTATION keyword to the AXES command. Using ORIENTATION=-90 in the above AXES command gives:

If you need an axis title as well the place this manually with a separate call to GPLOT . Note that the step and minor values for tick marks are sensitive to direction i.e. GSET, YMIN=1, YMAX=10 AXES, STEP=1 will make ten tick marks. GSET, YMIN=10, YMAX=1 AXES, STEP=1 will make no tick marks. Here you will have to select a negative step with STEP=-1 When making a log axis putting minor tick marks presents a problem because the step of the tick marks isn’t a regular one: GSET, XMIN=1, XMAX=1000, /XLOG vals=[1, 10, 100, 1000] AXES, XVALS=vals

Setting xminor to be a series of values labels the uneven log axis appropriately: xminor=[INDGEN(9)+1, INDGEN(10)*10+10, INDGEN(10)*100+100] AXES, XVALS=vals, XMINOR=xminor

97

COLBAR COLBAR is a procedure for displaying colour bars. The most basic use would be COLBAR, COORDS=coords, TITLE=title Where: COORDS=[x0,y0,x1,y1] - device (pixel) coordinates for the colour bar size. The bottom left point of the colour bar is (x0, y0) and the top right is (x1, y1). TITLE=title - the title to place on the colour bar. Extra options to COLBAR are: /TEXTPOS - on vertical colour bars display the text on the right hand side. Default=left hand side. /ALT - alternate the position of the text from bottom to top in a horizontal colour bar. NTH=nth - label every nth level on the colour bar rather than all the levels. Used when the contour plot has a lot of colours in to show structure within a field. /NOLINES - draw an internal colour bar level division only at the label points rather than every level. LABELS=labels - label just these points. Can be string variables toget correct looking labels i.e. LABELS=['0.1', '1', '10', '100'] Usually a call is made to COLBAR in the CON procedure unless the keyword /NOCOLBAR is given to CON. An example of a colour bar applying to two plots is provided in example 10.

When making separate calls to COLBAR use the /EXACT keyword to LEVS to setup your levels correctly. If this isn’t done then there will be a mismatch of plot and colour bar colours.

CON CON is a procedure for making contour plots. The most basic use of this procedure would be: CON, FIELD=field, X=x, Y=y where the FIELD is a two dimensional array with its values in the positions defined by the values in X and Y. An example would be where FIELD is an array of 96x73 points with the associated X locations having 96 points and Y locations having 73 points. Commonly used options to CON are: /AUTOLEVS - use the field min/max to make the levels. /NOCOLBAR - don't put a colour bar on the plot. /NOFILL - don't fill with colour. /NOLINES - don't put labelled lines on the plot. /BLOCK - make a blockfill plot. TRI=tri - the triangulation to use with irregular grids. /NOLINELABELS - don't put labels on the lines. /IMG - make an image contour plot in memory and place this in the contour plotting region. When plotting high resolution data this can make a significant reduction in the size of the output postscript file. This option only works for the cylindrical projection and for plots made when using GSET. The default image resolution is 100 dots per centimetre. To change this use IMG=img. So for example IMG=400 would give 400 dots per centimetre. TOL=tol - tolerance for wrapping the data in longitude. This is set to be 0.001 of a degree by default to take account of grids that use a third of a degree spacing. i.e. 0.000, 0.333, 0.666. 1.000 has a slightly uneven spacing. If you need more tolerance in the spacing this can be set with the TOL parameter. /QP - make a quick plot. CON, FIELD=SF('gdata.nc', 'temp', p=1000), /QP and CON, FIELD=SF('gdata.nc', 'temp', mean='lon'), /QP Are examples of making quick plots. See the chapter on quick plots for further details. MASK=mask - use a mask generated by COUNTRY to plot the contours from the specified countries.

98

Line drawing options to CON (all taking single values) are: NEGATIVE_STYLE=negative_style - style for negative lines. As for STYLE below. POSITIVE_STYLE=positive_style - style for positive lines. As for STYLE below. ZERO_STYLE=zero_style - style for zero line. As for STYLE below. NEGATIVE_THICK=negative_thick - thickness for negative lines, default=100 (%). POSITIVE_THICK=positive_thick - thickness for positive lines, default=100 (%). ZERO_THICK=zero_thick - thickness for zero lines, default=100 (%). NEGATIVE_COL=negative_col - colour for the negative lines. POSITIVE_COL=positive_col - colour for the positive lines. ZERO_COL=zero_col - colour for the zero line. Line drawing options to CON (all taking multiple values) are: STYLE=style - Changes the linestyle: 0=solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. COL=col - colours for the lines, default=1 (black). THICK=thick - thicknesses for the lines, default=100 (%). Titling and annotation options to CON are: /NOAXES - don't put axes on the plot if a MAP plot. TITLE=title - use this as the title above the plot. LEFT -TITLE = left _title - use this title on the left above the plot. RIGHT_TITLE = right _title - use this title on the right above the plot. /NOMAP - don't draw a map after drawing contours. Colour bar options to CON are: CB_TITLE=cb_title - title for colour bar. /CB_LEFT - place colour bar to the left of the plot. /CB_RIGHT - place colour bar to the right of the plot. /CB_UNDER - place colour bar under the plot. /CB_ALT - alternate text position (bottom to top) for horizontal colour bar. CB_WIDTH=cb_width - scaling factor for width of colour bar, default=100 (%). CB_HEIGHT=cb_height - scaling factor for height of colour bar, default=100 (%). CB_NTH=cb_nth - label every cb_nth level on the colour bar rather than all the levels. Used when the contour plot has a lot of colours in to show structure within a field. /CB_NOLINES - draw an internal colour bar level division only at the label points rather than every level. Most of these options are self explanatory but one or two will need a little explanation for you to use them properly. TRI=tri – see the chapter on contours for further details on contouring irregular grids. NEGATIVE_XXX , POSITIVE_XXX and ZERO_XXX all take just one value. This value applies to all the lines in that class. See example 5 for an example. STYLE, COL and THICK all take a series of values, one for each line defined by the LEVS command. See example 11 for an example. If a map is set then MAP and AXES are applied after a call to CON. There will be occasions where this isn’t required and the /NOMAP and /NOAXES keywords suppress this default behaviour. The default call to CON produces a colour filled plots with labelled lines drawn over and a colour bar in a default position. /NOFILL produces a simple unfilled contour plot with no colour bar. /NOCOLBAR suppresses the drawing of a colour bar on the plot even if colour filled contours are present.

99

COUNTRY COUNTRY is a procedure to select and plot countries on a map. To see the country names type COUNTRY, /LIST at the IDL prompt. The first name is a three letter name called the ISO name and this country can be selected using the ISO=iso flag to COUNTRY . The second name is the full name and can be selected using the NAME-=name flag to COUNTRY . The full list of flags to country is: NAME=name - select by full country name for plotting. ISO=iso - select by ISO name for plotting. COL=col - use this colour for plotting the boundary. FILLCOL=fillcol - use this colour to fill the country. /NOBORDER - Don’t draw a country border. THICK=thick - Use this thickness for the country border. Default=100 (%). /LIST - list the countries. MASK=mask - Use this mask to mask out all other data on the plot.

CS CS is a routine to select and make colour scales. There are 44 scales with a limited number of colours to select from using the notation CS, SCALE=scale Other keywords to CS are: COLS=[cols] - select colours by number. MIN=min - start colour (0-255). MAX=max - end colour (0-255). NCOLS=ncols - number of colours. /REV - reverse the colour scale. REV=rev - reverse the colours from colour 2 to this colour. WHITE=white - make this/these colour(s) white. This is applied after REVERSE if it is specified. /DRAW - draw this colour scale on the screen - a useful check of your colour scale before using it. FILE=file - read the colours from this file. OUTFILE=outfile - write colours to this file. SAVE=save - save the colours in this temporary scale. Values are 1 to 5. /MERGE - merge the saved colour scales in sequential order. /CLEAR - clear the temporary colour scales. The 44 scales selectable by the SCALE=scale option are as below.

100

Colour scale 1 is Dave Thompson’s colour scale from http://jisao.washington.edu The other colour scales are either from Data Graphics Research, Department of Geography, University of Oregon http://geography.uoregon.edu/datagraphics/index.htm or ColorBrewer http://www.colorbrewer.org Both these sites are well worth a browse as they have a lot of good advice on the subject of choosing a colour scale.

101

If your levels don’t fit into one of the previous number of levels then you can interpolate the scales to a new number of colours. The default SCALE=4 has twelve colours. CS, SCALE=4

This can be changed by the addition of the NCOLS parameter. CS, SCALE=4, NCOLS=8

The colour scales can be viewed interactively using the /DRAW option to CS. CS, SCALE=4, NCOLS=254, /DRAW

The first two colours in the colour map are reserved colours for the background and default line and text colours respectively. Colours that the user has control over range from 2 to 255. Generally plots with less than twenty colours are best as the eye has difficulty differentiating the different colours on a contour plot. If we used all 256 colours from the above colour scale then the variation between the second and fifteenth colours, for instance, are too subtle to notice. When a colour scale is interpolated to a new number of colours it is first expanded by interpolation to 254 colours. If only the NCOLS parameter is set then the scale is then stepped though at equal intervals to get a

102

new colour scale. If the MIN=min and MAX=max parameters are included then these are used in the 254 colours as the starting and finishing point for the stepping. Colour scales can be reversed by using the REV keyword. CS, SCALE=16, /DRAW

CS, SCALE=16, /REV, /DRAW

With some anomaly plots white is sometimes needed in the middle so that you don’t colour those regions. This can be done with the WHITE keyword. CS, SCALE=16, WHITE=6, /DRAW

Another way to make a colour scale is to specify numbered colours in the desired sequence as in example 9. CS, COLS=[93, 123, 91, 267, 272, 367, 409, 419, 407]

The numbered colours are shown on the next page.

103

Colour RGB values are from http://cloford.com/resources/colours/500col.htm

104

Around 10% of men have some form of colour deficiency. The most common form of this is Deuteranope, a red-green colour deficit. See http://www.vischeck.com for more information and an upload page to see how your colour plot will probably look to around 10% of men. Once you have a colour scale defined you can write it out with the OUTFILE=outfile option to CS. User defined colour scales can be read in with the FILE=file option. The colours used in the guide are based on red, green, blue triplets more commonly called an RGB scale . In this colour scheme the intensities of the red, green and blue components of colour are on a scale of zero to 255. To represent white in this colour scheme the red, green and blue components are set to their maximum intensity of 255. To represent black in this colour scheme the components are all set to be zero. The first six lines of SCALE=6 show how this works in practice. 255 255 255 0 0 0 0 0 255 255 255 255 255 0 0 255 255 255 These correspond to the colours below when displayed on the screen using CS, SCALE=6, /DRAW

Here the first six colours only are shown and the rest are all white. You may occasionally need to manually edit a colour scale to add new colours or if you wish to import a colour scale from another graphics package.

EBAR EBAR is a routine for plotting error bars on graphs. FILLCOL=fillcol X=x – x location of error bar. Y=y – y location of error bar. COL=col - colour for the lines. THICK=thick - thickness of the lines, default=100 (%). WIDTH=width - width of the error bar, default=100 (%) = 200 pixels. For box plots this can take two parameters where the first is the width of the error bar and the second is the width of the top and bottom terminator lines. The default for these is WIDTH=[100, 50] /DEVICE - plot in device (pixel) coordinates rather than in data coordinates. Simple error bar options: For a single xy point ERROR_X=error_x - x error. One value=both errors the same. Two values= different errors to left and right.

105

ERROR_y=error_y - y error. One value=both errors the same. Two values= different errors to left and right. EBARLEN=ebarlen The example to the right was produced with: EBAR, X=2, Y=6, ERROR_X=1, ERROR_Y=1

BOX=box BOX is a five element vector defining: [minimum, 25%, median, 75%, maximum] The example to the right was produced with: EBAR, X=7, BOX=[1, 1.5, 2, 2.5, 3]

PROB=prob PROB is a seven element vector defining: [minimum, 10%, 25%, median, 75%, 90%, maximum] The example to the right was produced with: EBAR, X=3, PROB=[1, 1.5, 2.0, 2.5, 3, 3.5, 4]

FEATURES FEATURES is a procedure for plotting features on a map. The routine looks at the data in field and finds the features that are separated by the number of separation points which is by default 1 point. FIELD=field - the two dimensional field to find features in. X=x - x locations of the field points. Y=y - y locations of the field points. MIN=min - find features less than this minimum. MAX=max - find features greater than this maximum. SEP=sep - the grid cell separation for the features. Default=1. DRAW=draw – draw a legend showing the number of points and the associated colours. LABEL=label - labels to use on the plot. 1=H or L, 2=High or Low, 3=numeric value. CHARSIZE=charsize - the character size for the labels. Default=100(%). FONT=font - font to use for the labels. Values=1-7. /ITALIC - use italic labels. COL=col - use this colour for the labels. /BOLD - use bold labels. NDECS=ndecs - number of decimal places for the labels if they are numbers. THRESHOLD=threshold - the number of points in a feature before a label is plotted. /V - verbose. Print information about the features found.

106

GPLOT GPLOT is a procedure for plotting lines, text and polygons on plots. To draw a line use: GPLOT, X=x, Y=y This would plot draw a line between the points specified in x and y. Other line keywords are: THICK=thick - change line thickness, default=100 (%). COL=col - the colour for each line. STYLE=style - use this style for the line. -1=no line, 0=solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. SYM=sym - the symbols for each line, values are 1-20 as below.

SIZE=size - change the size of the symbols, default=100 (%). /NOLINES - Don’t draw a line between the x and y points. /CLIP - clip to the plotting region. The default is that the GPLOT command can draw outside of the plotting region. BELOW=below - first value is colour for filling below y=0.0. If a two value array is passed then the second

value is substituted for that of y=0.0. ABOVE=above - first value is colour for filling above y=0.0. If a two value array is passed then the second

value is substituted for that of y=0.0. /DEVICE - use device (pixels) rather than data coordinates. When making graph plots the following will serve as an illustration of what you will see plotted. In this case we are plotting floating point numbers. X Y Lines plotted FLOAT=Array[15] FLOAT=Array[15] Single line of 15 points. FLOAT=Array[15,4] FLOAT=Array[15] 4 horizontal lines FLOAT=Array[15] FLOAT=Array[15,4] 4 vertical lines FLOAT=Array[15,4] FLOAT=Array[15,4] Collapses to a single line joining all the points. Polygon options: FILLCOL=fillcol - use this colour for filling the polygon. A line will join all the points as well unless the /NOLINES option is used. /LINEFILL - fill the polygon with lines. SPACING=spacing - spacing in centimetres for the lines. Line orientation, thickness and colour are defined by the ORIENTATION , THICK and COL keywords.

107

Legend options: /LEGEND - add a legend. LABELS=labels - the text label for each line. LEGPOS=legpos - location of the legend box, values are 1-16. Default=12. /NOLEGBOX - don’t plot a legend box. LEGCOL=legcol - use this colour for the legend background. LEGXOFFSET=legxoffset - legend offset in the x direction in pixels. LEGYOFFSET=legyoffset - legend offset in the y direction in pixels. Legend position numbers as defined by LEGPOS are as below. A legend is draw for each call to GPLOT if the /LEGEND keyword is set. You may need to form your data into an array before plotting so that you get a unified legend for all you lines to be plotted. A separate call to the LEGEND procedure cal be made if needed.

Text options: TEXT=text – Text to draw. CHARSIZE=charsize - character size default=100 (%). ALIGN=align - horizontal alignment, 0.0=left, 0.5=centre (default), 1.0=right. VALIGN=valign - vertical alignment, 0.0=bottom (default), 0.5=middle, 1.0=top. FONT=font /BOLD - use boldface if available. /ITALIC - use italics if available. ORIENTATION=orientation - orientation in degrees of text. Horizontal is the default=0.0 The following is a listing of the fonts that can be used with this guide. FONT FONT NAME NO OPTIONS /BOLD /ITALIC /BOLD, /ITALIC

Note that there are no bold typefaces available for FONT=5 or FONT=7. The /ITALIC keyword gives italic fonts for FONT=2, 3, 6 and 7 and oblique typefaces for FONT=1, 4 or 5.

10

11

12

1

2

3

4

5

6

7

8

9

14

15

16

13

108

To add Greek characters to plots use the above codes as in the following fashion. lambda='!9'+SCROP(BYTE(108))+'!X' mu= '!9'+SCROP(BYTE(109))+'!X' GPLOT, X=x, Y=y, TEXT=lamba+’=108’+mu+’m’

GSET GSET is a procedure for setting the plotting limits for any plot that isn’t a longitude-latitude plot. The most common use of this procedure is: GSET, XMIN=xmin, XMAX=xmax, YMIN=ymin, YMAX=ymax which would set the linear plotting limts for X and Y. Additional keywords are: TITLE=title - use this title for the plot. /XLOG - make the x-axis logarithmic. /YLOG - make the y-axis logarithmic. BCOL=bcol - background colour for the plot region.

GSYM GSYM is a routine for specifying the graphics symbol to be plotted. There are twenty symbols available with the guide as below.

GPLOT uses GSYM for specifying its symbols. For example GPLOT, X=xpts, Y=ypts, SYM=1 will plot a single line on a plot with filled squares at each data point. See example 36 for a simple plot with two lines plotted with different symbols. Setting the symbol to zero produces no symbol.

109

HIST HIST is a routine for drawing histograms or bar charts. X=x - x-points for routine. Y=y - y-points for routine. WIDTH=width - width of bar. Default=100 (%). COL=col - colour for line around bar THICK=thick - thickness of line around bar. Default=100 (%). FILLCOL=fillcol - colour to fill the bar with. OFFSET=offset - offset for starting drawing from. Default =0.0. /HORIZONTAL - draw a horizontal histogram rather than a vertical one. /NOBORDER - Don’t draw a border round the bars. /TOWER - Join data together to make a tower histogram. See examples 46 to 48 for some plot examples.

FEATURES FEATURES is a routine for finding features in a field. It examines the input field and finds points in the field that are below or above a threshold value. FIELD=field - the input data field. X=x - the x locations of the input field. Y=y - the y locations of the input field. MIN=min - the minimum threshold. MAX=max - the maximum threshold. SEP=sep - the separation of the data points to indicate that this is a feature. Default=1. /DRAW - draw the features on a plot. LABEL=label - type of labels to use for features. 0=H or L. 1=High or Low. 2=value of maximum or minimum in the feature. CHARSIZE=charsize - character size to use for the text. Default=100 (%). FONT=font - font to use for the labels. See GPLOT documentation for a list of fonts. /ITALIC - use italic font for the labels. COL=col - colour to use for the labels. /BOLD - use a bold font for the labels. NDECS=ndecs - number of decimal places to use when labeling the feature with a number. THRESHOLD=threshold - this is the minimum number of points before a label is made. Default=0. /V - print on the command line a list of the features found and the number of points in each of them.

GLEGEND GLEGEND is a procedure to plot legends on plots. This procedure has been renamed from LEGEND as IDL has a legend procedure as of version 8.0. The basic parameters passed to GLEGEND are: LABELS=labels - label for each line. COL=col - colour for each line. Other parameters to GLEGEND are: LEGPOS=legpos - position for the legend as below. The default position is 11. NOLEGENDBOX=nolegendbox - don’t draw a box around the legend. LEGCOL=legcol - use this colour for the legend background. LEGXOFFSET=legxoffset - the offset in the x-direction in pixels. LEGYOFFSET=legyoffset - the offset in the x-direction in pixels. SIZE=size - size of the symbols. Default=100 (%). STYLE=style - the style associated with each line.

110

SYM=sym - the symbol associated with each line. TYPE=type - the type of legend plot. 0 = a line. 1 = a colour filled box with a line around it. 2 = a colour filled box. FILLCOL=fillcol - the colour for the filled box. LENGTH=length - length of horizontal line or box in legend. Default=100 (%). BORDERSPACE=borderspace - the space between the surrounding box and the legend. Default=300 pixels. The legend positions are as shown below with a sample reference plot in the background.

LEVS Contour levels are selected using the LEVS command. Keywords to LEVS are: MIN=min - the minimum level. MAX=max - the maximum level. STEP=step - the step for the levels. /EXACT - keep levels to those specified. /LOWER - extend lower level limit. /UPPER - extend upper level limit. /NDECS - the number of decimal places. MANUAL=manual - supply your own levels. /NOZERO - remove the zero contour. /V - print the levels generated. A full discussion on using the LEVS command is given in the guide routines discussion. MAP The default mapping is the cylindrical projection with the longitude limits -180o to 180o and the latitude limits -90o to 90o. Keywords to MAP are: LONMIN=lonmin - minimum longitude. LONMAX=lonmax - maximum longitude. LATMIN=latmin - minimum latitude.

10

11

12

1

2

3

4

5

6

7

8

9

14

15

16

13

111

LATMAX=latmax - maximum latitude. /NH - north hemisphere stereographic projection. /SH - south hemisphere stereographic projection. /ORTHO - when used in conjunction with /SH or /NH swaps to the orthographic projection. /CYLINDRICAL - use the cylindrical projection - default setting. /ROBINSON - use the Robinson projection. /MOLLWEIDE - use the Mollweide projection. /SATELLITE - use the satellite projection. This defaults to a centre of 50o N on the Greenwich Meridian. Setting SATELLITE=[lon, lat] gives a centre on lon, lat. /SECTOR - produce a sector plot using the stereographic projection. The default is LONMIN=-20, LONMAX 20, LATMIN=0, LATMAX=80 LAND=land - use this colour for the land. OCEAN=ocean - use this colour for the ocean. /HIRES - change to high resolution continents. /DRAW - draw the map now. /SET - set the map now but don’t draw it. /ISOTROPIC - scale the longitude and latitude directions equally. /LAKES - draw the lakes such as the Great Lakes in the US, Caspian Sea etc. /COUNTRIES - draw the country outlines. When making a multiple plots on the same page a call to MAP must be made for each plot position. When making longitude-latitude vector plots with no previous call to CON the /DRAW keyword to MAP must be used to initiate the map coordinate system. The longitude limits of plotting are -360o to 360o with only 360o being able to be shown at one time. The latitude limits of a plot are -90o to 90o. Any input values beyond these limits will cause the MAP routine to show an error and stop.

NCREAD NCREAD is a function for reading netCDF files. A basic use of this function would be: d=NCREAD(‘gdata.nc’) This would read all the variables in the netCDF file gdata.nc into the structure d. As the file is read the variable dimensions are printed on the IDL command line. The data variables are modified according to netCDF attributes such as missing_value, add_offset etc. Missing and out of range data values are given the NaN value. The data in the structure d is in the form: d.var1 d.var2 To see what is in the structure use the command HELP, d, /STRUCTURE . Minimum and maximum values of d can be printed using: PRINT, MIN(d.var1), MAX(d.var1) If the data has missing values then you’ll need to change this to: PRINT, MIN(d.var1, /NAN), MAX(d.var1, /NAN) Keywords to the NCREAD function are: /SILENT - don’t report on the variables read. /NOMOD - don’t modify data according to netCDF attributes. VARS=[‘var1’, ‘var2’] – just read in these variables var1 and var2. Associated variables are read in as well. /ATT - read in netCDF variable and global attributes as well as the data.

112

/VALID – many datasetshave incorrect valid_min and valid_max netCDF attributes. These are ignored by default. If these attributes need to be taken into account then use the /VALID flag to NCREAD. When the /ATT keyword is used the structure has the form: d.var1.att1 d.var1.att2 d.var1.attn d.var1.data d.var2.att1 d.var2.att2 d.var2.attn d.var2.data d.gatt1 d.gatt2 d.gattn.... Where var, att are the variables and attributes and data and gatt are the data and global attributes. To see what is in the attribute enabled structure use the command HELP, d.var1, /STRUCTURE. When you are reading very large netCDF files you might want to return a subset of the data in the variables. The following keywords to NCREAD will help you to do this: COUNT=count - dimensions of dataset to be read. OFFSET=offset - starting position for read. STRIDE=stride - sampling intervals between accessed values. Say we have a temperature dataset with dimensions [lon,lat,p]. With lon=96, lat=73, p=22 elements. To pick off the second level you would use: d=NCREAD('data.nc', VARS=['temp'], COUNT=[96,73,1], OFFSET=[0,0,1])

PCON PCON is a function for converting pressure to height in kilometers and vice-versa. This function uses the equation P=Poexp(-z/H) to translate between pressure and height. In PCON the surface pressure Po is set to 1000.0mb and the scale height H is set to 7.0. The value of H can vary from 6.0 in the polar regions to 8.5 in the tropics as well as seasonally. The value of Po could also be said to be 1013.25mb rather than 1000.0mb. As this relationship is only approximate: (i) Only use this for making the axis labels on log pressure plots as in example 14. (ii) Put the converted axis on the right hand side to indicate that this isn’t the primary unit of measure. km=PCON(mb, /TO_KM) would convert the values in mb to height in kilometers and return them in the variable km. The reverse transformation to millibars can be achieved with: mb=PCON(km, /TO_MB) PRINT, PCON(['1000', '300', '100', '30', '10', '3', '1', '0.3'], /TO_KM) 0.00000 8.42781 16.1181 24.5459 32.2362 40.6640 48.3543 56.7821 PRINT, PCON([0.00000, 8.42781, 16.1181, 24.5459, 32.2362, 40.6640, 48.3543 , 56.7821], /TO_MB) 1000.00 300.000 100.000 30.0000 9.99999 3.00000 0.999998 0.300000

113

PFILL PFILL is a procedure to plot patterns on contour plots. The most basic use would be: PFILL, FIELD=field, X=x, Y=y, MIN=min, MAX=max where the FIELD is a two dimensional array with its values in the positions defined by the values in X and Y. This would plot a dotted pattern between the limits MIN and MAX . Other keywords to PFILL are: SPACE=space - space between the dots, default=100 (%) - 200 pixels (0.2cm). COL=col - colour for the dots or lines. SIZE=size - size for the dots, default=100 (%). SYM=sym - filled symbol, default=3 (a filled circle). STYLE=style - 0=dots, 1=vertical lines, 2=horizontal lines, 3=vertical and horizontal lines 4=diagonal / lines, 5=diagonal \ lines, 6=diagonal / and diagonal \ lines. RES=res - divide the space between the dots into this number of sections. The higher the number the closer the lines will get to the limiting contour values. The default is 4. Higher numbers increase the plotting time as more calculations have to take place. In the plots below the left plot was done with RES=4 (the default) and the right plot with RES=20.

Examples 15 and 16 are pattern fill plots.

POS POS is a procedure for positioning plots on a page. Keywords to POS are: XOFFSET=xoffset - offset in x direction. YOFFSET=yoffset - offset in y direction. XSIZE=xsize - x size in pixels. YSIZE=ysize - y size in pixels. /NP - new page - move onto the next page in the postscript file. By default contour plots with colour bars are resized to fit the plot area. To stop the resizing select the XSIZE and YSIZE for your plot and no resizing is preformed. For multiple plots on a page use PSOPEN is used to set the number of plots in the x and y-directions. POS, XPOS=xpos, YPOS=ypos would position the plot at column y in row x.

114

PSCLOSE Postscript files are closed and viewed with the PSCLOSE command. The default viewer is the ImageMagick display command. Other options are: /NOVIEW - close but don't view the postscript file. /GV - view using gv. When viewing on the screen using the default ImageMagick display command you’ll see some faint white lines on your plot. These are because the conversion to a screen plot was done at low resolution to make a quick plot. The postscript output doesn’t have these lines present.

PSOPEN To open a postscript file use the PSOPEN command. Commonly used keywords to PSOPEN are: FILE=file - create a postscript file called file. /PORTRAIT - create a portrait postscript file (default is landscape). /LETTER - create a letter size postscript file (default is A4). /A5 - create an A5 sized plot. /EPS - create an encapsulated postscript plot. XPLOTS=xplots - number of plots in the x direction. YPLOTS=yplots - number of plots in the y direction. XOFFSET=xoffset - offset in x direction, default=0 pixels. YOFFSET=yoffset - offset in y direction, default=0 pixels. XSIZE=xsize - x size in pixels on the present paper size. YSIZE=ysize - y size in pixels on the present paper size. MARGIN=margin - margin around paper edges, default=3000 pixels. SPACING=spacing - spacing between plots, default=3000 pixels. XSPACING=xspacing - x spacing between plots. YSPACING=yspacing - y spacing between plots. SIZE=size - size of postscript file in pixels. PSOPEN , SIZE=[14000, 10000] would give a postscript file of size 14cmx10cm. AXISTYPE=axistype - The longitude-latitude axis types are as follows: 0=90W, 0, 90E. 1=-90, 0, 90. 2) 0 with degree symbol. 3) 1 with degree symbol. By default the output postscript file is called idl.ps. This is changeable with the FILE=file option to PSOPEN. The paper sizes in pixels are: A4 - landscape=29,700x21,000 pixels,

- portrait=21,000x29,700 pixels. Letter - landscape=27,900x21,600 pixels,

- portrait=21,600x27,900 pixels. A5 - landscape=21,000x14,800 pixels. - portrait=14,800x21,000 pixels. You can see from these dimensions that the postscript files have a density of 1000 pixels per centimetre. Plots are sized so as to fit on the page with a 3000 pixel margin. The axes for the plots are then drawn around the plot. When a colour bar is selected the plot is resized as shown below so that this margin is retained.

115

Resizing isn’t performed when the XSIZE and YSIZE options to PSOPEN are selected. If your axes don’t entirely fit on the page then the XOFFSET, YOFFSET XSIZE , YSIZE and MARGIN parameters can be used to adjust the plot position. Plot attributes can be modified using the PSOPEN command as shown below. Changing plot attributes There are a variety of plot attributes you may wish to change according to your personal preferences or to allow better spacing of the plot elements. A list of the user definable plot attributes follows: PORTRAIT=0 ;Select portrait as the format. LETTER=0 ;Set to 1 to select letter paper. XPLOTS=1 ;Number of plots in the x direction. YPLOTS=1 ;Number of plots in the y direction. XOFFSET=0 ;X offset of first picture (pixels). YOFFSET=0 ;Y offset of first picture (pixels). MARGIN=3000 ;Margin around plot (pixels). XSPACING=3000 ;X spacing between plots (pixels). YSPACING=3000 ;Y spacing between plots (pixels). XSIZE=0 ;X size of plot (pixels). YSIZE=0 ;Y size of plot (pixels). SPACE1=200 ;Space between text (pixels). SPACE2=400 ;Space between colour bar and plot (pixels). SPACE3=800 ;Space between the title and the plot (pixels). TICKLEN=200 ;Tick length (positive is away from plot) (pixels). THICK=100 ;Thickness of lines (%). CTHICK=100 ;Thickness of continents (%). CSTYLE=0 ;Line style of continents. CCOLOUR=1 ;Colour of the continents. CB_WIDTH=100 ;Width of colour bar (%). CB_HEIGHT=100 ;Height of colour bar (%). BORDER_THICK=100 ;Thickness of the line around the plot (%). FONT=1 ;Font to use for text except titles (values=1-7). CHARSIZE=100 ;Size of text except for titles (%). BOLD=0 ;Set to 1 for bold text. ITALIC=0 ;Set to 1 for italic text. CFONT=1 ;Font to use for contours (values=1-7) CCHARSIZE=100 ;Size of text for contours (%) CBOLD=0 ;Set to 1 for bold contours CITALIC=0 ;Set to 1 for italic contours TFONT=1 ;Font to use for titles (values=1-7).

116

TCHARSIZE=100 ;Size of text for titles (%). TBOLD=0 ;Set to 1 for bold titles. TITALIC=0 ;Set to 1 for italic titles. AXISTYPE=0 ;Type of axis Fonts available are: 1=Helvetica, 2=Times, 3=Palatino, 4=Courier, 5=Avant-garde, 6=Schoolbook and 7=Bookman. Example fonts are shown in the fonts section of the reference for the GPLOT command at the back of the guide together with some additional notes about the ITALIC and BOLD settings. The hierarchy of setting the plot attributes is:

5) The system file $IDL_GUIDE/lib/idl_guide5.def 6) The users definition file $HOME/.idl_guide5.def (if it exists) 7) A definition file attached to the PSOPEN command: PSOPEN, DEF=’graph.def’ 8) Individual definitions to the PSOPEN command: PSOPEN, SPACE2=400

If you choose to have your own definition files as in options 2 or 3 then copy the system file: glib cp idl_guide5.def ~/.idl_guide5.def and then use this as your starting point.

REGRID REGRID is a bi-linear interpolation function for interpolating data to a new grid. The calling parameters for REGRID are: fieldout=REGRID(fieldin, longs_orig, lats_orig, longs_new, lats_new) fieldin is the original grid on the grid spacing longs_orig, lats_orig. fieldout is the output grid on the grid spacing longs_new, lats_new. longs_new and lats_new can be single or multi-value so you can get the value at a point or on a new grid. Example 1 - a single value. d=NCREAD('gdata.nc') newu=REGRID(d.u(*,*,0), d.lon, d.lat, 0.0, 51.5) HELP, newu NEWU FLOAT = 7.38125

Example 2 – multiple values. d=NCREAD('gdata.nc') newx=FINDGEN(11)-5 newy=FINDGEN(11)+48 HELP, newx, newy NEWX FLOAT = Array[11] NEWY FLOAT = Array[11] PRINT, newx -5.00000 -4.00000 -3.00000 -2.00000 -1.00000 0.00000 1.00000 2.00000 3.00000 4.00000 5.00000 PRINT, newy 48.0000 49.0000 50.0000 51.0000 52.0000 53.0000

117

54.0000 55.0000 56.0000 57.0000 58.0000 newu=REGRID(d.u(*,*,0), d.lon, d.lat, newx, newy) HELP, newu NEWU FLOAT = Array[11, 11]

RGAXES RGAXES is used to draw Met Office rotated grid axes. The minimum keywords are: XIN=xin - longitudes of rotated grid. YIN=yin - latitudes of the rotated grid. XPOLE=xpole - longitude pole in degrees. YPOLE=ypole - latitude pole in degrees. Other keywords to RGAXES are: XLAB=xlab - label x-axes. 0=none, 1=lower, 2=upper, 3=lower and upper. YLAB=ylab - label y-axes. 0=none, 1=left, 2=right, 3=left and right. /CONTINENTS -show continent outlines. /COUNTRIES - show country outlines. CCOL=ccol - colour of continents. Default=1 (black). CSTYLE=cstyle - line-style for continents. 0 =solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. CTHICK=cthick - thickness of continent lines. Default=100 (percentage). GSTYLE=gstyle - use this style for the grid. -1=no line, 0=solid (default), 1=dotted, 2=dashed, 3=dash dot, 4=dash dot dot and 5=long dashes. GTHICK=gthick - grid thickness, default=100 (%) GCOL=gcol - grid colour, default=1 (black). HIRES=hires - select high resolution coastlines.

RGROT RGROT is a procedure to change from longitude-latitude coordinates to a Met Office rotated coordinate system. XIN=xi n - input - locations of x-coordinates. YIN=yin - input - locations of y-coordinates. XOUT=xout - output - locations of x-coordinates. YOUT=yout - output - locations of x-coordinates. XPOLE=xpole - input - longitude pole. YPOLE=ypole - input - latitude pole. The ROT routine is okay to use for plotting but not for doing scientific calculations. Use the Fortran code lltoeq.f and eqtoll.f instead for these.

RGUNROT UNROT is a procedure to change from Met Office rotated coordinates to a longitude-latitude coordinate system. XIN=xi n - input - locations of x-coordinates. YIN=yin - input - locations of y-coordinates. XOUT=xout - output - locations of x-coordinates. YOUT=yout - output - locations of x-coordinates.

118

XPOLE=xpole - input - longitude pole. YPOLE=ypole - input - latitude pole. The UNROT routine is okay to use for plotting but not for scientific calculations. Use the Fortran code lltoeq.f and eqtoll.f instead for these.

SCROP SCROP is a function to remove whitespace from the start and end of a string. This is useful when you have to convert integer and floating point numbers to string variables. a=5.6 b=STRING(a) c=SCROP(a) HELP, a, b, c A FLOAT = 5.60000 B STRING = ' 5.60000' C STRING = '5.60000' SCROP also takes the NDECS keyword to trim to NDECS decimal places: PRINT, SCROP(0.123456789, NDECS=2) 0.12

SF SF is a routine for selecting field for contour plots. The data is returned as a structure and then can be passed to CON for contouring. The routine takes the netCDF filename and variable as the first two elements. Additional parameters may be passed such as p=1000 to select the pressure=1000mb from a field CON, FIELD=SF('gdata.nc', 'temp', p=1000), /QP Meaning can also be done with the mean parameter. CON, FIELD=SF('gdata.nc', 'temp', mean='lon'), /QP

STIPPLE STIPPLE is a procedure to plot stipples on contour plots. The most basic use would be: STIPPLE, FIELD=field, X=x, Y=y, MIN=min, MAX=max where the FIELD is a two dimensional array with its values in the positions defined by the values in X and Y. This would plot a stipple pattern between the limits MIN and MAX . Other keywords to STIPPLE are: SPACE=space – space between the stipples, default=100 (%) - 200 pixels (0.2cm). COL=col – colour for the stipples. SIZE=size – size for the stipples, default=100 (%). SYM=sym – stipple symbol, default=3 (a filled circle). Example 15 is a stipple plot. STIPPLE has been replaced by PFILL which enables pattern filling of contour plots. It is retained in the library code for backwards compatibility.

119

VECT VECT is a procedure to plot vectors. The most basic use would be: VECT, U=u, V=v, X=x, Y=y Where U and V are the horizontal and vertical vector components as two dimensional arrays and X and Y are the vector locations as one dimensional arrays. A common set of inputs would be: HELP, u, v, x, y U FLOAT = Array[96, 72] V FLOAT = Array[96, 72] X FLOAT = Array[96] Y FLOAT = Array[72] Optional parameters are: LENGTH=length - length of the vector, default=100 (%), 300 pixels (0.3cm). STRIDE=stride - pick every nth vector for plotting. TYPE=type - type of arrow head. 0-4, default=0.

ANGLE=angle - angle between shaft and vector head in degrees, default=22.5. HEAD_LEN=head_len - length of the arrow head relative to shaft, default=0.3 ALIGN=align - alignment of arrow. Default is 0.5, range=0.0 to 1.0. MAG=mag - reference arrow magnitude. REF_TEXT=ref_text - text to place to the left of the reference vector. COL=col - colour index of vectors. PTS=pts - the number of equally spaced points to interpolate to across the diameter of a cylindrical or polar polar plot. When plotting vectors in cylindrical projections this can take two elements, one for the x-direction and one for the y-direction. /DEVICE - plot the vector in device (pixel) rather than data coordinates. SIZE=size - if this keyword is set the vector head needs to be kept constant, default=100 (%). /MAP - only used when in cylindrical projection to draw vectors that are correct in map space. /AXES - draw vectors in data rather than in device space. MUNITS=munits - use these units in the legend. LEGCOL=legcol - use this colour for the legend background. LEGXOFFSET=legxoffset - the offset in the x-direction in pixels, default=400 (pixels). LEGYOFFSET=legyoffset - the offset in the y-direction in pixels, default=400 (pixels). LEGSPACE=legspace - distance between the legend and the axes. /NOLEGEND - turn off the legend. BORDERSPACE=borderspace - space between the legend elements and the edge of the legend, default=300 (pixels). TITLE=title - use this as the title above the plot. LEFT -TITLE = left _title - use this title on the left above the plot. RIGHT_TITLE = right _title - use this title on the right above the plot. /QP - make a quick plot. VECT, F=SF('gdata.nc', ['u', 'v'], p=1000), /QP LEGPOS=legpos - position for the legend as below. The default position is 11 for cylindrical projection plots and 16 for polar projection plots.

120

10

11

12

1

2

3

4

5

6

7

8

9

14

15

16

13

121

Appendix C - A brief introduction to IDL 1. IDL resources 1.1 Local online manuals IDL has an excellent documentation system which is available locally from the web page http://methome:62489/help/index.jsp External users of this guide might be able to type ? at the IDL prompt to get their own documentation interface. 1.2 Local manuals There are three good IDL manuals available within the department: Two copies of ‘Practical IDL programming’ by Liam Gumley are available from the department library. I also have copies of the above, ‘IDL programming techniques’ by David Fanning and ‘An Introduction to Programming with IDL’ by Kenneth Bowman that you can borrow from me in room 2L45. 1.3 The NCAS-Climate IDL script repository NCAS-Climate maintain a local repository of useful IDL scripts at the web address http://ncas-cms.nerc.ac.uk Under services on the left hand side, click on utilities and then scripts repository. There is a large library of software, particularly appropriate for manipulating and plotting data from the Met Office models. A guide covering this library, written by Jonathan Gregory, is available at http://ncas-cms.nerc.ac.uk . Under visualisation on the left hand side click on Guide to the Met Office PV-WAVE/IDL library. Jonathan’s guide is only available to people who have signed a Met Office collaboration agreement. Please contact j.m.gregory@rdg.ac.uk if you wish to use this software. 1.4 Web resources David Fanning’s website, http://www.dfanning.com, is an excellent online source of links and tips. ITT Visual Information Solutions, the makers of IDL, have a set of technical tips that are useful for the more experienced user – see http://www.ittvis.com under the support menu. If you are at the University of Reading then please join the meteorology department IDL user group. There is also a useful discussion archive for this group. Both are available at: http://www.met.rdg.ac.uk/Lists

2. Using IDL 2.1 Typing at the command line IDL is an interactively compiled language i.e. each command that is typed at the command-line is compiled and run when the return key is pressed. To use the command-line interface type: idl To scroll through the command history you can use the up and down keyboard keys. 2.2 Using program files Using this mode you can use program files that you edit in your favourite editor. After a change to the program source code a recompilation is needed before executing your changed program. 2.3. A sample program The code to print ‘Hello’ on the screen in IDL is:

122

PRO hello PRINT, ’Hello’ END In the IDL language, programs start with the PRO myname statement and finish with the END statement. The PRINT command is used to display on the terminal text or variables, in this case the string ‘Hello’. Comments in IDL are prefaced by a semi-colon, ;. Commands sometimes get too long to effectively fit on one line and can be continued to the next line using the dollar sign, $. 2.4 Some useful IDL commands PRINT, myvar – display the current contents of myvar HELP, myvar – provide basic information on the myvar variable. @myfile – include the file myfile.pro at this point 2.5 Compiling and running programs To compile and run the above program use: .compile hello hello In IDL commands prefaced by a dot are called executive commands. These commands can only be used from the IDL command-line and not within a program. Other executive commands you might use are: .continue continues the execution of a program that has stopped because of an error, a stop statement or a keyboard interrupt. .reset_session resets much of the state of an IDL session without requiring the user to exit and restart the IDL session. See also the .full_reset_session command in the reference manual for a fuller description of what each command resets.

3. Setting IDL preferences To change integers on the IDL command-line to be 32 bit, set: export IDL_STARTUP=~/.idlrc in your .kshrc file. Then edit ~/.idlrc and put in the following line: COMPILE_OPT DEFINT32 For each routine that you need 32 bit integers you need to put COMPILE_OPT DEFINT32 near the top of your routine. 3.1 Adding directories to your IDL path The environment variable IDL_DIR contains the search path for IDL routines. If you had a program directory ~/idl that you wished to add to your search path then adding the line export IDL_PATH=$IDL_PATH:~/idl in your .kshrc will do this. Don’t forget start a new terminal window to start using the new directory path. Any programs in your ~/idl directory that have the matching routine name and program name can now be called no matter which UNIX directory you are currently in.

123

4. Creating and manipulating variables Commonly used variable types are: Variable bits zero value BYTE 8 0B INT 16 0 LONG 32 0L LONG64 64 0LL FLOAT 32 0.0 DOUBLE 64 0.0D STRING up to 32,767 characters ‘’ The default size for signed integers is 2 bytes unless you have made the modification suggested in section 3. i.e. on a Linux PC or Sun workstation this will be +/-32,767. Specifying a number out of this range can produce strange results. a=320*160 HELP, a A INT = -14336 To ask for a 4 byte integer add the L symbol after the variable definition as in the table above, i.e. a=320*160L HELP, a A LONG = 51200 Also, note that integer arithmetic gives different results from floating point arithmetic. PRINT, 11/2, 11.0/2

5 5.50000 Float values have seven significant digits and can range from 10-37 to 1038 (positive or negative). The generation of a 16 byte double float can be accomplished with x=3.0D y=3.0 HELP, x,y X DOUBLE = 3.0000000 Y FLOAT = 3.00000 Formatting of strings can be done in a similar manner to Fortran. a=-40.0 b=STRING(a, FORMAT=’(f10.1)’) help, a,b A FLOAT = -40.0000 B STRING = ' -40.0' Some useful rounding routines are: ROUND – round to the closest integer FLOOR – round to the nearest integer less than or equal to the argument CEIL - round to the nearest integer greater than or equal to the argument a=5.6 b=-5.6 PRINT, ROUND(a), ROUND(b) 6, -6 PRINT, FLOOR(a), FLOOR(b) 5, -6 PRINT, CEIL(a), CEIL(b) 6, -5

124

4.2 Variable conversion Occasionally it is useful to convert one variable type into another, this can readily be accomplished using: BYTE(myvar) - converts myvar into a byte FIX(myvar) - converts myvar to an integer FLOAT(myvar) - converts myvar to floating point STRING(myvar) - converts myvar to a string DOUBLE(myvar) - converts myvar into a double For example: a=10 b=FLOAT(a) HELP, a, b A INT = 10 B FLOAT = 10.0000 4.3 String manipulation String manipulation is IDL is very easy and powerful. To add two strings together simply use the + operator a=’X axis’ b=’ is the temperature’ c=a+b HELP, c C STRING = ’X axis is the temperature’ Other string operators that you might use are b=STRTRIM(a,2) - delete the white space before and after the last characters of a. b=STRLEN(a) - return the length of string a in b. b=STRPOS(a,’x’) - return in b the first occurence of the string ‘x’ in a. STRPUT, mystr, substr, pos - place the string substr in the string mystr starting at the position pos. Using our previous example, we can remove the white space before as below: a=-40.0 b=STRTRIM(STRING(a, FORMAT=’(f10.1)’),2) HELP, a, b A FLOAT = -40.0000 B STRING = ’-40.0’ Or use the SCROP command: B=SCROP(a) HELP, b B STRING = ’-40.0’

5. Creating and manipulating arrays 5.1 Creating arrays There are a similar set of routines to variable creation for array creation: Variable Array creation BYTE BYTARR INT INTARR LONG LONARR LONG64 LON64ARR FLOAT FLTARR DOUBLE DBLARR STRING STRARR Array indices start at zero in IDL. Forgetting this is probably the most common mistake people make when starting to use IDL.

Remember that array indices in IDL start at zero.

125

Creating the array initializes it to zero. a=INTARR(10) PRINT,a 0 0 0 0 0 0 0 0 0 0 Another way is to specify the individual array elements n=[1,2,3,4] PRINT, n, n[1:2] 1 2 3 4

2 3

5.2 Manipulating arrays The IDL routines INDGEN and FINDGEN create sequences of numbers for integers and floating point numbers: ypts1=INDGEN(6) ypts2=FINDGEN(6) PRINT, ypts1,ypts2 0 1 2 3 4 5 0.00000 1.00000 2.00000 3.00000 4.00000 5.00000 A good use of INDGEN and FINDGEN is in the creation of regularly space sequences such as a set of latitude points. ypts=90.0-INDGEN(7)*30.0 PRINT, ypts 90.0000 60.0000 30.0000 0.00000 -30.0000 -60.0000 -90.0000 We could have used INDGEN here as an integer multiplied by a real will give a real number. Other common examples of array manipulation: a=a*10.0 - multiply all elements of a by 10.0 a=a-273.15 - take 273.15 off all array points pos=WHERE(a LT 0.0) - find the positions of all points where the value is less than zero maxval=MAX(arr, index ) - Find the maximum value of arr, put this in maxval and store the index of this point in the variable index. minval=MIN(arr,index) - Find the minimum value of arr, put this in minval and store the index of this point in the variable index. a=REVERSE(b, dimension index) - reverse the order of one dimension of an array. b=TOTAL(a, dimension index) - sum array over one dimension. t2=CONGRID(t, X, Y, Z) - shrink or expand an array of points to a new size. f=REFORM(e) - change the dimensions of an array without changing the number of elements. Useful for removing the degenerate leading dimensions of size 1. TRANSPOSE(a) - returns the transpose of the array a. ROTATE(a,direction) – rotate/transpose an array. c=a#b - multiply the columns of the array a by the rows of b. c=a##b - multiply the rows of the array a by the columns of b. a=[a,a(0,*)] – add a column to the end of a. a=[[a(*,0)],[a]] – add a row before a. 5.3 Use of the temporary function As your use of IDL progresses you might have need of the temporary function to save memory space. The code t=FLTARR(1000000) t=t-273.15 uses 1 million * 4 bytes = 4 million bytes for the first statement. The second statement creates a new array to hold the result of the subtraction and then frees the memory used by the old array version. The memory used in this code is 8 million bytes.

126

t=TEMPORARY(t)-273.15 uses just 4 million bytes. The temporary function can only be used where the array in question appears once on the right hand side of the equation. Multiple commands might be needed for more complex array manipulations but can substantially reduce the memory usage of your code.

6. Program control statements Each language has its own syntax for the control of a program which although similar have slight differences. These are examples of the common ones that you are likely to use in IDL: IF x LT 12.0 THEN y=0.8 IF (x LT 12.0) THEN BEGIN idl statements IF (x GT 5) THEN BEGIN ENDIF ELSE BEGIN idl statements idl statements ENDIF ENDELSE FOR I=0,9 DO BEGIN WHILE (x LE 0) DO BEGIN idl statements idl statements ENDFOR ENDWHILE REPEAT BEGIN idl statements ENDREP UNTIL (x EQ 27) Have is an example of a loop creating a filename that can be used to read ERA40 data from a machine called charney: FOR year=1979,1985 DO BEGIN stryear=STRTRIM(STRING(year),2) myfile=’/export/charney/data-01/era-40/monthly_means/’+stryear+$ ‘/ggapjan’+stryear+’.nc’ PRINT, ’reading ’ , year, myfile ENDFOR Gives the screen output reading 1979 /export/charney/data-01/era-40/monthly_means/1979/ggapjan1979.nc reading 1980 /export/charney/data-01/era-40/monthly_means/1980/ggapjan1980.nc reading 1981 /export/charney/data-01/era-40/monthly_means/1981/ggapjan1981.nc reading 1982 /export/charney/data-01/era-40/monthly_means/1982/ggapjan1982.nc reading 1983 /export/charney/data-01/era-40/monthly_means/1983/ggapjan1983.nc reading 1984 /export/charney/data-01/era-40/monthly_means/1984/ggapjan1984.nc reading 1985 /export/charney/data-01/era-40/monthly_means/1985/ggapjan1985.nc The program code for this is available by typing glib at the UNIX command line prompt and looking in the loop1.pro program. A second example is available in loop2.pro that lists in order the filenames for 6 hourly data in files for the 850 mb zonal wind for the months May to October and the years 1979 to 1980. This shows the flexibility of using IDL to correctly name files for reading in and doing running means on real data. Neither the program nor the output is listed here for brevity but is available by typing glib as above.

127

6.1 Speeding up loops In IDL array expressions execute faster than loops and conditional statements. If your program is running slowly try using the WHERE array operator. The example below shows this in action on an array of 100 million elements. It checks to see if the element is below zero and if so sets the corresponding mask value to be 1. This example could be a calculation of the land-sea mask, for instance. ix=10000 iy=10000 FOR i=0,ix-1 DO BEGIN FOR j=0,iy-1 DO BEGIN IF a(i,j) GT 0 THEN b(i,j)=1 ENDFOR ENDFOR This code took 78 seconds to execute on a 2.4GHz Linux PC. Reversing the order of the loops to FOR j=0,iy-1 DO BEGIN FOR i=0,ix-1 DO BEGIN reduces the execution time to 46 seconds. If you access by column first then the next element is more quickly retrieved because it’s the next in memory. Using the WHERE function this code can be simplified to: land=WHERE(a GT 0) b(land)=1 Using WHERE took 0.76 seconds i.e. a hundred times faster than our first attempt. There are variations on a theme here with other methods being b=a GT 0 and b(*)=a GT 0. The full code showing this is available in the examples directory as show_where_use.pro. Adding the COUNT parameter to the WHERE command will give you the number of times that a condition is met, i.e. land=WHERE(a GT 0, COUNT) If count is -1 then the condition hasn’t been met. To find the time spent in various sections of your code use t1=SYSTIME(/SECONDS) to find the present wallclock time at the start of the code section to be examined. A second call to SYSTIME at the end of the code will then help you debug where the code is spending the most time. If you have memory issues then PRINT, MEMORY(/CURRENT) will tell you how much memory the current IDL session is using,

7. Scientific routines IDL comes with the normal set of scientific functions, which can be called as listed below. SIN(x), COS(x), TAN(x) - sine etc. ASIN(x), ACOS(x), ATAN(x) - arcsine etc. SINH(x), COSH(x), TANH(x) - hyberbolic sine etc. SQRT(x) - returns the square root of x. a^b - a raised to the b power. CEIL(x) - returns the closest integer greater than or equal to the argument. FLOOR(x) - returns the closest integer less than or equal to the argument. ROUND(x) - rounds the argument to the closest integer. EXP(x) - returns the natural exponential function of x. ALOG(x), ALOG10(x) - return the natural logarithm and logarithm to the base 10 of x. !PI, !DPI - single and double precision values for π.

128

mag = SQRT(u^2.+v^2.) – gives the magnitude of the wind. !DTOR – degree to radians conversion factor. 7.1 Other routines There are a host of other routines in IDL to do correlations etc. Care is needed so that you understand how your data is being changed. IDL core routines such as mean, FFT etc. can cause unexpected results if you have a routine of your own with the same name.

8. ASCII and binary file input/output IDL recognizes both free and explicit format ASCII files. 8.1 ASCII input There are three commands for reading ASCII data READ – read free format data READF – read fixed format data READS – read free format data from a string variable A typical sequence of opening, reading data from and closing a file would be: OPENR, 1, ’ascii.dat’ READF,1, mydata CLOSE,1 This example explicitly uses logical unit number 1 for reading the data. A more general method would be: OPENR,lun, ’ascii.dat’, /GET_LUN READF,lun, mydat FREE_LUN, lun The /GET_LUN switch picks a free logical unit number from the pool of free units and places it in the integer variable lun. If mydata is undefined then it will just read the first variable from the file ascii.dat whether this is integer or floating point and place it in the variable mydata. As an example of reading some data the file comp.txt contains data in the form: year value1 value2 1880 -0.0228571 -0.0600000 1881 -0.0600000 0.0900000 etc. To read this data we create three IDL arrays, form a loop over the rows of data to be input, read the data into dummy variables and place the data from these into the IDL. Reading ASCII data directly into the arrays can give confusing results and should be avoided as is shown in read_row.pro in the examples directory. OPENR,1,'comp.txt' mystr=’’ READF,1,mystr ; read titles mytime=INTARR(121) temp1=FLTARR(121) temp2=FLTARR(121) FOR i=0,120 DO BEGIN READF, 1, val1, val2, val3 mytime(i)=val1 temp1(i)=val2 temp2(i)=val3 ENDFOR CLOSE, 1

129

8.2 ASCII output There are two ways of opening files for writing in IDL, OPENW – open for write (if the file exists overwrite it) OPENU – open a file for update. To open and write a data file an example would be: OPENW, lun, ’myfile.dat’, /GET_LUN PRINTF,lun, mydat CLOSE, lun 8.3 Binary files Binary files are read and written in the same manner as ASCII files but the read/write statements are changed to READU / WRITEU . OPENR,lun, ’binary.dat’, /GET_LUN, /F77_UNFORMATTED READU, lun, data CLOSE, lun Other file opening switches that you might find useful are: /SWAP_ENDIAN /SWAP_IF_LITTLE_ENDIAN /CLOBBER /NOCLOBBER Sun SPARC computers are big endian. Linux PCs are little endian. 8.4 Met Office PP files Met Office PP files are in binary format but we won’t cover them here, as there is an extensive PP file IDL library available already. The guide to these routines, written by Jonathan Gregory, is available at: http://ncas-cms.nerc.ac.uk Under visualisation on the left hand side click on Guide to the Met Office PV-WAVE/IDL library. Jonathan’s guide is only available to people who have signed a Met Office collaboration agreement. Please contact j.m.gregory@reading.ac.uk if you wish to use this software on Met Office model output.

9. Writing out netCDF data In this example data from the gdata.nc file is read in and regrided to the ERA-40 grid. This is then written out to a netCDF file. PRO ncwex ;Program to show the writing out of data in netCDF format d=NCREAD('gdata.nc') e=NCREAD('climatology_t.nc') ;Regrid data to ERA40 grid. tnew=REGRID(d.temp(*,*,0), d.lon, d.lat, e.lon, e.lat) ;Open the netCDF file. fid=NCDF_CREATE('era_new.nc', /CLOBBER) ;Define the dimensions and attributes. lonid=NCDF_DIMDEF(fid, 'longitude', N_ELEMENTS(e.lon)) latid=NCDF_DIMDEF(fid, 'latitude',N_ELEMENTS(e.lat)) tempvid=NCDF_VARDEF(fid, 'temperature', [lonid,latid ], /FLOAT) lonvid=NCDF_VARDEF(fid, 'longitude', [lonid], /FLOAT )

130

latvid=NCDF_VARDEF(fid, 'latitude', [latid], /FLOAT) NCDF_ATTPUT, fid, tempvid, 'units', 'Degrees Celsius' ;Finish define mode. NCDF_CONTROL, fid, /ENDEF ;Write out the data and close the netCDF file. NCDF_VARPUT, fid, lonvid, e.lon NCDF_VARPUT, fid, latvid, e.lat NCDF_VARPUT, fid, tempvid, tnew NCDF_CLOSE, fid END

10. Manipulating data Typing: ncdump –c file.nc on the UNIX command-line will print off the header and coordinate information for the netCDF file. You will be able to see the names, dimensions and units of data variables within your netCDF file. If you want to see the full contents then type: ncdump file.nc > myoutput xconv is a point and click data converter that you may find useful: http://ncas-cms.nerc.ac.uk/~jeff/xconv/index.html

Some excellent netCDF tools are found in the NCO (netCDF Operators) suite of programs: http://nco.sourceforge.net

11. Importing figures into documents The best way to do this in Word or Powerpoint is to produce a postscript file and then to use the UNIX command convert to produce a PNG image file. If you use a good resolution (say 400 dots per inch) then the image is virtually indistinguishable from an incorporated postscript file. All the plots in this guide are PNG files at 400 dots per inch. convert –density 400 –rotate -90 –trim idl.ps idl.png The –trim option cuts all the white space around the plot out making it easier to include in Powerpoint etc. You’ll need to include the –rotate -90 option for landscape postscript files produced by this guide. Encapsulated postscript files won’t load directly into PowerPoint and can cause screen refresh problems in Word if they are very complicated. If you use LaTeX then converting your postscript file into a PDF with ps2pdf produces good quality pictures.

12. Formatting text Text formatting is available in IDL to make up various characters that you might use in your plots i.e. superscripts - 12oC, subscripts – CO2, ñ as in El Niño. The following text operators are those you will probably use: !E – superscript mode. !I – subscript mode. !N – Return to normal mode. !X – return to the entry font. !! – display the ! symbol. !C – Begin a new line of text.

131

Further information is available in the fonts chapter in the IDL reference manual. Superscripts and subscripts are straightforward to use: mydeg="!Eo!N" myco2=”CO!I2!N” Unless you are labelling axes etc. you might find it easier to add unusual characters in the word processing package you are using for the final document.

13. Interpolation A simple re-gridding technique is to use bilinear interpolation. This technique is described in more detail on Wikipedia at http://en.wikipedia.org/wiki/Bilinear_interpolation. A longitude-latitude re-gridding function is provided with this guide and is called REGRID . The calling parameters for this program are: fieldout=REGRID(fieldin, longs_orig, lats_orig, longs_new, lats_new) fieldin is the original grid on the grid spacing longs_orig, lats_orig. fieldout is the output grid on the grid spacing longs_new, lats_new. longs_new and lats_new can be single or multi-value so you can get the value(s) at a point or on a new grid.

14. Animation A series of PNG files can be turned into an animated GIF with the ImageMagick convert command. convert –loop 10 –delay 10 *.png movie.gif The –loop 10 parameter will loop the movie ten times. The –delay 10 parameter will set a pause interval between each frame. Animated GIFs can be displayed in both Firefox and Internet Explorer. 14.2 Making a Quicktime or AVI movie AVI files can be played within PowerPoint or externally using RealPlayer / Quicktime and so are convenient when you are giving talks. You’ll need a full licensed version of QuickTime to save Quicktime / AVI movies. I have a copy on a PC if you are a local user and wish to make a movie by this method.

15. Running IDL in UNIX batch mode IDL can easily be run in UNIX batch mode so that scripts can run overnight or to plot data when it becomes available on a remote server. A simple script to download and plot some ozone data is available is shown below. #!/bin/sh PATH=/usr/bin:/bin:/opt/graphics/idl/idl/bin:/opt/local /bin:/opt/tools/bin:/opt/graphics/bin IDL_PATH=/opt/graphics/idl/idl_6.0/lib export PATH export IDL_PATH #Use ftp as below for ftp sites. #Use wget to get data from web servers. ftp -invd << EOF open toms.gsfc.nasa.gov user anonymous xxxx cd pub/eptoms/data/monthly_averages/ozone get L3_ozavg_ept_199911.txt quit EOF

132

idl << EOF .compile ozone ozone, 'L3_ozavg_ept_199911.txt' exit EOF The values of the PATH and IDL_PATH variables should be copied from your setup and inserted to the above code. You can set a script such as this to run each evening using a crontab entry - type man crontab for more details. You can also use at to run the script just once at a time when the computers are less used – type man at for more details.

16. Calling external objects IDL allows the integration of externally compiled code into your IDL programs. Here a simple example is given of an IDL program calling a Fortran compiled shared object which multiplies two numbers together. The result is then passed back to IDL and the result is printed on the screen. Use the following to locally setup the Fortran compiler and make the shared object. setup studio12 gex cp ext.f ext.pro ~ cd f90 -G -pic -c ext.f f90 -G ext.o -o ext.so Now we have made a shared object called ext.so we can call it from IDL using the supplied gex program. Care is needed to correctly match the data sizes in IDL and Fortran. This is a very simple example to help you understand the basics of calling external objects. Detailed notes are available in the IDL External Development Guide manual. Type ? at the IDL prompt and click on contents and then on Programmer’s Guides.

17. Passing parameters to programs When writing your own programs you will probably need to pass parameters to another program. The program ptest.pro shows show to do this. PRO PTEST, XVALS=xvals ;Program to show parameter passing. IF (N_ELEMENTS(xvals) GT 0) THEN BEGIN PRINT, 'XVALS are ', xvals HELP, XVALS ENDIF IF (N_ELEMENTS(xvals) EQ 0) THEN PRINT, 'XVALS are unset' END Several calls to ptest show how this program deals with the input data: ptest XVALS are unset ptest, xvals=34.

133

XVALS are 34.0000 XVALS FLOAT = 34.0000 ptest, xvals='testing' XVALS are testing XVALS STRING = 'testing' ptest, xvals=[2, 4] XVALS are 2 4 XVALS INT = Array[2]

If you modify the value of xvals inside ptest then the value is passed back into the calling procedure.

18. Writing style A simple program style is advisable for clarity and ease of later modification. The style adopted in the code for the library and examples is: 1) Use uppercase for IDL commands and reserved keywords. 2) Include a comment block at the top of your program describing the program function. Comment sections to allow easy understanding of the major program functions. 3) Add spacing to allow easy reading and indentation so loops are easily picked out. Appendix A of Kenneth Bowman’s ‘An Introduction to programming with IDL’ is a good style guide and well worth a read. As an example, the following: ;Crop decimal places if required IF (N_ELEMENTS(ndecs) NE 0) THEN BEGIN fmt='(f0.'+SCROP(ndecs)+')' levs=STRING(levs, FORMAT=fmt) ENDIF is easier to read than: if (n_elements(ndecs) ne 0) then begin fmt='(f0.'+scrop(ndecs)+')' levs=string(levs, format=fmt) endif When your command wraps over to the next line then good indetation also helps when reading the code. AXES, XSTEP=30, XTITLE='Degrees', YTITLE='Amplitude', YSTEP=0.25, NDECS=2 GPLOT, X=xpts, Y=ypts, /LEGEND, LEGPOS=3, COL=[3, 18], $ LABELS=['Sine', 'Cosine'] PSCLOSE is easier to read than: AXES, XSTEP=30, XTITLE='Degrees', YTITLE='Amplitude', YSTEP=0.25, NDECS=2 GPLOT, X=xpts, Y=ypts, /LEGEND, LEGPOS=3, COL=[3, 18], $ LABELS=['Sine', 'Cosine'] PSCLOSE