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

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


Data Product Name
_________________
.. DataProductNameStart

DpdHealpixBitMaskVMPZ

.. DataProductNameEnd

Data Product Custodian
______________________
.. DataProductCustodianStart

IDVMPZ

.. DataProductCustodianEnd

Name of the Schema File
_______________________
.. NameSchemaStart

.. raw:: html 

    <a href="https://gitlab.euclid-sgs.uk/ST-DM/ST_DataModel/-/blob/10.0.4/ST_DM_Schema/auxdir/ST_DM_Schema/dpd/le3/id/vmpz/out/euc-le3-id-vmpz-HealpixBitMask.xsd" target="_blank">euc-le3-id-vmpz-HealpixBitMask.xsd</a>

.. NameSchemaEnd

Last Edited for DPDD Version
____________________________
.. DpddVersionlTagStart

2.0

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

:Header: object of type sys:genericHeader
:Data: object of type vmpzid:bitMaskHealpixVMPZ
:QualityFlags: object of type dqc:sqfPlaceHolder
:Parameters: object of type ppr:genericKeyValueParameters

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

.. table::
   :width: 100%

   +--------------------------------------------------------------------------------------------------+
   |                                    **HDU** *PRIMARY*: header                                     |
   +==========+==========+================================================================+===========+
   |          | **Name** |                        **Description**                         | **Value** |
   +----------+----------+----------------------------------------------------------------+-----------+
   | Keywords |  SIMPLE  |                                                                |  logical  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  BITPIX  |                                                                |  integer  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  NAXIS   |                                                                |  integer  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  EXTEND  |                                                                |  logical  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | DATE-OBS |          e.g. Start date for observations considered           |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | DATE-END |           e.g. End date for observations considered            |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | TELESCOP |                       e.g. Euclid or -1                        |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | INSTRUME |                         e.g. VIS or -1                         |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  FILTER  |                         e.g. VIS or -1                         |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | FILTLST  | index for combination of filters if intersection of footprints |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  TILEID  |              e.g. 5237, or -1 if not single tile               |  integer  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  LISTID  |               Product ID for a MER list of tiles               |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | NSIDE_WK |             Nside used for mosaic frame to HEALPix             |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          |  BITSEL  |   e.g. Bit mask selection applied based on MER binary values   |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | SOFTNAME |                                                                |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | SOFTVERS |                                                                |   string  |
   +          +----------+----------------------------------------------------------------+-----------+
   |          | SOFTINST |                                                                |   string  |
   +----------+----------+----------------------------------------------------------------+-----------+


Time use format as 'yyyy-mm-ddThh:mm:ss.sss' and basic software parameters are:

* **SOFTNAME**: name of software used [StringKeyword]
* **SOFTVERS**: version of software used [StringKeyword]
* **SOFTINST**: institute developing the software [StringKeyword]

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

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

.. table::
   :width: 100%

   +-----------------------------------------------------------------------------------+
   |                             **HDU** *BIT_MASK*: header                            |
   +================+================+=============================+===================+
   |                |    **Name**    |       **Description**       |     **Value**     |
   +----------------+----------------+-----------------------------+-------------------+
   |    Keywords    |    XTENSION    |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     BITPIX     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     NAXIS      |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     NAXIS1     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     NAXIS2     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     PCOUNT     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     GCOUNT     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |    TFIELDS     |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TTYPE1     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TFORM1     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TTYPE2     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TFORM2     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TTYPE3     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     TFORM3     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |    PIXTYPE     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |    ORDERING    |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |    COORDSYS    |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |    EXTNAME     |                             |       string      |
   +                +----------------+-----------------------------+-------------------+
   |                |     NSIDE      |                             |      integer      |
   +                +----------------+-----------------------------+-------------------+
   |                |    INDXSCHM    |                             |       string      |
   +----------------+----------------+-----------------------------+-------------------+

.. table::
   :width: 100%

   +-----------------------------------------------------------------------------------+
   |                        **HDU** *BIT_MASK*: 3 columns table                        |
   +=========+==========+======================================+==========+============+
   |         | **Name** |           **Description**            | **Unit** | **Format** |
   +---------+----------+--------------------------------------+----------+------------+
   | Columns |  PIXEL   |   Index of the HEALPix pixel cell    |    NA    |  FITS *K*  |
   +         +----------+--------------------------------------+----------+------------+
   |         |  WEIGHT  | Mask value, ranging from O to 2^32-1 |    NA    |  FITS *J*  |
   +         +----------+--------------------------------------+----------+------------+
   |         |  ERROR   |           Mask error value           |    NA    |  FITS *E*  |
   +---------+----------+--------------------------------------+----------+------------+


#. **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]

The table is then expected to contain the following columns:

#. **PIXEL**: index of pixel [K, int64]
#. **WEIGHT**: (unsigned integer) value associated to pixel in [0,2^32-1] indicating one or more flags in the bitmask [J, uint32]

.. DetailedDescEnd