image

image#

astrophot.image.Image#

Core class to represent images with pixel values, pixel scale, and a window defining the spatial coordinates on the sky. It supports arithmetic operations with other image objects while preserving logical image boundaries. It also provides methods for determining the coordinate locations of pixels

Args:

data: The image data as a tensor of pixel values. If not provided, a tensor of zeros will be created.
zeropoint: The zeropoint of the image, which is used to convert from pixel flux to magnitude.
crpix: The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates.
pixelscale: The side length of a pixel, used to create a simple diagonal CD matrix.
wcs: An optional Astropy WCS object to initialize the image.
filename: The filename to load the image from. If provided, the image will be loaded from the file.
hduext: The HDU extension to load from the FITS file specified in filename.
identity: An optional identity string for the image.

these parameters are added to the optimization model:

Parameters:

crval: The reference coordinate of the image in degrees [RA, DEC].
crtan: The tangent plane coordinate of the image in arcseconds [x, y].
CD: The coordinate transformation matrix in arcseconds/pixel.

method: blank_copy( **kwargs)

Produces a blank copy of the image which has the same properties except that its data is now filled with zeros.

method: clear_state()

Clear the active state _value for all params below this Module in the DAG. This should not be used by a user under normal circumstances.

method: coordinate_center_meshgrid() -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of coordinate locations in the image, centered on the pixel grid.

method: coordinate_corner_meshgrid() -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of coordinate locations in the image, with corners at the pixel grid.

method: coordinate_quad_meshgrid( order=3) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of coordinate locations in the image, with quadrature sampling.

method: coordinate_simpsons_meshgrid() -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of coordinate locations in the image, with Simpson’s rule sampling.

method: copy( **kwargs)

Produce a copy of this image with all of the same properties. This can be used when one wishes to make temporary modifications to an image and then will want the original again.

method: crop( pixels: Union[int, Tuple[int, int], Tuple[int, int, int, int]], **kwargs)

Crop the image by the number of pixels given. This will crop the image in all four directions by the number of pixels given.

given data shape (N, M) the new shape will be:

crop - int: crop the same number of pixels on all sides. new shape (N - 2crop, M - 2crop) crop - (int, int): crop each dimension by the number of pixels given. new shape (N - 2crop[1], M - 2crop[0]) crop - (int, int, int, int): crop each side by the number of pixels given assuming (x low, x high, y low, y high). new shape (N - crop[2] - crop[3], M - crop[0] - crop[1])

method: find_index( param: Union[caskade.param.Param, tuple[caskade.param.Param], ForwardRef(‘Module’)], scheme: str = ‘array’) -> Union[int, slice]

Identify what index is associated with a param in the dynamic params array.

Parameters#

param: Union[Param, tuple[Param], Module] The param for which to find the associated index. scheme: str Whether to search the array (default) params or list version of params. dict is currently unsupported.

Returns#

param_info: Union[int, slice] A int giving the index associated with the provided Param object. If the param is multi-dimensional then the result will be a slice over all indices associated with that param.

method: find_param( idx: Union[int, tuple[int]], group: Optional[int] = None, scheme: str = ‘array’) -> tuple[caskade.param.Param, tuple[int]]

Identify which param is associated with the provided index in the dynamic params array.

Parameters#

idx: Union[int, tuple[int]] The index in the params array at which we wish to find the associated param. group: Optional[int] If the dynamic params have multiple group values, then this argument specifies which group to check. scheme: str Whether to search the array (default) params or list version of params. dict is currently unsupported.

Returns#

param_info: tuple[Param, tuple[int]] A tuple with the Param object and the index within the Param value associated with idx (empty tuple if scalar). If idx is a tuple then the result is a tuple of these results.

method: get_window( other: Union[astrophot.image.window.Window, ForwardRef(‘Image’)], indices=None, **kwargs)

Get a new image object which is a window of this image corresponding to the other image’s window. This will return a new image object with the same properties as this one, but with the data cropped to the other image’s window.

method: hierarchical_link( key: str, child: ‘Node’)

Link the current Node object to another Node object as a child in a hierarchical manner. See link for more detail on linking. A hierarchical link will allow batching internally to the simulator.

Parameters#

key: (str) The key to link the child node with. child: (Node) The child Node object to link to.

method: load( filename: Union[str, astropy.io.fits.hdu.hdulist.HDUList], hduext: int = 0)

Load an image from a FITS file. This will load the primary HDU and set the data, CD, crpix, crval, and crtan attributes accordingly. If the WCS is not tangent plane, it will warn the user.

method: pixel_center_meshgrid( window=None, pad=0, upsample=1) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of pixel coordinates in the image, centered on the pixel grid.

method: pixel_collecting_area( I_, J_, upsample, CD)

The area of the sky that each pixel collects light from, in arcsec^2. This is just the pixel area, but can be overridden for certain types of images (e.g. SIP images) where the pixel collecting area is not the same as the pixel area.

method: pixel_corner_meshgrid( window=None, pad=0, upsample=1) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of pixel coordinates in the image, with corners at the pixel grid.

method: pixel_quad_meshgrid( window=None, pad=0, upsample=1, order=3) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of pixel coordinates in the image, with quadrature sampling.

method: pixel_simpsons_meshgrid( window=None, pad=0, upsample=1) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

Get a meshgrid of pixel coordinates in the image, with Simpson’s rule sampling.

method: pixel_to_world( i: Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], j: Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

A wrapper which applies :meth:pixel_to_plane then :meth:plane_to_world, see those methods for further information.

method: reduce( scale: int, **kwargs)

This operation will downsample an image by the factor given. If scale = 2 then 2x2 blocks of pixels will be summed together to form individual larger pixels. A new image object will be returned with the appropriate pixelscale and data tensor. Note that the window does not change in this operation since the pixels are condensed, but the pixel size is increased correspondingly.

Args:

scale (int): The scale factor by which to reduce the image.

method: set_values( params: Union[Annotated[torch.Tensor, ‘One of: torch.Tensor, numpy.ndarray, jax.numpy.ndarray depending on the chosen backend.’], Sequence, Mapping], dynamic=True, attribute=’value’)

Fill the dynamic values of the module with the input values from params.

method: world_to_pixel( ra: Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], dec: Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]) -> Tuple[Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’], Annotated[torch.Tensor, ‘One of: torch.Tensor or jax.numpy.ndarray depending on the chosen backend.’]]

A wrapper which applies :meth:world_to_plane then :meth:plane_to_pixel, see those methods for further information.

astrophot.image.ImageBatchMixin#

Specialized ImageList type where the images are all the same size.

An ImageBatch has restrictions on the shape of the images it can hold, but in exchange it allows vectorized operations over a batch of images.

Some notes to keep in mind:

All the images must be the regular image type (i.e. not SIP or CMOS images yet).
All the images must have the same shape, otherwise the batch operations will not work.
The ImageBatch does not itself accelerate any operations, it facilitates the BatchSceneModel.
Otherwise the ImageBatch behaves like a regular ImageList.

astrophot.image.TargetImage#

Image object which represents the data to be fit by a model. It can include a variance image, mask, and PSF as anciliary data which describes the target image.

Target images are a basic unit of data in AstroPhot, they store the information collected from telescopes for which models are to be fit. There is minimal functionality in the Target_Image object itself, it is mostly defined in terms of how other objects interact with it.

Basic usage:

Some important information to keep in mind. First, providing an astropy WCS object is the best way to keep track of coordinates and pixel scale properties, especially when dealing with multi-band data. If images have relative positioning, rotation, pixel sizes, field of view this will all be handled automatically by taking advantage of WCS objects. Second, Providing accurate variance (or weight) maps is critical to getting a good fit to the data. This is a very common source of issues so it is worthwhile to review literature on how best to construct such a map. A good starting place is the FAQ for GALFIT: https://users.obs.carnegiescience.edu/peng/work/galfit/CHI2.html which is an excellent resource for all things image modeling. Just note that AstroPhot uses variance or weight maps, not sigma images. AstroPhot will not crete a variance map for the user, by default it will just assume uniform variance which is rarely accurate. Third, The PSF pixelscale must be a multiple of the image pixelscale. So if the image has a pixelscale of 1 then the PSF must have a pixelscale of 1, 1/2, 1/3, etc for anything to work out. Note that if the PSF pixelscale is finer than the image, then all modelling will be done at the higher resolution. This is recommended for accuracy though it can mean higher memory consumption.

SUBUNIT DataMixin

Mixin for data handling in image objects.

This mixin provides functionality for handling variance and mask, as well as other ancillary data.

Args:

mask: A boolean mask indicating which pixels to ignore.
std: Standard deviation of the image pixels.
variance: Variance of the image pixels.
weight: Weights for the image pixels.

Note that only one of std, variance, or weight should be provided at a time. If multiple are provided, an error will be raised.

SUBUNIT Image

Core class to represent images with pixel values, pixel scale, and a window defining the spatial coordinates on the sky. It supports arithmetic operations with other image objects while preserving logical image boundaries. It also provides methods for determining the coordinate locations of pixels

Args:

data: The image data as a tensor of pixel values. If not provided, a tensor of zeros will be created.
zeropoint: The zeropoint of the image, which is used to convert from pixel flux to magnitude.
crpix: The reference pixel coordinates in the image, which is used to convert from pixel coordinates to tangent plane coordinates.
pixelscale: The side length of a pixel, used to create a simple diagonal CD matrix.
wcs: An optional Astropy WCS object to initialize the image.
filename: The filename to load the image from. If provided, the image will be loaded from the file.
hduext: The HDU extension to load from the FITS file specified in filename.
identity: An optional identity string for the image.

these parameters are added to the optimization model:

Parameters:

crval: The reference coordinate of the image in degrees [RA, DEC].
crtan: The tangent plane coordinate of the image in arcseconds [x, y].
CD: The coordinate transformation matrix in arcseconds/pixel.