astrohack.utils.fits
====================

.. py:module:: astrohack.utils.fits


Functions
---------

.. autoapisummary::

   astrohack.utils.fits.get_stokes_axis_iaxis
   astrohack.utils.fits.safe_keyword_fetch
   astrohack.utils.fits.read_fits_no_checks
   astrohack.utils.fits.read_fits
   astrohack.utils.fits.get_axis_from_fits_header
   astrohack.utils.fits.write_fits
   astrohack.utils.fits.put_resolution_in_fits_header
   astrohack.utils.fits.put_axis_in_fits_header
   astrohack.utils.fits.put_stokes_axis_in_fits_header


Module Contents
---------------

.. py:function:: get_stokes_axis_iaxis(header)

   Get which of the axis in the header is the stokes axis
   :param header: FITS header

   :returns: None if no stokes axis is found, iaxis if stokes axis is found


.. py:function:: safe_keyword_fetch(header_dict, keyword)

   Tries to fetch a keyword from a FITS header / dictionary
   :param header_dict: FITS header / Dictionary
   :param keyword: The intended keyword to fetch

   :returns: Keyword value if prensent, None if not present.


.. py:function:: read_fits_no_checks(filename)

   Brute force reading of a fits file, no checks are performed
   :param filename: Fits filename

   :return: FITS header as a dict and associated data


.. py:function:: read_fits(filename, header_as_dict=True)

   Reads a square FITS file and do sanity checks on its dimensionality
   :param filename: a string containing the FITS file name/path
   :param header_as_dict: return header as dictionary

   Returns:
   The FITS header and the associated data array


.. py:function:: get_axis_from_fits_header(header, iaxis, pixel_offset=True)

   Pull axis information from FITS file and store it in a numpy array, ignores rotation in axes.
   :param header: FITS header
   :param iaxis: Which axis is to be fetched from the header.
   :param pixel_offset: apply one pixel offset

   :returns: numpy array representation of axis, axis type and axis unit


.. py:function:: write_fits(header, imagetype, data, filename, unit, origin=None, reorder_axis=True)

   Write a dictionary and a dataset to a FITS file
   :param header: The dictionary containing the header
   :param imagetype: Type to be added to FITS header
   :param data: The dataset
   :param filename: The name of the output file
   :param unit: to be set to bunit
   :param origin: Which astrohack mds has created the FITS being written
   :param reorder_axis: Reorder data axes so that they are compatible with regular FITS ordering


.. py:function:: put_resolution_in_fits_header(header, resolution)

   Adds resolution information to standard header keywords: BMAJ, BMIN and BPA
   :param header: The dictionary header to be augmented
   :param resolution: The lenght=2 array with the resolution elements

   Returns: The augmented header dictionary


.. py:function:: put_axis_in_fits_header(header: dict, axis, iaxis, axistype, unit, iswcs=True)

   Process an axis to create a FITS compatible linear axis description
   :param header: The header to add the axis description to
   :param axis: The axis to be described in the header
   :param iaxis: The position of the axis in the data
   :param axistype: Axis type to be displayed in the fits header
   :param unit: Axis unit
   :param iswcs: Is the axis a part of World Coordinate System for the image?

   Returns: The augmented header



.. py:function:: put_stokes_axis_in_fits_header(header, iaxis)

   Inserts a dedicated stokes axis in the header at iaxis
   :param header: The header to add the axis description to
   :param iaxis: The position of the axis in the data

   Returns: The augmented header