Description

The imUtil.psf package contains functions for the creation and transformations of source point spread functions (PSFs).

List of functions

PSF properties:

• imUtil.psf.quantileRadius - Measure the radius of signal containment in a PSF stamp at a given level
• imUtil.psf.cropByQuantile - Crop a PSF stamp so that to keep only a given quantile of the total flux
• imUtil.psf.normPSF - Normalize a PSF stamp to 1 or to its RMS value
• imUtil.psf.curve_of_growth - Calculate the curve of growth of a PSF
• imUtil.psf.information_loss - Measure information content lost when using a modified PSF stamp instead of the original stamp
• imUtil.psf.pseudoFWHM - Measure pseudo-FWHM width in a PSF stamp at a given flux level
• imUtil.psf.radialProfile - Calculate the radial profile around a position

Measure image quality:

• imUtil.psf.fwhm_fromBank - Measure the FWHM of an image by cross corr. with a Gaussian template bank
• imUtil.psf.image_quality - Measure the image quality as a function of position in image

Fit PSF:

• imUtil.psf.fitFunPSF - Fit a composite function to a PSF stamp

Modify PSF:

• imUtil.psf.psf_zeroConverge - Set the tail of the PSF to converge to zero
• imUtil.psf.oversampling - Resample a PSF stamp to a different pixel scale

Moments and shape:

• imUtil.psf.mom2shape - Calculate shape (A, B, Theta, Elongation,...) from 2nd moments

ULTRASAT and spectrum-dependent PSF:

• imUtil.psf.readULTRASATlabDB - Make .mat DB files from the ASCII DB of ULTRASAT PSFs for 5 resolution levels
• imUtil.psf.specWeight - Make source PSFs at certain pixel distances on the detector weighted with the given spectra of the sources

Auxilary:

• imUtil.psf.unitTest - Package Unit-Test

imUtil.psf.quantileRadius

Measure the pixel radius of signal containment in a PSF stamp at a given containment level. Note that the result may be unstable at low containment levels, especially if most of the signal is located relatively far from the center of the PSF stamp.

% Here PSF is a 2D array containing the PSF stamp and 0.5 corresponds to 50% signal containment
Rad = imUtil.psf.quantileRadius (PSF, 0.5);

imUtil.psf.cropByQuantile

Crop a PSF stamp so that to keep only a given quantile of the total flux. The function is based on imUtil.psf.quantileRadius. The default quantile is 0.95.

% Here PSF is a 2D array containing the PSF stamp and 0.99 corresponds to 99% signal containment
P = imUtil.kernel2.gauss;
P99 = imUtil.psf.cropByQuantile(P, 0.99);

imUtil.psf.normPSF

Normalize a PSF stamp to 1 or to its RMS value.

% Here PSF is a 2D array containing the PSF stamp. 
% Both normalization variants are shown, normalization to 1 is the default variant.
PSF = 10.*rand(5)
PSF1 = imUtil.psf.normPSF(PSF)
PSF2 = imUtil.psf.normPSF(PSF,'ReNormMethod','rms')
sum(PSF1,'all')
sum(PSF2,'all')

imUtil.psf.information_loss

Measure information content lost when using a modified PSF stamp M1 instead of the original stamp M0

% Generate a random "PSF" stamp, modify it and see how large is the difference in regards to information loss
M0 = rand(15,15); 
M1 = M0; M1(7,7) = 0.6; M1(2,1) = 0.1; M(10,10) = 1; M(12,4) = 0.8;
IC = imUtil.psf.information_loss(M0, M1)

imUtil.psf.pseudoFWHM

Measure pseudo-FWHM width (in pixels) in a PSF stamp at a given flux level (relative to the maximum, 0.5 is default).

[FWHM_X, FWHM_Y] = pseudoFWHM (PSF, 'Level', 0.8)

imUtil.psf.specWeight

Given an array of source spectra and their positions on the detector plane, as well as an array of laboratory-measured PSFs for various wavelengths and positions on the plane, the function makes a 3-D array where 2-D spectrum-weighted PSFs are contained for each of the sources.

% basic usage with mandatory inputs only:
% (SpecSrc is a vector of AstroSpec spectra, RadSrc is a vector of source pixel distances,
% PSFData is a 4-D array of laboratory PSFs)
% 
PSF = imUtil.psf.specWeight( SpecSrc, RadSrc, PSFdata);
% extended capabilities:
% (Rad is a vector of radial distances of the lab PSFs, 
% Lambda is a vector of wavelengths of the lab PSFs, 
% SpecLam is a vector of wavelengths of the source spectra (same for all),
% SizeLimit is the maximal array size in Gb which determines the calculation method: 
% a too large array may cause out of memory error, while for a smaller array 
% a faster algorithm is employed
PSF = imUtil.psf.specWeight( SpecSrc, RadSrc, PSFdata, ...
'Rad', Rad, 'Lambda', WavePSF, 'SpecLam', Wave, 'SizeLimit', 8);

imUtil.psf.readULTRASATlabDB

Digest the raw PSF database and produce .mat DB files for 5 resolution levels: ULTRASATlabPSF10.mat, ULTRASATlabPSF1.mat, ULTRASATlabPSF2.mat, ULTRASATlabPSF47.5.mat, ULTRASATlabPSF5.mat NB: the .mat files are saved locally in order not to interfere with the existing versions at ../data/ULTRASAT/PSF/

% digest the raw PSF database and produce .mat DB files for 5 resolution levels:
imUtil.psf.readULTRASATlabDB;

imUtil.psf.oversampling

Resample a PSF stamp to a different pixel scale. NB:resampling changes the sum of pixels, so usually we need to re-normalize the stamp afterwards.

% resample the first stamp by the factor of 2, use the default (bilinear) interpolation,
% resample the second stamp by the factor of 5/3, use a Lanczos interpolation
P0 = imUtil.kernel2.gauss; P1 = imUtil.psf.oversampling(P0,1,2); 
P0 = imUtil.kernel2.gauss; P1 = imUtil.psf.oversampling(P0,3,5,'InterpMethod','lanczos2');