procspec commands

procspec is a suite of IDL routines which replicate some of the functionality of the classic dipso, including a stack mechanism. The routines can be used on their own, or as part of other IDL programs, as required.


Update history


Installation & use

Mac laptops

To install procspec on your Mac, you will need to download some tar files and install them on your system. These are available within ARC from the installers AppleShare..

If you're expecting to need to read IRAF files then you'll also need to install the IDL Astronomy Users Library for the mrdfits routine.

I will assume that you do not already have IDL paths set up aside from the defaults - if you do, then you should adapt the instructions below accordingly, taking note of the precendence below in the IDL paths; IDL has a (useless) built-in function called pm and unless the IDL_PATH is set as below it will be called instead of the procspec routine.

To start using procspec, start IDL in the usual manner (typically typing idl at a command shell) and then type procspec to set up the procspec environment. You can then use any of the procspec commands detailed below, as well as any other IDL code, in the usual manner. Note that if you want to use the loaddipso command, you must have run the Starlink convert script before starting IDL.

The concepts involved in using these routines are similar to those from DIPSO, with a stack to push and pop data from, current arrays to hold the 'working' data, etc. However the routines are all IDL, coded from scratch, and do not do everything exactly the same way that DIPSO does - this may be because it was too hard to code, or else the DIPSO way didn't suit the way that I usually worked. For someone transitioning from DIPSO to procspec, the following are likely to be the most common issues:

On the positive side, since all these routines are just plain IDL, they can easily be combined with other IDL code to do pretty much anything you want, generally with not much coding. And since most of the routines can return anything they print up on screen as IDL variables, you can include appropriate logic, etc, in any IDL program which calls the procspec routines. And, obviously, it's easy to write you own IDL programs that tie into procspec to extend it however you want.


Purposely omitted features

A number of features from DIPSO are not replicated by procspec, either due to the difficulty in implementing them, or because it was pointless to replace equivalent native IDL functions. Some examples include:


Third party routines

A number of third party IDL routines were used in writing procspec:

The alasrd_iraf routine requires the installation of the IDL Astronomy Users Library for the mrdfits routine and its dependencies.


Routines listed by type


Initialising

procspec [, /clearstack]

Initialises the COMMON blocks, including the stack. Must be called before any other procspec routine.

clearstack - this keyword is used to quickly clear the stack by reinitialising it rather than deleting all entries, and should not in general be employed by end users.

Reserved variable names - procspec sets up a number of global variables in a COMMON block which are essential for the routines to function. It is therefore critical that you do not use these variable names in your own routines, since that would overwrite the global values and undoubtedly cause crashes and loss of data. The reserved variables are:

 


Input/Output

loadstack, name [, /replace, opstatus=opstatus, /quiet]

Loads a previously saved stack. Stacks are written as binary unformatted files with little-endian format (on big-endian systems IDL will map the data on the fly, which has a performance impact). The data is loaded to a temporary stack before the data is pushed to the main stack. If there is an error while reading the data in then an error status code is returned in opstatus.

name - a string which points to the stack file. These have a default suffic of .pstk which is automatically added if not specified.

replace - if this keyword is set the routine erases the current stack before leading in the file. The over-write is only done when all the new data has been copied to the temporary stack, so if things go wrong reading the new new data the extant stack is not deleted.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
loadstack, "/home/rsir/stacks/bstars/phl346.pstk"

 

savestack, name [, opstatus=opstatus, /quiet]

Saves the current stack to disk. Stacks are written as binary unformatted files in little-endian format.

name - a string containing the intended name of the stack file. These have a default suffix of .pstk which is added automatically if not specified. If the filename is not specified then the default name of save.pstk is used.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
savestack, "/home/rsir/stacks/bstars/pg0832.stack"

 

alasrd, filename [, rows=rows, cols=cols, nametrim=nametrim, opstatus=opstatus, /quiet]

Loads two column x/y pairs from an ASCII file - the user may specify arbitrary columns to be x and y, and may also choose only to extract certain rows from the file as well. Gzipped files can be accessed directly without bring decompressed beforehand. The data in the file is expected to be monotonically increasing in x value, and non-degenerate. If these conditions are not met the code will sort and remove duplicate x-axis values, which may not be the right thing to do.

filename - the name of the file to be read. Files with a .gz extension are assumed to be gzipped.

rows - optionally set this variable to an array of two integers indicating which columns are to be extracted from the file. If not specified the code defaults to reading in columns 1 and 2 as x/y respectively.

cols - optionally set this variable to an array of two integers to restrict the number of lines read in from the file. The first integer specifies the first line to be read (starting at 1) and the second specifies the last line to be read. To read all the way to the end of the file after skipping lines at the start set the second integer to 0.

nametrim - the stack titles of files read using alasrd are set to the name of the file, but titles have a limit of 60 characters, and full file paths are often longer. This parameter controls how the filename is truncated to make the title:

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
alasrd, "/home/rsir/tlusty/model_300_400.txt" - read all of a simple 2 column text file
alasrd, "/home/rsir/tlusty/model_300_400.txt", rows=[10,100], cols=[4,2] - read lines 10-100 of the file, taking column 4 as x and column 2 as y
alasrd, "/home/rsir/tlusty/model_300_400.txt", rows=[10,0], cols=[1,3] - read all the data in the file from line 10 onwards (eg. skipping header information), taking column 1 as x and column 3 as y

 

alasrd_lots, filter [, /quiet, opstatus=opstatus , other_alasrd_switches]

Reads multiple ASCII files into procspec and pushes them to the stack. The files are specifed via a standard shell filter which can contain the usual wildcards (*,?, []). All options available in alasrd are available (ie. cols, rows, nametrim).

filter - the specification for the list of files to read in, in standard shell format. This is a string and must therefore be in quotes. If the number of files matching the filter exceeds the number of spaces on the stack the routine will abort.

p>opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
alasrd_lots, "/home/model/TLUSTY/GAL/VT*/gal_000.200_400.*", rows=[1,1000], nametrim=1 - load the first 1000 lines of all TLUSTY galactic base abundance models at 20000/4.0 for all VT, trimming the filenames so that the start of the path is discarded if necessary.

 

alasrd_iraf, filename [, /quiet, opstatus=opstatus]

Reads an IRAF 2D spectrum from a FITS file. The name alasrd_iraf is chosen for its conceptual likeness to alasrd though the routine does not offer the full flexibility of that command.

IRAF 2D spectra are held as a 1D list of y-values, with the x data held in the FITS header as the first x value and then linear offset for each subsequent pixel - the code reconstructs the x axis from this data. The results are pretty much the same as would be obtained using listpix within IRAF, though one can see miniscule rounding errors in some cases.

filename - the name of the FITS file to read in.

p>opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
alasrd_iraf, "/Users/rsir/Desktop/my_iraf_file.fits"

 

alaswr, filename [, /header, opstatus=opstatus, /quiet]

Writes the contents of the current arrays to a two column ASCII file. If the filename ends in .gz then the file is written in gzip-compressed format.

filename - the name of the file to be written. Filenames with a .gz extension are automatically gzipped.

header - set this keyword to have the stack title written to the first line of the file.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

alaswr_lots, stacklist, suffix [, /all, /compress, /range, /header, opstatus=opstatus, /quiet]

Writes multiple stack entries out to ASCII files using alaswr. Header information and compression are optional, and a filename suffix may be specified. Files are written with names such as mydata.001.dat.gz, mydata.002.dat.gz....

stacklist - an array containing the list of stack entries which are to be written to file.

suffix - a string which gives the start of the filename to write each stack entry to.

all - set this keyword to write out all stack entries - the stacklist does not have to be specified (and is ignored) in this case.

compress - set this keyword to enable gzip compression on all files. All filenames will end in .gz if this is selected.

range - if this keyword is set then the contents of stacklist are treated as start and end limits on a range of entries to be written out. stacklist must contain only two entries if this option is selected.

header - set this keyword to have the stack title written to the first line of the ASCII file.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

loaddipso, filename [, opstatus=opstatus, /quiet]

Load a DIPSO stack onto the PROCSPEC stack. Not all DIPSO information is imported - only x/y pairs and stack entry titles - the more advanced HDF features are discarded. Note that this routine depends on the Starlink CONVERT package, and if CONVERT has not been run before IDL the routine will not be available.

filename - the name of the file to load. The routine will attempt to format the filename correctly for CONVERT, which requires the training .sdf to be removed from the filename, but the _STK to remain. If the user supplies any of filename, filename_STK, or filename_STK.sdf the routine will reformat it correctly. The former is probably the best standard to adopt, being the same as used in DIPSO itself.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 


Stack management

pop, number [, opstatus=opstatus, /quiet]

pop copies a stack entry to the 'current' data item.

number - the number of the stack entry to pop. Stack entries are numbered starting at 1.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
pop, 10

 

push [, item=item, stackpos=stackpos, opstatus=opstatus, /quiet]

push adds the current item to the end of the present stack.

item - a correctly formatted IDL structure, ready to add to the stack. This parameter is only intended for use by the loadstack routine, not end users.

stackpos - if set, this variable contains the number of the stack entry which the item was pushed to.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
push

 

retitle, position, titlestring [, /prefix, /suffix, opstatus=opstatus, /quiet]

retitle lets you change the title string of an entry on the stack.

position - the number of the entry on the stack to retitle.

titlestring - the string you want the title set to.

prefix - set this keyword to add the string to the start of the current title, ie. prefix it.

suffix - set this keyword to add the string to the end of the current title, ie. suffix it.

With both prefix and suffix options the code will not check if the requested change will make the title longer than the maximum 60 characters allowed - it will simply make the change and if this causes the title to 'overflow' and be truncated no error message will be displayed.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
retitle, 11, "My Lovely Horse"

 

title, titlestring [, /prefix, /suffix, opstatus=opstatus, /quiet]

title sets the title string for the current item.

titlestring - the string you want the title set to.

opstatus - an integer optionally returned with a status code which is:

prefix - set this keyword to add the string to the start of the current title, ie. prefix it.

suffix - set this keyword to add the string to the end of the current title, ie. suffix it.

With both prefix and suffix options the code will not check if the requested change will make the title longer than the maximum 60 characters allowed - it will simply make the change and if this causes the title to 'overflow' and be truncated no error message will be displayed.

quiet - set this keyword to suppress all message display.

Example:
title, "My brilliant result"

 

sl [, first, last]

lists the current stack

first - optionally set this parameter to the first stack entry to be listed. The default is 1.

last - optionally set this parameter to the last stack entry to be listed. The default is to list all entries. last can only be set when first is used.

Example:
sl, 10, 20 - list stack elements 10-20 inclusive

 

del, del_list [, range=range, /all, opstatus=opstatus, /quiet]

Delete items from the stack.

del_list - an array of integers, or a single integer (which does not have to specified as an array), representing the numbers of the stack entries to be deleted.

range - set this keyword to delete all stack entries between two specified values. In this case only two values must be passed in del_list.

all - this keyword causes the stack to be cleared and reinitialised. In this case del_range does not need to be specified.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
del, 10 - delete item 10
del, [11,15], /range - delete items 11-15 inclusive
del, [1,3,6,8,11] - delete items 1,3,6,8, and 11
del, /all - delete all items on the stack

 

extract, number, thevariable [, thetitle=thetitle, opstatus=opstatus, /quiet]

This routine extracts the contents of a stack entry to a named IDL variable.

number - the index of the stack entry to be extracted. The 'current' data item may be selected by specifying the stack number as 0.

thevariable - an IDL variable which will become a 2d array of the x,y pairs which made up the stack entry.

thetitle - specify this variable name to copy the title string of the stack entry.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
extract, 11, my_variable, thetitle=titlestring

 

makecurrent, xarr, yarr, title [, opstatus=opstatus, /quiet]

This routine imports a specified pair of x and y values, plus a title string, to the current data item. It can then be pushed, processed, etc. as usual.

xarr, yarr - the x and y arrays to be imported. They should - obviously - have the same number of elements.

title - the title string for the data, which can be up to 60 characters. Longer strings are truncated.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
makecurrent, my_xvals, my_yvals, "This is my data"

 

checkstackbounds(n [, /zerook])

This function is used to determine if a given stack entry, n, exists.

zerook - set this flag to permit the 'zeroth' element to be flagged as genuine - in some cases it does exist, as the 'current' item.

There are no quiet or opstatus flags. The routine returns 0 if the item can exist, 1 if it can't, and 3 if there was a problem with the input parameters.

Example:
test = checkstackbounds(11)

 

range(startpoint, endpoint)

This function generates a list of integers between startpoint and endpoint and returns them as an array. This is useful when dealing with a continuous range of spectra in a stack.

startpoint, endpoint - integers representing the first and last stack entries of interest. These are assumed to be integers ≥0.

There are no quiet or opstatus flags. The routine returns an array consisting of one entry, value -1, if there were any problems.

Example:
pm, range(10,15)

 

matchstackbyname, string, matches [, quiet=quiet]

This procedure returns an array in a named variable listing all stack entries whose title contains the specified string. You can then pass this to other routines. This is done as a procedure instead of a function since if there are no matches you'll need to alter your logic rather than plow ahead.

string - the (sub) string which is to be matched.

matches - a named variable which will hold the list of matches. This is either an array of integers, or a single item array containing [-1] if there are no matches.

quiet - set this keyword to suppress all message display.

There is no opstatus variable - the routine returns [-1] in all error conditions.

Example:
matchstackbyname, 'HD93521', hd93521list

 


Data processing

aadd, entry [, opstatus=opstatus, /quiet]

Add the current stack entry to the specified stack entry, leaving the result in the current arrays.The current entry is remapped to the X axis values of the stack entry before the operation. Only areas that overlap are included in the calculation.

entry - the number of the stack item which is to be added to.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

addnoise, snr [, seed=seed, /quiet, opstatus=opstaus]

Add gaussian pseudo-random noise to the current stack entry.

snr - the desired signal-to-noise ratio for the data.

seed - the seed value for the random number generator (RNG). If this is set to a fixed value the RNG will produce the same noise pattern each time, which may be useful for debugging purposes. If set to a named variable the seed used in the routine is returned, and can then be passed back into the next call of the procedure, which will allow for a reproducable sequence from the RNG.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
addnoise, 100 - degrade the current data to an SNR of 100
addnoise, 100, seed=myseedvalue - degrade the current data to an SNR of 100, keeping the RNG seed in the variable myseedvalue

 

adiv, entry [, opstatus=opstatus, /quiet]

Divide the current stack entry into the specified stack element, leaving the result as the new current entry. The current entry is remapped to the X axis values of the stack entry before the division. Only areas that overlap will be included in the calculation.

entry - the number of the stack item which is to be divided into.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
adiv, 11

 

asub, entry [, opstatus=opstatus, /quiet]

Subtract the current stack entry from the specified stack entry, leaving the result in the current arrays.The current entry is remapped to the X axis values of the stack entry before the operation. Only areas that overlap are included in the calculation.

entry - the number of the stack item which is to be subtracted from.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

broaden, gaussian=gaussian, vsini=vsini [, opstatus=opstatus, /quiet]

Apply gaussian and/or rotational broadening to the current stack item. The x axis of the data to be convolved must have a uniform spacing, and may need to be padded with artifical continuum if applying a large broadening.

Note that the width of the gaussian is specified as a FWHM for consistency with alf, etc. This is not the same as the widths used in, for example, the Dufton et al. paper on macroturbulence and vsini, which was instead a 1/e width. Those values should be scaled by a factor of 1.66 when comparing with these results.

gaussian - set this to the desired gaussian width in km/s. If you don't want to apply a gaussian, don't set this keyword.

vsini - set this to the desired vsini function width in km/s. If you don't want to apply a rotational broadening profile, don't set this keyword.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
broaden, gaussian=100 - apply a Gaussian of 100 km/s
broaden, vsini=150 - apply a v sin i of 150 km/s
broaden, gaussian=100, vsini=150 - apply both

 

chitest, stackno [, stats=stats, /quiet, opstatus=opstatus]

Calculate the chi-square statistic comparing the contents of the curent stack entry to a numbered stack entry. The data in the current array is mapped to the x scale of the specified stack entry and the comparison is then performed on the two sets of y values.

stackno - the number of the stack entry to compare the current array to.

stats - set this to a named variable which will be set to a two element array containing the results of the IDL xsq_test function.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
chitest, 5, stats=mystats - perform a comparison against stack entry 5 and return the result in mystats.

 

ew [, ews=ews, limits=limits, /quiet]

ew performs a quick and dirty trapezoidal integration of the data in the current arrays between points selected with the mouse. The data is linearly renomalised between the y values selected, so caution must be used when selecting the integration points. Multiple features can be measured by continuing to click - double click the same point to exit.

ews - set this keyword to a named variable which will be returned with an array containing all measured equivalent widths.

limits - set this keyword to a named variable which will return a two dimensional array containing the start and end points of integration for each of the equivalent widths returned in ews.

quiet - set this keyword to suppress all message display.

 

fakespec, lambda, fwhm, ew, res [, opstatus=opstatus, /quiet]

Generate a normalised gaussian absorption line with the specified parameters, and place it into the 'current' item. The spectrum is generated over a range of ±5Å about the centroid.

lambda - the centroid of the gaussian, in Å.

fwhm - the FWHM of the gaussian, in Å.

ew - the equivalent width of the gaussian, in mÅ.

res - the resolution of the gaussian, in Å.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
fakespec, 4000, 0.2, 100, 0.02 - generate a Gaussian centred on 4000Å, ranging from 3995-4005Å, with FWHM 0.2Å, equivalent width of 100mÅ, at a resolution of 0.02Å/pixel.

 

findgauss, obs, model, grange [, bestfit=bestfit, opstatus=opstatus, /quiet]

This routine applies a series of Gaussian broadening functions to a model spectrum and then caculates the Chi-Square statistic to evaluate how well it fits a specified set of observed data. It is useful for determining the amount of macroturbulence in a stellar atmosphere, for example.

The 'model' spectrum should be normalised, uniformly gridded, and hve sufficient continuum at either side (typically 15Å) for the broaden routine to operate. In general, one will determine a vsini value using vsinifft; select an appropriate model atmosphere spectrum; trim out the relevant line and scale it to match the equivalent width of the observed data; use pad to extend the continuum and also regrid the data to a regular x interval. Only then will one use findgauss...

Note that as with broaden, the gaussian is specified in terms of FWHM, not the 1/e widths used in some previous macroturbulence work.

obs - the number of the stack entry which contains the observed spectrum.

model - the number of the stack entry containing the suitably prepared model spectrum.

grange - a three element array which defines the start, end, and step for the range of gaussian broadening to be applied, in the form [start, end, step].

bestfit - set this keyword to a named variable which will be returned containing the gaussian FWHM which provided the best fit between model and data.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
findgauss, 4, 5, [0,150,10], bestfit=thebest - apply gaussian broadening from 0-150 km/s in steps of 10 km/s to the model in stack entry 5, compare to the observed data in stack entry 4, and return the best fit gaussian FWHM in the variable thebest.

 

logx [, /exclude, opstatus=opstatus, /quiet]

Converts all the x values in the current arrays to log10(x). If any of the x values are less than or equal to zero these can be removed from the array to avoid numerical errors.

exclude - set this keyword to drop any x values ≤0 before taking the logs. If this keyword is not set then if there are any such values in the current x axes the operation will abort.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

logy [, /exclude, opstatus=opstatus, /quiet]

Converts all the y values in the current arrays to log10(y). If any of the y values are less than or equal to zero these can be removed from the array to avoid numerical errors.

exclude - set this keyword to drop any y values ≤0 before taking the logs. If this keyword is not set then if there are any such values in the current y axes the operation will abort.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

mapto, stackno [, opstatus=opstatus, quiet=quiet]

Map the contents of the current arrays to the x axis of stack entry stackno. The current arrays will be replaced by the x axis of stackno and the y values are linearly interpolated to this new set of x values.

stackno - the number of the stack entry to map on to.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 

merge, item1, item2 [, weight1, weight2, /incommon, opstatus=opstatus, /quiet]

Merge two stack entries, optionally weighting them differently, and putting the merged item into the 'current' stack entry.

item1 - number of the first stack entry to merge. The first entry will be the dominant one - its x axis is used as the template for the merged dataset in areas were there is overlap. Outside those areas the data maintain their original x axis values.

item2 - number of the second stack entry to merge.

weight1, weight2 - optionally set these to the relative weights to apply to the two stack entries. If weight1 is set to a and weight2 to b then the data are averaged so that:
yfinal = (ay1 + by2)/(a+b)

incommon - set this keyword to only return the area where the two stack entries overlapped. The default is to average the overlap area, and add in the outlying data from both original stack entries.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
merge, 5, 6, 2, 1
merge, 5, 6, /incommon

 

multinorm, stacknos, fitorder, /noyscale, cmask=cmask, /savecmask, /pushfits, /quiet, opstatus=opstatus

Normalise multiple stack entries using low-order polynomials. The first spectrum is generally used as a template to define the continuum regions and select the polynomial order, and this is applied to all subsequent spectra. The continuum 'mask' may however be saved to the stack and used with subsequent analyses in the same wavelength space, ensuring consistency when processing large quantities of data. The filter option in pf is always enabled in multinorm to allow for severe cosmic ray problems.

stacknos - an array of integers specifying the stack entries to be normalised. The first listed entry is used as the template for continuum placement, so choose it carefully.

fitorder - an integer giving the initial fit order to apply. This can be adjusted when working on the first spectrum only and is applied to all other spectra automatically.

cmask - set this keyword equal to the value of a stack entry with containing a previously saved continuum mask.

savecmask - set this keyword to have the continuum mask pushed to the stack for subsequent use.

noyscale - by default the code will try to scale the y axes when plotting data to avoid the usual scaling problems seen with large cosmic ray events. The code works out the 3 sigma limits on the data and will have a lower limit of either the minimum Y value or the lower 3 sigma, and an upper limit of either the maximum Y value or the upper 3 sigma. Mostly it does the right thing.

pushfits - set this keyword to push each polynomial fit to the stack. Possibly useful for debugging and QA.

quiet - set this keyword to suppress most message display.

opstatus - an integer optionally returned with a status code which is:

Example:
multinorm, [4,5,6,8,9,11], 3, /save - apply a 3rd order polynomial to the listed stack entries, saving the continuum mask
multinorm, range(14,23), 3, cmask=13 - as above, but using the continuum mask previous saved to stack entry 13

 

mmmerge, stacknos, [, sample, /noscale, /push, opstatus=opstatus, /quiet]

Merge multiple stack entries - assumed to have near-identical x axis values - using a median filter and put the merged item into the 'current' stack entry. Stack entries are rescaled to the same y scale as the first specified stack entry to make the median filter work. This can be turned off if dealing with previously normalised spectra. The region to use for the y-axis scaling is either defined by passing an array of x-axis limits or interactively using the mouse.

stacknos - an array containing a list of the numbers of the stack entries to merge. The first entry in the array is treated as the 'prime' spectrum and all others are mapped to its x axis values before the merge. That entry is also used to define the scaling area (if using scaling).

sample - optionally set this to an array of two numbers representing the start and end x-axis values to use for the scaling function.

noscale - set this keyword to turn off y-axis scaling - only do this with data which are of identical y scales or the result will not make sense.

push - set this keyword have the remapped/rescaled stack entries pushed to the stack for later comparison. The first stack entry, being the reference, is neither remapped or rescaled and so is not pushed again.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress most message display.

Example:
merge, [4,5,6,8,9,11] - simply merge these, selecting the scaling area interactively
merge, [4,5,6,9,11,13], sample=[4510, 4520], push - perform merge using the region 4510-4520Å to calibrate scaling. Push modified stack entries.

 

mpf, order, stacknos [, /usemask, /nofits, /extrap, /savemask, /quiet, opstatus=opstatus]

Normalise multiple spectra using low order polynomials. The continuum regions are defined using the first specified spectrum and then applied to each of the subsequent ones in turn. Normalised spectra are pushed to the stack. Polynomial fits and the continuum mask may also be saved on the stack for later analysis and (optional) re-use. The observed data and fits are plotted, and the normalised spectrum is overplotted for quick review.

stacknos - an array of integers representing the stack numbers to be normalised. The first entry is taken as the reference spectrum and the continuum mask is selected against it using the mouse.

usemask - set this keyword to an integer which is the stack number of a previously generated (and saved) mask. This mask will then be used instead of having to redefine the continuum region. This may be useful if you wish to try a different order of fit.

savemask - set this keyword to have the mask stored on the stack for later use. By default it is deleted unless a mask entry was specified using the usemask option.

nofits - set this keyword to stop the polynomial fits being stored on the stack for later analysis.

extrap - by default the code only fits and normalises within the range defined by the continuum region. Set this keyword to force the polynomial to be fitted against the entire x range of the observed data. This may be dangerous...

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
mpf, 3, [4,5,6,7,8], /save, /nofits - fit 3rd order polynomials to stack entries 4-8, using 4 as the template. The polynomial fits are not to be saved but the continuum mask is.
mpf, 4, [4,5,6,7,8], usemask=11, /nofits - fit 4th order polynomials to the same set of stack entries but use a continuum mask from stack entry 11 instead of selecting interactively.

 

msnr, stacknos [, snrs=snrs, /nowait, opstatus=opstatus, /quiet]

Peform SNR measurements on multiple stack entries by running the snr command on the same region in each. The region to use is defined interactively by clicking on the first specified spectrum. Double-click on the same point to exit without fitting.

stacknos - an array of integers representing the stack numbers to be evaulated. The first entry is taken as the prime spectrum and used to interactively define the continuum region of interest.

snrs - set this keyword to a named variable which will be returned with the list of measured SNRs. Note that a value of -1 will be returned if sigma=0, as might happen with a model spectrum.

nowait - by default the code will wait a second between displaying each continuum fit - set this keyword to proceed immediately to the next spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
mnsr, [5,6,7,8,9,10], snrs=mysnrs - calculate SNRs for stack entries 5-10 and return the SNRs in an array 'mysnrs'.

 

pad, startpad, endpad [, /quiet, opstatus=opstatus]

Add false continuum to the current spectrum - startpad Å to the beginning and endpad Å to the end. The y values are set to 1.0, and the data is regridded to match the average resolution of the old data - if this is irregular it may be best to regrid it first.

This routine is useful when applying a large broadening to a model spectrum with limited continuum - if there are insufficient continuum points the the convolution function can suffer from edge effects.

startpad - the number of Angstroms of padding to add to the start of the current data.

endpad - the number of Angstroms of padding to add to the end of the current data.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

 

pf, order [, /noiter, fitparams=fitparams, thechi=thechi, yrange=yrange, maskused=maskused, usemask=usemask, /filter, /quiet, /old, opstatus=opstatus]

Perform a polynomial fit to the data in the 'current' arrays. The data in the current arrays are displayed and the user prompted to select the 'continuum' areas which are to be fitted. A fit is then performed and displayed, and the user may iterate various degrees of polynomial to obtain a more pleasing fit.

As of April 2013 this routine was changed to use MPFIT as the underlying fitting engine instead of IDL's POLY_FIT as POLY_FIT could produce nonsense at times. The POLY_FIT routines can be forced using the /old switch. The chi-square statistic produced using MPFIT differs from that returned by POLY_FIT so those will change!

order - the order of the polynomial fit.

noiter - don't offer the option to try polynomials of different order to that initially specified.

fitparams - set this keyword to a named variable which will return the array of fit coefficients [a0,a1,a2,a3 etc] where y = a0 + a1.x + a2.x2 + a3.x3 ....

maskused - set this keyword to a named variable which will return an array containing the continuum mask used. This can then be passed to subsequent runs of pf using the usemask option.

usemask - set this keyword to the name of a variable previously returned by the maskused option to use the same continuum regions. The regions are mapped to the current x-axis values so will not be exactly the same unless the spectra being fitted have the same x-axis values, but should be close enough for most purposes. If this is a significant concern then regrid the spectra to the same axis values before calling pf.

yrange - this keyword is used by the multinorm program only. Not for general users! It lets the code which shows points excluded due to filtering be smart when using a zoomed-in plot window.

filter - set this keyword to perform some simple filtering on the continuum region. After an initial polynomial fit is applied any points which lie over 3 sigma from the fit will be excluded, and the remaining points used for fitting. This is useful when sharing a mask between several spectra which suffer from significant cosmic ray contamination - most cosmics will be excluded from the fit.

thechi - set this keyword to a named variable which will return the chi-square goodness-of-fit parameter.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress most message display.

old - set this keyword to force use of the IDL POLY_FIT routine instead of MPFIT. You almost certainly don't want to do this.

Example:
pf, 3, /noiter - display the current spectrum, select points, and fit a 3rd order polynomial without iterating.

 

psfft [, /real, /imaginary, /quiet, opstatus=opstatus]

Perform an FFT on the contents of the current stack entry. The x axis must be uniformly spaced or the routine will abort.

real - set this keyword to make the routine return only the real component of the FFT. The default is to return the absolute values of the FFT.

imaginary - set this keyword to make the routine return only the imaginary component of the FFT. The default is to return the absolute values of the FFT.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress most message display.

Example:
psfft, /real
psfft,

 

regrid, resolution [, /quiet, /quad, /lsq, /spl, opstatus=opstatus]

Regrid the contents of the 'current' array to the specified x-resolution. The regridded data replaces the contents of the 'current' arrays. The routine defaults to linear interpolation, but the three other interpolation algorithms used by the IDL INTERPOL routine are available - spline, quadratic, and least-squares quadratic.

resolution - the desired x-axis resolution.

quad - set this keyword to use quadratic fitting when interpolating data.

lsq - set this keyword to use least-squares quadratic fitting when interpolating data.

spl - set this keyword to use spline fitting when interpolating data.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
regrid, 0.01 - regrid the current arrays to an x-axis resolution of 0.01.

 

rxr, lowx, highx [, /quiet, opstatus=opstatus]

Restrict the x range of the 'current' arrays to the specified limits. The trimmed data replaces the contents of the 'current' arrays.

lowx - the lower limit to be applied.

highx - the upper limit to be applied.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
rxr, 3400, 3600 - trim the current arrays to a range of 3400-3600.

 

snip, regions [, /quiet, opstatus=opstatus]

Select points in the current spectrum to be removed, either using the mouse or by specifying the regions to be removed on the command line. The edited version of the spectrum replaces the 'current' arrays. For clarity, the areas to be removed are highlighed in colour.

regions - set this to an array of pairs of numbers defining the start and end of the regions to be removed. If this variable is not set then point selection is interactive, using the mouse.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
snip, [4101, 4105, 4121, 4123] - remove the regions 4101-4105 and 4121-4123Å from the current spectrum.

 

snr [, snr=snr, region=region, useregion=useregion, opstatus=opstatus, /quiet]

Estimates the signal-to-noise ratio in the continuum of the current spectrum. The user selects a region of continuum with the mouse, and a linear fit is performed to this region (provided it consists of over 10 points) to quickly (re-)normalise the data. The standard deviation (sigma) of the renomalised data is then calculated, and the SNR is calculated as 1/sigma.

snr - set this keyword to a named variable which will be returned with the measured SNR. Note that a value of -1 will be returned if sigma=0, as might happen with a model spectrum.

region - set this keyword to a named variable which will be returned as a two element array containing the start and end wavelengths used in the calculation.

useregion - set this keyword to a two element array defining the start and end points to define the sample region, omitting the interactive selection.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

 

tenx [, opstatus=opstatus, /quiet]

Replaces the elements of the current x arrays with 10^x.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

 

teny [, opstatus=opstatus, /quiet]

Replaces the elements of the current y arrays with 10^y.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

 

tov, lambda, [, /quiet, opstatus=opstatus]

Transform the current spectrum from wavelength to velocity space, with a zero velocity point at the wavelength specified by lambda. Unlike dipso the code does not maintain a wavelength/velocity flag for the data and so will not stop you from doing something potentially silly. All this routine does is translate the x axis values, no interpolation takes place, so that a spectrum with uniform spacing in wavelength will not be uniformly spaced in velocity once transformed.

lambda - the wavelength which is to be the zero point for the transformed spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
tov, 4101 - translate current arrays to velocity space, centered on 4101Å.

 

tow, lambda, [, /quiet, opstatus=opstatus]

Transform the current spectrum from velocity to wavelength space, with the zero velocity point at the wavelength specified by lambda. Unlike dipso the code does not maintain a wavelength/velocity flag for the data and so will not stop you from doing something potentially silly. All this routine does is translate the x axis values, no interpolation takes place, so that a spectrum with uniform spacing in velocity space will not be uniformly spaced in wavelength once transformed.

lambda - the wavelength which is to be the zero velocity value for the transformed spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
tow, 4101 - translate current arrays to wavelength space, centered on 4101Å.

 

vsinifft [, /nopush, /pushall, thevsini=thevsini, opstatus=opstatus, /quiet]

Use the FFT technique to determine the vsini of a single, normalised, absorption line held in the current arrays. The current spectrum is displayed, and the user invited to click on the approximate location of the line centre. A vsini profile is then fitted to the absorption feature to determine the centroid, equivalent width, approximate vsini, and continuum level. Crude renormalisation is performed based on the continuum level, and then an FFT is performed on the profile. The code attempts to locate the first minimum in the FFT, which is used to determine the vsini, but the estimate is not always correct and the user can override the default choce.

Using the estimate of vsini the code generates narrow-lined model spectra of the same wavelength and equivalent width, and broadens then with a range of vsini from 0.6 to 1.4 times the estimate. These are in turn FFTd and their first minima measured, and from this the vsini of the observed spectrum is derived.

At the end of the fitting the code will show the observed data and one of the models with the optimal vsini applied. This should not be taken as an exact indication of the quality of fit, since the model is simply a narrow gaussian, and ignores effects such as intrinsic width, macroturbulence, and instrumental broadening.

nopush - by default the code pushes the renormalised observed data and the best-fit broadened model to the stack. Set this keyword to disable this behaviour.

pushall - set this keyword to make the code push all the model FFTs to the stack.

thevsini - set this to a named variable which will contain the estimated vsini of the spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

 

xcorr, s1, s2 [, /vel, /quiet, opstatus=opstatus]

Perform a cross-correllation on stack entries 1 and 2.

s1,s2 - the numbers of the stack entries to cross correllate. s1 is regridded to a regular spacing with a average resolution for the data, and s2 is then mapped to this. If there is no overlap between the two spectra in wavelength then the output from this routine will not make much sense...

vel - set this keyword to perform a cross correlation searching for velocity shifts between the two stack entries. The stack entries will be logx'd, cross correllated, then tenx, xshift, -1, and xscale 3e5 are applied so that the peak of the output occurs at the velocity offset between the two in km/s.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
xcorr, 4, 5, /vel - look for velocity shifts between stack entries 4 and 5.

 

xscale, scale [, /quiet, opstatus=opstatus]

Scale all x values in the current arrays by a given amount.

scale - the factor by which to scale the data in the current arrays.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
xscale, 2.0 - double all 'current' x values.
xscale, 0.5 - halve all 'current' x values.

 

xshift, shift [, /quiet, opstatus=opstatus]

Apply a shift to the x axis, positive or negative.

shift - the value to shift the x axis by.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
xshift, 2.5 - add 2.5Å to the x values.
xshift, -2.5 - subtract 2.5Å from the x values.

 

xyv [, /nearest, /noredraw, /once, xy=xy, /quiet, opstatus=opstatus]

Let the user click on points on the current plot and print out the x/y pairs corresponding to where they clicked. The user can either loop over multiple points, or use the once flag to click on a single point.

nearest - set this keyword to select the data point nearest to where the user clicked. The selection is based solely on the x axis value since these are unique - the data may be degenerate in y, but can't be in x. This option redraws the spectrum in the 'current' array before plotting so it is clear which spectrum the 'nearest' points are being calculated against.

noredraw - this keyword only functions in conjunction with /nearest and blocks the redraw which normally happend automatically with /nearest. Use with caution!

once - set this keyword to run the routine for a single point only. Otherwise the routine continues to print out x/y pairs until the user double-clicks on a given point.

xy - set this to the name of a variable which will be returned as a two dimensional array containing the values of all x/y pairs selected. The code is limited to returning 5000 x/y pairs - if you exceed this (!) then the last entry in the array will reflect the last point clicked, while the others will be the first 4999 - if you reach this limit you deserve to deal with this...

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
xyv, /nearest, /once
xyv, /nearest, xy=myvariable

 

yshift, shift [, /quiet, opstatus=opstatus]

Apply a shift to the y axis, positive or negative.

shift - the value to shift the y axis by.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress message display.

Example:
yshift, 0.1 - add 0.1 to the y values.
yshift, -0.1 - subtract 0.1 from the y values.

 

yscale, scale [, /quiet, opstatus=opstatus]

Scale all y values in the current arrays by a given amount.

scale - the factor by which to scale the data in the current arrays.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
yscale, 2.0 - double all 'current' y values.
yscale, 0.5 - halve all 'current' y values.

 


Data display

cdraw [, opstatus=opstatus, /quiet]

Draw a 'spectrum' on screen by clicking points with the mouse. The final spectrum is placed in the current stack entry. Double-click on the final point to exit.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
cdraw

 

crot [, /on, /off, /quiet]

Controls colour rotation in the plotting routines.

on - set this keyword to enable colour rotation. Rotation starts with the current colour, it does not reset each time.

off - set this keyword to disable colour rotation.

If neither /on or /off are specified then crot toggles the current rotating status.

quiet - set this keyword to suppress all message display.

There is no opstatus option with this command.

Example:
crot
crot, /on

 

cset, colour [, /list, /reset, opstatus=opstatus, /quiet]

Set the plotting colour directly, either by name or number.

colour - the colour which is desired, specified either as the integer index of the colour or else as the name of the colour as a string. To see a list of all colours, use the /list keyword.

list - list all registered colours by name and index number.

reset - reset the colour to index 0 - white (X11), black (PS).

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
cset, 2
cset, "red"
cset, /list

 

dev, dev [, psfile=psfile, epssize=epssize, /close, opstatus=opstatus, /quiet]

Select the device to use for graphics - switch between X Windows and various Postscript formats. The command is also used to close PS files after plotting - this is necessary since IDL does not write all of the plotting data to the file until it is sure nothing more will be added to the plot.

dev - the name of the device to use. Options are:

psfile - set this variable to the name to use for the Postscript file. If no filename is specified the defaults are used - procspec.xxx.ps for psl/psp, and procspec.xxx.eps for eps, where xxx is a number between 000 and 999, automatically incremented each time. The .ps/.eps suffixes are added automatically if not specified. If a file with the specified name exists (or one reaches procspec.999.[e]ps), it will be overwritten.

epssize - set this variable to an array of two numbers defining the x and y dimensions (in cm) of the EPS file (this does not affect psl/psp files). If this is not set then the plot defaults to 18x12 cm.

close - set this keyword to close the open Postscript file. Note that when selecting any new device (X or PS) any open PS files will be closed automatically as a precaution. It is, however, best to get into thehabit of closing a file after writing to it, to avoid problems. If this keyword is set, any open files are closed and the routine exits, regardless of any other parameters being set.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
dev, 'x' - select X Windows
dev, 'psl', psfile='myplot.ps' - select landscape portrait, written to the file myplot.ps
dev, 'eps', psfile='myplot.eps', epssize=[10,10] - write an EPS file with dimensions 10x10cm.

 

mpml, stacknumbers [, /attop, _extra=e]

Make a quick plot of the specified list of stack entries, with the x/y axes scaled so that all data are completely displayed. In addition the simple_legend routine is called to provide a quick key to the various plots.

stacknumbers - an array consisting of two or more stack numbers to be displayed.

attop - set this keyword to plot the legend at the top left of the plot instead of the bottom left.

Extra parameters - you can pass additional parameters to the procspec simple_legend command by appending them to the end of the mpml command.

Example:
mpml, [2,3,4,5,6]
mpml, [2,3,4,5,6], cscale=0.6, /attop, /horizontal - cscale and horizontal options are passed to simple_legend

 

nx

Disable fixed x-axis range, permit auto-scaling once more.

This routine is a simple call to xr provided for convenience. There are no parameters to pass or return.

Example:
nx

 

ny

Disable fixed y-axis range, permit auto-scaling once more.

This routine is a simple call to yr provided for convenience. There are no parameters to pass or return.

Example:
ny

 

nxy

Disable fixed x and y axes, all auto-scaling resumed.

This command is a simple call to nx and ny for convenience. Again, it has no parameters or options.

Example:
nxy - Well, what else were you expecting?

 

plotzone, zone [, rows=rows, cols=cols, /reset, /over, opstatus=opstatus, /quiet]

Allows multiple plots to be shown on the same 'page', using the IDL !P.MULTI mechanism. The plotting area may be split into a specified number of columns and rows, and the individual areas directly selected if desired. If the individual zones are not specified then IDL plots to each zone in the order left to right, top to bottom, with each pm.

zone - the number of the zone to print to. This does not have to be set if using the rows, cols, or reset options. Note that IDL has a rather eccentric way of numbering zones. While the zones are used left to right, top to bottom ,they are numbered the opposite way, so that the bottom right corner is 1, and the top left is n for a plot area of n zones.

rows - set this to the number of rows you want on the plotting area. Note that after (re)setting this parameter the next pm command will erase the entire plotting area unless /over is set.

cols - set this to the number of columns you want on the plotting area. Note that after (re)setting this parameter the next pm command will erase the entire plotting area unless /over is set.

reset - set this keyword to return to the default single plot per 'page' mode.

over - set this keyword to stop IDL from erasing the plotting surface when the number of rows or columns is altered. This may be useful in some cases if trying to get a complex layout.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
plotzone, 2, rows=2, cols=2 - set the plotting area to a 2x2 grid, and position the next plot at the bottom left.

 

pm, plotlist [, /over, opstatus=opstatus, /range, /notitle, /quiet, _extra=e]

Display stack entries on the selected plotting device. Data can be overplotted on an existing plot if desired.

plotlist - the stack number(s) of the item(s) to be plotted. To plot a single stack entry just specify the number of that entry. To plot the 'current' stack item you may either either use number 0 or simply not specify plotlist. To plot multiple spectra pass the stack entry numbers as an integer array.

over - set this keyword to display the spectrum plotted over the current plot. The code will not warn you if the data you are trying to plot exceeds the bounds of the current plot.

notitle - set this keyword to suppress printing the title of the first specified stack entry as the plot title. This may be useful in some cases where an untitled plot is needed.

range - if this keyword is set, and plotlist consists of two elements then all stack entries from the first to second entry will be plotted.

Extra parameters - you can pass additional parameters to the IDL PLOT command by appending them to the end of the pm command.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Examples:
pm - plot the 'current' stack entry on a fresh plot.
pm, 3, /over - overplot stack entry 3 on the current plot.
pm, 3, /over, linestyle=2 - as above, but note use of _extra functionality to pass linestyle options directly to PLOT.
pm, [2,3,4,5] - plot stack entries 2, 3, 4, and 5.
pm, [2,5], /r - as above, only more compact, using the /range option.
pm, [2,3,4,5,0] - plot stack entries 2, 3, 4, 5, and the current item too.

 

simple_legend, x, y, [labels=labels, stacknos=stacknos, /horizontal, /up, /rightalign, /centrealign, /nowrap, cscale=cscale, opstatus=opstatus, /quiet, _extra=e]

A simple routine to add a 'legend' to the current plot. This is useful with multi-element plots when you want to note on the plot what each colour means. The legends can be arranged vertically or horizontally. The text for each label can be provided either as a list of strings, or a set of stack entries can be specified and their titles are used instead. Additional text formatting options can be passed directly to the IDL xyouts command. If colour rotation is enabled via crot then each label is printed in a different colour, starting from the first plot colour.

x - the x position of the top left of the legend block, in data co-ordinates.

y - the y position of the top left of the legend block, in data co-ordinates.

Note that by default the first element of the legend is plotted at (x,y), with subsequent elements printed below it.

labels - an array of stings to be printed.

stacknos - an array of stack entry numbers, the titles of which will be used as the strings to print.

cscale - a scaling factor to apply to the characters displayed - less than 1 will be smaller, more than 1 will make them larger. Note that while one can pass CHARSIZE parameter (see below) to adjust type size, using cscale also affects the spacing.

horizontal - set this keyword to plot the legend texts horizontally instead of vertically. The first element is plotted at (x,y) and subsequent elements plotted to the right. By default the text will wrap to the next line below (or above if /up is set) if the text extends beyond 85% of the width of the plotting device rightward. No check is made for text running off the top or bottom of the page as that would make things too complex, and this routine is supposed to be simple

up - set this keyword to plot the legend texts with the first element at the bottom, and subsequent elements above it. In this case (x,y) is treated as the lower left corner of the legend. If /horizontal is set and wrapping is not disabled then setting /up will cause the text to wrap upwards instead of downwards.

nowrap - set this keyword to disable automatic text wrapping when horizontal is set. Text is then free to run off the side of the plotting device.

rightalign - set this keyword to right-align the legend text. Useful if plotting the legend on the right side.

centrealign - set this keyword to centre-align the legend text.

Extra parameters - you can pass additional parameters to the IDL XYOUTS command by appending them to the end of the pm command.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Examples:
simple_legend, 4000, 1.1, labels=['H2', 'Model 1', 'Model 2', 'Model 3'] - print the four text strings, arranged vertically, with their origin at the position x=4000, y=1.1.
simple_legend, 4000, 1.1, stacknos=[1,3,6,7,8], /horizontal - print the titles of the specified stack entries, arranged horizontally, with their origin at the position x=4000, y=1.1.
simple_legend, 4000, 1.1, stacknos=[1,3,6,7,8], /down, CHARSIZE=2.5, CHARTHICK=2, ORIENTATION=45 - as in the above example, with the first legend printed at the top, and passing additional parameters to the XYOUTS command to specify additional size, thickness, and angle options.

 

xr, lowx, highx [, /reset, /quiet, opstatus=opstatus]

Set the default range for plotting spectra. Note that if you set this to a given range, and then try to plot data which lie outside this range, IDL will happily produce a blank plot for you.

lowx - lower x limit.

high - upper x limit.

reset - set this keyword to reset the x range so that IDL automatically selects the best range to display the data.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
xr, 4100, 4200 - set the current x plotting range to 4100-4200Å
xr, /reset - disable fixed x limits, let IDL select the best values. Equivalent to the nx command.

 

xtitle, titlestring [, /dumb, opstatus=opstatus, /quiet]

Set the x axis title for plots.

titlestring - the string to be used for the x axis label. For convenience the routine will translate the strings Ang and km/s to the prettier Å and km s-1. Be aware that this is case sensitive - Ang will be converted, ang won't.

dumb - set this keyword to turn off the translation above.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
xtitle, 'Wavelength (Ang)' - set the x axis title to Wavelength (Å)
xtitle, 'Wavelength (Ang)', /dumb - set the x axis title to Wavelength (Ang)

 

yr, lowy, highy [, /reset, /quiet, opstatus=opstatus]

Set the default range for plotting spectra. Note that if you set this to a given range, and then try to plot data which lie outside this range, IDL will happily produce a blank plot for you.

lowy - lower y limit.

highy - upper y limit.

reset - set this keyword to reset the y range so that IDL automatically selects the best range to display the data.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
yr, 0.9, 1.1 - set the current y plotting range to 0.9-1.1.
yr, /reset - disable fixed y limits, let IDL select the best values. Equivalent to the ny command.

 

ytitle, titlestring [, opstatus=opstatus, /quiet]

Set the y axis title for plots.

titlestring - the string to be used for the y axis label.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
ytitle, 'Flux' - set the y axis title to Flux

 

zoomin [, /xonly, /yonly, therange=therange , opstatus=opstatus, /quiet]

Interactively select a region of the current spectrum to zoom into. Optionally the zoom effect may be restricted to the x or y axis only. When the command is used the current spectrum is displayed, and the user then clicks to select the start of the area of interest. When the mouse is moved an 'elastic' rectangle shows the currently selected area, and the selection is finalised by clicking again. The spectrum is then redisplayed with the new x/y range limits applied.

xonly - set this keyword to apply the zoom in the x axis only - y remains unbounded. By default the zoom is applied in both axes.

yonly - set this keyword to apply the zoom in the y axis only - x remains unbounded. By default the zoom is applied in both axes.

therange - set this to a named IDL variable which will be returned as a 4 element array giving the lower and upper x/y pairs defining the area selected.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

 


ALF - Absorption Line Fitting

ALF is a package which performs gaussian fitting to normalised absorption line spectra. It has a large number of dependent routines which are not documented below since they are not intended for general use - in the procspec folder these are all saved with names beginning alf_. Note that ALF only works with normalised absorption spectra.

alf, ngauss [, width=width, centres=centres, fitparams=fitparams, fiterrs=fiterrs, showelements=showelements, ews=ews, /now, /vsini, /quit, /quiet, opstatus=opstatus]

This is the only user-facing ALF routine, and controls all functions either with an IDL command-line mode or else with its own interactive command interpreter (somewhat similar to DIPSO's ELF). It fits the data in the current arrays, so a stack entry should be popped before using this routine.

ngauss - the number of gaussians to be included in the model. Must be in the range 1-20. This *cannot* be changed once set.

width - set this keyword to define the initial estimate of the gaussian width in Angstroms. The same initial value is applied to all gaussians since most lines in a star will have similar basic widths. If this parameter is not specified it defaults of 0.1Å for each line.

centres - set this keyword to define the inital estimates of the line centroids for each gaussian component. This must be an integer or floating point array with the same number of elements as ngauss. If these are not set using this keyword they must be specified in the interactive mode.

now - set this keyword to perform fitting immediately, without reviewing the model in the interactive mode. An initial attempt to run the fit will be made, assuming sufficient parameters were set on the IDL command line, and then the user is returned to the ALF interactive command line.

showelements - set this keyword to perform have the individual elements of the final fit plotted as well as the combined fit. May be useful in situations with serious blending. Works best with colour rotation turned on.

quit - set this keyword to make alf exit after performing one command. This is only really useful in conjunction with now, to permit semi-automated fitting, as done in quickfit.

vsini - set this keyword to use vsini style profiles instead of gaussians. The 'width' of the vsini profile is still specified as for the gaussian, as a FWHM-style value in Å, though it is not actually a FWHM. When printing out the fit parameters the FWHM is translated to velocity as well for convenience, which gives the actual vsini value used in the model.

fitparams - set this keyword to a named variable which will contain the parameters of the fit on exit. This will be an array of floating point numbers, element 0 being the continuum level taken (if this is far from 1 you have a problem!), followed by ngauss groups of three numbers which define each gaussian - [centroid, peak, width]. The gaussian is defined as y = peak*exp(-0.5*((x-centroid)/sigma)2), where sigma=width/2.35.

fiterrs - set this keyword to a named variable which will contain the standard errors on each of the fitparams.

ews - set this keyword to a named variable which will contain the equivalent width in mÅ of each gaussian in the fit. Note that these values will only be accurate for a normalised absorption spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress some error message display - this does not affect the interactive mode though.

Example:
alf, 3, width=0.5, centres=[4552,4567,4575], ews=myews - fit 3 gaussians to the data in the current arrays, with an initial width of 0.5Å and centroids as shown. The line equivalent widths will be returned as an array in the variable myews when the routine exits.

Interactive commands

When ALF is started users are presented with the interactive command prompt, which is separate from the main IDL prompt. This allows more detailed configuration of the fit parameters.

 

quickfit [,/quiet, /quit, /once, alf_parameters]

This routine provides a wrapper around alf for fast interactive fitting of the absorption features in the current arrays. When run the current spectrum is displayed, the user clicks on the centroids of each line to be fitted (double-clicking on the last one), and alf is then run, performing the initial fit automatically. The user is then returned to the standard alf command line.

Any of the parameters usually passed to alf can be passed using quickfit in the usual manner. You can certainly try to pass ngauss and centres but since quickfit works those out from the clicks on the spectrum things will get very confused.

quit - set this keyword to force quickfit to return to the main procspec command line after the first attempt at fitting, rather than the alf prompt.

quiet - set this keyword to suppress most text output.

once - fit a single feature, so only let the user click once and then fit.

Example:
quickfit, width=0.5, ews=the_ews - fit the data in the current arrays, with a starting line width of 0.5Å, returning the line equivalent widths in the variable the_ews.

 


ELF - Emission Line Fitting

ELF is a package which performs gaussian fitting to emission line spectra normalised to a baseline of zero. It is based on the ALF code (above) and operates in exactly the same manner, with the addition of one keyword.

elf, ngauss [, width=width, centres=centres, fitparams=fitparams, fiterrs=fiterrs, showelements=showelements, startpeak=startpeak, ews=ews, /now, /vsini, /quit, /quiet, opstatus=opstatus]

To avoid repetition the user is directed to the instructions above for most options. The best way to prepare a spectrum for use with ELF is to crop out the relevant part, push that to the stack, then create a baseline fit (using pf or cdraw), and asub that from the data. Push the result to the stack and then start to fit.

startpeak - sets a value for the initial guess at the peak height. By default the code assumes 0.1, which is entirely arbitrary, but has been shown to work fine in cases of actual peaks of around 1E-15. However in some cases it may be useful to set a starting value, which is applied to all fit elements.

 


TLUSTY nonLTE-related routines

These routines interface to the results of the TLUSTY model grids, allowing you to load a spectrum for a given grid point and also interpolate a spectrum to a given model. A version of the hydfit code is also available, accessing spectra stored on the stack.

getvt, infile, element, teff, logg, vts, grid [, /pushall, /prompt, ion=ion, zero=zero, stats=stats, /quiet, opstatus=opstatus]

This command automates the process of determining the microturbulent velocity for a star, using the Dufton abundance vs. equivalent width technique. The wavelength/equivalent width pairs are read in from an ASCII file and for a given model atmosphere (T, g, metallicity) a range of abundance vs. vt plots are produced, and their slopes measured. These are then presented to the user in a simple plot, from which the optimal vt should be easily determined - to help the code will interpolate the data to find the likely location of the zero gradient point and then plot a large red line to highlight it!

This command makes use of the modified tlabund routines, and these must be in your IDL_PATH or the procedure will fail. See installation instructions for details.

infile - the name of the ASCII file containing the list of lines to be used in the analysis. The file has the same format used by the tlbatch program - each line has three elements, the element name, wavelength, and equivalent width in mÅ, eg. si 4128 34. The file can contain data for elements other than the one specified by element - these will be ignored.

Note that the routine will ignore any lines which are not included in the TLUSTY model grids, but will extrapolate equivalent widths automatically. The routine will indicate how many 'good' lines were found to perform the analysis on.

element - a string which indicates the element being used for the analysis. Must be one of 'c', 'n', 'o', 'mg', 'si'.

teff - the effective temperature to use for the models.

logg - the surface gravity to use.

vts - a three element array which defines the microturbulences to be used. Takes the form [start, end, step] so that [0,20,5] would run analyses at vt = 0, 5, 10, 15, 20 km/s. In the TLUSTY grids vt is restricted to the range 0-30 km/s.

grid - a string defining the model grid to be used. Must be one of 'nlgal','nlsmc','nllmc','nlmcb','ltgal', 'ltsmc', 'ltlmc', 'ltmcb' following the usual naming conventions.

ion - set this keyword to restrict the ionisation state of the specified element. Must be in the range 1-5.

pushall - set this keyword to have all ew/abundance pairs and linear fits pushed to the stack. Useful if these have to be plotted later.

prompt - set this keyword to be prompted to move on to the next vt value. Useful if not analysing many lines and the plots flash past too quickly to study.

zero - set this keyword to a named IDL variable which will be returned containing the value of the microturbulence likely to give a zero gradient. Note that this is obtained from linear interpolation and should be properly tested, not taken for being the absolute truth!

stats - set this keyword to a named IDL variable which will be returned as an array containing the microturbulence, fit gradient, error on the gradient, and number of points used in the analysis for each vt considered.

quiet - set this keyword to suppress most message display - warnings about lines going into emission in the TLUSTY results cannot be suppressed (and nor should they be...).

opstatus - an integer optionally returned with a status code which is:

Example:
getvt, '~/o.lis', 'o', 21000, 4.0, [0,10,5], 'nlgal', stats=thestats - calculate the slope gradient using the O lines listed in ~/o.lis for a non-LTE galactic metallicity model of T=21000K, log g=4.0, at vt = 0, 5, 10 km/s.

 

hhefit, stackno, grid, vt [, normat=normat, vsini=vsini, gauss=gauss, teff=teff, logg=logg, /hi, /quiet, opstatus=opstatus]

This command provides automated H/He line fitting against profiles extracted from the TLUSTY runs. A chi-square test is performed over the selected grid and plotted as a colour contour map, and points on the map can be clicked on to show the fit at that particular point. On exit the model representing the last clicked point is left in the current arrays.

Lines available to auto-fit are:

The code will try to identify the line in question by looking at the mean wavelength of the specified stack entry. If the mean value is more than 20Å from the known centroids the code will abort.

The spectrum to be fitted should be trimmed of excess continuum and non-H/He features using snip, velocity corrected to the correct rest wavelength, and pushed to the stack before hhefit is invoked. Roughly equal amounts of continuum should be left on either side of the profile.

stackno - the number of the stack entry to be fitted.

grid - a string indicating the model grid to use - can be gal, smc, lmc, mcb following the usual conventions. Must be given in quotes, in lower case.

vt - the microturbulence to use. The H lines will be largely insensitive to this, but it does affect the He lines. As usual, this must be one of 0, 5, 10, 20, 30.

normat - set this keyword to indicate where to renormalise both the observed and model spectra. This is specified as an offset from the line centroid, to the profiles are normalised at ±normatÅ from the centroid. This value should be less than 50 since the models only extend to 50Å either side of the line centre. If this parameter is set then the model comparison only includes data from -normat to +normat, if it is not set then the entire observed spectrum is used in the comparison (this is the default).

gauss - set this keyword to the FWHM in km/s of a gaussian which will be applied to the models before fitting.

vsini - set this keyword to the width in km/s of a vsini profile to be applied to the models before fitting. Note that this is not currently reliable for small values of vsini (<10).

teff - set this keyword to a two element array giving the upper and lower limit of the temperatures to fit.

logg - set this keyword to a two element array giving the upper and lower limit of the gravities to fit.

hi - set this keyword to use the high-resolution model grids. The default is to use the standard resolution grid, which is quicker.

quiet - set this keyword to suppress message display.

opstatus - an integer optionally returned with a status code which is:

Example:
hhefit, 10, 'gal', 0, teff=[20000,30000], vsini=200, /hi - Fit Galactic models at VT=0 to stack entry 10, over the range 20000-30000K, applying a vsini of 200 km/s to each model before fitting.

 

loadhhemodel, teff, logg, vt, grid, line [,/quiet, opstatus=opstatus]

This procedure will load a TLUSTY H/He model spectrum for a specified line into the current arrays. If the exact specified model does not exist an error will be returned. This routine is used by fithhe.

teff - the temperature of the grid point.

logg - the gravity of the grid point.

vt - microturbulent velocity of the grid point - 0, 5, 10, 20, or 30.

grid - a string defining the Fe abundance of the grid. 'gal', 'smc', 'lmc', or 'mcb' following the local convention on grid names. Must be passed as a string, and is case sensitive.

line - the wavelength of the feature of interest. At the moment the following lines are available:

The line wavelength must be specified exactly or the routine will not work.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
loadhhemodel, 20000, 4, 5, 'smc', 4101.78 - load SMC model for Hδ, T=20000, g=4.00, vt=5.

 

loadtlmodel, teff, logg, vt, abund, grid [,/quiet, /hher, /hheb, opstatus=opstatus]

This procedure will load a specified TLUSTY model spectrum into the current arrays. If the exact specified model does not exist an error will be returned. By default the full model spectrum is loaded though optionally only H/He spectra can be specified.

teff - the temperature of the grid point.

logg - the gravity of the grid point.

vt - microturbulent velocity of the grid point - 0, 5, 10, 20, or 30.

abund - the metal abundance of interest, -0.8, -0.4, 0.0, 0.4, 0.8, following the local convention on metallicities.

grid - a string defining the Fe abundance of the grid. 'gal', 'smc', 'lmc', or 'mcb' following the local convention on grid names. Must be passed as a string, and is case sensitive.

hher - set this keyword to load the red-wavelength H/He only spectrum. This option cannot be used simultaneously with /hheb

hheb - set this keyword to load the blue-wavelength H/He only spectrum. This option cannot be used simultaneously with /hher

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
loadtlmodel, 20000, 4, 5, 0.4, 'smc' - load SMC model for T=20000, g=4.00, vt=5, metal abundances=+0.4 over baseline.

 

interp_tlmodel, teff, logg, vt, abund, grid [, range=range, opstatus=opstatus, /quiet]

Interpolate an arbitrary TLUSTY model spectrum from the database of TLUSTY 'full metal' spectra. Optionally a subsection of the spectrum can be extracted instead of the entire range (which is usually 3800-5000Å).

The final spectrum is left in the current arrays, and also pushed to the top of the stack. Note that the routine has several subfunctions which are called when performing the interpolations - these are not for general use and thus not documented here.

teff - effective temperature.

logg - logarithmic gravity.

vt - microturbulent velocity of the grid point - 0 to 30.

abund - the metal abundance of interest, -0.8 to 0.8, following the local convention on metallicities.

grid - a string defining the Fe abundance of the grid. 'gal', 'smc', 'lmc', or 'mcb' following the local convention on grid names. Must be passed as a string, and is case sensitive.

range - an optional array defining lower and upper limits on the wavelength of the intepolated spectrum.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
interp_tlmodel, 21000, 3.9, 5, 0.5, 'smc', range=[4000,4100] - interpolate an SMC model for T=21000, g=3.90, vt=5, metal abundances=+0.2 over baseline, between 4000 and 4100Å.

 

sibalance, infile, teff, logg, vt, grid [, /pushall, /quiet, opstatus=opstatus]

This command automates the process of determining the effective temperature of a star using the silicon ionisation balance technique. Si lines to be used are read in from an ASCII file and for a given set of model atmospheres (T, g, vt, metallicity) a range of abundance vs. T plots are produced. These are then presented to the user in a simple plot, and then averaged by ionisation state and plotted again so the intersection can be clearly seen.

This command makes use of the modified tlabund routines, and these must be in your IDL_PATH or the procedure will fail. See installation instructions for details.

infile - the name of the ASCII file containing the list of lines to be used in the analysis. The file has the same format used by the tlbatch program - each line has three elements, the element name, wavelength, and equivalent width in mÅ, eg. si 4128 34. The file can contain data for elements other than Silicon, these will be ignored.

Note that the routine will ignore any lines which are not included in the TLUSTY model grids, but will extrapolate equivalent widths automatically. The routine will indicate any 'bad' lines which were not identified and excluded from the analysis.

teff - a three element array defining the effective temperatures to use for the models. Takes the form [start, end, step] so that [18000,22000,1000] would run models at T=18000, 19000, 20000, 21000, 22000K.

logg - the surface gravity to use.

vts - the microturbulence to be used. In the TLUSTY grids vt is restricted to the range 0-30 km/s.

grid - a string defining the model grid to be used. Must be one of 'nlgal','nlsmc','nllmc','nlmcb','ltgal', 'ltsmc', 'ltlmc', 'ltmcb' following the usual naming conventions.

pushall - set this keyword to have all abundance/Teff pairs pushed to the stack. Useful if these have to be plotted later.

quiet - set this keyword to suppress most message display - warnings about lines going into emission in the TLUSTY results cannot be suppressed (and nor should they be...).

opstatus - an integer optionally returned with a status code which is:

Example:
sibalance, 'si.lis', [18000,22000,1000], 4, 5, 'nlgal', /push - perform an analysis using the Si lines listed in the file si.lis for a nonLTE Galactic grid, Teff=18000, 19000, 20000, 21000, 22000K, log g = 4, microturbulence = 5, pushing each set of Teff/abundance pairs to the stack.

 


Internal routines

These routines are not intended for end-users, and therfore do not in general have all of the error checking and reporting facilities of most of the other procedures. They may, however, be of use in writing your own codes. There are additional routines which are not included here, which are not intended for public use at all.

close_open_psfile [, /quiet]

This routine closes any open postscript files - it's called by dev and is probably not of general use. Rather than do a simple device, /close this checks the !d.unit number to see if a file was actually open before issuing a close. Not that it matters since device is smart enough to handle things, but I dislike putting up a 'Closing files' message if one is not needed...

quiet - set this keyword to suppress all message display.

 

crotcolour([/axiscol, opstatus=opstatus, /quiet])

Used by: pm, and others...

This function returns the colour index that should be used for the next plotting operation, based on whether crot is enabled. The routine can also return the current colour to use for axes, etc, based on whether the X or PS plot devices are in use.

If called with no parameters the function will simply return the appropriate colour code for the next plotting operation.

axiscol - set this keyword to get the correct colour code for axis elements, etc. This is assumed to be black for Postscript plots, and white for X Window System plots.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
plotcolour = crotcolour()

 

del1, itemno [, opstatus=opstatus, /quiet]

Delete a single item from the stack, specified by the integer itemno. This routine is called by del, and is not intended for general use.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
del1, 11

 

eval_poly(x, coefficients)

Used by: pf, snr

Evaluates a simple polynomial expansion at points x (which can be an array) for an array of coefficients [a0,a1,a2,a3 etc] where y = a0 + a1.x + a2.x2 + a3.x3 ....

x - the array of x values to evaluate the expression at.

coefficients - the list of coefficients in the expansion.

There is no opstatus or quiet option with this function.

Example:
a = [1.0, 2.0, 2.5] - define equation as y = 1 + 2x + 2.5x2
x = [1,2,3,4,5,6,7,8,9,10] - these are our x values
y = eval_poly(x, a) - returns y at each x value

 

gaussorvsini(x, p, proftype)

Used by: mkgauss, alf

This function generates a gaussian or vsini profile for a given set of parameters over a specified x range. The gaussian is a simple profile, while the vsini profile is a little more complex, being generated in the usual manner and then normalised so that its 'height' can be set exactly by the user.

x - an array containing the x axis points where the curve is to be calculated.

p - an array of three parameters which define the shape of the profile. Element 1 is the centroid (Å), element 2 the peak height, and element 3 the FWHM (Å) of the gaussian. In the case of the vsini profile this FWHM is converted to velocity based on the centroid. This is probably not the easiest way to think of a vsini profile but then the routine is not really intended for general use, and in ALF we're more concerned with getting a good fit than anything else.

proftype - set this to 0 to produce gaussians, 1 for vsini profiles.

Example:
y=gaussorvsini(x,[4000,0.5,0.2],0) - set y to an array of y values for each value of x, representing a gaussian profile centred on 4000Å with a peak of 0.5 and FWHM 0.2Å.

 

hhefit_single_model, stackno, t, g, gauss, vsini, normpts, pathheader, chisq [, opstatus=opstatus, quiet]

Used by: hhefit

This routine fits a single H/He line to the specified stack entry, plots it to the right hand side of the current X Window, and returns the chi-square statistics of the fit. Optionally both spectra can be renormalised at a specified point.

stackno - the stack entry number of the data to be fitted.

t, g - model temperature and gravity. Must be known grid points.

gauss, vsini - width of any gaussian or vsini broadening function to apply to the model before fitting.

normpts - a two element array giving the points at which to renomalise the spectrum. If set to zero no renomalisation is performed.

pathheader - a string giving the start of the path to the model files.

chisq - a named variable which will be set to the two element chi-square statistic of the fit between the model and data.

opstatus - many opstatus codes are returned, but unless it's zero hhefit aborts so who cares...

quiet - set this keyword to suppress message display.

 

idl8col_to_decomposed(rgb_array)

Used by: ps_setup_colours

This function maps the three-element RGB arrays returned by IDL8 !color system variable to the Long Int decomposed colour values used in procspec.

 

is_uniform(array [, /exact, tolerance=tolerance, /quiet])

Used by: broaden

This function tests if the 1D array passed to it is uniformly spaced or not. This is used by some routines which only operate with a uniformly spaced x-axis.To accommodate rounding errors (even in the double precision used for storing data) the routine permits a tolerance to be set below which the spacing is considered uniform.

array - a 1D array of integer or floating point numbers. If a 2D array is passed then it's treated as a 1D array and almost certainly this won't be what you want.

exact - set this keyword to set the tolerance to zero - this will often return errors due to rounding in IDL rather than the actual data though.

tolerance - set this to the fractional tolerance acceptable. If this is not set then the routine defaults to 10-7, which is 0.000001% or about 0.03 km s-1.

quiet - set this keyword to suppress all message display.

Example:
test = is_uniform([1,2,3,4,5,6,7,8,9]) - test will be a boolean value (true/false)

 

mask, data, mask [,/remap, /pushremap, /quiet, opstatus=opstatus]

Used by: mpf

This routine 'masks' one stack entry by another. The 'data' entry is a regular spectrum, the 'mask' is a spectrum whose y values are all 1 or 0, 1 indicating the x axis values where the data spectrum is to be kept - at other values it's expunged. Hence the name 'mask'. The masks are generated by mpf and are optionally stored on the stack to allow refitting using the same continuum region without reselecting everything. If the two stack entries do not have the same x axis values then mask can be remapped to the x axis of the spectrum, though clearly this will only be reliable if the x axes are similar.

data, mask - stack numbers of the data and mask entities.

/remap - if the x axes of the data and mask entries are not identical then the masking will not proceed unless this switch is set. The mask is remapped to the x axis values of the data stack entry. No quality control is (currently) done on this so it's entirely possible to try to map to a different axis. Be sensible.

/pushremap - if remapping is in operation the remapped masks will be pushed to the stack for later analysis. This may be useful for quality control purposes.

quiet - set this keyword to suppress all message display.

opstatus - an integer optionally returned with a status code which is:

 

marquee_select, colour

Used by: zoomin

This function permits the user to draw a rectangle (selection marquee) on the current device to select an area of interest. The user clicks once to start drawing, and a second time to stop. The rectangle is updated in real time as the mouse moves, using XOR graphics to avoid leaving a permanent mark on the display as the mouse moves. The routine returns a 4 element array containing the lower and upper x/y values selected by the user.

colour - the index of the colour to draw the marquee selection area in.

 

ps_filename, prefix, suffix

Used by: dev

This function is used to determine the name to use when opening a PS/EPS file. If the user specified a filename then this is in prefix and the routine simply makes sure the file has the correct suffix. If no prefix is specified then a prefix of the form procspec.xxx is generated, where xxx is a serial number in the range 000-999. The serial number is incremented each time, based on the files already present in the current directory, via a FILE_SEARCH command.

prefix - either the user supplied filename, or blank to indicate using the default.

suffix - the correct file suffix.

 

ps_setup_colours [, /reload]

Used by: dev, procspec

This procedure initialises or resets the system colour tables. Since IDL uses different colour depths for X and PS devices, one must use different colour indicies depending on which device is in use. This routine initialises the crotinfo variable which contains information on the colours in use, and can also reset it when the device changes without affecting information like the crot status.

reload - set this keyword to force a reload of the colour table but leave all other colour information alone.

 

read_2cols_dbl(filename)

Used by: hhefit

This function reads in a plain 2 column ASCII file as double precision X,Y pairs, and returns them in an array. If the routine encounters an error of some sort then the single value '-1' is returned. This routine has been superceded by the alasrd routine.

filename - the name of the file to be loaded. If the filename ends in .gz it is assumed to be gzipped and will be decoded automatically by IDL.

Example:
test = read_2cols_dbl('path/to/my/file.dat')

 

tlabund, species, lambda, width, t, g, v, modestr [, lineid=lineid, /extrap, /quiet, opstatus=opstatus]

Used by: getvt

This function provides a simple interface to the results of the TLUSTY nonLTE grids. It's really part of the tlabund suite of routines, but is used in some of the nonLTE routines. It returns a two element array containing linearly and polynomially interpolated abundances, if an error occurred (eg. the line was not identified) then both abundances are returned as -1.

species - a string defining the element of interest. Should be one of 'c', 'n', 'o', 'mg', 'si'.

lambda - the wavelength of the line of interest. Should be within 1Å of the line centroid in the TLUSTY models.

width - the equivalent width of the line.

t, g, v - the effective temperature, surface gravity, and microturbulent velocity of the model atmosphere.

modestr - a string indicating the model grid to use. Must be one of 'nlgal','nlsmc','nllmc','nlmcb','ltgal', 'ltsmc', 'ltlmc', 'ltmcb' following the usual naming conventions.

lineid - set this to a named IDL variable which will be returned containing the name of the line used in the calculation in the form Si_3_412800, etc.

extrap - set this keyword to enable extrapolation in equivalent width/abundance space.

opstatus - an integer optionally returned with a status code which is:

quiet - set this keyword to suppress all message display.

Example:
theabund = tlabund('si',4128,55,20000,4,5,'nlgal') - calculate the Si abundance for a 55mÅ 4128Å line with a nonLTE galactic model of T=20000, log g=4, vt=5.

 

vsinifft_getfm([/ytoo])

Used by: vsinifft

This function performs an FFT on the contents of the current array and then tries to find the first minimum in the FFT. This is done by simply looking for the first point where the value of point n exceeds that of point n-1, and works OK for the FFTs of model spectra. With real spectra noise gets in the way and this may not work, but that's overridden in vsinifft anyway.

ytoo - by default the function returns the x value of the minimum. If this keyword is set then the function returns an array containing the x and values.