## page was created by Michael Turmon, JPL
= ARmask - HMI Active Region Full-Disk Masks =

== Overview ==

This is a full-disk data product that currently identifies magnetically active pixels.
The corresponding data product is `hmi.Marmask_720s`.  There is also a near-real-time data product, 
which is used to get timely space weather information, called `hmi.Marmask_720s_nrt`.

The `Marmask` data products are indexed by `T_REC`.

The mask is an integer (char, or `BITPIX = 8`) value at each pixel.
Currently the integer can be one of three values: 0 for off-disk, 1 for quiet, and 2 for magnetically active.

We use two image series, magnetograms (from `hmi.M_720s`) and intensitygrams (from `hmi.Ic_noLimbDark_720s`), to determine class
membership.  We have concentrated on magnetically active regions, so we rely on the magnetograms
almost exclusively to compute the masks.  The mask image is computed and stored in "focal plane" or image coordinates,
so mask values at a given ''(i,j)'' pixel correspond with magnetic activity noted at that ''(i,j)'' pixel.

== Methodology ==

The methods used were developed by Turmon, Pap, and Mukhtar (ApJ, 2002, 568(1), 396-407), and subsequently refined to allow for spherical geometry (Solar Phys., 2010, 262(2), 277-298).

The core idea is that the mask should optimize a function containing two terms, one for pixel-by-pixel agreement of 
the observed ''(M,Ic)'' values to what is expected for a given class, and another for smoothness across adjacent pixels.
The first term, which matches observed ''(M,Ic)'' values to the expected scatter for each class, is dominant in the calculation.
The smoothness term only affects mask values that are near the boundary between classes (i.e., have an ''(M,Ic)'' value that is
inconclusive).  Geometrical information is encoded in the smoothness term.

The overall effect does not correspond to a threshold rule on ''M'' and ''Ic''.  Boundaries between classes follow non-axis-parallel contours that are a property of the competition between the expected scatter of the two classes.

As noted above, the current processing uses the magnetogram almost exclusively.  The plot below shows the distribution of quiet Sun pixels (blue line) and magnetically active pixels (green line) versus magnetic field (x axis, in HMI Gauss).  The gray areas are pixels whose classification can be changed if the spatial cues in the objective function indicate that it would be beneficial enough.

[[http://sun.stanford.edu/~turmon/jsoc-wiki/classhist2-2011-feb-14-small.png]]

The method is implemented in a pipeline module called `hmi_segment_module`.  It requires about 40 seconds per 4096x4096 image.

== Example Images ==

This is a labeling and the corresponding magnetogram from 2011 February 14.

[[http://sun.stanford.edu/~turmon/jsoc-wiki/mask2011-02-14.png]]
[[http://sun.stanford.edu/~turmon/jsoc-wiki/mag2011-02-14.png]]

This is a detail from the same mask image.  It shows the structure at fine spatial scales.

[[http://sun.stanford.edu/~turmon/jsoc-wiki/mask2011-02-14-zoom.png]]

== Keywords ==

Besides standard HMI image keywords (observational geometry, WCS, observation time), we set
some mask-specific keywords.  

''Using the following keywords will allow your code to continue to 
work even if the mask value for the Active class changes in the future.''
Currently, `OFFDISK` is 0, `QUIET` is 1, and `ACTIVE` is 2, but this is likely to change.
Also, we find a quality measure, `ARM_QUAL`, which is currently nonzero only in the event of
evident trouble at the solar limb.  It is a bit-field which is analogous to 
`QUALITY` for level 1 images.

||'''Name'''||'''unit'''||'''Description'''||
||OFFDISK||none||Mask value for off-disk pixels||
||QUIET||none||Mask value for quiet sun pixels||
||ACTIVE||none||Mask value for active region pixels||
||NCLASS||none||Total number of distinct values allowed for this mask||
||ARM_QUAL||none||Quality of the mask (bitfield)||
||ARM_NCLN||none||Number of limb pixels reset to quiet (annulus width ARM_EDGE)||

We also find some mask summary statistics, such as the number of pixels declared to be
active and their total line-of-sight flux.
These can be useful for screening images.

||'''Name'''||'''unit'''||'''Description'''||
||AR_NPIX||none||Number of active region (AR) pixels in the mask||
||AR_SIZE||mH||Projected area of AR pixels on image in micro-hemisphere||
||AR_AREA||mH||De-projected area of AR pixels on sphere in micro-hemisphere||
||AR_MTOT||weber||Sum of absolute LoS flux within all AR pixels||
||AR_MNET||weber||Net LoS flux within all AR pixels||
||AR_MPOS||weber||Absolute value of total positive LoS flux in AR pixels||
||AR_MNEG||weber||Absolute value of total negative LoS flux in AR pixels||
||AR_MMEAN||gauss||Mean of LoS flux density over AR pixels||
||AR_MSDEV||gauss||Standard deviation of LoS flux density over AR pixels||
||AR_MSKEW||none||Skewness of LoS flux density over AR pixels||
||AR_MKURT||none||Kurtosis of LoS flux density (Gaussian = 0) over AR pixels||

Finally, we record some algorithm parameters for reproducibility.
These should be of interest only to developers and operators.

||'''Name'''||'''unit'''||'''Description'''||
||ARMCODEV||none||ARmask code version||
||ARMDOCU||none||ARmask code documentation||
||ARM_ITER||none||ARmask parameter: Iteration-count parameter vector||
||ARM_TEMP||none||ARmask parameter: Annealing computational temperature||
||ARM_ALFA||none||ARmask parameter: Alpha (per-class prior log-probability)||
||ARM_MODL||none||ARmask parameter: Classification model name||
||ARM_EDGE||none||ARmask parameter: Width of annulus at limb to possibly reset (pixels)||
||ARM_BETA||none||ARmask parameter: Mask spatial smoothness||



== Related Data Series ==
 . [[HARPDataSeries]]