ProFound (version 1.14.1)

profoundFitMagPSF: Fit PSF Magnitudes to an Image

Description

Fits PSF mags to an image with known source positions. This is the best deblend option in the regime where the sources are not well resolved, but the source positions are reasonably well defined.

Usage

profoundFitMagPSF(xcen = NULL, ycen = NULL, RAcen = NULL, Deccen = NULL, mag = NULL,
image = NULL, im_sigma = NULL, mask = NULL, psf = NULL, fit_iters = 5, magdiff = 1,
modxy = FALSE, sigthresh = 0, itersub = TRUE, magzero = 0, modelout = TRUE,
fluxtype = 'Raw', psf_redosky = FALSE, fluxext = FALSE, header = NULL, doProFound = FALSE,
findextra = FALSE, verbose = FALSE, ...)

Arguments

xcen

Numeric vector; x centres. If provided, must be the same length as mag, and be paired with ycen.

ycen

Numeric vector; y centres. If provided, must be the same length as mag, and be paired with xcen.

RAcen

Numeric vector; right ascension centres in degrees. If provided, must be the same length as mag, and be paired with Deccen.

Deccen

Numeric vector; declination centres in degrees. If provided, must be the same length as mag, and be paired with RAcen.

mag

Numeric vector; required, initial PSF mags. This is what will be fitted.

image

Numeric matrix; required, the image we want to analyse. If image is a list as created by readFITS, read.fits of magcutoutWCS then the image part of these lists is passed to image and the correct header part is passed to header. Note, image NAs are treated as masked pixels.

im_sigma

Numeric matrix; required, the measurement errors per pixel (expressed in terms of sigma).

mask

Boolean matrix; optional, parts of the image to mask out (i.e. ignore), where 1 means mask out and 0 means use for analysis. If provided, this matrix *must* be the same dimensions as image.

psf

Numeric matrix; required, an empirical point spread function (PSF) image matrix that ProFit will use to convolve the model.

fit_iters

Integer scalar; how many iterations should be run? Usually converges quite quickly, so rarely needs to be much larger than 5 (default).

magdiff

Numeric scalar; required, what is the allowed magnitude adjustment per iteration. Smaller values means faster fitting, but the correct solution obviously needs to lie with itersxmagdiff for all PSF magnitudes.

modxy

Logical; should xcen and ycen positions be adjusted during fitting? This adds computation time (roughly an extra 50%), but generally produces slightly better fits. It is limited so positions can only move 0.5 pixels per iteration, so the maximum move possible is iters x 0.5 pixels.

sigthresh

Numeric scalar; the cut level to apply before re-estimating the xcen and ycen positions. Higher means only brighter pixels are considered so is more robust, but it means fainter sources might not be adjusted at all. Only relevant if modxy=TRUE.

itersub

Logical; should each marginalised source profile be subtracted as we loop around the sources within a given iteration? The reason to perhaps set this to FALSE is that the source order will then affect the results (the earlier source will collect more flux where they overlap), but the overall solution will always be better with this set to TRUE (default).

magzero

Numeric scalar; the magnitude zero point. What this implies depends on the magnitude system being used (e.g. AB or Vega).

modelout

Logical; should the full model image be output?

fluxtype

Character scaler; specifies whether fluxes will be output in Jansky / MicroJansky ('Jansky' / 'microjansky'), or in raw/unscaled image ADUs ('Raw' / 'ADU' / 'ADUs', the default). You can only use 'Jansky' if the specified magzero gets the data into the AB system, else the fluxes will not be Jansky.

psf_redosky

Logical; should the sky calulcated by profoundProFound be subtracted from the target image? Since FIR frames are often confused, this should be turned on with care since possibly none of the pixels are a good sky reference. Put another way, you really need to trust your PSF wings.

fluxext

Logical; should the full model be used to compute an image deblending function better suited for extended sources? This means fluxes are guaranteed to add up to those available in the image. The fit PSF can differ, especially if the psf supplied is not in detail identical to the true image PSF. In practice we find that using fluxext=FALSE works better when the sources are not well resolved (assuming the true psf ~ true PSF), but when sources are marginally extended then fluxext=TRUE is probably the safer mode to use (hence the name).

header

Full FITS header in table or vector format. Legal table format headers are provided by the read.fitshdr function or the hdr list output of read.fits in the astro package; the hdr output of readFITS in the FITSio package or the header output of magcutoutWCS. If a header is provided then key words will be taken from here as a priority. Missing header keywords are printed out and other header option arguments are used in these cases.

doProFound

Logical; if TRUE then profoundProFound will be run with the arguments provided by …. This will be used to determine xcen, ycen and mag blindly.

findextra

Logical; if TRUE then after an initial run of profoundFitMagPSF profoundProFound is used to find additional sources that cannot be well modelled. The combined set if the initial sources and the new extra sources are then passed back into profoundFitMagPSF for a final run. The main source list is output to psfstats, and the extra sources are output to psfstats_extra. psfstats_extra is otherwise NULL.

verbose

Logical; should verbose output be displayed to the user? Since a big image can take a long time to run, you might want to monitor progress.

…

Arguments to be passed on to profoundProFound. Only relevant if doProFound=TRUE or findextra=TRUE.

Value

Object of class "fitmagpsf", a list containing:

psfstats

Data.frame; main source photometric properties (see below).

origmodel

Numeric matric; the original model image before optimisation. This will have the same dimensions as the input image. Only relevant if modelout=TRUE, else NA.

finalmodel

Numeric matric; the final model image after optimisation. This will have the same dimensions as the input image. Only relevant if modelout=TRUE, else NA.

origLL

Numeric scalar; the original data-model log-likelihood. Only relevant if modelout=TRUE, else NA.

finalLL

Numeric scalar; the final data-model log-likelihood. Only relevant if modelout=TRUE, else NA.

image

Numeric matric; the image directly used for fitting. This might have an additional sky component removed (if doProFound=TRUE) and NAs for masked regions.

header

The header provided, if missing this is NULL.

psfstats_extra

Data.frame; xtra photometric properties if findextra=TRUE, otherwise NULL (see below).

profound

List; an object of class profound as output by the profoundProFound function. This contains the output for the ProFound part of the analysis if doProFound=TRUE or findextra=TRUE.

mask

The input or computed mask matrix, else NULL.

call

The original function call.

date

The date, more specifically the output of date.

time

The elapsed run time in seconds.

ProFound.version

The version of ProFound run, more specifically the output of packageVersion('ProFound').

R.version

The version of R run, more specifically the output of R.version.

psfstats psfstats_extra data.frames have the following columns:

xcen

Numeric vector; x centres. If modxy=FALSE these will be the same as the input xcen, but if modxy=TRUE they will be adjusted.

ycen

Numeric vector; y centres. If modxy=FALSE these will be the same as the input ycen, but if modxy=TRUE they will be adjusted.

flux

Numeric vector; the final fitted PSF fluxes (either Jansky or raw, depending on fluxtype). This will be the same length as the input mag vector.

flux_err

Numeric vector; the final fitted PSF flux errors (either Jansky or raw, depending on fluxtype). This will be the same length as the input mag vector.

mag

Numeric vector; the final fitted PSF magnitudes. This will be the same length as the input mag vector.

mag_err

Numeric vector; the final fitted PSF magnitude errors. This will be the same length as the input mag vector.

psf

Numeric vector; the log-likelihood of the individual source fit.

signif

Numeric vector; approximate singificance of the detection using the Chi-Square distribution.

Details

This function uses ProFit to make a full model image. It then makes a model image for each indiviual PSF component and optimises just this alone. This means a maximum likelihood solution is converged on very efficiently, and is inspired by Expectation Maximisation which is often used for mixture model problems (which this basically is) for the reason of fast convergence. Here we use optim with method Brent to achieve the individual PSF optimisations.

References

Expectation Maximisation Wikipedia.

See Also

profoundFluxDeblend, plot.fitmagpsf

Examples

# NOT RUN {
s250_im=readFITS(system.file("extdata", 'IRdata/s250_im.fits', package="ProFound"))
s250_psf=readFITS(system.file("extdata",'IRdata/s250_psf.fits', package="ProFound"))$imDat
magzero_s250=11.68

pro_s250=profoundProFound(s250_im, pixcut=1, skycut=2, ext=1, redosky=FALSE, iters=1,
tolerance=0, sigma=0, magzero=magzero_s250)
pro_s250$segstats=pro_s250$segstats[!is.na(pro_s250$segstats$mag),]

newmag=profoundFitMagPSF(RAcen=pro_s250$segstats$RAcen, Deccen=pro_s250$segstats$Deccen,
image=s250_im, psf=s250_psf, doProFound=TRUE, findextra=TRUE, verbose=TRUE, redosky=FALSE,
magzero=magzero_s250)

magimage(newmag$image, qdiff=TRUE)
magimage(newmag$image - newmag$origmodel, qdiff=TRUE)
magimage(newmag$image - newmag$finalmodel, qdiff=TRUE)

magplot(pro_s250$segstats$mag, newmag$psfstats$mag, xlim=c(11,18), ylim=c(11,18),
xlab='ProFound Mag', ylab='FitPSF Mag', asp=1, grid=TRUE)
magerr(pro_s250$segstats$mag, newmag$psfstats$mag, xlo=pro_s250$segstats$mag_err,
ylo=newmag$psfstats$mag_err)
abline(0,1, col='red')

#We can also run slightly adjusting the xcen and ycen as we go:

newmag2=profoundFitMagPSF(RAcen=pro_s250$segstats$RAcen, Deccen=pro_s250$segstats$Deccen,
image=s250_im, psf=s250_psf, doProFound=TRUE, findextra=TRUE, verbose=TRUE, redosky=FALSE,
modxy=TRUE, magzero=magzero_s250)

magimage(newmag2$image - newmag2$finalmodel, qdiff=TRUE)

magplot(pro_s250$segstats$mag, newmag2$psfstats$mag,xlim=c(11,18), ylim=c(11,18),
xlab='ProFound Mag', ylab='FitPSF Mag', asp=1, grid=TRUE)
magerr(pro_s250$segstats$mag, newmag2$psfstats$mag, xlo=pro_s250$segstats$mag_err,
ylo=newmag2$psfstats$mag_err)
abline(0,1, col='red')

# The two profoundFitMagPSF approaches agree well within the error:

magplot(newmag$psfstats$mag, newmag2$psfstats$mag,xlim=c(11,18), ylim=c(11,18),
xlab='FitPSF Mag', ylab='FitPSF (mod xy) Mag', asp=1, grid=TRUE)
magerr(newmag$psfstats$mag, newmag2$psfstats$mag, xlo=newmag$psfstats$mag_err,
ylo=newmag2$psfstats$mag_err)
abline(0,1, col='red')
# }