NDCube

class ndcube.NDCube(data, wcs=None, uncertainty=None, mask=None, meta=None, unit=None, copy=False, **kwargs)

Bases: ndcube.ndcube.NDCubeBase

Class representing N-D data described by a single array and set of WCS transformations.

Parameters

• data (numpy.ndarray) – The array holding the actual data in this object.

• wcs (astropy.wcs.wcsapi.BaseLowLevelWCS, astropy.wcs.wcsapi.BaseHighLevelWCS, optional) – The WCS object containing the axes’ information, optional only if data is an astropy.nddata.NDData object.

• uncertainty (any type, optional) – Uncertainty in the dataset. Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, for example “std” for standard deviation or “var” for variance. A metaclass defining such an interface is NDUncertainty - but isn’t mandatory. If the uncertainty has no such attribute the uncertainty is stored as UnknownUncertainty. Defaults to None.

• mask (any type, optional) – Mask for the dataset. Masks should follow the numpy convention that valid data points are marked by False and invalid ones with True. Defaults to None.

• meta (dict-like object, optional) – Additional meta information about the dataset. If no meta is provided an empty collections.OrderedDict is created. Default is None.

• unit (Unit-like or str, optional) – Unit for the dataset. Strings that can be converted to a Unit are allowed. Default is None.

• extra_coords (iterable of tuple, each with three entries) – (str, int, astropy.units.quantity or array-like) Gives the name, axis of data, and values of coordinates of a data axis not included in the WCS object.

• copy (bool, optional) – Indicates whether to save the arguments as copy. True copies every attribute before saving it while False tries to save every parameter as reference. Note however that it is not always possible to save the input as reference. Default is False.

Attributes Summary

array_axis_physical_types	Returns the physical types associated with each array axis.
combined_wcs	A BaseHighLevelWCS object which combines .wcs with .extra_coords.
data	The stored dataset.
dimensions	The array dimensions of the cube.
extra_coords	An ExtraCoords object holding extra coordinates aligned to array axes.
global_coords	A GlobalCoords object holding coordinate metadata not aligned to an array axis.
mask	Mask for the dataset, if any.
meta	Additional meta information about the dataset.
plotter	A MatplotlibPlotter instance providing visualization methods.
uncertainty	Uncertainty in the dataset, if any.
unit	Unit for the dataset, if any.
wcs	A world coordinate system (WCS) for the dataset, if any.

Methods Summary

axis_world_coords(*axes[, pixel_corners, wcs])	Returns WCS coordinate values of all pixels for all axes.
axis_world_coords_values(*axes[, ...])	Returns WCS coordinate values of all pixels for desired axes.
crop(lower_corner, upper_corner[, wcs])	Crop given world coordinate objects describing the lower and upper corners of a region.
crop_by_values(lower_corner, upper_corner[, ...])	Crops an NDCube given lower and upper real world bounds for each real world axis.
explode_along_axis(axis)	Separates slices of NDCubes along a given axis into an NDCubeSequence of (N-1)DCubes.
plot(*args, **kwargs)	A convenience function for the plotters default plot() method.
reproject_to(target_wcs[, algorithm, ...])	Reprojects this NDCube to the coordinates described by another WCS object.

Attributes Documentation

array_axis_physical_types

Returns the physical types associated with each array axis.

Returns an iterable of tuples where each tuple corresponds to an array axis and holds strings denoting the physical types associated with that array axis. Since multiple physical types can be associated with one array axis, tuples can be of different lengths. Likewise, as a single physical type can correspond to multiple array axes, the same physical type string can appear in multiple tuples.

The physical types are drawn from the WCS ExtraCoords objects.

combined_wcs

A BaseHighLevelWCS object which combines .wcs with .extra_coords.

data

The stored dataset.

Type

ndarray-like

dimensions

extra_coords

An ExtraCoords object holding extra coordinates aligned to array axes.

global_coords

A GlobalCoords object holding coordinate metadata not aligned to an array axis.

mask

Mask for the dataset, if any.

Masks should follow the numpy convention that valid data points are marked by False and invalid ones with True.

Type

any type

meta

Additional meta information about the dataset.

Type

dict-like

plotter = None

A MatplotlibPlotter instance providing visualization methods.

The type of this attribute can be changed to provide custom visualization functionality.

uncertainty

Uncertainty in the dataset, if any.

Should have an attribute uncertainty_type that defines what kind of uncertainty is stored, such as 'std' for standard deviation or 'var' for variance. A metaclass defining such an interface is NDUncertainty but isn’t mandatory.

Type

any type

unit

Unit for the dataset, if any.

Type

Unit

wcs

A world coordinate system (WCS) for the dataset, if any.

Type

any type

Methods Documentation

axis_world_coords(*axes, pixel_corners=False, wcs=None)

Returns WCS coordinate values of all pixels for all axes.

Parameters

• axes (int or str, or multiple int or str, optional) – Axis number in numpy ordering or unique substring of world_axis_physical_types of axes for which real world coordinates are desired. axes=None implies all axes will be returned.

• pixel_corners (bool, optional) – If True then instead of returning the coordinates at the centers of the pixels, the coordinates at the pixel corners will be returned. This increases the size of the output by 1 in all dimensions as all corners are returned.

• wcs (astropy.wcs.wcsapi.BaseHighLevelWCS, optional) – The WCS object to used to calculate the world coordinates. Although technically this can be any valid WCS, it will typically be self.wcs, self.extra_coords, or self.combined_wcs which combines both the WCS and extra coords. Defaults to the .wcs property.

Returns

axes_coords – An iterable of “high level” objects giving the real world coords for the axes requested by user. For example, a tuple of SkyCoord objects. The types returned are determined by the WCS object. The dimensionality of these objects should match that of their corresponding array dimensions, unless pixel_corners=True in which case the length along each axis will be 1 greater than the number of pixels.

Return type

list

Example

>>> NDCube.all_world_coords(('lat', 'lon')) 
>>> NDCube.all_world_coords(2) 

axis_world_coords_values(*axes, pixel_corners=False, wcs=None)

Returns WCS coordinate values of all pixels for desired axes.

Parameters

• axes (int or str, or multiple int or str, optional) – Axis number in numpy ordering or unique substring of world_axis_physical_types of axes for which real world coordinates are desired. axes=None implies all axes will be returned.

• pixel_corners (bool, optional) – If True then instead of returning the coordinates of the pixel centers the coordinates of the pixel corners will be returned. This increases the size of the output along each dimension by 1 as all corners are returned.

• wcs (astropy.wcs.wcsapi.BaseHighLevelWCS, optional) – The WCS object to used to calculate the world coordinates. Although technically this can be any valid WCS, it will typically be self.wcs, self.extra_coords, or self.combined_wcs, combing both the WCS and extra coords. Defaults to the .wcs property.

Returns

axes_coords – An iterable of “high level” objects giving the real world coords for the axes requested by user. For example, a tuple of SkyCoord objects. The types returned are determined by the WCS object. The dimensionality of these objects should match that of their corresponding array dimensions, unless pixel_corners=True in which case the length along each axis will be 1 greater than the number of pixels.

Return type

list

Example

>>> NDCube.all_world_coords_values(('lat', 'lon')) 
>>> NDCube.all_world_coords_values(2) 

crop(lower_corner, upper_corner, wcs=None)

Crop given world coordinate objects describing the lower and upper corners of a region.

The region of interest is defined in pixel space, by converting the world coordinates of the corners to pixel coordinates and then cropping the smallest pixel region which contains the corners specified. This means that the edges of the world coordinate region specified by the coordinates are not guaranteed to be included in the cropped output. This is normally noticeable when cropping a celestial coordinate in a frame which differs from the native frame of the coordinates in the WCS.

Parameters

• lower_corner (iterable whose elements are None or high level astropy objects) – An iterable of length-1 astropy higher level objects, e.g. SkyCoord, representing the real world coordinates of the lower corner of the region of interest. These are input to astropy.wcs.WCS.world_to_array_index so their number and order must be compatible with the API of that method. Alternatively, None, can be provided instead of a higher level object. In this case, the corresponding array axes will be cropped starting from 0th array index.

• upper_corner (iterable whose elements are None or high level astropy objects) – An iterable of length-1 astropy higher level objects, e.g. SkyCoord, representing the real world coordinates of the upper corner of the region of interest. These are input to astropy.wcs.WCS.world_to_array_index so their number and order must be compatible with the API of that method. Alternatively, None, can be provided instead of a higher level object. In this case, the corresponding array axes will be cropped to include the final array index.

• wcs (astropy.wcs.wcsapi.BaseHighLevelWCS) – The WCS object to used to convert the world values to array indices. Although technically this can be any valid WCS, it will typically be self.wcs, self.extra_coords.wcs, or self.combined_wcs, combing both the WCS and extra coords. Default=self.wcs

Returns

result

Return type

ndcube.NDCube

crop_by_values(lower_corner, upper_corner, units=None, wcs=None)

Crops an NDCube given lower and upper real world bounds for each real world axis.

The region of interest is defined in pixel space, by converting the world coordinates of the corners to pixel coordinates and then cropping the smallest pixel region which contains the corners specified. This means that the edges of the world coordinate region specified by the coordinates are not guaranteed to be included in the cropped output. This is normally noticeable when cropping a celestial coordinate in a frame which differs from the native frame of the coordinates in the WCS.

Parameters

• lower_corner (iterable whose elements are None, astropy.units.Quantity or float) – An iterable of length-1 Quantities or floats, representing the real world coordinate values of the lower corner of the region of interest. These are input to astropy.wcs.WCS.world_to_array_index_values so their number and order must be compatible with the API of that method, i.e. they must be in world axis order. Alternatively, None, can be provided instead of a Quantity or float. In this case, the corresponding array axes will be cropped starting from 0th array index.

• upper_corner (iterable whose elements are None, astropy.units.Quantity or float) – An iterable of length-1 Quantities or floats, representing the real world coordinate values of the upper corner of the region of interest. These are input to astropy.wcs.WCS.world_to_array_index_values so their number and order must be compatible with the API of that method, i.e. they must be in world axis order. Alternatively, None, can be provided instead of a Quantity or float. In this case, the corresponding array axes will be cropped to include the final array index.

• units (iterable of astropy.units.Unit) – The unit of the corresponding entries in lower_corner and upper_corner. Must therefore be the same length as lower_corner and upper_corner. Only used if the corresponding type is not a astropy.units.Quantity.

• wcs (astropy.wcs.wcsapi.BaseLowLevelWCS) – The WCS object to used to convert the world values to array indices. Although technically this can be any valid WCS, it will typically be self.wcs, self.extra_coords.wcs, or self.combined_wcs, combing both the WCS and extra coords. Default=self.wcs

Returns

result

Return type

ndcube.NDCube

explode_along_axis(axis)

Separates slices of NDCubes along a given axis into an NDCubeSequence of (N-1)DCubes.

Parameters

axis (int) – The array axis along which the data is to be changed.

Returns

result

Return type

ndcube.NDCubeSequence

plot(*args, **kwargs)

A convenience function for the plotters default plot() method.

Calling this method is the same as calling cube.plotter.plot, the behaviour of this method can change if the NDCube.plotter class is set to a different Plotter class.

reproject_to(target_wcs, algorithm='interpolation', shape_out=None, order='bilinear', output_array=None, parallel=False, return_footprint=False)

Reprojects this NDCube to the coordinates described by another WCS object.

Parameters

• algorithm (str) – The algorithm to use for reprojecting. This can be any of: ‘interpolation’, ‘adaptive’, and ‘exact’.

• target_wcs (astropy.wcs.wcsapi.BaseHighLevelWCS, astropy.wcs.wcsapi.BaseLowLevelWCS,) – or astropy.io.fits.Header The WCS object to which the NDCube is to be reprojected.

• shape_out (tuple, optional) – The shape of the output data array. The ordering of the dimensions must follow NumPy ordering and not the WCS pixel shape. If not specified, array_shape attribute (if available) from the low level API of the target_wcs is used.

• order (int or str) – The order of the interpolation (used only when the ‘interpolation’ or ‘adaptive’ algorithm is selected). For ‘interpolation’ algorithm, this can be any of: ‘nearest-neighbor’, ‘bilinear’, ‘biquadratic’, and ‘bicubic’. For ‘adaptive’ algorithm, this can be either ‘nearest-neighbor’ or ‘bilinear’.

• output_array (numpy.ndarray, optional) – An array in which to store the reprojected data. This can be any numpy array including a memory map, which may be helpful when dealing with extremely large files.

• parallel (bool or int) – Flag for parallel implementation (used only when the ‘exact’ algorithm is selected). If True, a parallel implementation is chosen and the number of processes is selected automatically as the number of logical CPUs detected on the machine. If False, a serial implementation is chosen. If the flag is a positive integer n greater than one, a parallel implementation using n processes is chosen.

• return_footprint (bool) – Whether to return the footprint in addition to the output NDCube.

Returns

• resampled_cube (ndcube.NDCube) – A new resultant NDCube object, the supplied target_wcs will be the .wcs attribute of the output NDCube.

• footprint (numpy.ndarray) – Footprint of the input array in the output array. Values of 0 indicate no coverage or valid values in the input image, while values of 1 indicate valid values.

Notes

This method doesn’t support handling of the mask, extra_coords, and uncertainty attributes yet. However, meta and global_coords are copied to the output NDCube.