Peakfind algorithm hierarchy

Semantics: Peakfind is a bit of an ambiguous word. Peakfind is the name of a software package used to fit mode-frequencies in m-nu power spectra. Peakfind II is the next generation of Peakfind, written in C, rather than SPP. However, Peakfind is also a term used for the entire processing sequence encompassed by this package. For simplicity MODEFREQ is used in this document to refer to the pipeline stage. If Peakfind is mentioned, it refers only to the mode-frequency fitting software.

Program directory contents

After the modefreq.YYYYMMDD.tar.Z file has been uncompressed and untarred, you should end up with a structure shown here:
	 |-- bin:  All Perl scripts, Iraf executables and symlinks
	 |         to compiled C-executables from src directory.
	 |         The environment variable $MODEFREQBIN is set to this
	 |	   directory when properly installed.
	 |-- src:  All source code for Peakfind II, Multitapers, 
	 |	   cfitsio library and other programs.
	 |-- dat:  All fixed information.  Includes Peakfind guess
	 |  	   table, standard table formats, standard file headers.
	 |-- RLIDL: Ritzwoller-Lavely IDL code.
	 |-- Scripts: Some handy user scripts.

Program hierarchy

 |-- MAKE3: Make 3 month timeseries
 |    |
 |    |-- Uses Iraf tasks from executables:
 |    |      x_grtools.e, x_images.e, xx_grhistory.e, x_dataio.e
 |    |      xx_tsneff.e
 |    |
 |    |-- MKVWT_LOWMEM: Uses x_images.e, xx_grhistory.e
 |    |     |-- CPHDR
 |    |
 |    |-- TSN
 |    |
 |    |-- PSERIES_MT: Uses x_grtools.e, x_images.e, xx_grhistory.e
 |          |-- MTGEN
 |          |-- TAPERMULT
 |-- MPEAK: Uses x_images.e
 |    |
 |    |-- PEAK: Uses x_images.e, x_grtools.e
      |-- PKANALYSE: Uses x_ttools.e
      |    |
      |    |- MFIT: Uses mfit.e, gongcon.e, x_ttools.e
      |-- RUNRL
	   |-- PROCJTA.IDL: Created on the fly.  Calls procedures from	
	   |      the RLIDL directory.
	   |-- MERGE_JTA

Output hierarchy

The output generated by PKALL, when run according to operating instructions is organized as follows:
WORKING DIRECTORY: PKALL is run from this directory
  |-- M??-?? (created by MAKE3) eg: M20-22. 3-month timeseries directory.
  |	 Contains mrv3t files
  |-- PS??-??_5t (created by MAKE3) eg: PS20-22_5t.  Multitapered 
  |      power spectra directory (mrvtp).  5t stands for "5 tapers".
  |         |
  |         |-- PEAKFIND: Raw peakfind tables (mrv1f*.tab) are
  |                stored in this directory.
  |			|
  |                     |-- ANALYSIS: Holds PKANALYSE output
  |                     |      (transitional files)
  |                     |       |
  |                     |       |-- MFIT: Holds MFIT output
  |                     |       |
  |                     |       |-- TXT: Holds finished data products
  |                     |                i.e.: mrv1f, mrv1y, mrv1z,
  |                     |                mrv1j and mrh1p.
  |                     |
  |                     |--IMAGES: Stores .fits output from Peakfind
  |                        Under current configuration, this directory
  |                        remains empty.
  |-- PS??-??_rotcor (created by MAKE3) eg: PS20-22_rotcor. 
  |      Rotation-corrected power spectra (psrtcr).
  |-- mrv3lYYMMDD.fits (created by MAKE3) eg: mrv3l970513.fits.
  |      Rotation-corrected m-averaged l-nu spectrum.
  |-- mrvwtYYMMDD.fits (created by MAKE3) eg: mrvwt970513.
         Window function image.

Program description

PKALL (Perl): This is the one-call way of running the MODEFREQ processing stage. It can be easily edited if processing parameters change, or if it is transferred to a new machine. Input data is read from a single one-month timeseries directory (it will create symbolic links if the data is in subdirectories within the directory specified). Output data is written in the directory hierarchy shown above. It generates symlinks to 1-month timeseries input files, then calls MAKE3, MPEAK, and finally PKWORKS. MPEAK (Perl): Spawns a user-specified number of instances of PEAK in parallel for a dataset, consolidates the output, and creates a history file. Can be called for a single instance of PEAK. It has the added advantage of logging peakfind's verbose output to a logfile. MPEAK2 (Perl): Same as MPEAK, but for Peakfind II. PKWORKS (Perl): Processes Peakfind output tables (mrv1f*.tab) to create data products (mrv1f*.txt, mrv1y*.txt, mrv1j*.txt and mrv1z*.txt) It calls PKANALYSE to remove leaks, flag bad peaks and produce Legendre and Clebsch-Gordon coefficients, then calls RUNRL to produce RL- coefficients. MTS.PL (Perl): A series of subroutines and variable definitions which are used in all of the Perl scripts above.

Description of data files

gong_months.dat: (Text) List of starting and ending dates for GONG months.

gong_nu_table.dat: (STSDAS table) Rotation coefficients for producing rotation-corrected m-nu power spectra. (STSDAS table) Initial guess table for Peakfind.

mrv0f980901.txt: (Text) Initial guess table for Peakfind II.

AAAREADME.tmp: (Text) Header for all mrv1f (mode-frequency) products.

cg.readme, leg.readme: (Text) Header for all mrv1y Clebsch-Gordon coefficients) and mrv1z (Legendre coefficients) data products respectively.

rltab.hdr: (Text) Header for all mrv1j (Ritzwoller-Lavely coefficients) data products.

asymmetric, gong: (TCREATE) Format specifiers for creating STSDAS tables from Peakfind II results. Used for 'nigam' asymmetric and 'lorentz' profiles respectively., cdfile.leg: (TCREATE) Format specifiers for creating STSDAS tables for Clebsch-Gordon and Legendre coefficient files respectively.

awksafe: (AWK) Used by PEAK2 to touch up mode frequency tables in order to make them machine readable for conversion to STSDAS tables. This involves changing Inf and NaN values to 0.

bad.dat: (TCALC) Script used by STSDAS software (x_ttools.e) in PKANALYSE to create 'bad' flag.

ierr.dat, conv.dat, dnu1.dat, dnu2.dat, freq.dat, merit.dat, power.dat, fwhm.dat: (TCALC) Used by PKANALYSE to evaluate peaks and provide data for bad.dat to generate 'bad' flag.

fhbad.dat: (TCALC) Used by PKANALYSE to create 'fhbad' flag.

fhb1.dat, fhb2.dat, fhb3.dat, fhb3b.dat, fhb4.dat: (TCALC) Used by PKANALYSE to evaluate peaks and provide data for fhbad.dat to create 'fhbad' flag.

grasp.par: (IRAF) This file reflects the status and version number of the executables in the GRASP system.

procjta_template: (IDL) This file is tacked onto the end of a variable definition header by RUNRL to create the PROCJTA.IDL file.

Handy scripts

A number of handy (albeit poorly documented) scripts are available in the MODEFREQ/Scripts directory:

To get the input argument format for any of these scripts, simply invoke them from the command line with NO arguments (with the exception of transdata which doesn't take any arguments).

dsetstats (Perl): Used to generate comparison statistics for two sets of finished MODEFREQ data products. It is useful for comparing results from Peakfind I with those from Peakfind II. For output from other fitting engines, you can reformat the output to look like MODEFREQ output. dsetstats will generate the following directory structure:

DIAG -- holds some temporary files, not of interest to user
  |-- totals: Holds all the statistics interesting to user.  Although
        there are many files in this directory, the following are of
        most interest:


        nu.txt:  Contains matching peaks n, l, m values
           and nu1, nu2: their frequencies in file1 and file2 respectively
        fwhm.txt: Contains matching peaks n, l, m values
           and fwhm1, fwhm2: their line-widths in file1 and file2 
        psamp.txt: Contains matching peaks n, l, m values
           and psamp1, psamp2: their peak amplitudes in file1 and file2 
        dnu.txt: n,l,m and dnu1, dnu2: freq. uncertainties
        dmfwhm.txt, dpfwhm.txt: n,l,m and dp(dm)fwhm1, dp(dm)fwhm2
           line-width uncertainties in plus/minus direction
        dmpsamp.txt, dppsamp.txt: n,l,m and dp(dm)psamp1, dp(dm)psamp2
           amplitude uncertainties in plus/minus direction


        To plot these histograms, read the first column into the x-
          axis and the second column into the y-axis, and generate
          a line plot using your favorite plotting package.

        nubinhisto.txt: ONLY ACCURATE for three-month (108-day) power spectra.
          Histogram of difference between mode-frequencies in the two
          datasets in units of frequency resolution (1 bin=~0.107 
        nuerrhisto.txt: Histogram of difference between mode-frequencies
          divided by error (error=sqrt(nuerr1^2+nuerr2^2)).  This
          histogram is ideally symmetric, centered on zero and has
          a full-width at half-maximum no greater than 2.
        fwhmerrhisto.txt: Same as above, but for full-width at half-
          maximum, except that each error is the average between
          dpfwhm and dmfwhm values.  These averages are then combined
          to yield the overall error as above.
        amperrhisto.txt: Same procedure as fwhmerrhisto.txt, but for
          psamp values.

        histogood1.txt, histogood2.txt: Number of good fits in first 
          and second datasets as a function of frequency, in 100
          microhertz bins.

pkcompare (Perl): Used by dsetstats. dsetstats runs a loop over the dataset, calling pkcompare for each file. You can use pkcompare if you only want to compare one l-value (one file). The source can/ be edited for l-nu fitting comparisons, or for different file formats. It produces the files nu.txt, dnu.txt, fwhm.txt, dpfwhm.txt, dmfwhm.txt, psamp.txt, dppsamp.txt, dmpsamp.txt (see descriptions above), among others, whose names should be sufficiently descriptive. oddpeaks1.txt and oddpeaks2.txt contain peaks in each file which had no match in the other file.

transdata (Perl): Used by dsetstats to generate input files needed to create histograms.

histo (Perl): Generates x and y coordinates for a line plot which will produce a histogram of a single-column file fed in as input.

PSERIES_LONG (Perl): The GRASP PSERIES script will run out of memory on timeseries larger than about 400 MB (approx l=110 for 360-day timeseries). This is due to an IRAF memory limitation. PSERIES_LONG splits the time-series up into chunks, calls GRASP PSERIES task and then stitches the power spectrum together again. It is slower than PSERIES , so it should only be used when necessary.

PSERIES_MT_LONG (Perl): See PSERIES_LONG description above. This script does the same thing as PSERIES_MT, except it is designed for timeseries which are too long for PSERIES to handle.

Documentation Main Page | FITS Header Parameter Descriptions | IRAF GRASP Help Pages

Revision: $Id: Peakfind_algorithm_hierarchy.html,v 1.3 2004/10/08 22:27:40 khanna Exp $