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

Output Product: HEALPix Footprint Mask
============================================


Data Product Name
_________________
.. DataProductNameStart

DpdHealpixFootprintMaskVMPZ

.. 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-HealpixFootprintMask.xsd" target="_blank">euc-le3-id-vmpz-HealpixFootprintMask.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:footprintMaskHealpixVMPZ
:QualityFlags: object of type dqc:sqfPlaceHolder
:Parameters: object of type ppr:genericKeyValueParameters

.. DataProductElementsEnd

Detailed Description of the Data Product
________________________________________
.. DetailedDescStart

This output product is essentially the footprint of the survey for a given band/instrument. This product is equivalent
to apply *weights > 0* on the coverage mask.

The **FootprintMaskHealpix** metadata includes a container with a FITS file (of type le3.id.vmpz.healpixfootprintmask)
describing the footprint for the survey in partial HEALPix format,
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>`_).
Finally, the mask parameters **FootprintMaskHealpixParams** 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  |
   +----------+----------+----------------------------------------------------------------+-----------+



**Some Keyword not in FDM**
#. **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**: combination of bits reported in the bitmask (32 binary digits, each 0 or 1,
   following the standard most significant bit first convention) [StringKeyword]
   and basic software parameters:

*   **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** *FOOTPRINT_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** *FOOTPRINT_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 1 |    NA    |  FITS *E*  |
   +         +----------+---------------------------------+----------+------------+
   |         |  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** (= 'FOOTPRINT_MASK') [StringKeyword]
#. **NSIDE** [IntegerKeyword]
#. **INDEXSCHM** (= 'EXPLICIT') [StringKeyword]

The table is then expected to contain the following columns:

#. **PIXEL**: index of pixel [K, int64]
#. **WEIGHT**: weight associated to pixel (0 or 1) indicating the fraction of the pixel
   actually covered by the footprint (1: fully not observed regions) [E, float32]

.. DetailedDescEnd