DataIMG

class sherpa.astro.data.DataIMG(name, x0, x1, y, shape=None, staterror=None, syserror=None, sky=None, eqpos=None, coord='logical', header=None)

Bases: Data2D

Image data set

This class builds on sherpa.data.Data2D to add support for region filters and the ability to describe the data in different coordinate systems, such as the “logical” coordinates (pixels of the image), the “physical” coordinates (e.g. detector coordinates), and the “world” coordinates (e.g. Ra/Dec on the sky).

Note

In principle, this class can deal with any shape of data, even with sparse data. However, the added functionality over the base class is most useful for regularly gridded images. In that case, that data should be ordered as in the FITS image conventions, i.e. [column, row]; in other words x0 is the x-axis of the image and x1 is the y-axis in an x-y-plot. (Sherpa uses y for the dependent variable and calls the axes x0 and x1.)

Only with this convention will the routines that return a 2D array (e.g. for plotting) work correctly. Fitting is done on the flattened 1D arrays and will work for any ordering.

Parameters:

namestr

name of this dataset

x0array_like

Independent coordinate values for the first dimension

x1array_like

Independent coordinate values for the second dimension

yarray_like

The values of the dependent observable.

shapetuple

Shape of the data grid (optional). This is used return the data as an image e.g. for display, but it not needed for fitting and modelling.

staterrorarray_like

the statistical error associated with the data

syserrorarray_like

the systematic error associated with the data

skysherpa.astro.io.wcs.WCS

The optional WCS object that converts to the physical coordinate system.

eqpossherpa.astro.io.wcs.WCS

The optional WCS object that converts to the world coordinate system.

coordstr

The coordinate system of the data. This can be one of ‘logical’, ‘physical’, or ‘world’. ‘image’ is an alias for ‘logical’ and ‘wcs’ is an alias for ‘world’.

headerdict

The FITS header associated with the data to store meta data.

Attributes:

coord

Return the coordinate setting.

dep

Left for compatibility with older versions

eqpos

indep

The grid of the data space associated with this data set.

mask

Mask array for dependent variable

size

The number of elements in the data set.

sky

staterror

The statistical error on the dependent axis, if set.

syserror

The systematic error on the dependent axis, if set.

x0

kept for compatibility

x1

kept for compatibility

y

The dependent axis.

Methods

eval_model(modelfunc)	Evaluate the model on the independent axis.
eval_model_to_fit(modelfunc)	Evaluate the model on the independent axis after filtering.
from_2d_array(name, *, y[, x0, x1, ...])	Create a DataIMG instance from a 2-dimensional array.
from_2d_array_with_wcs(name, *, y[, ...])	Create a DataIMG instance from 2D data and WCS information.
get_dep([filter])	Return the dependent axis of a data set.
get_dims([filter])	Return the dimensions of this data space as a tuple of tuples.
get_error([filter, staterrfunc])	Return the total error on the dependent variable.
get_img([yfunc])	Return the dependent axis as a 2D array.
get_indep([filter])	Return the independent axes of a data set.
get_max_pos([dep])	Return the coordinates of the maximum value.
get_staterror([filter, staterrfunc])	Return the statistical error on the dependent axis of a data set.
get_syserror([filter])	Return the systematic error on the dependent axis of a data set.
get_x0label()	Return the label for the first independent axis.
get_x1label()	Return the label for the second independent axis.
get_y([filter, yfunc, use_evaluation_space])	Return dependent axis in N-D view of dependent variable
get_yerr([filter, staterrfunc])	Return errors in dependent axis in N-D view of dependent variable.
get_ylabel([yfunc])	Return label for dependent axis in N-D view of dependent variable.
notice2d([val, ignore])	Apply a 2D filter.
set_coord(coord)	Change the coord attribute.
set_dep(val)	Set the dependent variable values.
set_x0label(label)	Set the label for the first independent axis.
set_x1label(label)	Set the label for the second independent axis.
set_ylabel(label)	Set the label for the dependent axis.

apply_filter
filter_region
get_bounding_mask
get_filter
get_filter_expr
get_image
get_imgerr
get_logical
get_physical
get_wcs
get_world
get_x0
get_x1
ignore
notice
set_indep
to_contour
to_fit
to_guess

Examples

In this example, we create an image data set, but do not specify the coordinate system. This means that the coordinates are expressed in the logical coordinates of the image, i.e. in pixels:

>>> from sherpa.astro.data import DataIMG
>>> import numpy as np
>>> # Note ordering of x1, x0 here
>>> x1, x0 = np.mgrid[20:30, 5:20]
>>> datashape = x0.shape
>>> y = np.sqrt((x0 - 10)**2 + (x1 - 31)**2)
>>> x0flat = x0.flatten()
>>> x1flat = x1.flatten()
>>> yflat = y.flatten()
>>> image = DataIMG("bimage", x0=x0flat, x1=x1flat, y=yflat, shape=datashape)

In this example, we end up with a “logical” coordinate system in image and no WCS system to convert it to anything else. On the other hand, in FITS standard terminology, the “logical” coordinate system is the “image”, counting pixels starting at 1, while here the x0lo` and x1lo actually start at 20 and 5, respectively. This behavior works for now, but might be revisited.

For the common case of creating an image data set from a 2D array, the from_2d_array class method can be used. In this case, the length of x0 and x1 must match the shape of the 2D numpy array and Sherpa will take care of transforming it from numpy [row, column] ordering to the [column, row] ordering:

>>> x0 = np.arange(20, 30)
>>> x1 = np.arange(5, 20)
>>> print(y.shape, x0.shape, x1.shape)
(10, 15) (10,) (15,)
>>> image = DataIMG.from_2d_array("bimage", y=y, x0=x0, x1=x1)

It’s even easier if no particular coordinate system is needed for x0 and x1 and the coordinates are simply pixel indices, which can be generated automatically (starting at 1):

>>> image = DataIMG.from_2d_array("bimage", y=y)

Attributes Summary

coord	Return the coordinate setting.
dep	Left for compatibility with older versions
eqpos	The optional WCS object that converts to the world coordinate system.
indep	The grid of the data space associated with this data set.
mask	Mask array for dependent variable
ndim	The dimensionality of the dataset, if defined, or None.
size	The number of elements in the data set.
sky	The optional WCS object that converts to the physical coordinate system.
staterror	The statistical error on the dependent axis, if set.
syserror	The systematic error on the dependent axis, if set.
x0	kept for compatibility
x1	kept for compatibility
y	The dependent axis.

Methods Summary

apply_filter(data)
eval_model(modelfunc)	Evaluate the model on the independent axis.
eval_model_to_fit(modelfunc)	Evaluate the model on the independent axis after filtering.
filter_region(data)
from_2d_array(name, *, y[, x0, x1, ...])	Create a DataIMG instance from a 2-dimensional array.
from_2d_array_with_wcs(name, *, y[, ...])	Create a DataIMG instance from 2D data and WCS information.
get_bounding_mask()
get_dep([filter])	Return the dependent axis of a data set.
get_dims([filter])	Return the dimensions of this data space as a tuple of tuples.
get_error([filter, staterrfunc])	Return the total error on the dependent variable.
get_filter()
get_filter_expr()
get_image()
get_img([yfunc])	Return the dependent axis as a 2D array.
get_imgerr()
get_indep([filter])	Return the independent axes of a data set.
get_logical()
get_max_pos([dep])	Return the coordinates of the maximum value.
get_physical()
get_staterror([filter, staterrfunc])	Return the statistical error on the dependent axis of a data set.
get_syserror([filter])	Return the systematic error on the dependent axis of a data set.
get_wcs()
get_world()
get_x0([filter])
get_x0label()	Return the label for the first independent axis.
get_x1([filter])
get_x1label()	Return the label for the second independent axis.
get_y([filter, yfunc, use_evaluation_space])	Return dependent axis in N-D view of dependent variable
get_yerr([filter, staterrfunc])	Return errors in dependent axis in N-D view of dependent variable.
get_ylabel([yfunc])	Return label for dependent axis in N-D view of dependent variable.
ignore(*args, **kwargs)
notice([x0lo, x0hi, x1lo, x1hi, ignore])
notice2d([val, ignore])	Apply a 2D filter.
set_coord(coord)	Change the coord attribute.
set_dep(val)	Set the dependent variable values.
set_indep(val)
set_x0label(label)	Set the label for the first independent axis.
set_x1label(label)	Set the label for the second independent axis.
set_ylabel(label)	Set the label for the dependent axis.
to_contour([yfunc])
to_fit([staterrfunc])
to_guess()

Attributes Documentation

coord

Return the coordinate setting.

The attribute is one of ‘logical’, ‘physical’, or ‘world’. Use set_coord to change the setting.

dep

Left for compatibility with older versions

eqpos = None

The optional WCS object that converts to the world coordinate system.

indep

The grid of the data space associated with this data set.

When set, the field must be set to a tuple, even for a one-dimensional data set. The “related” fields such as the dependent axis and the error fields are set to None if their size does not match.

Changed in version 4.14.1: The filter created by notice and ignore is now cleared when the independent axis is changed.

Returns:

tuple of array_like or None

mask

Mask array for dependent variable

Returns:

maskbool or numpy.ndarray

ndim: int | None = 2

The dimensionality of the dataset, if defined, or None.

size

The number of elements in the data set.

Returns:

sizeint or None

If the size has not been set then None is returned.

sky = None

The optional WCS object that converts to the physical coordinate system.

staterror

The statistical error on the dependent axis, if set.

This must match the size of the independent axis.

syserror

The systematic error on the dependent axis, if set.

This must match the size of the independent axis.

x0

kept for compatibility

x1

kept for compatibility

y

The dependent axis.

If set, it must match the size of the independent axes.

Methods Documentation

apply_filter(data)

eval_model(modelfunc: Callable[[...], Sequence[float] | ndarray]) → Sequence[float] | ndarray

Evaluate the model on the independent axis.

eval_model_to_fit(modelfunc: Callable[[...], Sequence[float] | ndarray]) → Sequence[float] | ndarray

Evaluate the model on the independent axis after filtering.

filter_region(data)

classmethod from_2d_array(name: str, *, y: NDArray[floating], x0: NDArray[floating] | None = None, x1: NDArray[floating] | None = None, staterror: NDArray[floating] | None = None, syserror: NDArray[floating] | None = None, header: Mapping[str, Any] | None = None) → DataIMG

Create a DataIMG instance from a 2-dimensional array.

Parameters:

namestr

The name of the dataset.

yndarray with 2 dimensions

The dependent variable array.

x0, x1: ndarray, optional

The independent variable arrays; the length of x0 must match y’s first dimension, and the length of x1 must match y’s second dimension. If not provided, they will be generated, starting at 1.

Note

This does not follow the usual Python conventions to start enumerations at 0, instead, it follows the fits conventions where the first pixel has the coordinate (1, 1).

staterrorndarray with 2 dimensions, optional

The statistical error array.

syserrorndarray with 2 dimensions, optional

The systematic error array.

headerdict, optional

The header information for the data.

Returns:

dataimgDataIMG

A DataIMG instance.

Examples

Create a DataIMG instance from 2D data. Here, we first create a 2-D array of values y, but in practice this might be read in from a file, from the output of a simulation, or as a result of some other computation.

>>> import numpy as np
>>> from sherpa.astro.data import DataIMG
>>> x1 = np.arange(20, 30, 2)
>>> x0 = np.arange(5, 20, 2)
>>> y = np.sqrt((x0[:, np.newaxis] - 10)**2 + (x1[np.newaxis, :] - 31)**2)
>>> reg2d = DataIMG.from_2d_array("regular2d", x0=x0, x1=x1, y=y)

Changed in version 4.19.0: The get_axis method has been removed because it had inconsistent outputs. Use get_x0 and get_x1 or get_indep instead.

classmethod from_2d_array_with_wcs(name: str, *, y: npt.NDArray[np.floating], staterror: npt.NDArray[np.floating] | None = None, syserror: npt.NDArray[np.floating] | None = None, sky: WCS, eqpos: WCS, coord: Literal['logical', 'image', 'physical', 'world', 'wcs'] = 'logical', header: Mapping[str, Any] | None = None) → DataIMG

Create a DataIMG instance from 2D data and WCS information.

get_bounding_mask()

get_dep(filter: bool = False) → ndarray | None

Return the dependent axis of a data set.

Parameters:

filterbool, optional

Should the filter attached to the data set be applied to the return value or not. The default is False.

Returns:

axis: array

The dependent axis values for the data set. This gives the value of each point in the data set.

See also

get_indep

Return the independent axis of a data set.

get_error

Return the errors on the dependent axis of a data set.

get_staterror

Return the statistical errors on the dependent axis of a data set.

get_syserror

Return the systematic errors on the dependent axis of a data set.

get_dims(filter: bool = False) → tuple[int, ...]

Return the dimensions of this data space as a tuple of tuples. The first element in the tuple is a tuple with the dimensions of the data space, while the second element provides the size of the dependent array.

Returns:

tuple

get_error(filter=False, staterrfunc=None)

Return the total error on the dependent variable.

Parameters:

filterbool, optional

Should the filter attached to the data set be applied to the return value or not. The default is False.

staterrfuncfunction

If no statistical error has been set, the errors will be calculated by applying this function to the dependent axis of the data set.

Returns:

axisarray or None

The error for each data point, formed by adding the statistical and systematic errors in quadrature.

See also

get_dep

Return the independent axis of a data set.

get_staterror

Return the statistical errors on the dependent axis of a data set.

get_syserror

Return the systematic errors on the dependent axis of a data set.

get_filter()

get_filter_expr()

get_image()

get_img(yfunc=None)

Return the dependent axis as a 2D array.

The data is not filtered.

Parameters:

yfuncsherpa.models.model.Model instance or None, optional

If set then it is a model that is evaluated on the data grid and returned along with the dependent axis.

Returns:

imgndarray or (ndarray, ndarray)

The data as a 2D array or a pair of 2D arrays when yfunc is set.

get_imgerr()

get_indep(filter: bool = False) → tuple[ndarray, ...] | tuple[None, ...]

Return the independent axes of a data set.

Parameters:

filterbool, optional

Should the filter attached to the data set be applied to the return value or not. The default is False.

Returns:

axis: tuple of arrays

The independent axis values for the data set. This gives the coordinates of each point in the data set.

See also

get_dep

Return the dependent axis of a data set.

get_logical()

get_max_pos(dep: ndarray | None = None) → tuple[float, float] | list[tuple[float, float]]

Return the coordinates of the maximum value.

Parameters:

depndarray or None, optional

The data to search and it must match the current data filter. If not given then the dependent axis is used.

Returns:

coordspair or list of pairs

The coordinates of the maximum location. The data values match the values returned by get_x0 and get_x1. If there is only one maximum pixel then a pair is returned otherwise a list of pairs is returned.

See also

get_dep, get_x0, get_x1

get_physical()

get_staterror(filter: bool = False, staterrfunc: Callable[[Sequence[float] | ndarray], Sequence[float] | ndarray] | None = None) → Sequence[float] | ndarray | None

Return the statistical error on the dependent axis of a data set.

Parameters:

filterbool, optional

Should the filter attached to the data set be applied to the return value or not. The default is False.

staterrfuncfunction

If no statistical error has been set, the errors will be calculated by applying this function to the dependent axis of the data set.

Returns:

axisarray or None

The statistical error for each data point. A value of None is returned if the data set has no statistical error array and staterrfunc is None.

See also

get_error

Return the errors on the dependent axis of a data set.

get_indep

Return the independent axis of a data set.

get_syserror

Return the systematic errors on the dependent axis of a data set.

get_syserror(filter: bool = False) → ndarray | None

Return the systematic error on the dependent axis of a data set.

Parameters:

filterbool, optional

Should the filter attached to the data set be applied to the return value or not. The default is False.

Returns:

axisarray or None

The systematic error for each data point. A value of None is returned if the data set has no systematic errors.

See also

get_error

Return the errors on the dependent axis of a data set.

get_indep

Return the independent axis of a data set.

get_staterror

Return the statistical errors on the dependent axis of a data set.

get_wcs()

get_world()

get_x0(filter: bool = False) → ndarray | None

get_x0label() → str

Return the label for the first independent axis.

If set_x0label has been called then the label used in that call will be used, otherwise the label will change depending on the coordinate setting.

Changed in version 4.17.0: The return value depends on if set_x0label has been called.

See also

get_x1label, set_coord, set_x0label

get_x1(filter: bool = False) → ndarray | None

get_x1label() → str

Return the label for the second independent axis.

If set_x1label has been called then the label used in that call will be used, otherwise the label will change depending on the coordinate setting.

Changed in version 4.17.0: The return value depends on if set_x1label has been called.

See also

get_x0label, set_coord, set_x1label

get_y(filter=False, yfunc=None, use_evaluation_space=False)

Return dependent axis in N-D view of dependent variable

Parameters:

filter

yfunc

use_evaluation_space

Returns:

y: array or (array, array) or None

If yfunc is not None and the dependent axis is set then the return value is (y, y2) where y2 is yfunc evaluated on the independent axis.

get_yerr(filter=False, staterrfunc=None)

Return errors in dependent axis in N-D view of dependent variable.

Parameters:

filter

staterrfunc

Returns:

get_ylabel(yfunc=None) → str

Return label for dependent axis in N-D view of dependent variable.

Parameters:

yfunc

Unused.

Returns:

label: str

The label.

See also

set_ylabel

ignore(*args, **kwargs) → None

notice(x0lo: float | None = None, x0hi: float | None = None, x1lo: float | None = None, x1hi: float | None = None, ignore: bool = False) → None

notice2d(val=None, ignore=False)

Apply a 2D filter.

Parameters:

valstr or None, optional

The filter to apply. It can be a region string or a filename.

ignorebool, optional

If set then the filter should be ignored, not noticed.

set_coord(coord)

Change the coord attribute.

Changed in version 4.14.1: The filter created by notice2d is now cleared when the coordinate system is changed.

Parameters:

coord{‘logical’, ‘image’, ‘physical’, ‘world’, ‘wcs’}

The coordinate system to use. Note that “image” is a synonym for “logical” and “wcs” is a synomyn for “world”.

set_dep(val: Sequence[float] | ndarray | float) → None

Set the dependent variable values.

Parameters:

valsequence or number

If a number then it is used for each element.

set_indep(val: tuple[Sequence[float] | ndarray, ...] | tuple[None, ...]) → None

set_x0label(label: str) → None

Set the label for the first independent axis.

Added in version 4.17.0.

Parameters:

label: str

See also

get_x0label, set_x1label

set_x1label(label: str) → None

Set the label for the second independent axis.

Added in version 4.17.0.

Parameters:

label: str

See also

get_x1label, set_x0label

set_ylabel(label: str) → None

Set the label for the dependent axis.

Added in version 4.17.0.

Parameters:

label: str

The new label.

See also

get_ylabel

to_contour(yfunc=None)

to_fit(staterrfunc: Callable[[Sequence[float] | ndarray], Sequence[float] | ndarray] | None = None) → tuple[ndarray | None, Sequence[float] | ndarray | None, ndarray | None]

to_guess() → tuple[ndarray | None, ...]