HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications

mtrack

Module Version
	2.6	5 XI 2021

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.

Specification Details

Status
	Included in JSOC release 9.5
	In use for ring-diagram and time-distance pipelines 2021.11.05 –
	This version supersedes Version 2.5

	The source code and Makefile are  in the JSOC CVS repository

Usage
	mtrack [flags] 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
	-r	remove line-of-sight component of solar rotation from input data
	-v	run verbose
	-w	experimental run, with no reading of image data nor mapping nor
			output; just rapidly process input record key information
	-x	experimental run (do not insert records in output series)
	-G	use geocentric ephemeris for time of meridian crossing,
			regardless of data platform
	-M	use MDI keywords for input and correct for MDI distortion;
			use of MDI keywords not currently implemented
	-S	suppress correction of SDO Carrington longitude and position angle
	-Z	log times in UT (default is TAI)

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. Default: unspecified.

	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.

	sdofix		the name of a data series containing a corrected SDO
			observer ephemeris to be consulted if needed. The data series
			is expected to have keywords T_REC and CLON to be used for
			temporal interpolation of the Carrington longitude; other
			keys are ignored. Default: sdo.location

	bckgn		The record-segment identifier 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.
			to be tracked. Detrending is performed before the images
			are mapped.
			Default: unspecified, implying no background subtraction

	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.
			Default: unspecified, implying no rejection list

	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). Default: 0x80000000

	max_miss	The tolerance threshold for the value of keyword MISSVALS.
			If the value for an input record exceeds this value, that
			record will be skipped (treated as if it contained no data).
			Default: All (implies no check)

	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, or if the length
			parameter is not specified and both the tstart and tstop
			parameters are. Default: unspecified.

	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, or if the tmid parameter is not specified and both
			the tstart and tstop parameters are.
			Default: unspecified.

	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 and length parameters are
			specified. Default: unspecified.

	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 and length parameters are
			specified. Default: unspecified

	tstep		The temporal cadence of the output tracked cubes. If either
			the tmid and length or tstart and tstop parameters are
			specified, and if the keyword specified by tstp_key is constant
			or if the keyword specified by trec_key is slotted, tstep is
			assumed to be expressed in units of the input cadence; otherwise
			in sec. If the input data set is explicitly specified, tstep is
			assumed to be expressed in units of the original data cadence
			of the input series (not the time spacing of the explicitly
			specified input records!). If unspecified, defaults to the
			cadence of the input series. Default: unspecified.

	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, nearest (for nearest
			neighbor “interpolation”), and bilinear Default: cubiconv

	fillopt		Option for fill value used for missing frames; recognized
			values (strings) are interp, zero, and nan.
			Default: interp.

	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(s) of heliographic north on the output
			maps, measured westward (counter-clockwise), in deg. May be
			a comma-separated list of values corrresponding to the regions
			defined by the lat and lon arrays, in the same order. If the
			number of values is less than the number of regions, the last
			value will be applied to all succeeding regions. 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
			solar image semi-diameter (in pixels) at the time of
			observation in the input data series; Default: R_SUN

	apsd_key	The key name to be used for the key value representing the
			apparent solar semi-diameter (in arcsec) at the time of
			observation in the input data series; Default: RSUN_OBS

	dsun_key	The key name to be used for the key value representing the
			distance between the sun and the observer (in m) at the time of
			observation in the input data series; Default: DSUN_OBS

	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.

	cvkey		The key name to be used for the key value representing the
			calibration version in the input data series to be tested
			against values of cvok and cvno; Default: CalVer64

	cvok	 	The acceptable value of cvkey; Default: any

	cvno	 	The unacceptable value of cvkey; Default: none

	id_key		The key name to be used for the key value with which the Ident
			key value is to be associated; Default: ident

	ident		An identification string; Default: unspecified.
			If set to a non-default value; the value will be used to set
			the key values associated with the id_key value in all output records. 

Input Data series class:
	slotted time series of solar image data

Sample input series:
	hmi.V_45s
	mdi.fd_V

Input keys used or inspected:
	TELESCOP, MISSVALS, T_REC_index, trec_key*, tstp_key*, tobs_key*,
	clon_key*, crot_key*, clat_key*, rsun_key*, apsd_key*,  dsun_key*,
	CUNIT1, CUNIT2, CDELT1, CDELT2, CRPIX1, CRPIX2, R_SUN, OBS_ASD,
	CROTA2, S_MAJOR, S_MINOR, S_ANGLE

	* specified as module argument

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, Created, BLD_VERS, Backgrnd, RejectList,
	MapScale, Duration, Width, Height, Size, Map_PA, RSunRef, MAI,
	MDI_PA_Corr, PrimeKeyString

Input keys propagated to output (if possible) from last input record only:
	CONTENT

Sample output series:
	hmi.rdVtrack_fd05
	hmi.rdVtrack_fd15
	hmi.rdVtrack_fd30
	hmi.tdVsynop_HC
	mdi.rdVtrack_dp
	su_rsb.gentrack

Sample command:
	mtrack -v in= hmi.V_45s out= hmi_test.rdVtrack_cm30 \
	  tmid= 2099:180.0 length= 4608 cols= 384 rows= 384 scale= 0.08 \
	  map= Postel bckgn= hmi.V_avg120"[2099][180]" \
	  qmask= 0x80004000 reject = ~rick/hmi/qual/reject.V \
	  lat= "{-60.0, -45.0, -30.0, -15.0, +00.0, +15.0, +30.0, +45.0, +60.0}" \
	  lon= 180.0  \
	  mai= "{0.227, 0.630, 3.572, 2.324, 1.439, 2.390, 2.216, 1.019, 0.497}" 

Bugs in current version
	The removal of observer velocity is performed on mapped images, not the
	input, and the removed velocity applies only to the value at the map
	center. This is efficient for small tracked regions, but implies field
	inaccuracies over large regions.

	Image geometry for cases with unequal scales CDELti is not to be trusted

	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 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.

	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

	When the target cadence is much larger than the input cadence, many
	input records are read needlessly; likewise, if there are multiple
	records for the same reference time.

Significant Changes from Previous Version
	— Fixed non-initialization bug exposed when merid_v is non-zero

	— Added option for specifying different name of identifier key

	— Removed potentially dangerous frees of template records

	— Forced the use of localized serverdefs for locations of ephemeris tables.

Valid HTML 4.01 Transitional HMI Ring Diagrams 22 Sep 2023, 13:42-0700