regularizepsf

Global init.

Submodules

• regularizepsf.builder
• regularizepsf.exceptions
• regularizepsf.image_processing
• regularizepsf.psf
• regularizepsf.transform
• regularizepsf.util
• regularizepsf.visualize

Attributes

__version__

Classes

ArrayPSFBuilder	A builder that will take a series of images and construct an ArrayPSF to represent their implicit PSF.
ArrayPSF	A PSF represented as a set of arrays.
ArrayPSFTransform	Representation of a transformation from a source to a target PSF that can be applied to images.

Functions

simple_functional_psf(→ SimpleFunctionalPSF)	Decorate a SimpleFunctionalPSF.
varied_functional_psf(→ VariedFunctionalPSF)	Decorate to create a VariedFunctionalPSF.

Package Contents

class regularizepsf.ArrayPSFBuilder(psf_size: int)

A builder that will take a series of images and construct an ArrayPSF to represent their implicit PSF.

Initialize an ArrayPSFBuilder.

_psf_size

property psf_size

build(images: list[str] | list[pathlib.Path] | numpy.ndarray | collections.abc.Generator, sep_mask: list[str] | list[pathlib.Path] | numpy.ndarray | collections.abc.Generator | None = None, hdu_choice: int | None = 0, num_workers: int | None = None, interpolation_scale: int = 1, star_threshold: int = 3, average_method: str = 'median', percentile: float = 50, saturation_threshold: float = np.inf, image_mask: numpy.ndarray | None = None, star_minimum: float = 0, star_maximum: float = np.inf, sqrt_compressed: bool = False, return_patches: bool = False) → tuple[regularizepsf.psf.ArrayPSF, dict] | tuple[regularizepsf.psf.ArrayPSF, dict, dict]

Build the PSF model.

Parameters:

• images (list[str] | list[pathlib.Path] | np.ndarray | Generator) – Input images to use for PSF characterization

• sep_mask (list[str] | list[pathlib.Path] | np.ndarray | Generator | None) – Mask to use with source extraction (sep)

• hdu_choice (int | None) – HDU index to use when loading FITS input files

• num_workers (int | None) – Number of worker processes for multithreaded image processing, with None using all available CPUs

• interpolation_scale (int) – Interpolation scale to apply to input images after loading

• star_threshold (int) – Minimum threshold value for star detection using sep

• average_method (str) – Method for patch averaging (mean, percentile, or median)

• percentile (float) – Percentile value when specifying the percentile patch averaging method

• saturation_threshold (float) – Pixel value above which stars are considered saturated

• image_mask (np.ndarray | None) – Mask of pixels to ignore for PSF characterization in input images

• star_minimum (float) – Minimum threshold of center star for patch inclusion, in units of input data

• star_maximum (float) – Maximum threshold of center star for patch inclusion, in units of input data

• sqrt_compressed (bool) – Toggle to indicate if input data has been square-root compressed, and requires decompression

• return_patches (bool) – Toggle to return computed patches alongside model output

Returns:

Array PSF and the counts of stars in each component

Return type:

(ArrayPSF, dict)

class regularizepsf.ArrayPSF(values_cube: regularizepsf.util.IndexedCube, fft_cube: regularizepsf.util.IndexedCube | None = None, workers: int | None = None)

A PSF represented as a set of arrays.

Initialize an ArrayPSF model.

Parameters:

• values_cube (IndexedCube) – PSF model where keys are upper left coordinates of array patches in the image

• fft_cube (IndexedCube) – fft of the model

• workers (int | None) – Maximum number of workers to use for parallel computation of FFT. If negative, the value wraps around from os.cpu_count(). See scipy.fft.fft for more details. Only used if fft_cube is None.

_values_cube

_fft_cube = None

_workers = None

property coordinates: list[tuple[int, int]]

Get the keys of the PSF model, i.e., where it is evaluated as an array.

property values: numpy.ndarray

Get the model values.

property fft_evaluations: numpy.ndarray

Get the model values.

__getitem__(coord: tuple[int, int]) → numpy.ndarray

Evaluate the PSF model at specific coordinates.

fft_at(coord: tuple[int, int]) → numpy.ndarray

Retrieve the FFT evaluation at a coordinate.

save(path: pathlib.Path) → None

Save the PSF model to a file. Supports h5 and FITS.

Parameters:

path (pathlib.Path) – where to save the PSF model

Return type:

None

classmethod load(path: pathlib.Path) → ArrayPSF

Load the PSF model from a file. Supports h5 and FITS.

Parameters:

path (pathlib.Path) – where to load the PSF model from

Returns:

loaded model

Return type:

ArrayPSF

visualize_psfs(fig: matplotlib.figure.Figure | None = None, fig_scale: int = 1, edge_trim: int = 1, patch_stride: int = 1, imshow_args: dict | None = None) → None

Visualize the PSFs.

Parameters:

• fig (mp.figure.Figure) – the figure to plot in

• fig_scale (int) – increasing this will make the figure higher resolution

• edge_trim (int) – how many pixels to drop on each side of the PSF for plotting

• patch_stride (int) – multiple of how many patches to skip when plotting, 1 means no skipping, 2 plots every other, 3 every third

• imshow_args (dict) – additional arguments for imshow

Return type:

None

visualize_ffts(fig: matplotlib.figure.Figure | None = None, fig_scale: int = 1, edge_trim: int = 1, patch_stride: int = 1, imshow_args: dict | None = None) → None

Visualize the FFT kernels.

Parameters:

• fig (mp.figure.Figure) – the figure to plot in

• fig_scale (int) – increasing this will make the figure higher resolution

• edge_trim (int) – how many pixels to drop on each side of the PSF for plotting

• patch_stride (int) – multiple of how many patches to skip when plotting, 1 means no skipping, 2 plots every other, 3 every third

• imshow_args (dict) – additional arguments for imshow

Return type:

None

__eq__(other: ArrayPSF) → bool

Check equality between two ArrayPSFs.

property sample_shape: tuple[int, int]

Get the sample shape for this PSF model.

__len__() → int

Get the number of coordinates evaluated in this model.

regularizepsf.simple_functional_psf(arg: Any = None) → SimpleFunctionalPSF

Decorate a SimpleFunctionalPSF.

regularizepsf.varied_functional_psf(base_psf: SimpleFunctionalPSF = None) → VariedFunctionalPSF

Decorate to create a VariedFunctionalPSF.

class regularizepsf.ArrayPSFTransform(transfer_kernel: regularizepsf.util.IndexedCube)

Representation of a transformation from a source to a target PSF that can be applied to images.

Initialize a PSFTransform.

Parameters:

transfer_kernel (TransferKernel) – the transfer kernel required by this ArrayPSFTransform

_transfer_kernel

property psf_shape: tuple[int, int]

Retrieve the shape of the individual PSFs for this transform.

property coordinates: list[tuple[int, int]]

Retrieve the coordinates of the individual PSFs for this transform.

__len__() → int

Retrieve the number of coordinates used to represent this transform.

classmethod construct(source: regularizepsf.psf.ArrayPSF, target: regularizepsf.psf.ArrayPSF, alpha: float, epsilon: float) → ArrayPSFTransform

Construct an ArrayPSFTransform from a source to a target PSF.

Parameters:

• source (ArrayPSF) – source point spread function

• target (ArrayPSF) – target point spread function

• alpha (float) – controls the “hardness” of the transition from amplification to attenuation

• epsilon (float) – controls the maximum of the amplification

Returns:

corresponding ArrayPSFTransform instance

Return type:

ArrayPSFTransform

apply(image: numpy.ndarray, workers: int | None = None, pad_mode: str = 'symmetric', saturation_threshold: float = math.inf, saturation_dilation: int = 1, neighborhood_width: int = 7) → numpy.ndarray

Apply the PSFTransform to an image.

Parameters:

• image (np.ndarray) – image to apply the transform to

• workers (int | None) – Maximum number of workers to use for parallel computation of FFT. If negative, the value wraps around from os.cpu_count(). See scipy.fft.fft for more details.

• pad_mode (str) – how to pad the image when computing ffts, see np.pad for more details.

• saturation_threshold (float) – pixels brighter than this threshold are filled with their neighborhood average before PSF correction and then refilled with the raw value after correction to avoid producing artifacts

• saturation_dilation (int) – a nonnegative number of times to morphologically dilate the saturation mask before application

• neighborhood_width (int) – an odd positive number indicating the size of the neighborhood used for filling saturated pixels

Returns:

image with psf transformed

Return type:

np.ndarray

visualize(fig: matplotlib.figure.Figure | None = None, fig_scale: int = 1, patch_stride: int = 1, edge_trim: int = 1, imshow_args: dict | None = None) → None

Visualize the transform kernels.

Parameters:

• fig (mp.figure.Figure) – the figure to plot in

• fig_scale (int) – increasing this will make the figure higher resolution

• edge_trim (int) – how many pixels to drop on each side of the PSF for plotting

• patch_stride (int) – multiple of how many patches to skip when plotting, 1 means no skipping, 2 plots every other, 3 every third

• imshow_args (dict) – additional arguments for imshow

Return type:

None

save(path: pathlib.Path, overwrite: bool = False) → None

Save a PSFTransform to a file. Supports h5 and FITS.

Parameters:

• path (pathlib.Path) – where to save the PSFTransform

• overwrite (bool) – toggle to overwrite an existing file

Return type:

None

classmethod load(path: pathlib.Path) → ArrayPSFTransform

Load a PSFTransform object. Supports h5 and FITS.

Parameters:

path (pathlib.Path) – file to load the PSFTransform from

Return type:

PSFTransform

__eq__(other: ArrayPSFTransform) → bool

Test equality between two transforms.

regularizepsf.__version__