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