HMI_Logo 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:
  1. by using the DRMS dataset naming conventions, e.g.
    1. in= hmi.V_45s[2010.05.01_00:00:00_TAI-2010.05.01_00:59:15_TAI]
    2. in= hmi.V_45s[2010.05.01_00:00:00_TAI/1h]
    3. in= hmi.V_45s[2010.05.01_00:00:00_TAI/1h@3m]
    4. in= hmi.lev1[2010.05.01_00:00:00_TAI/1h][?FID=10078 and CAMERA=2?]
    5. in= hmi.lev0a[4612139,4612163,4612187,4612211,4612235,4612259,4612283] (Note 1)
    6. in= hmi.lev0a[4612139/240@24]
    7. in= aia.lev1_euv_12s[2010.05.13/1h@2m][94]
    8. in= mdi.fd_M_96m_lev182[2010.05.01/3d]
    9. in= hmi.B_720s[2010.05.01_00:00:00_TAI/6h]{field}
  2. 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.
    1. in= hmi.V_45s tmid= 2010.05.01_00:30:00_TAI length= 80
    2. in= hmi.V_45s tmid= 2096:250.90 length= 80
    3. in= hmi.B_720s{field} tmid= 2010.05.01_00:24:00_TAI length= 5
  3. by providing a series name (with optional segment specifier), a start and stop time and an optional time step value, e.g.
    1. in= hmi.V_45s tstart= 2010.05.01_00:00:00_TAI tstop= 2010.05.01_01:59:15_TAI
    2. in= hmi.V_45s tstart= 2010.05.01_00:00:00_TAI tstop= 2010.05.01_01:59:15_TAI tstep= 180
    3. in= hmi.V_45s tstart= 2096:251.18 tstop= 2096:250.63
    4. 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:
  1. 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
  2. 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)
  3. 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)
  4. if the time value associated with the keyword specified by the tobs_key is the same as that of the previous record
  5. 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
  6. 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
  7. 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.