|
HMI Ring Diagrams
Pipeline Module Specifications
|
mtrack - Specification Details
Input
The input is required to be a set of records representing solar imagery
with sufficient metadata to permit mapping from the projected spherical
surface to another flat map whose location with respect to the images
varies in time following the assumed rotational or other motion of the
solar “surface”. In normal use the images are assumed to be consecutive
in time and equally spaced (with possible gaps suitably marked), but in
certain conditions this assumption can be relaxed. The input data set
can be specified in one of three ways:
- by using the DRMS dataset naming conventions, e.g.
- in= hmi.V_45s[2010.05.01_00:00:00_TAI-2010.05.01_00:59:15_TAI]
- in= hmi.V_45s[2010.05.01_00:00:00_TAI/1h]
- in= hmi.V_45s[2010.05.01_00:00:00_TAI/1h@3m]
- in= hmi.lev1[2010.05.01_00:00:00_TAI/1h][?FID=10078 and CAMERA=2?]
- in= hmi.lev0a[4612139,4612163,4612187,4612211,4612235,4612259,4612283] (Note 1)
- in= hmi.lev0a[4612139/240@24]
- in= aia.lev1_euv_12s[2010.05.13/1h@2m][94]
- in= mdi.fd_M_96m_lev182[2010.05.01/3d]
- in= hmi.B_720s[2010.05.01_00:00:00_TAI/6h]{field}
- by providing a series name (with optional segment specifier),
a target midpoint time, which can be in either standard date_time format
or in Carrington time format, and a length in units of the data cadence, e.g.
- in= hmi.V_45s tmid= 2010.05.01_00:30:00_TAI length= 80
- in= hmi.V_45s tmid= 2096:250.90 length= 80
- in= hmi.B_720s{field} tmid= 2010.05.01_00:24:00_TAI length= 5
- by providing a series name (with optional segment specifier), a start
and stop time and an optional time step value, e.g.
- in= hmi.V_45s tstart= 2010.05.01_00:00:00_TAI
tstop= 2010.05.01_01:59:15_TAI
- in= hmi.V_45s tstart= 2010.05.01_00:00:00_TAI
tstop= 2010.05.01_01:59:15_TAI tstep= 180
- in= hmi.V_45s tstart= 2096:251.18 tstop= 2096:250.63
- in= hmi.B_720s{field} tstart= 2010.05.01_00:00:00_TAI
tstop= 2010.05.01_00:48:00_TAI
Method (b) is used for both the ring-diagrams and time-distance pipelines,
(b.1) for time-distance and (b.2) for ring-diagrams.
Both methods (b) and (c) require that the input data series have a
time-like key, ordinarily T_REC, but it can be overridden with the trec_key
parameter, and a known cadence supplied by either (i) a constant "cadence"
key (CADENCE by default, but it can be overridden with the tstp_key parameter);
(ii) the T_REC_step key (or equivalent time-like prime key step) if the
"cadence" key is variable; or (iii) the default for the "cadence" key value
if it is variable and there is no time-like prime key. If none of those
is present, the input cadence is assumed to be the output cadence specified
by the tstep parameter, with unpredictable results for data selection (Note 2).
For method (c) only, if both the tstart and tstop
parameters are specified as data_time strings (not Carrington times),
they, along with the known cadence or the tstep parameter if present,
will be used to characterize the output times, and if they do not coincide
with the values of the input records the output will be time-interpolated;
otherwise the output times are adjusted to match those of the input times.
If multiple methods are implied by specifying more than the minimally
required parameter values, method (a) takes precedence over method (b),
which in turn takes precedence over method (c). Note that if the dataset
is not fully specified using method (a) and if tmid is specified, then
length must also be specified; likewise, if the dataset is not fully
specified using method (a) and if tmid is not specified, then both
tstart and tstop must be specified.
Note also that the tstep parameter refers to the output cadence, not
the input record selection, so (c.2) is not equivalent to (a.3). With
(a.3), only every fourth record in the input series (which has a 45-sec
cadence) would be read; with (c.2) every record in the input range would
be read, but only every fourth one used if the output times are exactly
matched to the inputs; if the output times are not exactly matched to
the input times, temporal interpolation would be effected in case (c).
Specification of the midtime or the start and stop times in Carrington time
requires the existence of appropriate ephemeris data to determine the time
of the relevant central-meridian crossing. Data tables exist for both the
geocentric ephemerides and the SOHO ephemerides, for which the times of
central-meridian crossing can differ by up to half an hour. Prior to v 2.3,
the locations of the relevant tables were “hard-coded” to refer to
paths in the JSOC system — not quite, as they were defines which could of course
be overridden at compilation. In version 2.3, the defines refer to values
established on a site-dependent basis in the NetDRMS config.local table
via the DRMS serverdefs.h file.
Input segment selection
For input series that contain more than one “relevant” data segment,
it may be necessary to specify the applicable segment name, either
explictly via the segment parameter, or via the dataset or series descriptor,
as in the examples shown above, with the segment name in braces following
the series name or record selector. Any 2-dimensional segment is considered
“relevant” If the input series contains more than one 2-dimensional segment,
the desired segment must be specified. Only one segment may be specified. If
the segment is specified via both the dataset/data series descriptor and
the segment parameter, they must agree. If the segment name is specified
it must exist in the data series (and be appropriate!).
Input record selection rules
Input records are ignored, and their corresponding planes in the output
cube filled, based on various criteria, in order:
- if the time value associated with the keyword specified by the tobs_key
parameter (T_OBS by default) is invalid, either a NaN or JD_0
- if the integer value associated with the keyword specified by the
qual_key parameter (Quality by default) bit matches any of the bits specified
by the qmask parameter (default 0x80000000)
- if there is a keyword MISSVALS and the value associated with it is
greater than the value of the max_miss parameter and that value is
non-negative (it is negative by default)
- if the time value associated with the keyword specified by the tobs_key
is the same as that of the previous record
- if an appropriately formatted file containing a list of records to be
rejected based on their value of the prime index key (e.g. T_REC_index) is
supplied by the reject parameter and the prime index key value is
in that list
- if either the 64-bit mask for the parameter cvno contains any 1's
(default all 0's) or the mask for the parameter cvok contains any 0's
(default all 1's), and there is a keyword corresponding to the cvkey
parameter (default CalVer64) and any of the bits in the corresponding
value matches any of those in the cvno mask or fails to match any of
those in the cvok mask
- if the call to read the data segment fails to return a data array
and there is no key associated with the qual_key parameter
(if there is such a key the program aborts in this case)
Temporal interpolation or fill
The time targets for the output planes begin with the value for the starting
time, specified directly as parameter tstart, calculated indirectly from
tmid, length, and data cadence, or as the value corresponding to the trec_key
parameter for the first record of an explicitly specified data set. They
are spaced by the value of the tstep parameter if specified, otherwise by
the input cadence, and end with the greatest value less than or equal to
the stopping time (specified similarly to the starting time).
There are three options for filling planes whose data may be missing by virtue
of a missing input record or a record being skipped for one of the reasons
enumerated above. The option is determined by the value of the parameter
fillopt, which can be "zero", "nan" or "interp",
"interp" being the default. If "zero" or "nan", the plane is filled with
0- or NaN- values, respectively. The normal fill is by pixel-by pixel
linear interpolation from the mapped values for the nearest accepted
records, or constant extrapolation if there are no accepted records before
or after the target for the plane to be filled.
Note that it is the value associated with the tobs_key rather than the
trec_key that determine whether a plane is to be filled or interpolated.
If these keys are different there is a likelihood that either all planes
will be interpolated (or worse, all planes blank-filled!). In order to avoid
this from happening, it is a good idea to use the same value for trec_key
and tobs_key. To avoid unnecessary interpolation the values from the tstart,
tstop, and/or tmid parameters are automatically adjusted to coincide with
the trec_key values. (This is especially important when they are specified
as Carrington times, which are unlikely to fall on the trec_key steps.)
When record selection is by the tmid/length method, there is a phasing
issue depending on whether the length (which is in units of the data
cadence) is an even or odd number. When it is odd, the target midtime should
of course simply be adjusted to the closest trec_key step to the target.
But when it is even it should be adjusted to the half-way point between
trec_key steps closest to the target. The actual midtime value used
has always been so adjusted, but in versions through 2.2 the reported
value for the keyword MidTime did not reflect the adjustment,
Consequently, if the midtime targeted by method b.1 coincided with an input
cadence step and the tracking length was even, the MidTime keyword
value reported would be consistently half a cadence step later than the real
value. If the target midtime was random with respect to the input time steps,
such as the case with midtime targets selected at fixed Carrington time
steps (method (b.2), the reported MidTime keyword value would be
on average half a cadence step later than the real value, being
reported to coincide with either the immediately preceding or the immediately
following input time step. This has been corrected in version 2.3.