MadcubaMap#

The MadcubaMap class is a specialized container for FITS file data and metadata, aimed for MADCUBA workflows. While it closely resembles Astropy’s CCDData class, it includes additional functionality that makes it tailored for working with MADCUBA products, but also versatile for many other FITS workflows.

Overview#

The MadcubaMap class is designed to:

  • Integrate FITS file data with metadata, including history from MADCUBA’s external history files.

  • Provide seamless compatibility with Astropy-based workflows by mimicking the behavior of CCDData.

Core Attributes#

The MadcubaMap class stores FITS information in several attributes, some of which are identical to those contained in a CCDData object:

  • data: The array containing the FITS image data.

  • header: The FITS header object, storing metadata about the observation.

  • wcs: The World Coordinate System (WCS) information for the FITS file.

  • unit: The physical unit of the data, derived from the FITS header’s BUNIT keyword.

  • restfreq: Rest frequency of the FITS file.

  • integrated_range: Velocity or frequency range selected for integrating the map.

  • sigma: The measured noise of the data.

alongisde additional attributes:

  • hist: Stores information from MADCUBA’s history file.

  • filename: Filename of the FITS file. Used for tracking several operations performed on the file.

  • ccddata: A CCDData object representing the same FITS data. Used as a failsafe for incompatibilities with MadcubaMap.

Note

Modifying a MadcubaMap object attributes manually will also set the same attributes into the underlying CCDData object. However, due to compatibility reasons, the opposite is not the case. Changes in a MadcubaMap.ccddata attributes will not be reflected onto the MadcubaMap object. Users are encouraged to work with MadcubaMap directly and only use the ccddata attribute as a failsafe in workflows that raise errors when using a MadcubaMap instance.

Examples#

Create an instance by reading a FITS file through MadcubaMap.read() (recommended method):

>>> from madcubapy.io import MadcubaMap
>>> madcubamap = MadcubaMap.read("example_cube.fits")

Note

Due to how MADCUBA saves some fits header cards, several astropy warnings can pop up when reading fits files. Usually these warnings are unexpected card names using non-standard conventions.

We can also create an instance manually by providing any attribute stated before, for example:

>>> import numpy as np
>>> madcubamap = MadcubaMap(data=np.array([[1, 0, 0], [0, 1, 0], [0, 0, 1]]))

To access attributes, the data for example, we can call them directly:

>>> madcubamap.data

The history information is present in the hist attribute:

>>> madcubamap.hist

For a fully fledged example on how to work with a MadcubaMap object, check the begginer’s tutorial on how to read and plot FITS files using MadcubaMap.

Compatibility with CCDData#

The ccddata attribute provides a failsafe for scenarios where functions are incompatible with the MadcubaMap class. By accessing this attribute, users can work with a standard CCDData object while retaining access to the original FITS data:

We can directly use this attribute or set a variable to point to its content:

>>> ccd = madcubamap.ccddata

Quality-of-Life Features#

The MadcubaMap class also introduces methods and functions that improve usability and accuracy when working with FITS files (even non-MADCUBA products):

  • Correction of data units

    Fixes improperly formatted units in the BUNIT header card, ensuring compatibility with Astropy. We can tell the program to try to fix the units with the fix_units() method:

    >>> madcubamap.fix_units()

  • Noise measurement

    The user can measure the noise level of an image with the update_sigma() method.

    >>> madcubamap.update_sigma()

    The map is shown in pop-up window where the user can select several polygons using the mouse. This method automatically calculates the noise value inside the polygons and stores it in the sigma attribute and adds it to the FITS header using the ‘SIGMA’ keyword.

    This method calls the measure_noise() function on itself to calculate the noise level. Check the documentation page for a detailed overview on the noise measurement functionality, or take a look into the Measure noise of a FITS file tutorial for a beginner friendly explanation on the basics.

  • Quick map visualization

    The user can quickly take a look at a map in a pop-up window using:

    >>> madcubamap.show()

  • Extensibility

    New features will continue to be added, enhancing its capabilities for FITS file workflows.

Why Use MadcubaMap?#

Advantages Over CCDData#

The MadcubaMap class provides the following benefits:

  • Integrated History: Combines FITS data with history files for a unified representation.

  • Improved Compatibility: Fixes common issues in FITS files, such as improperly formatted BUNIT keywords.

  • Added Functionality: Built-in features like noise level calculation simplify data processing.

Beyond MADCUBA#

While designed for MADCUBA workflows, the MadcubaMap class is suitable for general-purpose FITS file processing. Its features make it a powerful tool even for FITS files unrelated to MADCUBA.