Calculate the sky and sky RMS for a subset region of a larger image, as used in profoundMakeSkyMap.
profoundSkyEstLoc(image, objects, mask, loc = dim(image)/2, box = c(100, 100),
skytype = "median", skyRMStype = "quanlo", sigmasel = 1, doclip = TRUE, shiftloc = FALSE,
paddim = TRUE, plot = FALSE, ...)Numeric matrix; required, the image we want to analyse.
Boolean matrix; optional, object mask where 1 is object and 0 is sky. If provided, this matrix *must* be the same dimensions as image.
Boolean matrix; optional, non galaxy parts of the image to mask out, where 1 means mask out and 0 means use for analysis. If provided, this matrix *must* be the same dimensions as image.
Integer vector; the [x,y] location where we want to estimate the sky and sky RMS.
Integer vector; the dimensions of the box car filter to estimate the sky with.
Character scalar; the type of sky level estimator used. Allowed options are 'median' (the default), 'mean' and 'mode' (see Details for an explanation of what these estimators do). In all cases this is the estimator applied to unmasked and non-object pixels. If doclip=TRUE then the pixels will be dynamically sigma clipped before the estimator is run.
Character scalar; the type of sky level estimator used. Allowed options are 'quanlo' (the default), 'quanhi', 'quanboth', and 'sd' (see Details for an explanation of what these estimators do). In all cases this is the estimator applied to unmasked and non-object pixels. If doclip=TRUE then the pixels will be dynamically sigma clipped before the estimator is run.
Numeric scalar; the quantile to use when trying to estimate the true standard-deviation of the sky distribution. If contamination is low then the default of 1 is about optimal in terms of S/N, but you might need to make the value lower when contamination is very high.
Logical; should the unmasked non-object pixels used to estimate to local sky value be further sigma-clipped using magclip? Whether this is used or not is a product of the quality of the objects extraction. If all detectable objects really have been found and the dilated objects mask leaves only apparent sky pixels then an advanced user might be confident enough to set this to FALSE. If an doubt, leave as TRUE.
Logical; should the cutout center shift from loc if the desired box size extends beyond the edge of the image? (See magcutout for details).
Logical; should the cutout be padded with image data until it meets the desired box size (if shiftloc is true) or padded with NAs for data outside the image boundary otherwise? (See magcutout for details).
Logical; should a diagnostic plot be generated?
Further arguments to be passed to magimage. Only relevant is plot=TRUE.
A 2 component list containing:
A length two vector where the first element is the sky and the second is the skyRMS.
The full vector of pixels selected as being sky pixels (can then be plotted with maghist etc.)
This is a somewhat handy standalone utility function if you have a large image and want to check the quality and stability of the local sky and sky RMS.
Regarding skytype, the meaning of the median and mean options re obvious enough. The mode is computed by running the data through density with the default options including automatuc selection of the appropriate smoothing band-width. The peak value of the smoothed density is then extracted, and the pixel value at this point is returned as the 'mode' sky estimator.
Regarding skyRMStype, if you know that your contamination only comes from positive flux sources (e.g., astronomical data when trying to select sky pixels) then you should probably use the lower side to determine Normal statistics (quanlo). Similarly if the contamination is on the low side then you should use the higher side to determine Normal statistics (quanhi). If you believe the selected sky pixels to be unbiased then 'quanboth' uses both sides and will give you a more accurate estimator of the sky RMS. The final option is to use the standard-deviation, with the caveat that this is calculated around the esstimated sky level (of type specified by skytype) and not necessarily simply the mean (as it would be typically). The most common choices for skyRMStype will likely be 'quanlo' or 'sd'.
There are many questions to think about when choosing the best combination of sky estimators. Have all detectable sources been robustly extracted and masked? Is the remaining contamintion due to background undetected sources or wing flux from foreground stars? The most significant choice to be made is whether to choose the more robust 'median' or the potentially biased 'mean'. The former makes sense if you think there might be detectable sources still contributing to your nominal sky pixels, the latter makes sense if the positive flux of undetected sources is spread round the sky in an random but uniform manner. If you are very confident that your object mask represents all plausible sources then you might even want to set doclip=FALSE. The defaults behave in quite a safe manner and have resistance to unmasked objects being included in the sky pixels. Using different options (particularly doclip=FALSE and skytype) requires more advanced knowledge about the specific data being anlysed.
# NOT RUN {
image=readFITS(system.file("extdata", 'VIKING/mystery_VIKING_Z.fits',
package="ProFound"))$imDat
profoundSkyEstLoc(image, loc=c(20,20), box=c(40,40), plot=TRUE)$val
profoundSkyEstLoc(image, loc=c(40,20), box=c(40,40), plot=TRUE)$val
profoundSkyEstLoc(image, loc=c(60,20), box=c(40,40), plot=TRUE)$val
# }
Run the code above in your browser using DataLab