FITS file exchange system for kernel-analysis

Table of Contents

1 Motivation

As the kernel-analysis of data is maturing and being used in a couple different places across the world, it has become essential to define a data exchange format that can be be stored to disk and shared by collaborators, without having to repeat the kernel-phase extraction and initial massaging required prior to do the interesting data modeling of the data that leads to real science.

Kernel-phase is a somewhat abstract concept that confounds even interferometry experts that have somehow built an intuitive understanding of things very weird quantities like the closure-phase, which kernel-phase generalizes and therefore makes even weirder.

For a kernel-phase data-set to make any sense, it must be accompanied by some information that describe the properties of the virtual interferometric array used to build these quantities.

To achieve this, the Kernel-phase data exchange format uses a multi-extension FITS file structure. The first 5 extensions contain the information relevant to the virtual interferometric array (which will be refered to as the Kernel-Phase Information or KPI), eventually accompanied by Kernel-Phase Data or KPD.

2 Kernel-phase information

The following script assumes that the user has access to the discrete representation of the aperture of an instrument and that this model was well constructed, for instance using the xara.core.create_model() function call and following the recommendations provided in its documentation. The model is either a numpy array (if already loaded or freshly computed) or a comma separated text file. Refer the dedicated page to see how to create a kernel model.

The KPO constructor takes a pre-loaded model, stored in memory as a 3-column numpy array, and creates the first part of a KPD data structure, filling it up with information about the aperture, the uv-plane it corresponds to, the kernel-matrix and the baseline-mapping matrix. It then saves the structure as a fits file than can be lated reloaded:

#!/usr/bin/env python
import xara

cal = xara.KPO(array=model)
cal.save_as_fits("my_kernel_model.fits")

Note that the astropy.io.fits library supports gzip compression/decomression on the fly, the user may wish to save a compressed structure to save some disk space. To activate this, simply append the .gz extension to your file:

#!/usr/bin/env python
import xara

cal = xara.KPO(array=model)
cal.save_as_fits("my_kernel_model.fits.gz")

The content of the file that was just created can be visualized using fv: FITS Viewer and Editor. The structure of the file follows this architecture (numbers in the dimension column will of course differ depending on the details of your model):

>> fv ./my_kernel_model.fits &
Index Extension Type Dimension Remarks
0 Primary Image 0 Header only
1 APERTURE Binary 3 cols x 428 rows Header + data
2 UV-PLANE Binary 3 cols x 1000 rows Header + data
3 KER-MAT Image 1000 x 786 Header + data
4 BLM-MAT Image 427 x 1000 Header + data

Once saved as a fits file, the data structure can be quickly be reloaded:

#!/usr/bin/env python
import xara

cal = xara.KPO(fname="my_kernel_model.fits")

3 Kernel-phase data

The Fourier processing of an image or a group of images using the higher level methods of the KPO object in XARA will append extra data structures. At the moment, only the kernel-phases are committed to file: raw Fourier visibilities are not stored. If one were to take a look at the data structure of the saved fits file after extracting data out of a single file, here is what the structure looks like:

Index Extension Type Dimension Remarks
0 Primary Image 0 Header only
1 APERTURE Binary 3 cols x 428 rows Header + data
2 UV-PLANE Binary 3 cols x 1000 rows Header + data
3 KER-MAT Image 1000 x 786 Header + data
4 BLM-MAT Image 427 x 1000 Header + data
5 KP-DATA1 Image 786 x 1 Header + data
6 KP-INFO1 Binary 2 cols x 1 rows Header + data

Two structures were added:

  • KP-DATA1 contains the (here unique) realization of a kernel-phase vector. If several images forming together a single continuous observation (e.g. an ADI like observing sequence), the size of the array would change and include as many rows as there were files.
  • KP-INFO1 contains additional tid-bits of information that are useful to the observer: the orientation of the detector relative to the sky (when available in the image FITS header) and the modified Julian date of the observation.

If another file or group of files is added, it will create a second set of structures: KP-DATA2 and KP_INFO2

4 Covariance matrix!

TB added to the documentation!

Back to the documentation index

Author: Frantz Martinache

Created: 2019-11-03 Sun 18:13

Validate