How to read help pages
When reading help pages for functions and procedures, read carefully the "Calling Sequence", the descriptions of each of the required "Input parameters", the descriptions of the "output parameters", the descriptions of the "optional keyword parameters", and the "Examples". The calling sequences give the EXACT calling sequence you need to follow. The Examples give ONE way to implement the calling sequence that may be directly helpful to you. But think about what the example is doing relative to what you want to do, and evaluate whether that is the implementation that would make sense for you.

In the Calling Sequence, optional parameters are denoted between the square brackets []. When using optional parameters, you don't actually put them between [], as illustrated below.

It is critical to input different pieces of information in the exact order that the calling sequence puts forth. That said, you can call a variable anything you want. For example, when calling the glactc procedure in IDL you can say

IDL> glactc,peanuts,crackerjack,year,ell,bee,j,/degree

but peanuts and crackerjack must contain the values for (or receive the output of the values for) RA and Dec.

Running Procedures and Functions: Inline vs. within a program
IDL'ing inline (i.e. writing commands right at the IDL> prompt) is a fast and handy way to use IDL for calculations, or to run procedures in functions. This convenience must be balanced with the fact that writing programs to perform your calculations and make your figures will keep track of your work and make it FAR easier to debug and to perform repeated analagous analyses. In the long term, writing programs will be essential so it is good to get into the habit now. The only different between doing inline and writing a program is that your program begins with "pro mypro" and ends with "end" and must be compiled.

When you run a procedure for the first time, either within a program you write yourself or at the IDL prompt, you may see things like:

% Compiled module: GLACTC.
% Compiled module: BPRECESS.

This is just because, like the programs you will write, many procedures you use will rely on other functions and procedures. The first time you run a function or procedure, it will (try to) compile all functions and procedures that it is dependent on.

Bits of Syntax and Math

1. To add comments into your code (notes to yourself that the computer doesn't try to execute), begin a line with a ";".

2. When you run a procedure, you can either directly pass it numbers or pass it variables that you have defined to be particular numbers or arrays of numbers (or strings or arrays of strings, as the case may be). Unlike most common programming languages, you do not need to initialize variables before they appear. The following examples illustrate these points (note that ell and bee are never defined before calling the glactc procedure).

IDL> glactc, 22.5, 65., 2000, ell, bee, 1
% Compiled module: GLACTC.
% Compiled module: BPRECESS.
IDL> print, ell, bee
108.69271 6.1147575
IDL> ra = 22.5
IDL> dec = 65.
IDL> year = 2000
IDL> j = 1
IDL> glactc, ra, dec, year, ell, bee, j
IDL> print, ell, bee
108.69271 6.1147575

In the above example, the procedure glactc has returned ell and bee as double precision scalar numbers. You can find out how a variable has been defined with the help procedure:

IDL> help, ell
ELL DOUBLE = 108.69271
IDL> help, bee
BEE DOUBLE = 6.1147575

If you pass a procedure/function an array of values rather than inputting a scalar in the first place, then it will often return an array of answers. If you ask IDL to print out two entire arrays, it will first print out all of one array and then print out all of the other array. You can instead loop through each elements of a set of arrays and print out each set explicitly. In the below example, the Galactic longitude and latitude for each ra,dec combination are printed out in the FOR loop:

IDL> ra = [12.3,9.6,0.5]
IDL> dec = [158.2,76.4,250.0]
IDL> glactc, ra, dec, year, ell, bee, j
IDL> print, ell, bee
112.72078 135.49728 301.08665
-40.407741 35.512697 -7.2050733
IDL> FOR j = 0, n_elements(ra)-1 do print, ell[j], bee[j]
112.72078 -40.407741
135.49728 35.512697
301.08665 -7.2050733

3. Basic math uses typical logical operators and order of operations rules: +, -, *, /, and ^. See Operators on Page 1 of the IDL HandyGuide, Boolean and Relational Operators on Page 2 of the IDL Guide, and Transcendental Functions on Page 8 of the IDL Guide to see lists of typical operators and, well, transcendental functions. Know that the trig function inputs must be in radians. The correct syntax to call a function is straightforward:

a = alog10(50.)

Making Figures

1. Plotting a Line: The IDL help page for the "plot" procedure is a bottomless pit of helpful information. The back side of the first page of the IDL HandiGuide packet also contains a key to the linestyles and the plotsym shapes. (Note that this backside of the first page is "Page 12".) When plotting lines, you should NOT set a plotsym but should instead set a linestyle and a thick (ness) of the line. Remember that $ continues a line of code onto the next line, so there is one 4-line-long plot statement in the below example.:

plot, a, b, xrange = [-0.5,2.0], linestyle = 0, $
thick = 2., yrange = [14,-5], $
title = 'My first line', xstyle = 1, ystyle = 1, $
xtitle = 'a', ytitle = 'b'

To plot something on top of a figure you've already drawn, use the "oplot" procedure. This stands for overplot. When overplotting, you don't redefine or label the axes. You just tell IDL what you want it to plot, and what line/symbol you would like it to use. You can overplot lines on top of points, or vice versa, as well as on top of much fancier things (contour plots, true images). A simple example:

oplot, c, d, psym = 8, symsi = 1.25

2. Overplotting data with FOR loops: It can be a good idea to use FOR loops when making figures where many things will be overplotted (or when making many identical figures). When you are looping through N sets of identical data (such as a bunch of isochrones of 1 age but different [Fe/H]), you want to PLOT the first set and OPLOT the 2-N sets. Moreover, you often want to use a different plotting symbol or line for each different set of data that you are plotting, so that you can distinguish them in the final product. There are a few ways to tell IDL that you want to do this. Here is an example based on the IF conditional that tells IDL to use a different line thickness for each dataset. Successive datasets are plotted with increasingly thicker lines.

FOR j = 0, n_elements(filelist)-1 do begin
readcol, filelist[j], a, b
IF j eq 0 then plot, a, b, xrange = [-0.5,2.0], linestyle = 0, $
thick = j*1.0+1.0, yrange = [14,-5], $
title = 'My Data', xstyle = 1, ystyle = 1, $
xtitle = 'a', ytitle = 'b'
IF j ne 0 then oplot, a, b, linestyle = 0, thick = j*1.0 + 1.0

3. Adding a legend to your figure: This is another cat to skin in many possible ways. I like to draw brute force figure labels and legends with the xyouts procedure. Another option is the procedure legend. Read the IDL documentation for this, but I give the basics here.

legend first takes as input the set of strings that you want to use in your legend. Remember that strings need to be surrounded by quote marks.

Say you are plotting 5 isochrones that have [Fe/H] = -2 and Age = 5,8,10,12, and 14 Gyr. You may want your plot figure to be titled "[Fe/H] = -2.0" and your legend to include:

modelnames = ["5 Gyr", "8 Gyr", "10 Gyr", "12 Gyr", "14 Gyr"]

legend also needs you to input what symbol you would like to associate with each of those strings. If you made a figure with individual symbols, then you would define "psym", just like you did in "plot". If you used lines, then you need to instead specify the linestyle and thickness. If you used the same linestyle = 0 to draw each isochrone and a thickness that varied with each line, as in the example above, you could define:

line_array = [0,0,0,0,0]
thickarr = FLTARR(n_elements(modelnames))
FOR j = 0, n_elements(modelnames) - 1 do thickarr[j] = j*1.0 + 1.0
legend, modelnames, linestyle = line_array, thick = thickarr

Note two new things in the above example. First, you have used the function fltarr to define an empty array of floating point precision numbers that will contain the values of line thickness. Although you don't need to pre-define scalars in IDL or pre-define arrays in many situations, you do need to pre-define arrays if you are going to be depositing numbers into them one at a time. Second, this FOR loop has a "do" instead of a "do begin" and does not end with an "ENDFOR". If you are executing a single command in a for loop, then you can use this shorthand syntax. You could also use the other syntax if you prefer.

Last modified: Thu Sep 11 13:30:24 EDT 2008