.. include:: ../../idsubstitutions.txt

.. _VMPZIDHEALPixBitMask:



Output Product: HEALPix Bit Mask
=================================

$SetSchemaPath le3/id/vmpz/out/euc-le3-id-vmpz-HealpixBitMask.xsd

Data Product Name
__________________
.. DataProductNameStart

$PrintDataProductName

.. DataProductNameEnd

Data Product Custodian
_______________________
.. DataProductCustodianStart

$PrintDataProductCustodian

.. DataProductCustodianEnd

Name of the Schema File
________________________
.. NameSchemaStart

$PrintSchemaFilename

.. NameSchemaEnd

Last Edited for DPDD Version
____________________________
.. DpddVersionlTagStart

1.1

.. DpddVersionTagEnd

Processing Elements Creating / Updating / Using the Product
___________________________________________________________
.. PECreatorStart

**Creators:**

* VMPZ_Main (LE3_VMPZ_ID_Main)

**Consumers:**

* VMPZ_Visibility (LE3_VMPZ_ID_Visibility)

.. PECreatorEnd

Processing function using the data product
_____________________________________________
.. PFUsingStart

* 2PCF-WL, PK-WL, 2PCF-GC, 3PCF-GC, PK-GC, DET-CL, PROF-CL, VMSP-ID
* SWG-GC, SWG-WL, SWG-CL

.. PFUsingEnd

Proposed for inclusion in EAS/SAS
_________________________________

.. IncludeInSASStart

This product is proposed for inclusion in SAS: yes

This product is used by different PFs in OU-LE3 and expected to be used in scientific analysis in SWG-GC, SWG-WL and SWG-CL.

.. IncludeInSASEnd

Data Product Elements
______________________
.. DataProductElementsStart

$PrintDataProductElements

.. DataProductElementsEnd

Detailed Description of the Data Product
_________________________________________
.. DetailedDescStart

This output product contains essentially a container for a map for one or more flags
in the bitmask as defined in the `MER definition <https://euclid.roe.ac.uk/projects/eucrma/wiki/ImageBitMasks?parent=20120410UserStories>`_.

It includes in **BitMaskHealpix** a container with a FITS file (of type le3.id.vmpz.healpixbitmask)
describing the flag(s) selected, in partial HEALPix format (one bit per column),
for a given observed band/instrument (Euclid/EXT), and a raw description with polygons
of the envelope of the sky covered is added as well to ease future queries on the
product (**SpatialCoverage** metadata, see `spatialFootprint <https://gitlab.euclid-sgs.uk/ST-DM/ST_DataModel/-/blob/develop/ST_DM_Schema/auxdir/ST_DM_Schema/dictionary/bas/cot/euc-cot.xsd>`_).  The bit selected is also indicated in the product.
Finally, the mask parameters **BitMaskHealpixParams** can optionally be associated to the product.


Keywords (Primary HDU)
++++++++++++++++++++++

The primary HDU is expected to contain the following keywords, characterizing
important parameters of the input product:

$PrintPrimaryHeader fit/euc-le3-id.xml le3.id.vmpz.healpixbitmask

#. **DATE-OBS**: start of observation with format 'yyyy-mm-ddThh:mm:ss.sss' [StringKeyword]
#. **DATE-END**: end of observation with format 'yyyy-mm-ddThh:mm:ss.sss' [StringKeyword]
#. **TELESCOP**: name of the telescope [StringKeyword]
#. **INSTRUME**: name of the instrument [StringKeyword]
#. **FILTER**: name of the filter [StringKeyword]
#. **FILTLST**: selection of filter if intersection of multiple footprints [StringKeyword]
#. **TILEID**: identifier of the MER Tile processed (-1 if multiple Tiles) [IntegerKeyword]
#. **LISTID**: identifier of a MER list of tiles product (-1 if single Tile) [StringKeyword]
#. **NSIDE_WK**: Nside parameter used for frame->HEALPix [StringKeyword]
#. **BITSEL**: identifier of the bit of combination of bits reported in the bitmask
   (e.g. 0 for least significant bit,..,18) [StringKeyword]

   and basic software parameters:

#. **SOFTNAME**: name of software used [StringKeyword]
#. **SOFTVERS**: version of software used  [StringKeyword]

Partial HEALPix Footprint Table (First Extension, Binary Table)
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

The following keywords are used to describe what HEALPix conventions are followed:

$PrintHDUTableContents fit/euc-le3-id.xml le3.id.vmpz.healpixbitmask BIT_MASK

#. **TTYPE1**  (= 'PIXEL') [StringKeyword]
#. **TFORM1**  (= 'K') [StringKeyword]
#. **TTYPE2**  (= 'WEIGHT') [StringKeyword]
#. **TFORM2**  (= 'E') [StringKeyword]
#. **PIXTYPE** (= 'HEALPIX') [StringKeyword]
#. **ORDERING** (= 'RING' or 'NESTED') [StringKeyword]
#. **COORDSYS** (= 'C'=celestial, 'E'=ecliptic or 'G'=galactic) [StringKeyword]
#. **EXTNAME** (= 'BIT_MASK') [StringKeyword]
#. **NSIDE** [IntegerKeyword]
#. **INDEXSCHM** (= 'EXPLICIT') [StringKeyword]
#. **OBJECT** (= 'PARTIAL') [StringKeyword]

The table is then expected to contain the following columns:

#. **PIXEL**: index of pixel [K, int64]
#. **WEIGHT**: weight associated to pixel in [0,1] indicating the fraction of the pixel
   actually flagged by the bitN of the mask (1: fully flagged regions) [E, float32]

.. warning::
    We have here a solution where we collect just one bit/a combination of bits
    in the bitmask for a single band of an instrument in a partial HEALPix file.
    Note that the conversion frame->HEALPix implies that we lose the binary format
    if we want the fraction of sky flagged or not in a HEALPix pixel - and therefore
    we need the single bit products.
    The alternative is to have a vectorial form, e.g TFORM2='19E'

.. DetailedDescEnd