|
HMI Ring Diagrams
Pipeline Module Specifications
|
mtrack
Module Version
0.9 8 II 2010
General Description
mtrack takes as its input a dataset of records representing solar
image data observed at a uniform temporal cadence, and produces as
its output a set of records representing mapped cubes at selected
heliographic coordinates, tracked at selected rates for the duration
of the input data interval. The tracked data cubes provide the input
to pspec3 and all subsequent ring-diagram analysis procedures; they
also provide input to the time-distance analysis pipeline and possibly
other local analysis procedures. They may also be used for animations.
Status
This version has been superseded by Version 1.0
Included in JSOC release 5.7 as mtrack
This version supersedes Version 0.8
The source code and Makefile are in the JSOC CVS repository
Usage
mtrack_v09 [-cnorvxGM] in= InputDescriptor out= OutputDescriptor
[param= val ...]
Flags
-c track at Carrington rate (a0 = a2 = a4 = merid_v = 0)
-n turn off tracking, just correct for any observer motion
(a0 = -2.8653291, a2 = a4 = merid_v = 0)
-o remove line-of-sight component of observer velocity from input data
not currently implemented
-r remove line-of-sight component of solar rotation from input data
not currently implemented
-v run verbose
-x experimental run (do not insert records in output series)
-G use GONG keywords for input; not currently implemented
-M use MDI keywords for input and correct for MDI distortion;
use of MDI keywords not currently implemented
Parameters
in either the name of an input data set (record selection)
or the name of an input data series; in the latter case,
either tmid and length parameters or tstart and tstop
must also be supplied. No default, must be provided.
segment the name of the data segment to be used as input;
required if the input data series has more than one data
segment per record, otherwise ignored.
out the name of the output data series, which must already
exist; record selection is based on runtime parameters
and the series prime keywords. No default, must be provided.
bckgn The file name of a background image to be subtracted
from the data for purposes of detrending. If no value
is supplied, no detrending is performed. The background
image must be in the same format as the images.
Detrending is performed before the images are mapped.
reject The name of a file containing a list of records in the
input data series to be rejected for various reasons.
This is a list that can be prepared supplementary to
whatever quality/rejection criteria may be contained in
the records. The format of this file is to be specified.
qmask A 32-bit quantity specifying acceptable values of the quality
value of the key associated with qual_key. If the bitwise
and of qmask and the quality value for an input record is
non-zero, that record will be skipped (treated as if it
contained no data).
tmid The target midpoint of the tracking interval, which may
be expressed in either standard Date_Time format or in
CarringtonRotation:Longitude format (e.g. 1988:150.0),
in which case it refers to the central meridian crossing
time appropriate to the observing platform. Must be used
in conjunction with the length parameter. Ignored if the
in value is a specific data recordset.
length The length of the tracking interval, in units of the tstep
parameter, hence it corresponds to the number of timesteps
in the output data cube. Must be used in conjunction with the
tmid parameter. Ignored if the in value is a specific data
recordset.
tstart The target starting time of the tracking interval, expressed
in standard Date_Time format. Must be used in conjunction with
the tstop parameter. Ignored if the in value is a specific
data recordset, or if the tmid parameter is specified..
tstop The target ending time of the tracking interval, expressed
in standard Date_Time format. Must be used in conjunction with
the tstart parameter. Ignored if the in value is a specific
data recordset, or if the tmid parameter is specified..
tstep The temporal cadence of the output tracked cubes, in sec.
If unspecified, defaults to the cadence of the input series.
lat An array of heliographic latitudes (in degrees) of the
centers of regions at the midpoint of the tracking interval.
Default: [0.0] (If there is only one target, the enclosing
characters, which may be brackets, braces, or parentheses,
may be omitted. Target values are separated by commas.)
If there are more lon values than lat values, the final
lat value is replicated.
lon An array of heliographic longitudes (in degrees) of the
centers of regions at the midpoint of the tracking interval.
Default: [0.0] If there are more lat values than lon
values, the final lon value is replicated. Note that
the longitudes are Carrington, not Stonyhurst.
map The mapping projection option; recognized values are:
carree, Cassini, Mercator, cyleqa, sineqa, gnomonic,
Postel, stereographic, orthographic, and Lambert.
Default: Postel. This parameter, along with all of the
succeeding ones, applies to all output regions.
interp An option for spatial interpolation in the input images;
recognized values are cubiconv and nearest (for nearest
neighbor “interpolation”) Default: cubiconv
scale The scale of the tracked regions at map center, in
heliographic degrees per pixel. No default.
cols Number of columns in the output maps (pixels). Default: 0,
but at least one of cols and rows must be set non-zero; if
either is 0, it will be set to the value of the other, so
that the tracked region maps will be square.
rows Number of rows in the output maps (pixels). Default: 0;
see cols.
map_pa The position angle of heliographic north on the output
maps, measured westward (counter-clockwise), in deg.
Default: 0.
a0 The 0 order term in an expansion in sin^2 (latitude) of the
assumed rotation rate for tracking, minus the Carrington rate,
in μrad/sec. Default: -0.02893, which corresponds, along with
the defaults for a2 and a4, to the Snodgrass 1982/84 photospheric
Doppler rate. This parameter, along with a2, a4 and merid_v, is
ignored if either of the flags -c or -n is set.
a2 The 1st order term in the assumed rotation rate profile for
tracking.Default: -0.3441. See a0.
a4 The 2nd order term in the assumed rotation rate profile for
tracking .Default: -0.5037. See a0.
merid_v The assumed meridional velocity for tracking, in μrad/sec,
positive northward. Default: 0. See a0. Note that the
velocity in μrad/sec is about 0.0014368 times the meridional
velocity in m/sec.
bscale The scaling to be applied to output data stored externally as
short integers to convert to floating-point values. Default: 1.0
bzero The offset to be applied to output data stored externally as
short integers, after multiplication by bscale, to convert to
floating-point values. Default: 0.0
trec_key The key name to be used for the prime key of the input data
series, assumed to be a slotted time series; Default: T_REC
tobs_key The key name to be used for the key value representing the
midpoint of the record observation times in the input data
series; Default: T_OBS
tstp_key The key name to be used for the key value representing the
trec_key step size in the input data series; Default: CADENCE
qual_key The key name for a 32-bit image quality field in the input data
series; Default: Quality
clon_key The key name to be used for the key value representing the
observer Carrington longitude at the time of observation in
the input data series; Default: CRLN_OBS
clat_key The key name to be used for the key value representing the
observer heliographic latitude at the time of observation in
the input data series; Default: CRLT_OBS
crot_key The key name to be used for the key value representing the
observer Carrington rotation number at the time of observation
in the input data series; Default: CAR_ROT
rsun_key The key name to be used for the key value representing the
apparent solar semi-diameter (in pixels) at the time of
observation in the input data series; Default: R_SUN
mai An array of Magnetic Activity Index (MAI) values corresponding
to the regions defined by the lat and lon arrays, in the same
order; Default: [NaN]. These must have been calculated elsewhere;
they are only used for setting the MAI key values in the output
records. If the number of MAI values in the array differs from
the number of regions, the key values will not be set in any of
the output records.
Input Data series class:
slotted time series of solar image data
Input keys used or inspected:
TELESCOP, MISSVALS, T_REC_index, trec_key*, tstp_key*, tobs_key*,
clon_key*, crot_key*, clat_key*, CUNIT1, CUNIT2, CDELT1, CDELT2,
CRPIX1, CRPIX2, R_SUN, OBS_ASD, CROTA2, S_MAJOR, S_MINOR, S_ANGLE
* specified as module argument
Sample input series:
mdi.fd_V_lev18
Output Data series class:
tracked mapped data cubes from solar image data
Output keys set (if possible):
WCSNAME, WCSAXES, CTYPE1, CTYPE2, CTYPE3, CUNIT1, CUNIT2, CUNIT3,
CRPIX1, CRPIX2, CRPIX3, CRVAL1, CRVAL2, CRVAL3, CDELT1, CDELT2, CDELT3,
LonHG, LatHG, MapProj, Interp, MidTime, CarrTime, CarrRot, CMLon, CarrLon,
LonCM, T_START, T_STOP, LonSpan, Coverage, ZonalTrk, ZonalVel, MeridTrk,
MeridVel, Module, Source, Input, Backgrnd, RejectList, MapScale, Duration,
Width, Height, PosAng, RSunRef, MDI_PA_Corr, PrimeKeyString
Input keys propagated to output (if possible):
Sample output series:
mdi.rdVtrack_dp
Sample command:
mtrack_v09 -v in= mdi.fd_V_lev18 out= mdi.rdVtrack_dp \
tmid= 1988:180.0 length= 1664 cols= 128 rows= 128 scale= 0.125 \
bckgn= ~rick/avgs/vel/mdi/lev15/1988/1988:180/mean.fits \
reject = ~rick/soi/qual/reject.fd_V_01h \
lat= "{-30.0, -22.5, -15.0, -7.5, 0.0, 7.5, 15.0, 22.5, 30.0}" \
lon= "{150.0, 157.5, 165.0, 172.5, 180.0, 187.5, 195.0, 202.5, 210.0}"
Testing
The current version has been run extensively on local workstations
and on cluster nodes with input from typical MDI level 1.8 full-disk
Dynamics Doppler data and up to 195 1664-step 128*128 cubes tracked
at the Snodgrass rates. It has also been run extensively with input
from typical MDI level 1.5 high-res Doppler data with output of 8
5120-step 128*128 regions regions tracked uniformly and interpolated
to a 45-second cadence
Bugs in current version
Missing data are written as 0 rather than Nan
Checks for validity of tstart and tstop parameters are unreliable, due
to bugs in DRMS treatment of scans of invalid strings for times
(ticket #177).
Should free log, map
Will not accept an input dataset specification of @*
The image foreshortening corrections are appropriate for 1 AU, independent
of DSUN_OBS.
The input of the ellipse position angle has not been verified, but then
neither has the correction for ellipticity of the image altogether.
If there are multiple data segments of rank 3 in the output series, a
warning is generated and the first one is used.
The protocol of the Log segment, if present in the output series, is not
verified to be generic.
There is no verification that numerous essential key data are actually
in the input dataset, in particular trec_key, tobs_key, clon_key,
clat_key, and crot_key.
Uses private local FITS code rather than cfitsio for reading in
background image
When a target time and length are given, the actual number of records
may differ by one from the expected number; this only occurs if
the target time differs by a small but non-zero amount (< 0.1 sec)
from either the data record time or the midway point between data
record times. This happens for example, if the length is odd and
the target time differs from an actual observation time by more than
0.1 usec but less than 0.05 sec, with a 1-minute cadence.
The input data are unconditionally read in as floats (single-precision),
and the output data written as scaled shorts.
There is evidently no WCS conventional name for the Cassini-Soldner
(transverse plate carree) projection; CAS is arbitrarily used; the
alternative would be to interchange HGLT and HGLN, but that would
necessitate a change in the position angle.
The keyword unit for "Duration" in the output series is ignored, and
assumed to be "sec"; there are probably a few other keywords for which
there is a similar issue.
T_REC is not supported as an output key
Changes from Previous Version
Writes output by slices, avoiding massive memory allocation
Added code for nearest-value "interpolation" (untested)
Added processing of optional OBS_ASD key in place of R_SUN if missing
Changed defaults for output scaling to use output series defaults
Changed Duration key type from int to float
Reject images with MISSVALS != 0 (if present)
Fixed setting of ZonalTrk and MeridTrk keys, added corresponding ZonalVel
and MeridVel keys and RSunRef; added MDI_PA_Corr key; fixed setting of
Duration and CDELT3 keys
Adjusted Carrington rate (by 5 parts in 10^9)
Fixed setting of scaling when overrides in effect; support vardim output
by setting segment axis
Added argument rsun_key, verification of some essential keys
Added recognition of GONG site data origins, support for JPL table-based
ephemerides
Added processing of quality keyword against qmask
Added optional processing of MAI value(s) into keyword
Changed constituent of primekeystring from CarrTime to CarrRot and CMLon
Added setting of Size keyword (geometric mean of Height and Width) and
Cadence (= CDELT3) keyword
Key Differences from fastrack
The input and output data must be in DRMS data series rather than DSDS
data sets.
The target locations are calculated for the midpoint of the tracking
interval, not the start.