vpguess

Introduction

Download

Installation

vpguess uses the cpgplot library for all graphics. Its FORTRAN base, PGPLOT, is pretty much standard but if you don't have it, you can get it here. cpgplot is the C extension of PGPLOT. Although it is included in the standard PGPLOT distribution, it is for some reason often not installed. If PGPLOT is installed on your computer, but cpgplot is not, then you need to get your system administrator to type make cpg in the PGPLOT directory (often /usr/local/pgplot). This will only work if the PGPLOT source or distribution directory has not been deleted. If the make was successful then the files libcpgplot.a (library) and cpgplot.h (header file) or links to them need to be put in the appropriate system directories so that your compiler can find them. These would be something like /usr/lib for the library and /usr/include for the header file.

It is also recommended to install this modification of the PGPLOT library to enable additional functionality for navigating the on-screen plots produced by vpguess. Specifically, the patch will allow you to use your mouse's scroll wheel to zoom in and out, drag the plot, and edit absorption lines more conveniently. This makes life quite a bit easier. It is, however, perfectly possible to install and use vpguess without this patch.

vpguess also needs the cfitsio and GSL libraries. Both are commonly used libraries and are part of ESO's scisoft collection. Hence they may well be installed on your system already.

Once these libraries are installed you should take a look at the Makefile in the src/ directory and edit it to suit your OS. In particular, if you have installed the PGPLOT patch mentioned above, then you should remove the -DNO_PGPATCH flag from CFLAGS to enable the additional functionality provided by the patch. Once you are happy with your Makefile you can type make in the src/ directory. This will produce the executable vpguess. This should be put in your bin directory (or somewhere else in your PATH). You can then type make clean to clean up.

Although vpguess can be used by itself it is primarily meant to help facilitate the interaction with VPFIT. If you plan to use vpguess in conjunction with VPFIT (see below) then VPFIT must be installed on your system. vpguess currently works with VPFIT version 10.2. There is no guarantee that it will still work with earlier VPFIT versions. You can get the VPFIT code and some installation hints here.
 

Environment variables

If you plan to call VPFIT from within vpguess you will have to let vpguess know where your version of VPFIT lives and what it is called. This is done by setting the environment variable VPG_VPFIT to the full path and name (something like /home/jliske/bin/vpfit) of the VPFIT executable that you wish to use with vpguess. If you don't have VPFIT then don't set the environment variable. In this case the command to fit ('F') will just fail harmlessly (but not quietly).

You can also set the variable VPG_ATOM_DATA to point to the atomic data file. If this is set you don't need the file atom.dat in your working directory. VPFIT uses its own environment variable (ATOMDIR) for the same purpose. If VPG_ATOM_DATA is not defined then vpguess will attempt use ATOMDIR instead.
 

Input files

From version 1.2 vpguess can read the spectral data and "associated arrays" either from ASCII files or from FITS files. In general, the "associated arrays" are the error array, the continuum and the sky (or background). However, the last is never used in vpguess and is included below only for completeness.

In addition to the spectral data itself, vpguess also needs corresponding error and continuum arrays. All error arrays are assumed to be 1 sigma unless variance is indicated (see below). Note that reasonable error estimates are important for meaningful fitting. Hence, if vpguess cannot find an associated error array (see below) then it will try to provide reasonable values by setting the error array to sqrt(data * (N_S^2 - SKY^2) + SKY^2), where N_S and SKY are parameters defined in spec.h. Once vpguess is up and running you can also use 'y' to create a new error array or to improve an existing one. If no continuum is found it is set to 1, i.e. the spectrum is assumed to be normalised.

ASCII files

Let's assume your data file is called foo. First, vpguess will look for a header file called foo.hdr. If the data file is called foo.txt (or .dat or whatever) then vpguess will check for foo.hdr, foo.hdr.txt and foo.txt.hdr. If found, the header file is assumed to be an ASCII file in FITS header style, i.e. each line is assumed to consist of a keyword name (maximum of 8 letters), followed by a '=', followed by a keyword value.

If a header file is present, then vpguess will search it for wavelength information (just as in the case of FITS data files, see below). So far, only linear and log-linear coordinate systems are supported. (The latter is used by the SDSS.) IRAF's MULTISPEC format is not (yet) supported. The wavelength info is simply derived from the header keywords CTYPE1, CRPIX1, CRVAL1 and CD1_1 or CDELT1. If the wavelength info is found in the header file then the data file does not need to contain a wavelength array.

If no header file is found or if it contains none of the keywords that define the wavelength scale, then it is assumed that the first column of the data file lists the wavelengths.

If a header file is present, then vpguess will also use it to try to figure out which of the columns in the data file contain the spectrum and associated arrays. The keyword names identifying the columns can be either BANDIDn, ROWn or ARRAYn, where n is a number between 1 and the number of columns in the data file. The values of these keywords should contain the words (case insensitive):

• spectrum: SPECTRUM or SPEC
• error array: SIGMA, SIG, ERROR, ERR, VARIANCE or VAR
• continuum: CONTINUUM or CONT
• sky: SKY, BACKGROUND or BKG

If this fails for the spectrum, i.e. if no header file is found or if it contains no identifier for the spectrum, then the spectrum is assumed to be stored in either the first or second column of the data file, depending on whether the wavelength information is specified in the header or not (see above).

If the above fails for one of the associated arrays vpguess attempts to use the appropriate default column defined in spec.h (taking into account the possible presence of a wavelength array).

If this also fails, i.e. if the specified column doesn't exist in the data file, then the associated array is sought in a separate ASCII file. For example, if the continuum cannot be identified/found and if the data file is called foo, then vpguess will look for a file foo.cont. If the data file is called foo.txt (or .dat or whatever) then vpguess will check for foo.cont, foo.cont.txt and foo.txt.cont. Similarly, if the error array cannot be identified in foo, then vpguess will try to find an error array in foo.sig, foo.err, foo.var and all the various combinations involving the data file's extension (if present). If the sky is missing, then the file extensions used for trying to find a sky (or background) array are .sky or .bkg.

The format of the .sig/.cont/.sky files is

To summarise: if you do not wish to use a header (.hdr) file then your ASCII data file should look like this:

FITS files

1D case:
In this case it is obvious where to get the spectrum. The associated arrays (error, continuum, sky) are first sought in other FITS extensions of the same FITS file. vpguess looks for the following extension names:

• error array: SIGMA, SIG, ERROR, ERR, VARIANCE, VAR
• continuum: CONTINUUM, CONT
• sky: SKY, BACKGROUND, BKG

If that fails vpguess looks for separate FITS files. If the data file is called foo.fit, then vpguess checks for foo.sig.fit, foo.err.fit, foo.var.fit, foo.cont.fit, foo.sky.fit, foo.bkg.fit.

As for ASCII files, vpguess never checks that the wavelength information in the various FITS extensions or files is the same.

2D case:
vpguess will first attempt to determine the positions of the spectrum and associated arrays along the second axis from FITS header keywords. The keyword names can be either BANDIDn, ROWn or ARRAYn, where n goes from 1 - length of second axis. The values of these keywords should contain either of the words SPECTRUM or SPEC for the data or the the extension names listed above for the associated arrays (all case insensitive). If this fails for the spectrum, i.e. if the identifying keywords (BANDIDn, etc.) do not exist in the header or if their values don't contain the 'magic' words, then vpguess reads the spectrum from the first row – unless the length of the second axis is > 9. In this case vpguess assumes that the file contains multiple spectra (as opposed to a single spectrum + associated arrays) and the user is queried for the position of the spectrum along the second axis.

If the identification process fails for the associated arrays (or if the length of the second axis is > 9), vpguess goes through the same process as in the 1D case (assuming that the separate FITS extensions or files are also 2D and using the same position along the second axis as for the spectrum). If this also fails, vpguess uses the default positions defined in spec.h (row 2 = error array, row 3 = continuum).

3D case:
First the user is queried for a position along the second axis. Then vpguess tries to determine the positions of the spectrum and the associated arrays along the third axis using FITS header keywords as above. If that fails the first position is used for the spectrum while the default positions defined in spec.h are used for the associated arrays (standard IRAF settings: band 4 = error array, band 5 = continuum).

Wavelength information:
So far, only linear and log-linear coordinate systems are supported. (The latter is used by the SDSS.) IRAF's MULTISPEC format is not (yet) supported. The wavelength info is simply derived from the FITS header keywords CTYPE1, CRPIX1, CRVAL1 and CD1_1 or CDELT1.
 

atom.dat

You need to have a copy of this file, or a link to it, in your current directory in order to be able to run vpguess. Alternatively, you can set one of the environment variables VPG_ATOM_DATA or ATOMDIR (or both) to point to it.
 

Getting started

Once vpguess is up and running you interact with it via single key strokes. Type '?' to get a list of all the available commands. Type all commands in the graphics window, not the terminal from which you started vpguess. The only exception is when you are in command line mode or when vpguess prompts you for input in the terminal. Here is a screen shot of what vpguess looks like in its simplest incarnation,

and here is a more complicated (and bigger) example. If the vpguess window is too large or too small for your screen, go back to the vpguess/src distribution directory and change the definitions of WW and/or WH (and/or LEWW) in the file vpguess.h to something more suitable for your screen. You then have to recompile vpguess by typing make.
 

Getting help

Interaction with VPFIT

Note that although VPFIT only accepts ASCII files in a particular multicolumn format you can still make use of the various formats and mechanisms for ASCII file input described above if you interact with VPFIT through vpguess.

As explained above already you should set the environment variable VPG_VPFIT to let vpguess know where VPFIT lives on your machine. If it is not set then vpguess will alternatively look for $HOME/bin/vpfit and ./vpfit. However, I recommend the use of VPG_VPFIT. If nothing else it allows you to have several versions of VPFIT without any danger of confusion. For example, if you have modified VPFIT in some way which makes it incompatible with vpguess, but you would still like to be able to use standard VPFIT through vpguess, then you would need to have two versions of VPFIT: your own version (probably called "vpfit") and one standard version compiled for use with ASCII files as explained above (called, e.g., vpg_vpfit). Simply point vpguess at vpg_vpfit by setting the VPG_VPFIT environment variable appropriately (full path name!) and there will never be any confusion.

Another requirement for vpguess to play nicely with VPFIT is to uncomment the parameter nopchan in VPFIT's setup parameter file vp_setup.dat, and to set it to 2 (see section 7 of the VPFIT documentation).

For those of you who know anything about VPFIT and wonder about the details of how vpguess interacts with it: when you hit the 'F' key vpguess first writes out a fort.13 (a "save file" in vpguess lingo). It then writes all the data chunks to temporary files (in the multicolumn format expected by VPFIT) to ensure that VPFIT will work on the same data (= spectra, error arrays and continua) that you see on the screen. Thus if you have made any modifications to the data after it was read in (e.g. with the 'n' key or other features that may be added in future) these will be passed on to VPFIT. This procedure also allows the use of .sig and .cont files which cannot be read in by VPFIT. Using a system call vpguess then fires up VPFIT in "file mode", giving it appropriate answers where they are expected. (If you ever want to change the answers supplied to VPFIT you need to edit the file vpgvpfitif.c and recompile vpguess.) Finally, when the fit is done vpguess reads in the results for the fitted parameters and displays the corresponding model spectrum.

VPFIT produces various outputs. First there is the screen output. Although this rather voluminous output can be quite annoying sometimes vpguess does not just pipe it to /dev/null but simply displays it in the terminal from which vpguess was called. I am told that some people are actually interested in the fit statistics, parameter errors and actual parameter values. Also, it may be useful to check that no error occurred during the execution of VPFIT. (In addition I guess it wouldn't be right to suppress VPFIT's copyright notice...) Secondly, VPFIT produces various files: fort.18 and f26.xxxxxxx, where the x's denote a random alphanumerical sequence. Note that fort.18 is only produced if nopchan=2 in VPFIT's vp_setup.dat. It is the fort.18 file that vpguess reads the fit result from.

If you like the idea of using vpguess to set up first guesses but would rather invoke VPFIT independently of vpguess (e.g. because you want to use some feature of VPFIT not currently supported by vpguess) then you can do so. Simply write out the results of your "guess work" to a save file (hit the 's' key). The resulting file is in the style of a VPFIT fort.13 and can therefore be used to fire up VPFIT. This procedure allows you to manually edit your guess work or add things which are currently not (fully) supported by vpguess.

VPFIT comes with its own atom.dat file. It is identical to the one included in the vpguess distribution (at least at the time of the current release). Read about it here.

VPFIT uses a Voigt profile generation routine that is less accurate (but faster) than that used by vpguess (see below). So the model spectrum displayed by vpguess is not exactly that fit by VPFIT.
 

Voigt function

To compute H(a,u) vpguess uses a Taylor expansion in a:
H(a,u) = sum_i=0 aⁱ H_i(u)
going to fourth order. High-density, high-accuracy lookup tables are used for the non-analytical functions H₁(u) and H₃(u) and an asymptotic approximation is used for u > 20. (Note: a given absorption line's contribution to the optical depth, tau, is only included for those parts of the spectrum where the line's tau is > 10^-7.) In those parts of the (a,u) parameter space probed by QSO absorption lines the above is more accurate than the method used by VPFIT by at least 2 orders of magnitude and is comparable to or better than the popular algorithm advanced by Humlicek (see Murphy's thesis for a direct comparison).
 

Some tips

• Make your data chunks as small as possible. Crop your spectra to remove as much as possible of the data which will not be used in the analysis. This will increase the speed of vpguess. You can use the '|' command for cropping. You may want to save ('Ctrl-s') the cropped spectra afterwards.

• On the other hand, don't remove too much! Make sure that you have 10 - 20 pixels on either end of each data chunk that will not be included in any fitting regions. The last few pixels of the model spectrum at either end of a data chunk will always be set to the continuum level because they are "polluted" by the convolution with the line spread function (unless the convolution has been turned off with the 'k' command).

• To add a continuum or zero level correction you can use 'CC' or 'ZC' respectively for the element id. The VPFIT notations '<>' and '__' (two underscores) work as well and these are also used in save files.

• When you are asked by vpguess for a file name either to write something to or to read something from, and if you prepend your answer with '!', then the rest of the answer will be interpreted as a system command. For example, if you answer '!ls' then vpguess will show you the contents of the current directory before repeating its query for the file name. Note that this implies that you cannot access files whose names begin with '!'. You can use the up and down arrow keys to access previous answers (history function) and the tab key for filename completion, just as in a shell.

• When you add an absorption line to the model you will be offered a list of ions to choose from. This list takes the form of a number of buttons that are displayed in the currently active panel. If the ion you want is not among the offered list, click "Other" and you will be prompted for an ion in the terminal from which you called vpguess. The format for the ion is a 2 letter code for the element followed directly (i.e. without a separating whitespace) by a 4 letter code for the ionization. Trailing white-spaces for the ionization may be omitted, but not for the element. Thus in order to get neutral hydrogen the correct sequence of key strokes is 'H' - 'space' - 'I' - 'return', where three trailing white-spaces have been omitted. To get MgII the sequence would be 'M' - 'g' - 'I' - 'I' - 'return'. A '?' at this prompt will produce a list of all the ions in your atom.dat file which you can use to check the code for the ion you want. Note that this facility can also be used to figure out which atom.dat you are using in case there are any uncertainties or confusion.

• When adding an absorption line to the model at some stage one is offered a list of transitions to choose from. This list takes the form of a number of buttons that are displayed in the currently active panel. For some ions (e.g. HI or FeII) there are a large number of transitions and the buttons may go off the top of the window if the currently active panel is fairly small and near the top of the window. If the transition you want is near the beginning of the list (e.g. Ly-alpha) then you can't select it because it isn't displayed! Solution: use the 'u' and 'j' keys to scroll the list up and down. This also works when choosing an ion in the previous step.

• When you're done editing an absorption line you need to quit the line control window by typing 'q' in order to get back to the main window.

• When you edit an absorption line you'll find that the column density will not be allowed to go negative and the b parameter won't be allowed to go below B_MIN = 0.2 km/s (defined in vpguess.h). However, redshift is allowed to go negative, which may useful when analysing ISM absorption lines.

• If you are editing an absorption line of which one or more parameters are fixed ('Z', 'N' and 'B' keys), then these parameter values are shown in red in the line editing window and you will not be able to edit them. The same is true for an absorption line whose parameters are tied to other lines unless the line is the reference or primary line. You can override this behaviour with the 'o' command (in the line editing window). Once you've hit 'o' the parameter name will still be shown in red but the value will be shown in yellow in order to remind you that you are editing a fixed (or tied) parameter. In general you should release the parameter before editing it or edit the primary line of the tie.

• The redshift of a continuum or zero level correction must be fixed. This will automatically be the case after you have added a correction (using the 'l' key). vpguess will not allow you to release the redshift of a correction by the use of the 'Z' key. Thus you have to use the override option mentioned above if you want to change the initial redshift of a correction, or else delete the correction and create a new one at the correct position instead.

• You can easily get an overview of the entire absorption model (fitting regions, line parameters, ties, fixes, etc) by typing 'I'.

• When you tie b parameters then every b parameter in the tie (including the reference or primary b parameter) is calculated from

  b^2 = v_turb^2 + f * T / m,

  where m is the element's atomic number and f = 2 * k / u / 10^-6 = 0.0166 (k = Boltzmann's constant, u = atomic mass unit). If during the tying you specified a non-zero value for v_turb, or if you specified a zero value for both v_turb and the temperature, then we have

  v_turb = whatever you specified
  T = max (0.0, (b(ref)^2 - v_turb^2) * m(ref) / f),

  where the (ref) refers to the reference or primary line of the tie. If on the other hand you specified a zero value for v_turb and a non-zero value for the temperature then we have

  T = whatever you specified
  v_turb = max(0.0, b(ref)^2 - f * T / m(ref)).

  Note that the above implies that when you specify a v_turb during the tying that is larger than b(ref), then b(ref) will be set to v_turb. Equivalently, if you specify v_turb = 0 and a temperature that corresponds to a thermal width larger than b(ref), then b(ref) is set to that thermal width.

  I believe that all of the above is consistent with the way VPFIT handles the tying of b parameters.

• The above also explains some slightly strange behaviour which is best explained using an example: say you have tied a bunch of b parameters together with v_turb = 20 km/s. Now you decide to edit the reference or primary line of the tie and you change the b parameter from whatever it was to, say, 15 km/s. When you hit 'f' or quit the editing window you'll find that the line now has b = 20 km/s although you have just set it to 15 km/s! That's because in a tie the v_turb or the thermal width implied by the temperature are the minimum b values that any of the members of the tie can take on (as explained above).

• Say you've just fitted a complicated absorption system with many components in FeII. Now you want to transfer the whole system to MgII. It would be quite tedious if you had to copy the system line by line with the 'c' command. Therefore I've introduced the 'C' command in version 1.1 of vpguess. It allows you to copy several lines to several different ions, so that if you are copying n lines to m ions then n*m new lines will be created. You also have the option to tie the redshifts and/or b parameters of the corresponding original and copied lines. If the redshift or b parameter of any of the original lines are already part of a tie, then the corresponding new lines will be included in the existing tie (but only if the option to tie parameters is selected by the user). If the redshift or b parameter of any of the original lines are fixed then the corresponding new lines will not be tied to them, even if this is requested.

• To 'F'it your model to the data (using VPFIT), remember that you first have to 'm'ark those regions of the data that you want to be used in the fit.

• If you ever want to change the resolution of a data chunk, i.e. the FWHM of the line spread function, then you have to unload the chunk with 'Ctrl-u' and then re-read it using 'Ctrl-r'.

• If you should ever compare a model spectrum produced by vpguess with some other program's spectrum for the same model, and if you should discover slight differences despite using the same atomic data, then the reason is probably due to different implementations of the Voigt function. Another reason could be be slight differences in the values of the natural constants (electron mass and charge, etc). vpguess uses the most accurate values for these constants that I could find (from Allen's Astrophysical Quantities, Fourth Edition) and they're listed in the header file const.h.

Known bugs

• Tying column densities is currently fairly meaningless since there is no mechanism in vpguess for storing abundances at the moment. Tied column densities are simply set equal at the moment. See also the VPFIT documentation on this topic.

• The 'a' command (toggle automatic window resizing) may crash vpguess.

• The following is not really a bug since this problem is inherently unavoidable: In theory there are an infinite number of HI transitions on the red side of the HI Lyman limit. However, the atomic data file atom.dat necessarily only contains a finite number of transitions. The missing transitions will cause some (usually small) part of the spectrum just above the Lyman limit to be modelled incorrectly. The size of this region depends primarily on the b parameter of the absorption line but it comprises at least the region between the last HI transition in atom.dat (currently Ly-31 at a rest wavelength of 912.645 A) and the Lyman limit (at a rest wavelength of 911.7634 A). vpguess deals with this problem by simply extrapolating the optical depth from beyond the Lyman limit across the affected region.

If you find a bug that is not listed here please let me know. See the README file that comes with the distribution for a list of bug fixes and changes.
 

Things to do and notes to myself

• The marking of lines whose parameters are tied is less than perfect.
• Column density ties are weird.
• Add MULTISPEC support.

License / Disclaimer

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.