mangadap.util.fitsutil module

Defines a class with common functions for MaNGA fits files. This class needs to be as core as possible (little to no dependencies are higher-level classes).

class mangadap.util.fitsutil.DAPFitsUtil[source]

Bases: object

An abstract class that only implements a set of static methods for interaction with MaNGA fits files.

Todo

Make this a base class for all the fits files used/created by the DAP?
Use HDUList as a base class for this object?

static _mask_data_type(bit_type)[source]

static add_channel_names(hdr, names, units=None)[source]

static build_cube_header(cube, author, maskname=None)[source]

static build_map_header(hdr, author, multichannel=False, maskname=None)[source]

static clean_cube_header(hdr)[source]

static clean_dap_primary_header(hdr)[source]

static clean_map_header(hdr, multichannel=False)[source]

static copy_to_array(hdu, ext='FLUX', allowed_ext=None, waverange=None, select_bins=None, missing_bins=None, nbins=None, unique_bins=None)[source]

Return a copy of the selected data array. The array size is always \(N_{\rm spec} \times N_{\rm wavelength}\); i.e., the CUBE files are flattened to two dimensions, matching the dimensionality of the RSS files. The spatial positions within the original DRP file for each spectrum are given by tuples in spatial_index. See copy_to_masked_array() for arguments.

Returns:: A 2D array with a copy of the data from the selected extension.
Return type:: numpy.ndarray

static copy_to_masked_array(hdu, ext='FLUX', mask_ext=None, flag=None, bitmask=None, allowed_ext=None, waverange=None, select_bins=None, missing_bins=None, nbins=None, unique_bins=None)[source]

Return a copy of the selected data array as a masked array. This is functionally identical to DRPFits.copy_to_array(), except the output format is a numpy.ma.MaskedArray. The pixels that are considered to be masked can be specified using the flag option.

Parameters:

waverange (array-like) – (Optional) Two-element array with the first and last wavelength to include in the computation. Default is to use the full wavelength range.
ext (str) – (Optional) Name of the extension from which to draw the data. Must be allowed for the current mode; see spectral_arrays. Default is ‘FLUX’.
mask_ext (str) – (Optional) Name of the extension with the mask bit data. Must be allowed for the current mode; see spectral_arrays. Default is ‘MASK’.
flag (str or list) – (Optional) (List of) Flag names that are considered when deciding if a pixel should be masked. The names must be a valid bit name as defined by the provided bitmask (see mangadap.util.bitmask.BitMask). If not provided, ANY non-zero mask bit is omitted.
bitmask (mangadap.util.bitmask.BitMask) – (Optional) BitMask object used to determine if pixel is flagged as being masked by a specific maskbit.
allowed_ext (array-like) – (Optional) List of allowed extenstions that can be copied to an array; the mask extension must be one of these.
waverange – (Optional) A two-element array with the valid wavelength range. Anything outside of this range is masked.
select_bins (array-like) – (Optional) A list of spectra in the flattened cube (with shape \(N_{\rm spec} \times N_\lambda\)) to return.
missing_bins (list) – (Optional) A list of bin numbers that are missing from the output selection and that will be replaced with masked spectra.
nbins (int) – (Optional) The total number of defined bins. Default is to find the maximum number in the unique_bins list.
unique_bins (array-like) – (Optional) The indices of the bins that have valid spectra. The length of this array should match the selected_bins array.

Returns:

A 2D array with a copy of the data from the selected extension.

Return type:

numpy.ndarray

Raises:

KeyError – Raised if ext is not a valid extension.

static downselect_bins(bin_indx, good_bins)[source]: Replace values in bin_indx with -1 if they are not in good_bins.

static empty_hdus(ext)[source]

static finalize_dap_header(hdr, ext, bunit=None, hduclas2='DATA', err=False, qual=False, multichannel=False, bit_type=None, prepend=True, channel_names=None, channel_units=None)[source]

static get_spatial_shape(shape, dispaxis)[source]

Return the shape of the spatial axes given the specified dispersion axis.

Parameters:

shape (tuple) – Shape of the full numpy.ndarray object.
dispaxis (int) – Axis with the spectra.

Returns:

Shape of the remaining axes.

Return type:

tuple

static initialize_dap_primary_header(cube, maskname=None)[source]

static list_of_image_hdus(data, hdr, ext)[source]

static marginalize_mask(mask, inp_flags=None, inp_bitmask=None, out_flag=None, out_bitmask=None, out_mask=None, dispaxis=2)[source]

Marginalize a mask over one of its spectral dimension.

The output mask selects pixels that are masked by all pixels along the spectral axis.

If no optional arguments are provided, the input mask must be a boolean array and the result is identically numpy.all(mask, axis=dispaxis).

Parameters:

mask (numpy.ndarray) – The mask with more than 1 dimension. The spectral axis is defined by dispaxis. The array can be either a bitmask or a boolean mask; the latter is assumed if inp_bitmask is not provided, and vice versa.
inp_flags (str, list, optional) – The list of input flags used to select masked values in bitmask arrays. If None and inp_bitmask is provided, all flags are check individually.
inp_bitmask (BitMask, optional) – Object used to identify bits in the input mask.
out_flag (str, optional) – If returning a bitmask, this sets the flag to use to identify the masked pixels. If None and inp_bitmask is provided, the output flags are identical to the input flags.
out_bitmask (BitMask, optional) – Object used to identify bits in the output mask.
out_mask (numpy.ndarray, optional) – If provided, any masking is applied directly to this array; i.e., this is both modified and returned by the function. If provided, the array must have the correct shape (same as the input array wihtout the spectral axis).
dispaxis (int, optional) – The spectral axis of the array.

Returns:

A mask array with the marginalized mask. The shape is the same as the input array, but without the spectral axis.

Return type:

numpy.ndarray

Raises:

ValueError – Raised if the input arrays have incorrect shapes.

static match_image_naxis(hdu, ext=None)[source]

Match the NAXISn header keywords to the shape of the image data. That is, reset the header keywrods such that the shape of the data array is (NAXIS1, NAXIS2, NAXIS3, …).

Note that any reordering of the NAXISn keywords will not change the WCS information. You will have to account for if you need the WCS information.

Todo

If a WCS is detected, use WCS.swapaxes() to transpose the WCS system!

static read(ofile, permissions='readonly', checksum=False)[source]

static reconstruct_cube(cube_shape, bin_indx, arr, dtype=None)[source]

Reconstruct a set of cubes with the specified shape based on a set of input 2D arrays. The cube shape is expected to be \((N_x,N_y,N_\lamba)\) and the array shapes are expected to be \((N_{\rm spec},N_\lambda)\), where \(N_{\rm spec}\) does not have to match the number of unique bins. The bin_indx array is expected to be a vector with length \(N_x\timesN_y\).

The data type of the output arrays is set by the input type if the provided dtype is None; otherwise, the code attempts to case each output cube accordint to each element of dtype.

Returns a tuple if the number of arrays is larger than one so that they can be caught by individual variables.

static reconstruct_map(map_shape, bin_indx, arr, dtype=None, quiet=False)[source]

Reconstruct a set of maps with the specified shape based on a set of input 1D arrays. The map shape is expected to be \((N_x,N_y)\) and the array shapes are expected to be \((N_{\rm pix},)\), where \(N_{\rm pix}\) does not have to match the number of unique bins. The bin_indx array is expected to be a vector with length \(N_x\timesN_y\).

The data type of the output arrays is set by the input type if the provided dtype is None; otherwise, the code attempts to case each output map according to each element of dtype.

Returns a tuple if the number of arrays is larger than one so that they can be caught by individual variables.

static redshift_to_Newtonian_velocity(v, redshift, ivar=False)[source]

static storage_mode_options()[source]

Return the allowed storage modes.

Returns:: List of the allowed storage mode for DAP fits files.
Return type:: list

static transpose_image_data(hdu, ext=None)[source]

Transpose all image data in an HDUList.

The primary use of this function is to ensure the HDUList data arrays use C-contiguous memory but with the natural array ordering of the axes that follow the NAXIS keywords in the header. I.e., data arrays provided by astropy.io.fits have shapes like (…, NAXIS3, NAXIS2, NAXIS1). This function reorders the data arrays to have shapes like (NAXIS1, NAXIS2, NAXIS3, …), and ensures that the NAXISn header keywords reflect this. Typically, one would do:

hdu = transpose_image_data(fits.open('test.fits'))

To prepare the image data for writing to a new fits file, one would do:

transpose_image_data(hdu).writeto('new.fits')

If you just want to ensure that the NAXISn keywords refect the python native ordering, then use match_image_naxis().

Note that any WCS information will not be transposed, which you will have to account for if you need the WCS information.

Todo

If a WCS is detected, use WCS.swapaxes() to transpose the WCS system!

static unique_bins(bin_indx, return_index=False)[source]: Get the unique bins and the indices of the unique bins in the flattened spatial dimension, ignoring the bins with indices of -1.

static write(hdu, ofile, overwrite=False, checksum=False, symlink_dir=None, relative_symlink=True, loggers=None, quiet=False)[source]: Write an HDUList to an output file. It is expected that the hdu was either read by the read() function, or that the hdu was passed through transpose_image_data() such that HDUList data arrays use C-contiguous memory but with the natural array ordering of the axes that follow the NAXIS keywords in the header.