Data

Image data handling and WCS coordinate grid utilities.

socca.data.pad_size(shape, factor=2.0)

Compute the standard padded shape for convolution.

class socca.data.WCSgrid(hdu, subgrid=1)

Bases: object

WCS coordinate grid for image.

Parameters:

• hdu (fits.PrimaryHDU) – FITS HDU object containing image data and header.

• subgrid (int, optional) – Subgrid factor for sub-pixel sampling (default is 1).

Variables:

• x (jax.numpy.ndarray) – x-coordinate array in world coordinates.

• y (jax.numpy.ndarray) – y-coordinate array in world coordinates.

static getmesh(hdu=None, wcs=None, header=None)

Generate mesh coordinate arrays in world coordinate system.

Creates 2D coordinate grids in world coordinates from either an HDU, WCS object, or FITS header. Handles 360-degree wraparound for RA coordinates near the discontinuity.

Parameters:

• hdu (fits.PrimaryHDU or fits.ImageHDU, optional) – FITS HDU object containing header with WCS information.

• wcs (astropy.wcs.WCS, optional) – WCS object for coordinate transformation. If None, derived from header or HDU.

• header (fits.Header, optional) – FITS header containing WCS keywords.

Returns:

(gridwx, gridwy) - 2D arrays of x and y world coordinates.

Return type:

tuple of numpy.ndarray

Raises:

ValueError – If neither header nor hdu is provided, or if both are provided.

Notes

Exactly one of hdu or header must be specified (not both). The method automatically handles RA coordinate discontinuity at 360°.

class socca.data.FFTspec(hdu)

Bases: object

FFT specification for image.

Parameters:

hdu (fits.PrimaryHDU) – FITS HDU object containing image data and header.

Variables:

• image_shape (tuple of int) – Shape of the original image (ny, nx).

• padded_shape (tuple of int) – Shape of the zero-padded array used for convolution.

• header (dict) – Dictionary containing relevant header keywords.

• center (jax.numpy.ndarray) – FFT of a unit impulse at the image centre, computed on the padded grid.

• freq (list of jax.numpy.ndarray) – Frequency grids in u and v directions, defined on the padded grid.

• pulse (jax.numpy.ndarray) – FFT of a unit pulse at the reference pixel position.

shift(xc, yc)

Compute Fourier shift for a point source at (xc, yc).

Parameters:

• xc (float) – x-coordinate of the point source in world coordinates.

• yc (float) – y-coordinate of the point source in world coordinates.

Returns:

Complex array representing the Fourier shift for the point source.

Return type:

jax.numpy.ndarray

fft(data)

Compute FFT of the input data with zero-padding.

ifft(data)

Compute inverse FFT to get image from Fourier-space data.

class socca.data.Image(img, response=None, exposure=None, noise=None, **kwargs)

Bases: object

Image object for astronomical data.

A class for handling astronomical images with support for WCS, PSF, masking, and noise modeling.

This class provides a comprehensive framework for working with astronomical images, including coordinate transformations, PSF convolution, exposure and response maps, region masking, and various noise models. It supports FFT-based operations and sub-pixel sampling through a configurable subgrid parameter.

Parameters:

• img (str, HDU, or array_like) – Input image data. Can be a filename, FITS HDU object, or array.

• response (str, HDU, or array_like, optional) – Response map for the image. If None, uniform response is assumed.

• exposure (str, HDU, or array_like, optional) – Exposure map for the image. If None, uniform exposure is assumed.

• noise (noise object, optional) – Noise model instance (e.g., Normal, NormalALMA). Defaults to Normal().

• **kwargs (dict, optional) –

  Additional keyword arguments:

  • subgridint, optional

    Subgrid factor for sub-pixel sampling (default: 1).

  • img_idxint, optional

    HDU index to load from the image file (default: 0).

  • exp_idxint, optional

    HDU index to load from the exposure file (default: 0).

  • resp_idxint, optional

    HDU index to load from the response file (default: 0).

  • centertuple or SkyCoord, optional

    Center coordinates for cutout operation.

  • csizeint, array_like, or Quantity, optional

    Size for cutout operation.

  • addmaskdict, optional

    Dictionary with ‘regions’ and ‘combine’ keys for masking.

  • addpsfdict, optional

    Dictionary with ‘img’, ‘normalize’, and ‘idx’ keys for PSF.

Variables:

• hdu (fits.PrimaryHDU) – FITS HDU object containing image data and header.

• wcs (astropy.wcs.WCS) – World Coordinate System object for coordinate transformations.

• data (jax.numpy.ndarray) – Image data array.

• mask (jax.numpy.ndarray) – Binary mask array (1 for valid pixels, 0 for masked).

• grid (WCSgrid) – Coordinate grid object with x and y coordinate arrays.

• fft (FFTspec) – FFT specification object for Fourier space operations.

• exp (jax.numpy.ndarray) – Exposure map array (applied after the beam convolution).

• resp (jax.numpy.ndarray) – Response map array (applied prior to the beam convolution).

• psf (ndarray or None) – Point spread function kernel.

• psf_fft (jax.numpy.ndarray or None) – FFT of the PSF kernel.

• noise (noise object) – Noise model instance.

• subgrid (int) – Subgrid sampling factor.

Notes

• Missing CDELT keywords are computed from CD matrix elements.

• NaN values in the input image are automatically masked.

cutout(center, csize)

Extract a cutout region from the image.

Creates a smaller cutout of the image centered at the specified coordinates. All image attributes (data, mask, exposure, response, PSF, grid, FFT) are updated to reflect the cutout region.

Parameters:

• center (tuple or astropy.coordinates.SkyCoord) – Center coordinates for the cutout. Can be a SkyCoord object or a tuple of (RA, Dec) values.

• csize (int, array_like, or astropy.units.Quantity) – Size of the cutout. Can be a single value (for square cutout), a tuple of (width, height), or a Quantity with angular units.

Raises:

NotImplementedError – If the noise model is not Normal (uncorrelated noise).

Notes

• Updates all image attributes including WCS, grid, and FFT specifications

• If a PSF is present, it is also cutout to match the new image size

• The image center (CRPIX/CRVAL) is updated to the cutout center

addmask(regions, combine=True)

Add or update masking regions to the image.

Applies masking from various input formats (region files, pyregion objects, arrays, or HDUs). Masks can be combined with existing masks or replace them entirely.

Parameters:

• regions (list) –

  List of regions to be masked. Elements can be:

  • str: Path to a region file (DS9/CRTF format)

  • pyregion.Shape: pyregion shape object

  • numpy.ndarray: Binary mask array (1=valid, 0=masked)

  • fits.ImageHDU or fits.PrimaryHDU: FITS mask HDU

• combine (bool, optional) – If True, combine with the existing mask (logical AND). If False, reset and replace the existing mask. Default is True.

Notes

• Multiple regions can be specified in a single call

• For region files/shapes, pixels inside the region are masked (set to 0)

• For array/HDU inputs, the mask is multiplied with existing mask

• HDU masks are automatically reprojected to match image WCS

addpsf(img, normalize=True, idx=0)

Add a point spread function (PSF) to the image.

Loads and prepares a PSF kernel for convolution operations. The PSF is normalized, resized if needed, and its FFT is precomputed for efficient convolution in Fourier space.

Parameters:

• img (array_like, fits.HDU, or str) –

  PSF image input. Can be:

  • numpy or jax array: PSF kernel directly

  • fits.ImageHDU or fits.PrimaryHDU: FITS HDU with PSF

  • str: Path to FITS file containing PSF

• normalize (bool, optional) – If True, normalize the PSF to unit sum before use. Default is True.

• idx (int, optional) – HDU index to load if img is a filename. Default is 0 (primary HDU).

Notes

• If PSF dimensions exceed image dimensions, it is automatically cropped

• The PSF FFT is precomputed and stored in self.convolve.psf_fft

• PSF kernel is stored in self.psf for reference

• PSF is zero-padded to match image dimensions before FFT

class socca.data.Convolve(kernel, image_shape)

Bases: object

FFT-based convolution operator with optional zero-padding.

__init__(kernel, image_shape)

Initialize the convolution operator.

Parameters:

• kernel (array_like) – PSF kernel array.

• image_shape (tuple of int) – Shape of the images to convolve.