diffspec - a suite of programs for the relative scaling of spectra Version 1.1.OSU May 1992 [RWP & BMP] Based on CHI_AUTO Version 1.0 by Ignaz Wanders & Ernst van Groningen of the Uppsala Astronomical Observatory. Modified for operation on Sun Microsystems SPARCstation computers and to provide a more friendly user interface by Richard Pogge of the Ohio State University Astronomy Dept. Users of this program should cite the original paper describing the algorithm: "An Algorithm for the Relative Scaling of Spectra", van Groningen, E., & Wanders, I. 1992, PASP, 104, in press [August issue] In 1999 it was ported to Linux using the g77 fortran compiler on a RedHat Linux 6.0 system. The port has been verified on the 6.1 and 6.2 releases of RedHat Linux. Some minor changes were made to the code to eliminate sloppy coding practices that prevented compilation under the more strict g77 compiler. --------------------------------------------------------------------------- Installation Instructions: 1) Unpack the compressed tar file using the tar command: % tar xvzf diffspec.tgz This will create the "Diffspec" directory tree and the package source code and installation scripts. Note: if you are on a solaris system with GNU tar, you can type % gtar xvzf diffspec.tgz Otherwise, if a version of tar that does not recognize the "z" option (z = uncompress on-the-fly), the you have to unzip the archive by hand before unpacking, like this % mv diffspec.tgz diffspec.tar.gz % gunzip diffspec.tar.gz % tar xvf diffspec.tar 2) cd to the "Diffspec" directory. You should see these files: File Comments ---------------------------------------------------------------------- 00README.txt This file NOTES.autodiff brief overview of autodiff NOTES.diffspec brief overview of diffspec source/ Main source code directory, with these files: autodiff.f Main program for the OSU version of the program diffspec.f main program for diffspec, a version of autodiff that uses a unix-like command/argument syntax to facilitate running autodiff in "batch mode" using shell scripts (OSU version) mkdiff.f Main program for mkdiff, a program to create diffspec configuration files via a user-input dialog. (OSU version) buildauto csh script to compile the autodiff executable builddiff csh script to compile the diffspec executable buildmkdiff csh script to compile the mkdiff executable conv_gauss.f program subroutine (general) covsrt.f program subroutine (general) find_min.f program subroutine (general) find_min_d.f program subroutine (general) find_min_f.f program subroutine (general) find_min_r.f program subroutine (general) fitpoly.f program subroutine (general) funcs.f program subroutine (general) gaussj.f program subroutine (general) lfit.f program subroutine (general) read_data.f program subroutine (Uppsala version) read_data2.f program subroutine (OSU version) read_init.f program subroutine (Uppsala version) read_init2.f program subroutine (OSU version) read_lamb.f program subroutine (Uppsala version) read_lamb2.f program subroutine (OSU version) shift_spec.f program subroutine (general) write_res.f program subroutine (Uppsala version) write_res2.f program subroutine (OSU version) wrout.f program subroutine (Uppsala version) wrout2.f program subroutine (OSU version) iosubs.f user I/O routines (OSU version) stdio.inc for iosubs.f (OSU version) bin/ Executable binaries. This is where the build files for the various packages deposit the working programs. plot/ Difference spectrum plotter (OSU version) plotdiff.f Main program buildplot csh script to compile plotdiff plotdiff.hlp brief help file for plotdiff defunct/ Defunct or debug code (OSU version) autodiff.F a large file with all subroutines included for testing purposes. Ignore unless you really need it. iraf2diff.f convert old-style (pre-v2.11) IRAF spectra into 3-column autodiff/diffspec ASCII format. Based on IRAF/imfort libraries, most likely won't work anymore. orig/ Original Wanders chi_auto source code Guaranteed not to compile on Sun or Linux, but may work on Alpha, Apollo, or VMS/VAX with the right f77 compiler. For reference only. ---------------------------------------------------------------------- 3) cd to the diffspec/source/ directory and build the executables: % buildauto % builddiff % buildmkdiff This will compile each of the subroutines and compile/link the main programs. If successful, you will have the executable files autodiff, diffspec, and mkdiff in the /Diffspec/bin/ directory. --------------------------------------------------------------------------- Notes: The input files for both object and reference spectra are assumed to be 3-column ASCII text files with no informational headers in the following format: lambda(1) flux(1) sigma(1) . . . . . . . . . lambda(N) flux(N) sigma(N) where: lambda = the wavelength flux = the flux at wavelength LAMBDA sigma = the uncertainty (sigma) of FLUX The assumptions about the input files are as follows: 1) The object and reference spectrum have a linear wavelength scale with pixels evenly spaced in wavelength, with a maximum of 1024 pixels. 2) Both the object and reference spectra have the SAME starting and ending wavelength, and the same dispersion (Angstroms/Pixel) (note that this does not mean that they are perfectly aligned in absolute wavelength, as the program will take care of that, but the input wavelength grids must be aligned). 3) A consequence of (2) is that both the object and reference spectra are assumed to have the same number of pixels. This may require trimming to a common size externally before handing the spectra off to the autodiff program. 4) The data in the SIGMAS column of the files have the same units as the data in the FLUX column (i.e., assumes absolute, not relative sigmas) --------------------------------------------------------------------------- Program Description: ------------------- We call our program autodiff to distinguish it from the original CHI_AUTO developed by Ernst van Groningen and Ignaz Wanders (see below). Comments below on the operation of this program are slightly edited from the comments in the original chi_auto program. Except for a few minor modifications required to ensure proper compilation and execution under ANSI-standard f77 (in particular, Sun f77 v1.4 and GNU g77), most of the source code was left untouched. Most of the modification has taken place in I/O routines (to accomodate local formats) and some user I/O routines to help ultimately streamline user input or batch-mode operation. This program fits a simple function to the difference between two spectra in the specified wavelength range, and calculates the Chi-Squared goodness of fit estimator. By varying a flux scaling factor, the amount of wavelength shift between the object and reference spectrum, and smoothing either the object or reference spectrum by a variable width Gaussian kernel to take into account differences in spectral resolution, the minimum Chi-Squared is determined using a conventional grid search algorithm (see Bevington, Data Reduction and Error Analysis for the Physical Sciences, McGraw-Hill, 1969, page 208ff - though the algorithms in this program were taken from those in Numerical Recipes by Press, Flannery, Teukolksy, & Vetterling). The search is performed twice, either smoothing (i.e., degrading the resolution of) the reference spectrum or the object spectrum. The lowest value found is used to calculate the output file. The program stops when the relative change in Chi-Squared from one step to the next is less than the "stopping criterion" provided by the user. The program prompts for the following input parameters in order. Typical values, where appropriate, are given in []'s: > "reference" spectrum file in 3 column ascii format: lambda, flux, rms > "object" spectrum to be scaled, same file format > starting wavelength of fitting region > ending wavelength of fitting region > initial estimate of the flux scale factor > initial estimate of the FWHM (in pixels) of the spectral Gaussian smoothing kernel [1.0] > initial estimate of the wavelength shift (in pixels) [0.0] > Grid search step size for the flux factor [0.01] > Grid search step size for the smoothing kernel FWHM [0.01] > Grid search step size for the wavelength shift [0.001] > Stopping (convergence) criterion [0.0001] When the computation is completed, it will also ask for > name of an output file to hold the difference spectrum and modified reference and object spectrum fluxes & sigmas A summary of the results is written to the file 'results' (in routine WRITE_RES). The 4 columns contain: > the Flux Ratio (i.e. for scaling the object spectrum) > the Gaussian smoothing kernel FWHM. if FWHM > 0 the object spectrum was smoothed if FWHM < 0 the reference spectrum was smoothed > the Wavelength Shift (applied to the object spectrum) > the value of Chi-Squared found when the stopping criterion was satisfied The "results" file is updated with each execution of autodiff, and thus provides a running record of the basic results of all difference spectrum runs since the results file was created. The modified spectra are written into a user-named output file which contains seven columns. The contents of these columns depend somewhat on the sign of the FWHM (see above). Unlike the original CHI_AUTO program, we have adopted our own, more-or-less uniform output format. For FWHM > 0 1. wavelength 2. flux difference spectrum (scaled/smoothed/shifted obj)-(ref) 3. one sigma rms of the difference spectrum 4. the fluxes of the reference spectrum (unmodified for FWHM>0) 5. the sigmas of the reference spectrum (unmodified for FWHM>0 6. the fluxes object spectrum fluxes (scaled/smoothed/shifted) 7. the sigmas of the modified object spectrum For FWHM < 0 1. wavelength 2. flux difference spectrum (scaled/shifted obj)-(smoothed ref) 3. one sigma rms of the difference spectrum 4. the fluxes of the SMOOTHED reference spectrum 5. the sigmas of the SMOOTHED reference spectrum 6. the fluxes object spectrum fluxes (scaled & shifted) 7. the sigmas of the modified object spectrum Modification History: The original CHI_AUTO program of Wanders & van Groningen was modfied to implement features of interest to the AGN Watch "group" at OSU, as well as to make the original CHI_AUTO source code compatible with the Sun version 1.4.X f77 compiler. The basic code was substantially unchanged, with most of the modifications were to user and data input/output routines, as well as to solve ANSI compatibility problems with the original source code. We call our version autodiff to distiguish it from the original CHI_AUTO program, but we hasten to emphasize that we are making claims as to its uniqueness or originality. All citations to use of this program should be to the paper van Groningen & Wanders 1992 (PASP, 104, in press [August issue]). Specific Modifications: 1992 May 15: First pass over original CHI_AUTO code to ensure compatibility with Sun f77 v1.4 ("ANSI" f77). The original used many Apollo, VMS, & f90 conventions. 1992 May 19: First test runs: corrected error in array declaration in FITPOLY subroutine that made f77v1.4 unhappy 1992 May 20: Made all I/O using the default trapping utility routines (rputil library) Made all Fortran error traps give explicit traceback info Added a flux autoscaling feature (original CHI_AUTO assumes that fluxes are de-scaled before being passed to CHI_AUTO). Changed output format to a uniform format useful to us at OSU 1999 July 20: Ported to g77 on a RedHat Linux 6.0 system. Later verified on RH6.1 and 6.2 systems. Removed dependence on the rputil libraries (see instead iosubs.f in the source directory).