`regularizepsf`#

Submodules#

Package Contents#

Classes#

`ArrayCorrector`	A PSF corrector that is evaluated as array patches
`FunctionalCorrector`	A version of the PSF corrector that stores the model as a set of functions.
`CoordinatePatchCollection`	A representation of a PatchCollection that operates

Functions#

`calculate_covering`(→ numpy.ndarray)	Determines the grid of overlapping neighborhood patches.
`simple_psf`(→ SimplePSF)
`varied_psf`(→ VariedPSF)
`visualize_patch_counts`(→ matplotlib.axes.Axes)	Utility to visualize the number of stars identified within each patch
`visualize_PSFs`(→ matplotlib.figure.Figure)	Utility to visualize estimated PSFs.
`visualize_transfer_kernels`(→ matplotlib.figure.Figure)	Utility to compute and visualize transfer kernels.

class regularizepsf.ArrayCorrector(evaluations: dict[Any, numpy.ndarray], target_evaluation: numpy.ndarray)#

Bases: CorrectorABC

A PSF corrector that is evaluated as array patches

property evaluations: dict[Any, numpy.ndarray]#

property evaluation_points: list#

correct_image(image: numpy.ndarray, size: int | None = None, alpha: float = 0.5, epsilon: float = 0.05) → numpy.ndarray#

PSF correct an image according to the model

Parameters:

image (2D float np.ndarray) – image to be corrected
size (int) – how big to make the patches when correcting an image, only used for FunctionalCorrector
alpha (float) – controls the “hardness” of the transition from amplification to attenuation, see notes
epsilon (float) – controls the maximum of the amplification, see notes

Returns:

a image that has been PSF corrected

Return type:

np.ndarray

__getitem__(xy: Tuple[int, int]) → numpy.ndarray#

save(path: str) → None#

Save the model to a file.

Parameters:: path (str or pathlib.Path) – where to save the model, suggested extension is “.psf”
Return type:: None

classmethod load(path: str) → ArrayCorrector#

Loads a model from the path

Parameters:: path (str or pathlib.Path) – where to load the model from, suggested extension is “.psf”

simulate_observation(image: numpy.ndarray) → numpy.ndarray#

Simulates on a star field what an observation using this PSF looks like

Parameters:: image (2D float np.ndarray) – image of point source stars to simluate PSF for
Returns:: an image with the PSF applied
Return type:: np.ndarray

class regularizepsf.FunctionalCorrector(psf: regularizepsf.psf.PointSpreadFunctionABC, target_model: regularizepsf.psf.SimplePSF | None)#

Bases: CorrectorABC

A version of the PSF corrector that stores the model as a set of functions. For the actual correction, the functions must first be evaluated to an ArrayCorrector.

property is_variable: bool#

returns: True if the PSF model is varied (changes across the field-of-view): and False otherwise

Return type:: bool

evaluate_to_array_form(x: numpy.ndarray, y: numpy.ndarray, size: int) → ArrayCorrector#

Evaluates a FunctionalCorrector to an ArrayCorrector

Parameters:

x (np.ndarray) – the first dimension coordinates to evaluate over
y (np.ndarray) – the second dimension coordinates to evaluate over
size (int) – how large the patches in the PSF correction model shouuld be

Returns:

an array evaluated form of this PSF corrector

Return type:

ArrayCorrector

correct_image(image: numpy.ndarray, size: int, alpha: float = 0.5, epsilon: float = 0.05) → numpy.ndarray#

PSF correct an image according to the model

Parameters:

image (2D float np.ndarray) – image to be corrected
size (int) – how big to make the patches when correcting an image, only used for FunctionalCorrector
alpha (float) – controls the “hardness” of the transition from amplification to attenuation, see notes
epsilon (float) – controls the maximum of the amplification, see notes

Returns:

a image that has been PSF corrected

Return type:

np.ndarray

abstract save(path: str) → None#

Save the model to a file.

Parameters:: path (str or pathlib.Path) – where to save the model, suggested extension is “.psf”
Return type:: None

abstract classmethod load(path: str) → FunctionalCorrector#

Loads a model from the path

Parameters:: path (str or pathlib.Path) – where to load the model from, suggested extension is “.psf”

simulate_observation(image: numpy.ndarray, size: int) → numpy.ndarray#

Simulates on a star field what an observation using this PSF looks like

Parameters:

image (2D float np.ndarray) – image of point source stars to simluate PSF for
size (int) – the PSF will be evaluated to size x size pixels box

Returns:

an image with the PSF applied

Return type:

np.ndarray

regularizepsf.calculate_covering(image_shape: tuple[int, int], size: int) → numpy.ndarray#

Determines the grid of overlapping neighborhood patches.

Parameters:

image_shape (tuple of 2 ints) – shape of the image we plan to correct
size (int) – size of the square patches we want to create

Returns:

an array of shape Nx2 where return[:, 0] are the x coordinate and return[:, 1] are the y coordinates

Return type:

np.ndarray

class regularizepsf.CoordinatePatchCollection(patches: dict[Any, numpy.ndarray], counts: dict[Any, int] | None = None)#

Bases: PatchCollectionABC

A representation of a PatchCollection that operates on pixel coordinates from a set of images

classmethod extract(images: list[numpy.ndarray], coordinates: list[CoordinateIdentifier], size: int) → PatchCollectionABC#

Construct a PatchCollection from a set of images using the specified coordinates and patch size

Parameters:

images (list of np.ndarrays) – the images loaded
coordinates (list) –

A list of coordinates for the lower left pixel of each patch,
specified in each type of PatchCollection
size (int) – size of one side of the square patches extracted

Returns:

the square patches extracted into a PatchCollection

Return type:

np.ndarray

classmethod find_stars_and_average(images: list[str] | numpy.ndarray | Generator, psf_size: int, patch_size: int, interpolation_scale: int = 1, average_mode: str = 'median', percentile: float = 10, star_threshold: int = 3, star_mask: list[str] | numpy.ndarray | Generator | None = None, hdu_choice: int = 0) → CoordinatePatchCollection#

Loads a series of images, finds stars in each,: and builds a CoordinatePatchCollection with averaged stars

Parameters:

images (List[str] or np.ndarray or Generator) – The images to be processed. Can be a list of FITS filenames, a numpy array of shape (n_images, ny, nx), or a Generator that yields each data array in turn.
psf_size (int) – size of the PSF model to use
patch_size (int) – square size that each PSF model applies to
interpolation_scale (int) –

if >1, the image are first scaled by this factor.
This results in stars being aligned at a subpixel scale
average_mode (str) – “median”, “percentile”, or “mean”: determines how patches are combined
percentile (float) – If average_mode is “percentile”, use this percentile value (from 0 to 100)
star_threshold (int) –

SEP’s threshold for finding stars. See threshold
in https://sep.readthedocs.io/en/v1.1.x/api/sep.extract.html#sep-extract
star_mask (List[str] or np.ndarray or Generator) – Masks to apply during star-finding. Can be a list of FITS filenames, a numpy array of shape (n_images, ny, nx), or a Generator that yields each mask array in turn. Where the mask pixel is True, the corresponding data array pixel will not be selected as a star. See mask in https://sep.readthedocs.io/en/v1.1.x/api/sep.extract.html#sep-extract for more details.
hdu_choice (int) –

Which HDU from each image will be used,
default of 0 is most common but could be 1 for compressed images

Returns:

An averaged star model built from the provided images

Return type:

CoordinatePatchCollection

Notes

Using an interpolation_scale other than 1: for large images can dramatically slow down the execution.

average(corners: numpy.ndarray, patch_size: int, psf_size: int, mode: str = 'median', percentile: float = 10) → PatchCollectionABC#

Construct a new PatchCollection where patches lying inside a new grid are averaged together

Parameters:

corners (np.ndarray) – an Nx2 np.ndarray of the lower left corners of the new patch grid
step (int) – how far apart each corner patch is
size (int) – dimension of the new (size, size) shaped square patches
mode (str) – either average using “mean” or “median”

Returns:

a PatchCollection where data is sampled at the new grid

Return type:

PatchCollectionABC

static _validate_average_mode(mode: str, percentile: float) → None#: Determine if the average_mode is a valid kind

_calculate_pad_shape(size: int) → Tuple[int, int]#

abstract fit(base_psf: regularizepsf.psf.SimplePSF, is_varied: bool = False) → regularizepsf.psf.PointSpreadFunctionABC#

Parameters:

base_psf
is_varied

to_array_corrector(target_evaluation: numpy.array) → regularizepsf.corrector.ArrayCorrector#

Converts a patch collection that has been averaged into an ArrayCorrector

Parameters:: target_evaluation (np.ndarray) – the evaluation of the Target PSF
Returns:: An array corrector that can be used to correct PSFs
Return type:: ArrayCorrector

save(path: str) → None#

Save the CoordinatePatchCollection to a file

Parameters:: path (str) – where to save the patch collection
Return type:: None

classmethod load(path: str) → PatchCollectionABC#

Load a PatchCollection from a file

Parameters:: path (str) – file path to load from
Returns:: the new patch collection
Return type:: PatchCollectionABC

regularizepsf.simple_psf(arg: Any = None) → SimplePSF#

regularizepsf.varied_psf(base_psf: SimplePSF = None) → VariedPSF#

regularizepsf.visualize_patch_counts(patch_collection: regularizepsf.fitter.PatchCollectionABC, ax: matplotlib.axes.Axes | None = None, label_pixel_bounds: bool = False) → matplotlib.axes.Axes#

Utility to visualize the number of stars identified within each patch

Parameters:

patch_collection (PatchCollectionABC) – A patch collection, such as that returned by CoordinatePatchCollection.find_stars_and_average.
ax (matplotlib.axes.Axes) – An Axes object on which to plot. If not provided, a new Figure will be generated.
label_pixel_bounds (bool) – If True, the axes of the plot will be labeled with the pixel range spanned by each patch.

regularizepsf.visualize_PSFs(psfs: regularizepsf.corrector.ArrayCorrector, corrected: regularizepsf.fitter.PatchCollectionABC | None = None, all_patches: bool = False, region_size: int = 0, label_pixel_bounds: bool = False, fig: matplotlib.figure.Figure | None = None, fig_scale: float = 1, colorbar_label: str = 'Normalized brightness', axis_border_color: str = 'white', imshow_args: dict | None = None) → matplotlib.figure.Figure#

Utility to visualize estimated PSFs.

Accepts an ArrayCorrector, which contains the estimated PSFs across the image.

This utility can also produce a “before and after” visualization. To do this, apply your ArrayCorrector to your image set, and then run CoordinatePatchCollection.find_stars_and_average on your corrected images. This will estimated the PSF of your corrected images. Pass this CoordinatePatchCollection as the corrected argument to this function.

Parameters:

psfs (ArrayCorrector) – An ArrayCorrector containing the estimated PSFs
corrected (PatchCollectionABC) – A CoordinatePatchCollection computed on the corrected set of images
all_patches (boolean) – PSFs are estimated in a grid of overlapping patches, with each image pixel being covered by four patches. If True, all of these patches are plotted, which can be useful for diagnosing the estimated PSFs. If False, only a fourth of all patches are plotted (every other patch in both x and y), which can produce simpler illustrations.
region_size (int) – The width of the central region of each patch to plot, or 0 to plot each entire patch. If the PSFs were computed with a psf_size less than patch_size, it may be convenient to set region_size=psf_size, to omit the empty edges of each patch.
label_pixel_bounds (bool) – If True, the axes of the plot will be labeled with the pixel range spanned by each patch.
fig (matplotlb.figure.Figure) – A Figure on which to plot. If not provided, one will be created.
fig_scale (float) – If fig is not provided, scale the generated Figure up or down by this factor.
colorbar_label (str) – The label to show on the colorbar
axis_border_color (str) – The color to use for the lines separating the patch plots.
imshow_args (dict) – Additional arguments to pass to each plt.imshow() call

Returns:

fig – The generated figure

Return type:

matplotlib.figure.Figure

regularizepsf.visualize_transfer_kernels(psfs: regularizepsf.corrector.ArrayCorrector, alpha: float, epsilon: float, all_patches: bool = False, region_size: int = 0, label_pixel_bounds: bool = False, fig: matplotlib.figure.Figure | None = None, fig_scale: float = 1, colorbar_label: str = 'Transfer kernel amplitude', axis_border_color: str = 'black', imshow_args: dict | None = None) → matplotlib.figure.Figure#

Utility to compute and visualize transfer kernels.

Accepts an ArrayCorrector, which contains the estimated PSFs across the image. These PSFs, and the target PSF, will be used to compute each transfer kernel.

Parameters:

psfs (ArrayCorrector) – An ArrayCorrector containing the estimated PSFs and target PSF
alpha (float) – Values used in computing the regularized reciprocal of the computed PSFs. Provide the same values that you would pass to ArrayCorrector.correct_image.
epsilon (float) – Values used in computing the regularized reciprocal of the computed PSFs. Provide the same values that you would pass to ArrayCorrector.correct_image.
all_patches (boolean) – PSFs are estimated in a grid of overlapping patches, with each image pixel being covered by four patches. If True, all of these patches are plotted, which can be useful for diagnosing the computed PSFs. If False, only a fourth of all patches are plotted (every other patch in both x and y), which can produce simpler illustrations.
region_size (int) – The width of the central region of each patch to plot, or 0 to plot each entire patch. If the PSFs were computed with a psf_size less than patch_size, it may be convenient to set region_size=psf_size, to omit the empty edges of each patch.
label_pixel_bounds (bool) – If True, the axes of the plot will be labeled with the pixel range spanned by each patch.
fig (matplotlb.figure.Figure) – A Figure on which to plot. If not provided, one will be created.
fig_scale (float) – If fig is not provided, scale the generated Figure up or down by this factor.
colorbar_label (str) – The label to show on the colorbar
axis_border_color (str) – The color to use for the lines separating the patch plots.
imshow_args (dict) – Additional arguments to pass to each plt.imshow() call

Returns:

fig – The generated figure

Return type:

matplotlib.figure.Figure

regularizepsf#

Submodules#

Package Contents#

Classes#

Functions#

`regularizepsf`#