NDCube¶
-
class
ndcube.
NDCube
(data, wcs=None, uncertainty=None, mask=None, meta=None, unit=None, copy=False, **kwargs)[source]¶ Bases:
ndcube.ndcube.NDCubeBase
,astropy.nddata.mixins.ndarithmetic.NDArithmeticMixin
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 ifdata
is anastropy.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
Returns the physical types associated with each array axis.
A
BaseHighLevelWCS
object which combines.wcs
with.extra_coords
.The stored dataset.
The array dimensions of the cube.
An
ExtraCoords
object holding extra coordinates aligned to array axes.A
GlobalCoords
object holding coordinate metadata not aligned to an array axis.Mask for the dataset, if any.
Additional meta information about the dataset.
Uncertainty in the dataset, if any.
Unit for the dataset, if any.
A world coordinate system (WCS) for the dataset, if any.
Methods Summary
add
(operand[, operand2])Performs addition by evaluating
self
+operand
.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.
divide
(operand[, operand2])Performs division by evaluating
self
/operand
.explode_along_axis
(axis)Separates slices of NDCubes along a given axis into an NDCubeSequence of (N-1)DCubes.
multiply
(operand[, operand2])Performs multiplication by evaluating
self
*operand
.plot
(*args, **kwargs)A convenience function for the plotters default
plot()
method.reproject_to
(target_wcs[, shape_out, order, …])Reprojects this NDCube to the coordinates described by another WCS object.
subtract
(operand[, operand2])Performs subtraction by evaluating
self
-operand
.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
.
-
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 byFalse
and invalid ones withTrue
.- Type
any type
-
plotter
= None¶
-
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 isNDUncertainty
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
-
classmethod
add
(operand, operand2=None, **kwargs)¶ Performs addition by evaluating
self
+operand
.- Parameters
operand (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
+operand
. Ifoperand2
is given it will performoperand
+operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.operand2 (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
+operand
. Ifoperand2
is given it will performoperand
+operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.propagate_uncertainties (
bool
orNone
, optional) –If
None
the result will have no uncertainty. IfFalse
the result will have a copied version of the first operand that has an uncertainty. IfTrue
the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties areNDUncertainty
-like. Default isTrue
.Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated.
None
was added as valid parameter value.handle_mask (callable,
'first_found'
orNone
, optional) –If
None
the result will have no mask. If'first_found'
the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the resultsmask
and if necessary provide a copy. Default isnumpy.logical_or
.New in version 1.2.
handle_meta (callable,
'first_found'
orNone
, optional) –If
None
the result will have no meta. If'first_found'
the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the resultsmeta
and if necessary provide a copy. Default isNone
.New in version 1.2.
compare_wcs (callable,
'first_found'
orNone
, optional) –If
None
the result will have no wcs and no comparison between the wcs of the operands is made. If'first_found'
the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare thewcs
. The resultingwcs
will be like ifFalse
was given otherwise it raises aValueError
if the comparison was not successful. Default is'first_found'
.New in version 1.2.
uncertainty_correlation (number or
ndarray
, optional) –The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.
New in version 1.2.
- kwargs :
Any other parameter that should be passed to the callables used.
- Returns
result – The resulting dataset
- Return type
NDData
-like
Notes
If a
callable
is used formask
,wcs
ormeta
the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined askwargs
and must start with"wcs_"
(for wcs callable) or"meta_"
(for meta callable). This startstring is removed before the callable is called."first_found"
can also be abbreviated with"ff"
.
-
axis_world_coords
(*axes, pixel_corners=False, wcs=None)¶ Returns WCS coordinate values of all pixels for all axes.
- Parameters
axes (
int
orstr
, or multipleint
orstr
, optional) – Axis number in numpy ordering or unique substring ofworld_axis_physical_types
of axes for which real world coordinates are desired. axes=None implies all axes will be returned.pixel_corners (
bool
, optional) – IfTrue
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 beself.wcs
,self.extra_coords
, orself.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, unlesspixel_corners=True
in which case the length along each axis will be 1 greater than the number of pixels.- Return type
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
orstr
, or multipleint
orstr
, optional) – Axis number in numpy ordering or unique substring ofworld_axis_physical_types
of axes for which real world coordinates are desired. axes=None implies all axes will be returned.pixel_corners (
bool
, optional) – IfTrue
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 beself.wcs
,self.extra_coords
, orself.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, unlesspixel_corners=True
in which case the length along each axis will be 1 greater than the number of pixels.- Return type
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
-
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
orfloat
) – 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 toastropy.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
orfloat
) – 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 toastropy.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 aastropy.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
-
classmethod
divide
(operand, operand2=None, **kwargs)¶ Performs division by evaluating
self
/operand
.- Parameters
operand (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
/operand
. Ifoperand2
is given it will performoperand
/operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.operand2 (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
/operand
. Ifoperand2
is given it will performoperand
/operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.propagate_uncertainties (
bool
orNone
, optional) –If
None
the result will have no uncertainty. IfFalse
the result will have a copied version of the first operand that has an uncertainty. IfTrue
the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties areNDUncertainty
-like. Default isTrue
.Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated.
None
was added as valid parameter value.handle_mask (callable,
'first_found'
orNone
, optional) –If
None
the result will have no mask. If'first_found'
the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the resultsmask
and if necessary provide a copy. Default isnumpy.logical_or
.New in version 1.2.
handle_meta (callable,
'first_found'
orNone
, optional) –If
None
the result will have no meta. If'first_found'
the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the resultsmeta
and if necessary provide a copy. Default isNone
.New in version 1.2.
compare_wcs (callable,
'first_found'
orNone
, optional) –If
None
the result will have no wcs and no comparison between the wcs of the operands is made. If'first_found'
the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare thewcs
. The resultingwcs
will be like ifFalse
was given otherwise it raises aValueError
if the comparison was not successful. Default is'first_found'
.New in version 1.2.
uncertainty_correlation (number or
ndarray
, optional) –The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.
New in version 1.2.
- kwargs :
Any other parameter that should be passed to the callables used.
- Returns
result – The resulting dataset
- Return type
NDData
-like
Notes
If a
callable
is used formask
,wcs
ormeta
the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined askwargs
and must start with"wcs_"
(for wcs callable) or"meta_"
(for meta callable). This startstring is removed before the callable is called."first_found"
can also be abbreviated with"ff"
.
-
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
-
classmethod
multiply
(operand, operand2=None, **kwargs)¶ Performs multiplication by evaluating
self
*operand
.- Parameters
operand (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
*operand
. Ifoperand2
is given it will performoperand
*operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.operand2 (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
*operand
. Ifoperand2
is given it will performoperand
*operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.propagate_uncertainties (
bool
orNone
, optional) –If
None
the result will have no uncertainty. IfFalse
the result will have a copied version of the first operand that has an uncertainty. IfTrue
the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties areNDUncertainty
-like. Default isTrue
.Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated.
None
was added as valid parameter value.handle_mask (callable,
'first_found'
orNone
, optional) –If
None
the result will have no mask. If'first_found'
the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the resultsmask
and if necessary provide a copy. Default isnumpy.logical_or
.New in version 1.2.
handle_meta (callable,
'first_found'
orNone
, optional) –If
None
the result will have no meta. If'first_found'
the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the resultsmeta
and if necessary provide a copy. Default isNone
.New in version 1.2.
compare_wcs (callable,
'first_found'
orNone
, optional) –If
None
the result will have no wcs and no comparison between the wcs of the operands is made. If'first_found'
the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare thewcs
. The resultingwcs
will be like ifFalse
was given otherwise it raises aValueError
if the comparison was not successful. Default is'first_found'
.New in version 1.2.
uncertainty_correlation (number or
ndarray
, optional) –The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.
New in version 1.2.
- kwargs :
Any other parameter that should be passed to the callables used.
- Returns
result – The resulting dataset
- Return type
NDData
-like
Notes
If a
callable
is used formask
,wcs
ormeta
the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined askwargs
and must start with"wcs_"
(for wcs callable) or"meta_"
(for meta callable). This startstring is removed before the callable is called."first_found"
can also be abbreviated with"ff"
.
-
plot
(*args, **kwargs)[source]¶ 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 theNDCube.plotter
class is set to a differentPlotter
class.
-
reproject_to
(target_wcs, shape_out=None, order='bilinear', output_array=None, return_footprint=False)¶ Reprojects this NDCube to the coordinates described by another WCS object.
- Parameters
target_wcs (
astropy.wcs.wcsapi.BaseHighLevelWCS
,astropy.wcs.wcsapi.BaseLowLevelWCS
,) – orastropy.io.fits.Header
The WCS object to which theNDCube
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 thetarget_wcs
is used.order (
int
orstr
) – The order of the interpolation. This can be any of: ‘nearest-neighbor’, ‘bilinear’, ‘biquadratic’, or ‘bicubic’.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.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 suppliedtarget_wcs
will be the.wcs
attribute of the outputNDCube
.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
, anduncertainty
attributes yet. However,meta
andglobal_coords
are copied to the outputNDCube
.
-
classmethod
subtract
(operand, operand2=None, **kwargs)¶ Performs subtraction by evaluating
self
-operand
.- Parameters
operand (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
-operand
. Ifoperand2
is given it will performoperand
-operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.operand2 (
NDData
-like instance) – Ifoperand2
isNone
or not given it will perform the operationself
-operand
. Ifoperand2
is given it will performoperand
-operand2
. If the method was called on a class rather than on the instanceoperand2
must be given.propagate_uncertainties (
bool
orNone
, optional) –If
None
the result will have no uncertainty. IfFalse
the result will have a copied version of the first operand that has an uncertainty. IfTrue
the result will have a correctly propagated uncertainty from the uncertainties of the operands but this assumes that the uncertainties areNDUncertainty
-like. Default isTrue
.Changed in version 1.2: This parameter must be given as keyword-parameter. Using it as positional parameter is deprecated.
None
was added as valid parameter value.handle_mask (callable,
'first_found'
orNone
, optional) –If
None
the result will have no mask. If'first_found'
the result will have a copied version of the first operand that has a mask). If it is a callable then the specified callable must create the resultsmask
and if necessary provide a copy. Default isnumpy.logical_or
.New in version 1.2.
handle_meta (callable,
'first_found'
orNone
, optional) –If
None
the result will have no meta. If'first_found'
the result will have a copied version of the first operand that has a (not empty) meta. If it is a callable then the specified callable must create the resultsmeta
and if necessary provide a copy. Default isNone
.New in version 1.2.
compare_wcs (callable,
'first_found'
orNone
, optional) –If
None
the result will have no wcs and no comparison between the wcs of the operands is made. If'first_found'
the result will have a copied version of the first operand that has a wcs. If it is a callable then the specified callable must compare thewcs
. The resultingwcs
will be like ifFalse
was given otherwise it raises aValueError
if the comparison was not successful. Default is'first_found'
.New in version 1.2.
uncertainty_correlation (number or
ndarray
, optional) –The correlation between the two operands is used for correct error propagation for correlated data as given in: https://en.wikipedia.org/wiki/Propagation_of_uncertainty#Example_formulas Default is 0.
New in version 1.2.
- kwargs :
Any other parameter that should be passed to the callables used.
- Returns
result – The resulting dataset
- Return type
NDData
-like
Notes
If a
callable
is used formask
,wcs
ormeta
the callable must accept the corresponding attributes as first two parameters. If the callable also needs additional parameters these can be defined askwargs
and must start with"wcs_"
(for wcs callable) or"meta_"
(for meta callable). This startstring is removed before the callable is called."first_found"
can also be abbreviated with"ff"
.