Map2D

class sofia_redux.scan.source_models.maps.map_2d.Map2D(data=None, blanking_value=nan, dtype=<class 'float'>, shape=None, unit=None)

Bases: Overlay

Initialize a Map2D instance.

The 2D map is an extension of the Image and Overlay classes. In addition to the standard image handling methods, a grid is also included to allow for projections and deprojections of pixels to/from real coordinates.

An underlying beam representing the observation PSF may also be modeled as well as a beam to represent any smoothing operations that may be applied.

Parameters:

datanumpy.ndarray, optional

Data to initialize the flagged array with. If supplied, sets the shape of the array. Note that the data type will be set to that defined by the dtype parameter.

blanking_valueint or float, optional

The blanking value defines invalid values in the data array. This is the equivalent of defining a NaN value.

dtypetype, optional

The data type of the data array.

shapetuple (int), optional

The shape of the data array. This will only be relevant if data is not defined.

unitstr or units.Unit or units.Quantity, optional

The data unit.

Attributes Summary

CORRECTED_BEAM_FITS_ID
FILTER_BEAM_FITS_ID
SMOOTHING_BEAM_FITS_ID
UNDERLYING_BEAM_FITS_ID
pixel_area	Return the pixel area of the grid.
projection	Return the grid projection.
reference	Return the reference position of the grid.
reference_index	Return the reference index of the grid.

Methods Summary

add_proprietary_units()	Add proprietary units to the local units.
add_smoothing(psf)	Convolve the smoothing beam with a PSF (Point Spread Function).
auto_crop()	Auto crop the image data.
claim_image(image)	Claim an image.
convert_range_value_to_index(ranges)	Calculate the index range for a given value range.
copy([with_contents])	Return a copy of the map.
copy_processing_from(other)	Copy the processing from another map.
copy_properties_from(other)	Copy the properties from another map.
count_beams()	Return the number of beams in the map.
count_independent_points(area)	Find the number of independent points in a given area.
crop(ranges)	Crop the image data.
default_beam()	Return the default beam for this map.
edit_coordinate_info(header)	Update a header with the current WCS information.
edit_header(header)	Edit a FITS header using information in the current map.
fast_smooth(beam_map, steps[, ...])	Smooth the data with a given beam map kernel using fast method.
fft_filter_above(fwhm[, valid, weight])	Filter the image with the supplied FWHM using the FFT method.
filter_above(fwhm[, valid])	Filter the image using the supplied filtering FWHM.
filter_beam_correct()	Scale the map data by the filter correction factor.
filter_correct(underlying_fwhm[, reference, ...])	Apply a filtering correction factor to the map data.
get_anti_aliasing_beam_for(map2d)	Return the anti-aliasing beam for a given Map2D.
get_anti_aliasing_beam_image_for(map2d)	Return an antialiasing beam image.
get_area()	Return the total area of the map.
get_default_grid_unit()	Return the default grid unit.
get_display_grid_unit()	Return the display grid unit.
get_filter_area()	Get the filtering beam area.
get_filter_correction_factor([underlying_fwhm])	Return the filter correction factor.
get_image([dtype, blanking_value])	Return the basis image.
get_image_beam()	Return the image beam.
get_image_beam_area()	Get the beam area of the image beam.
get_index_transform_to(map2d)	Return the grid indices of this map projected onto another.
get_info()	Return strings describing the map.
get_pixel_smoothing()	Return a Gaussian model representing pixel smoothing.
get_points_per_smoothing_beam()	Get the number of pixels per smoothing beam.
get_resolution()	Return the grid resolution in (x, y).
get_table_entry(name)	Return a parameter value for a given name.
is_corrected()	Return whether the map has been corrected.
is_filter_blanked()	Return whether the map is filter blanked.
is_filtered()	Return whether the map has been filtered.
merge_properties_from(other)	Merge properties from another map.
nearest_to_offset(offset)	Return the nearest map index for a given offset.
no_data()	Discard all data.
numpy_to_fits(coordinates)	Convert numpy based (x, y) coordinates/indices to FITS coordinates.
parse_coordinate_info(header[, alt])	Parse and apply the WCS information from a FITS header.
parse_corrected_beam(header)	Parse the corrected beam from a FITS header.
parse_filter_beam(header)	Parse the filtering beam from a FITS header.
parse_header(header)	Parse and apply information from a FITS header.
parse_smoothing_beam(header)	Parse the smoothing beam from a FITS header.
parse_underlying_beam(header)	Parse the underlying beam from a FITS header.
renew()	Renew the map by clearing all processing and data.
resample(resolution)	Resample the map to a new resolution.
resample_from_map(map2d[, weights])	Resample from one map to another.
reset_filtering()	Reset the map filtering.
reset_processing()	Reset the processing status.
reset_smoothing()	Reset the map smoothing.
set_correcting_fwhm(fwhm)	Set the correcting FWHM.
set_default_unit()	Set the default unit for the map data.
set_display_grid_unit(unit)	Set the grid display unit.
set_filter_blanking(value)	Set the filter blanking.
set_filtering(fwhm)	Set the filtering FWHM.
set_grid(grid)	Set the map grid.
set_image(image)	Set the basis image.
set_pixel_smoothing()	Set the smoothing beam to the pixel smoothing beam.
set_resolution(resolution[, redo])	Set the resolution of the grid.
set_smoothing(psf)	Set the smoothing beam.
set_underlying_beam(psf)	Set the underlying beam.
set_unit(unit)	Set the map data unit.
smooth(beam_map[, reference_index, weights])	Smooth the data with a given beam map kernel.
smooth_to(psf)	Smooth to a given PSF or FWHM.
smooth_with_psf(psf)	Smooth with a given PSF or FWHM.
undo_filter_correct([reference, valid])	Undo the last filter correction.
update_filtering(fwhm)	Update the filtering.

Attributes Documentation

CORRECTED_BEAM_FITS_ID = 'C'

FILTER_BEAM_FITS_ID = 'X'

SMOOTHING_BEAM_FITS_ID = 'S'

UNDERLYING_BEAM_FITS_ID = 'I'

pixel_area

Return the pixel area of the grid.

Returns:

areaunits.Quantity or float

projection

Return the grid projection.

The grid projection transforms coordinates to map offsets.

Returns:

Projection2D

reference

Return the reference position of the grid.

Returns:

Coordinate2D

reference_index

Return the reference index of the grid.

Returns:

indexCoordinate2D

Methods Documentation

add_proprietary_units()

Add proprietary units to the local units.

Returns:

None

add_smoothing(psf)

Convolve the smoothing beam with a PSF (Point Spread Function).

Parameters:

psfGaussian2D or astropy.units.Quantity

A Gaussian model or an FWHM from which to create the model.

Returns:

None

auto_crop()

Auto crop the image data.

The data is cropped to the extent of valid data point indices.

Returns:

rangesnumpy.ndarray (int)

The cropping range for each dimension of shape (n_dimensions, 2) where […, 0] is the minimum range and […, 1] is the maximum crop value (inclusive).

claim_image(image)

Claim an image.

Parameters:

imageImage2D

Returns:

None

convert_range_value_to_index(ranges)

Calculate the index range for a given value range.

Converts a range of dimensional offsets to an appropriate range of map indices for use in cropping.

Parameters:

rangesunits.Quantity or Coordinate2D

An array of shape (n_dimensions, 2) containing the minimum and maximum ranges in each dimension. Dimension ordering is FITS based (x, y).

Returns:

index_rangenumpy.ndarray (int)

The ranges as indices (integer values) on the grid.

copy(with_contents=True)

Return a copy of the map.

Returns:

Map2D

copy_processing_from(other)

Copy the processing from another map.

Processing includes the underlying and smoothing beams, the filtering FWHM, filtering blanking value and correcting FWHM.

Parameters:

otherMap2D

Returns:

None

copy_properties_from(other)

Copy the properties from another map.

The properties copied include anything under Map2D.copy_processing_from() along with the map grid and FITS properties.

Parameters:

otherMap2D

Returns:

None

count_beams()

Return the number of beams in the map.

Returns:

float

count_independent_points(area)

Find the number of independent points in a given area.

In 1-D at least 3 points per beam are needed to separate a positioned point source from an extended source. Similarly, 9 points per beam are necessary for 2-D.

Parameters:

areaastropy.Quantity

The area to consider.

Returns:

pointsint

crop(ranges)

Crop the image data.

Parameters:

rangesnumpy.ndarray (int,) or units.Quantity

The ranges to set crop the data to. Should be of shape (n_dimensions, 2) where ranges[0, 0] would give the minimum crop limit for the first dimension and ranges[0, 1] would give the maximum crop limit for the first dimension. In this case, the ‘first’ dimension is in FITS format. i.e., (x, y) for a 2-D image. If a Quantity is supplied this should contain the min and max grid values to clip to in each dimension.

Returns:

None

classmethod default_beam()

Return the default beam for this map.

Returns:

Gaussian2D

edit_coordinate_info(header)

Update a header with the current WCS information.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

edit_header(header)

Edit a FITS header using information in the current map.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

fast_smooth(beam_map, steps, reference_index=None, weights=None)

Smooth the data with a given beam map kernel using fast method.

Parameters:

beam_mapnumpy.ndarray (float)

The beam map image kernel with which to smooth the map of shape (ky, kx).

stepsIndex2D

The fast step skips in (x, y).

reference_indexCoordinate2D, optional

The reference pixel index of the kernel in (x, y). The default is the beam map center ((kx-1)/2, (ky-1)/2).

weightsnumpy.ndarray (float), optional

The map weights of shape (ny, nx). The default is no weighting.

Returns:

None

fft_filter_above(fwhm, valid=None, weight=None)

Filter the image with the supplied FWHM using the FFT method.

Parameters:

fwhmunits.Quantity

The FWHM of the Gaussian with which to filter the image.

validnumpy.ndarray (bool), optional

An optional mask where False excludes a map element from inclusion in the convolution and subtraction.

weightnumpy.ndarray (float), optional

An optional weighting array with the same shape as the map data. These should be the inverse variance values.

Returns:

None

filter_above(fwhm, valid=None)

Filter the image using the supplied filtering FWHM.

The image data is modified via:

filtered = data - convolve(data, Gaussian(fwhm))

Parameters:

fwhmunits.Quantity or Coordinate2D1

The FWHM of the Gaussian with which to filter the image.

validnumpy.ndarray (bool), optional

An optional mask where False excludes a map element from inclusion in the convolution and subtraction.

Returns:

None

filter_beam_correct()

Scale the map data by the filter correction factor.

The filter correction factor is determined by applying Map2D.get_filter_correction_factor() to the underlying beam of the map. All data are scaled by this factor.

Returns:

None

filter_correct(underlying_fwhm, reference=None, valid=None)

Apply a filtering correction factor to the map data.

The filtering correction factor is derived from the supplied underlying_fwhm using Map2D.get_filter_correction_factor(), and is only applied to valid data elements. The validity of the elements may be supplied or determined from the map itself or a supplied reference.

If a correction factor was previously applied, it will be removed before applying the new factor.

Parameters:

underlying_fwhmunits.Quantity or Coordinate

The underlying FWHM of the beam used to derive the filtering correction factor to apply to the data.

referenceFlaggedArray or numpy.ndarray, optional

If valid is not supplied, calculate the validity mask from this reference array and whether those values are within the blanking value range, and are themselves valid (if the reference is a FlaggedArray). Only valid data will be scaled by the filtering correction factor.

validnumpy.ndarray (bool), optional

A boolean mask with the same shape as the map data. Elements flagged as False will not be scaled by the filtering correction factor. If not supplied, the validity mask will be derived from this map, or a supplied reference array.

Returns:

None

get_anti_aliasing_beam_for(map2d)

Return the anti-aliasing beam for a given Map2D.

The anti-aliasing beam is the beam representing the pixel smoothing for this map deconvolved by the input map smoothing beam. If the smoothing beam of the input map encompasses the pixel smoothing of this map, None will be returned.

Parameters:

map2dMap2D

Returns:

anti_aliasing_beamGaussian2D or None

get_anti_aliasing_beam_image_for(map2d)

Return an antialiasing beam image.

The anti-aliasing beam is the beam representing the pixel smoothing for this map deconvolved by the smoothing beam of the input map. A representation of this beam is returned by projecting it onto the grid of this map. If there is no valid anti-aliasing beam, None is returned.

Parameters:

map2dMap2D

Returns:

anti_aliasing_beam_imagenumpy.ndarray (float) or None

get_area()

Return the total area of the map.

The total area is the number of pixels multiplied by the pixel area.

Returns:

areaunits.Quantity or float

get_default_grid_unit()

Return the default grid unit.

Returns:

units.Quantity

get_display_grid_unit()

Return the display grid unit.

Returns:

units.Quantity

get_filter_area()

Get the filtering beam area.

Returns:

areaunits.Quantity

get_filter_correction_factor(underlying_fwhm=None)

Return the filter correction factor.

The filtering correction factor is given as:

factor = 1 / (1 - ((a1 - a2) / (a1 + a3)))

where a1 is the underlying beam area, a2 is the smoothing beam area, and a3 is the filtering beam area.

Parameters:

underlying_fwhmastropy.units.Quantity or float, optional

The underlying FWHM. If not supplied, defaults to the map underlying beam FWHM.

Returns:

correction_factorfloat

get_image(dtype=None, blanking_value=None)

Return the basis image.

Parameters:

dtypetype, optional

The image data type.

blanking_valueint or float, optional

The new image blanking value.

Returns:

Image2D

get_image_beam()

Return the image beam.

The image beam is the underlying beam convolved with the smoothing beam. If one is not set, the other is returned. If neither is set, None is returned.

Returns:

Gaussian2D or None

get_image_beam_area()

Get the beam area of the image beam.

Returns:

float or units.Quantity

get_index_transform_to(map2d)

Return the grid indices of this map projected onto another.

Parameters:

map2dMap2D

Returns:

indicesCoordinate2D

The indices of this map projected onto the grid indices of the input map2d. Note that these indices are flat and correspond to the flattened map data.

get_info()

Return strings describing the map.

Returns:

list of str

get_pixel_smoothing()

Return a Gaussian model representing pixel smoothing.

Returns:

Gaussian2D

get_points_per_smoothing_beam()

Get the number of pixels per smoothing beam.

Returns:

float

get_resolution()

Return the grid resolution in (x, y).

Returns:

resolutionCoordinate2D

get_table_entry(name)

Return a parameter value for a given name.

Parameters:

namestr, optional

Returns:

value

is_corrected()

Return whether the map has been corrected.

Returns:

bool

is_filter_blanked()

Return whether the map is filter blanked.

Returns:

bool

is_filtered()

Return whether the map has been filtered.

Returns:

filteredbool

merge_properties_from(other)

Merge properties from another map.

Merging the properties results in the encompassed smoothing beam of this map by the other, and the minimum filtering FWHM of both maps.

Parameters:

otherMap2D

Returns:

None

nearest_to_offset(offset)

Return the nearest map index for a given offset.

Parameters:

offsetCoordinate2D or tuple or numpy.ndarray or list.

The spatial offset given as a coordinate or tuple of (x, y) offsets.

Returns:

x_index, y_index2-tuple (int or numpy.ndarray)

The x and y map indices.

no_data()

Discard all data.

Returns:

None

classmethod numpy_to_fits(coordinates)

Convert numpy based (x, y) coordinates/indices to FITS coordinates.

Parameters:

coordinatesnumpy.ndarray

Returns:

Coordinate2D

parse_coordinate_info(header, alt='')

Parse and apply the WCS information from a FITS header.

This process sets the grid for the map based on the contents of a given FITS header.

Parameters:

headerastropy.io.fits.header.Header

altstr, optional

The alternate WCS transform to use. This replaces the “a” part of the CTYPEia cards.

Returns:

None

parse_corrected_beam(header)

Parse the corrected beam from a FITS header.

The correcting beam FWHM is taken from the CBMAJ and CBMIN keywords, or the CORRECTN keyword in the FITS header. If neither is found, the default correcting FWHM defaults to NaN.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

parse_filter_beam(header)

Parse the filtering beam from a FITS header.

The correcting beam FWHM is taken from the XBMAJ and XBMIN keywords, or the EXTFLTR keyword in the FITS header. If neither is found, the default filtering FWHM defaults to NaN.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

parse_header(header)

Parse and apply information from a FITS header.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

parse_smoothing_beam(header)

Parse the smoothing beam from a FITS header.

The smoothing beam is taken from the SBMAJ and SBMIN keywords, or the SMOOTH keyword in the FITS header. The no keywords are found, the smoothing beam FWHM defaults the pixel smoothing.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

parse_underlying_beam(header)

Parse the underlying beam from a FITS header.

Uses IBMAJ/IBMIN if available, will then look to BMAJ/MIN, will then look for BEAM, and finally the old RESOLUTN.

Parameters:

headerastropy.io.fits.header.Header

Returns:

None

renew()

Renew the map by clearing all processing and data.

Returns:

None

resample(resolution)

Resample the map to a new resolution.

Parameters:

resolutionunits.Quantity

A resolution for all dimensions if scalar, or each dimension if supplied as an array of shape (n_dimensions,) using the (x, y) FITS convention.

Returns:

None

resample_from_map(map2d, weights=None)

Resample from one map to another.

Parameters:

map2dMap2D

The map to resample from.

weightsnumpy.ndarray (float), optional

Optional weights to include during the resampling. Weights should be the same shape as the map2d and represent inverse variance.

Returns:

None

reset_filtering()

Reset the map filtering.

Returns:

None

reset_processing()

Reset the processing status.

Sets the smoothing beam to be consistent with the current grid, and removes all filtering and correcting FWHM parameters.

Returns:

None

reset_smoothing()

Reset the map smoothing.

Returns:

None

set_correcting_fwhm(fwhm)

Set the correcting FWHM.

Parameters:

fwhmunits.Quantity

Returns:

None

set_default_unit()

Set the default unit for the map data.

Returns:

None

set_display_grid_unit(unit)

Set the grid display unit.

The display grid unit defines the spatial units of the map.

Parameters:

unitstr or units.Unit or units.Quantity or None

Returns:

None

set_filter_blanking(value)

Set the filter blanking.

Parameters:

valuefloat or None

The value to set for filter blanking. If None is supplied, the filter blanking value is set to NaN (disabled).

Returns:

None

set_filtering(fwhm)

Set the filtering FWHM.

Parameters:

fwhm.units.Quantity

Returns:

None

set_grid(grid)

Set the map grid.

Parameters:

gridSphericalGrid

Returns:

None

set_image(image)

Set the basis image.

Parameters:

imageImage2D or numpy.ndarray

Returns:

None

set_pixel_smoothing()

Set the smoothing beam to the pixel smoothing beam.

Returns:

None

set_resolution(resolution, redo=False)

Set the resolution of the grid.

Sets a new resolution for the map grid. If the smoothing beam has already been determined and redo is True, it is first deconvolved by the original grid resolution before being encompassed by a smoothing beam determined from the new grid resolution.

Parameters:

resolutionfloat or numpy.ndarray or units.Quantity or Coordinate2D

An array of shape (2,) giving the (x, y) grid resolution.

redobool, optional

If True deconvolve with the smoothing beam, and convolve after the resolution is set.

Returns:

None

set_smoothing(psf)

Set the smoothing beam.

Parameters:

psfGaussian2D or units.Quantity

A Gaussian PSF model, or a FWHM from which to create the model.

Returns:

None

set_underlying_beam(psf)

Set the underlying beam.

Parameters:

psfGaussian2D or units.Quantity

A Gaussian PSF model, or a FWHM from which to create the model.

Returns:

None

set_unit(unit)

Set the map data unit.

Parameters:

unitastropy.units.Quantity or str or astropy.units.Unit

The unit to set as the map data unit. Should be a quantity (value and unit type). If a string or Unit is supplied, the map data unit will be set to the value located in the local_units dictionary. If no such value exists, a KeyError will be raised.

Returns:

None

smooth(beam_map, reference_index=None, weights=None)

Smooth the data with a given beam map kernel.

Parameters:

beam_mapnumpy.ndarray (float)

The beam map image kernel with which to smooth the map of shape (ky, kx).

reference_indexCoordinate2D or numpy.ndarray

The reference pixel index of the kernel in (x, y).

weightsnumpy.ndarray (float)

The map weights of shape (ny, nx).

Returns:

None

smooth_to(psf)

Smooth to a given PSF or FWHM.

Parameters:

psffloat or Gaussian2D or Quantity

Returns:

None

smooth_with_psf(psf)

Smooth with a given PSF or FWHM.

Parameters:

psffloat or Gaussian2D or Quantity

Returns:

None

undo_filter_correct(reference=None, valid=None)

Undo the last filter correction.

Performs the reverse of Map2D.filter_correct() with the last used underlying FWHM.

Parameters:

referenceFlaggedArray or numpy.ndarray (float), optional

The data set to determine valid data within the blanking range. Defaults to self.data.

validnumpy.ndarray (bool), optional

True indicates a data element that may have the filter correction factor un-applied.

Returns:

None

update_filtering(fwhm)

Update the filtering.

The filtering is only updated when it is NaN or the provided filtering FWHM is less than that which is currently set.

Parameters:

fwhmunits.Quantity

Returns:

None