NAME

geomagterp - Interpolate geomagnetic quantities

USAGE

geomagterp infile outfile geofile

DESCRIPTION

geomagterp takes a set of standardized geomagnetic quantities in FITS format and interpolates them onto an existing table.

The inputs are a FITS table containing a geomagnetic quantity, and a FITS table where the quantity is to be interpolated into. The output is the revised table with a newly interpolated column of geomagnetic quantities.

The geomagnetic quantities (geofile) are FITS tables such as Planetary Kp, DST storm index, F10.7 solar radio index. The inputs must be in FITS format in a certain structure. The intent is to make these available by HEASARC's CALDB, but that functionality is not ready at the moment. One quantity can be interpolated at a time.

The task takes an existing table (infile) with a TIME column, and adds new columns with a geomagnetic quantity using linear interpolation. The input file must adhere to the OGIP standard for temporal quantities. The task uses the TIME column and its units, along with TIMESYS, TSTART, TSTOP, TIMEZERO, and MJDREF to determine an accurate time system of the input file.

The output (outfile) is a revised table with one new column containing the interpolated geomagnetic quantity. If outfile=INFILE, then the input file is modified in place.

To aid users that keep a separate directory of geomagnetic quantities, this task keeps the "file" and "path" as separate input parameters, geofile and geopath. This may allow users to relocate the absolute directory (or even use remote https access) without changing the file portion. If geopath is a non-empty string, then it is prepended to geofile before geomagterp attempts to locate the file. Thus, users may either supply a geopath as an absolute path and geofile as relative; or using the default geopath="", geofile itself can be an absolute path.

PARAMETERS

infile [filename]
Name of the input file, which adheres to OGIP standards for temporal data.
outfile [filename]
Name of the output file, where the revised input table is to be placed. If outfile=INFILE then the input file is modified in place. NOTE that if the requested column name is already present in the output, then it will not be deleted, and instead the quantities in that column will be adjusted.
geofile [filename]
Name of the file containing geomagnetic quantities. To this name, the "geopath" parameter is prepended to find the location of the file.
(geopath="") [string]
Absolute path to the directory containing geomagnetic quantities. This path is prepended to geofile.
outname [filename]
Name of the output file. To overwrite a preexisting file with the same name, prefix the name with an exclamation point '!', or set the 'clobber' parameter = YES.
(outcol="INDEF") [string]
Name of the interpolated column in the output file. If INDEF, the name of the column in geofile is preserved.
(source="INDEF") [string]
Name of CALDB "SOURCE" to use if multiple sources are available for the same data type. Sorry, CALDB access is not ready yet, so this is ignored.
(tcheck=YES) [boolean]
If YES, then check for complete overlap between infile and geofile. If geofile does not completely temporally cover infile, then an error condition is generated. If NO, then the interpolation is done blindly, regardless of temporal coverage (not recommended).
(cleanup=YES) [boolean]
If YES, then clean up temporary files. If NO, then temporary files are preserved.
(clobber = NO) [boolean]
If outname already exists, then "clobber = yes" will overwrite it.
(history = yes) [boolean]
If set, HISTORY keywords are written to output.
(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

EXAMPLES

1. Execute geomagterp prompting the user for parameter values.

	geomagterp

2. Execute geomagterp interpolating from kp.fits to filter.mkf. The input file is modified in place using the outfile=INFILE option.

	geomagterp filter.mkf INFILE kp.fits

SEE ALSO

prefilter task for creating filter files.

LAST MODIFIED

January 2020