HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications

datavg

Module Version
	1.4	13 January 2015

General Description
	datavg averages the data from a selected segment in a set of DRMS records,
	constructing "images" (hypercubes of the same dimensionality as the input
	segment) of the mean value, the standard deviation, and the number of valid
	values for each pixel over the set.

Status
	Included in JSOC release 8.7
	In use for ring-diagram pipelines from 2014.10.10
	This version supersedes Version 1.3

	The source code and Makefile are in the JSOC CVS repository

Usage
	datavg [-nov] in= InputDescriptor out= OutputDescriptor
	    tmid= MidpointDescriptor length= LengthDescriptor
	    [param= val ...]
	
Flags
	-n	do not save output record (diagnostics only)
	-o	remove effects of observer velocity from data before averaging
	-v	run verbose

Parameters
	in		The name of an input data set (record selection) or series.
			If only a data series name is provided, then the parameters
			tmid and length must also be provided; otherwise they are
			ignored. If the input data series contains more than one
			segment, the name of the data segment to be averaged must be
			provided as part of the specification.
			No Default, must be provided

	out		The name of the output data series, which must already
			exist; record specification is based on the input data record(s)
			and the series prime keywords. No default, must be provided

	tmid		The midpoint value for tobs_key of the interval over which
			records are averaged; No valid default, must be provided if
			in is a data series. The module will convert the requested
			range specified by tmid and length to times that can be
			compared with the values of the tobs_key.

	length		The length of the averaging interval for the input data set,
			in degrees of Carrington longitude.
			No valid default, must be provided if in is a data series

	pa		The centre of the acceptable values of the roll-angle keyword
			CROTA2 [deg]; Default: 180.0

	dpa		The maximum permitted deviation from the pa value of the
			roll-angle keyword CROTA2 [deg]; Default: 1.0

	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: 0x8000000

	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. see mtrack; No valid default

	cvkey	 	The key name to be used for the key value representing the
			the calibration version bitmask to be used for acceptance
			or rejection; Default: CalVer64

	cvok		A value of the calibration version cvkey for which records
			are to be accepted for averaging; Default: any

	cvno		A value of the calibration version cvkey for which records
			are to be rejected when averaging; Default: none

	copy		A comma-separated list of keywords to be propagated as-is
			from the (first) input data record to the output. If the
			keyword "+" occurs in the list, the following default set
			of keywords will be propagated in addition to any others
			listed: TELESCOP, INSTRUME, WCSNAME, WCSAXES. N.B.: The WCS
			keywords CTYPEn and CUNITn are always propagated.
			Default: "+"

	average		A comma-separated list of keywords whose values are to be
			averaged over all accepted input data records and so set
			in the output. If the keyword "+" occurs in the list, the
			following default set of keywords will be averaged in
			addition to any others listed: T_OBS, SAT_ROT, OBS_VR,
			OBS_VW, OBS_VN. N.B.: The WCS keywords CRVALn, CRPIXn,
			CDELTn, and CROTAn are always averaged. For the averaged
			keyword XXX, an additional RMS keyword D_XXX will also be set.
			Default: "+"

	pkey		The key name to be used for the key value representing the
			index over which records are to be selected for averaging;
			Default: T_OBS

	qual_key	The key name for a 32-bit image quality field in the input data
			series;  Default: Quality

	roll_key	The key name for the quantity specifying the roll angle
			(position angle of solar north on the image) in the input
			data series;  Default: CROTA2

	count		Name of the output data segment containing the count of valid
			values at each pixel;  Default: valid

	mean		Name of the output data segment containing the mean of valid
			values at each pixel;  Default: mean

	power		Name of the output data segment containing the variance of valid
			values at each pixel;  Default: power

	setkey		Name of a special extra key to be set;  Default: Not Specified

	setval		The value to set for the key specified by setkey;
			Default: Not Specified

	mscale		Output BSCALE factor to be applied for mean segment, overriding
			default in output series;  Default: Segment Default

	mzero		Output BZERO offset to be applied for mean segment, overriding
			default in output series;  Default: Segment Default

	pscale		Output BSCALE factor to be applied for power segment, overriding
			default in output series;  Default: Segment Default

	pzero		Output BZERO offset to be applied for power segment, overriding
			default in output series;  Default: Segment Default


Input Data series class:
	This module should work with arbitrary types of data cubes in the input
	record segment; if the series contains multiple segments (of any type!),
	the segment to be averaged must be spceified as part of the input dataset
	name.

Sample input series:
	hmi.V_45s, hmi.rdVpspec_fd15, hmi.rdVpspec_fd30

Input keys used or inspected:
	OBS_VR, T_REC_index, WCSAXES

Output Data series class:
	Data statistics cubes: expected to contain three segments, named valid,
	mean, and power, with same rank and size (if not vardim) as input series

Sample output series:
	hmi.V_avg120, hmi.rdVavgpspec_fd15, hmi.rdVavgpspec_fd30

Output keys set (if possible):
	CarrRot, CMLon, MidTime, Module, BLD_VERS, Source, Input, Created, Interval,
	DataRecs, MissRecs, CountMIN, CountMAX, MeanMIN, MeanMAX, MeanAVG, MeanRMS,
	MeanSKEW, MeanKURT, PowrMIN, PowrMAX, PowrAVG, PowrRMS, PowrSKEW, PowrKURT
	COMMENT, HISTORY

Bugs in current version:
	The application of the optional orbital velocity correction is purely scalar;
	only the value of OBS_VR is subtracted from all image values, regardless of
	image location, and transverse components of the orbital velocity are ignored.

	There is no check that the propagated keys from the first input record have
	constant values in the input dataset.

	If the input dataset is specified explicitly in the in string, the keywords
	for CarrRot and CMLon are set to garbage, and there is no checking that the
	length is correct.

	The presence of generic segments in the input data series should not require
	specification of the segment name in the input data set.

	The reported extremal values of mean and power are determined before possible
	output scaling; they may be outside the representable range

No substantive changes from Previous Version
	(Code reorganization only)

Valid HTML 4.01 Transitional HMI Ring Diagrams 14 Jan 2015, 12:39-0800