profoundFitMagPSF: Fit PSF Magnitudes to an Image
In ProFound: Photometry Tools

Description Usage Arguments Details Value Author(s) References See Also Examples

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.

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, ...)

`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.

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.

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.

Aaron Robotham

Expectation Maximisation Wikipedia.

profoundFluxDeblend, plot.fitmagpsf

## 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')

## End(Not run)