HMI_Logo HMI Ring Diagrams
Pipeline Module Specifications

maicalc

Module Version
	2.0	25 IX 2016

General Description
	maicalc takes as its input a dataset of records representing solar
	magnetograms during a selected interval, and produces as its output
	the values of the Magnetic Activity Index (MAI) appropriate for a
	selected set of target locations as they would be mapped and tracked
	by mtrack for the duration of the input data interval and apodized by
	pspec3. The MAI values may be used as a set of input parameter values
	to mtrack, and will be used to set appropriate keyword values in its
	output data records.  Also writes an output file containing values at
	grid points of integrated values of Bz as well as |Bz| and the
	time derivatives of both.

Status
	This version has been superseded by Version 2.1

	Not included in any JSOC release
	In use for ring-diagram pipelines 2017.09.28 – 2018.02.09
	This version supersedes Version 1.1

	maicalc_v20 is a compiled standalone DRMS binary built with NetDRMS 9.1
	to run in the JSOC configuration. Versions are in:
		~rick/bin/rick/maicalc_v20
		~rick/bin/linux_x86_64/maicalc_v20
		~rick/bin/linux_avx/maicalc_v20
	The source code and Makefile is in ~rick/hmi/rings/src/versions/maicalc/

Usage
	maicalc [-nrv] los= DataDescriptor length= tracking length
	    scale= target tile mapping scale extent= target tile size
	    lat= target latitude(s) lon= target longitude(s)
	    [param= val ...]
	
Flags
	-l	list MAI values only on stdout
	-n	turn off tracking, just correct for any observer drift
		in the latitudinal direction
	-r	turn off spatial apodization
	-s	turn off despiking (elimination of outliers)
	-v	run verbose (overrides -l flag)

Parameters
	los		Either the name of an input LOS magnetogram data set (record
			selection) or the name of an input LOS magnetogram data series;
			in the latter case, tmid and length parameters must also be
			supplied. No Default, must be provided

	length	 	The length of the analysis interval, in units of the input cadence.
			 No Default, must be provided

	scale		The scale of the mapped region(s) at map center, in
			heliographic degrees per pixel. No Default, must be provided

	extent		Extent of the integrating analysis region(s), in 
			heliographic degrees. No Default, must be provided

	lat		An array of heliographic latitudes (in degrees) of the
			centers of regions at the midpoint of the tracking.
			If there is more than target, the comma-separated list must
			enclised in brackets, braces, or parentheses.
			If there are more lon values than lat values, the final
			lat value is replicated.
			No Default, must be provided

	lon		An array of heliographic longitudes (in degrees) of the
			centers of regions at the midpoint of the tracking.
			Default: [0.0]  If there are more lat values than lon
			values, the final lon value is replicated. Note that
			the target longitudes are Carrington, not Stonyhurst.
			No Default, must be provided

	los_seg		Name of the segment in the LOS magnetogram series containing
			LOS magnetograms. Default: unspecified, implies first of Rank 2.
	
	vec		Name of an input vector magnetogram data set or data
			series. Default: unspecified N. B. This option is not supported;
			the value will be ignored.

	mai		Name of an output data series for which records will be
			populated with appropriate keys.
			Default: unspecified, implying no record creation

	tmid		Midpoint of the target analysis interval, expressed either
			in standard DATE_TIME format or in CR:CL format.
			Default: unspecified; if not specified, then the values
			for cr and cl are used.

	cr		The Carrington rotation number at the target midpoint
			of the analysis interval. Default: current value.

	cl		The Carrington longitude of central meridian at the target
			midpoint of the tracking interval. Default: current value.

	qmask		A bit mask for image rejection aplied to the Quality
			keyword specified by qual_key; Default: 0x80000000

	reject		Name of a file containing a list of input magnetograms
			 to be rejected regardless of Quality.
			 Default: unspecified, implies none

	rec_step	The sampling step, in units of the input record steps.
			Default: 64

	max_reach	Maximum distance allowed from a rejected or missing record
			in the magnetogram dataset to an acceptable replacement record,
			in units of the rec_step value. Default: 0.5

	mask_in		The inner edge for a (1-r^2) apodization to be applied
			to the mapped regions; Default: 0.9765625

	mask_ex		The outer edge for a (1-r^2) apodization to be applied
			to the mapped regions; Default: 1.0

	apodize		Inner edge of a (1-t^2) temporal taper; Default: 0.96875

	floor		The "noise" floor below which data values are ignored for
			the sake of integration (gauss); Default: 50.0

	trec_key	The key name to be used for the key value representing the
			(slotted) prime key for reference time
			Default: T_REC

	tstp_key	The key name to be used for the key value representing the
			cadence associated with the reference times
			Default: CADENCE

	qual_key	The key name to be used for the key value representing the
			data quality word (a 32-bit mask used in conjunction with
			the qmask value for image rejection;
			Default: Quality

	clon_key	The key name to be used for the key value representing the
			observer Carrington longitude in degrees 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 in degrees 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
			Carrington rotation number appropriate to the observer
			central meridian at the time of observation in the input
			data series; Default: CAR_ROT

	rsun_key	The key name to be used for the image semi-diameter in
			pixels in the input data series; Default: R_SUN

	apsd_key	The key name to be used for the solar semi-diameter in
			arcsec in the input data series; Default: RSUN_OBS

	dsun_key	The key name to be used for the sun-observer distance in
			meters (to be used in conjunction with rsun_key in default
			of a keyword for apsd_key; Default: DSUN_OBS


Input Data series class:
	time series of solar magnetogram data

Sample input series:
	hmi.M_45s
	mdi.fd_M_96m_lev182

Comments:
	If tracking is turned off, the location of the target region will be
	appropriate for the midpoint of the tracking interval. For example, if
	the target interval ranges from central meridian longitudes 190–170
	and a target region is at Carrington longitude 150, the Stonyhurst
	longitude of the target would remain at 30° east for the duration of
	the analysis interval.

Sample command:
	maicalc los= hmi.M_45s mai= hmi.rdMAI_fd30 cr= 2100 cl= 180.0 \
          scale= 0.04 extent= 30.72 length= 4608 rec_step= 64 \
	  qmask= 0x8001c540 max_reach= 0.5 \
	  reject= /home/jsoc/hmi/tables/LHS_reject.m45 \
	  floor= 50 mask_in= 0.9765625 apodize= 0.96875 \
          lat= "{-60.0, -60.0, -45.0, -45.0, -30.0, -30.0, -15.0, -15.0, \
	      +00.0, +15.0, +15.0, +30.0, +30.0, +45.0, +45.0, +60.0, +60.0}" \
	  lon= "{120.0, 240.0, 135.0, 225.0, 150.0, 210.0, 165.0, 195.0, \
	       180.0, 195.0, 165.0, 210.0, 150.0, 225.0, 135.0, 240.0, 120.0}"

Significant changes from Previous Version
	Added the option for creating records in an output series with key values
	for the MAI and numerous associated quantities.

	Modified the algorithm for determination of the sampling interval to
	agree with that for mtrack, requiring a change of argument from interval
	(in units of Carrington degrees) to length (in units of the input cadence)

	Implemented temporal apodization weighting to agree with the form used
	for module pspec3, requiring the additional optional argument apodize,
	with the same default as for pspec3.
	
 	- Replaced argument ds with los

	- Added arguments los_seg, vec, mai, tmid, apodize, trec_key and tstp_key

	- Added flags -l and -s; removed flag -t

	- Replaced argument interval with length

	- Removed argument file

Bugs in current version
	Processing of vector magnetic field data is not implemented

	When there is a contribution from partial magnetograms such that there are
	no contributing pixels in one of the samples for a given tile, the reported
	area covered by large B is NaN. (Fixed in next version.)

	When there are no contributions from magnetograms to any pixel values
	(for example if the target region is always invisible), the reported
	accumulated values such as MAI are all 0.0 rather than NaN.

	Selection of input data records as a DRMS DataSet name is not supported;
	the los or vec parameter value should be a DataSeries name, and values
	for either the tmid or the cr, cl, parameters and the length parameter
	must be supplied. If a data record selector is included in the los or vec
	string, it is ignored.

	The los_seg parameter is not supported — it must be left unspecified.

	Time selection by Carrington Longitude is based on the Earth ephemeris

	The default value for the mask_in parameter is not the same as that for
	module pspec3, but rather the value used in the HMI rings pipeline
 
	There is no option for tracking at rates other than the Carrington rate
	(or not at all).

	Calculation of maximum distance from center of image may not be correct
	in case of no tracking.

	There is no option for mapping using a projection other than the Lambert
	azimuthal equivalent projection.

	When the tmid parameter is specified in CR:CL format (as it is in the
	ring-diagrams pipeline) or left unspecified in favor of the cr and cl
	parameters, the time center of magnetograms selected for analysis is
	that of the last record before the target time. This results in an
	average bias of the mean observation time of one-half of the magnetogram
	cadence before the target time. (This is consistent with the time bias
	for the corresponding tracked cubes.) For HMI, where the magnetogram
	cadence is 45 sec, the bias is inconsequential, but for MDI, where the
	magnetogram cadence is 96 min, the bias is quite substantial.

Valid HTML 4.01 Transitional HMI Ring Diagrams 22 Feb 2021, 12:44-0800