profoundMakeSkyMap: Calculate Sky Maps

Description

The high level function computes the absolute sky and sky RMS level over an image at a scale defined locally by the box parameter. This coarse map can then be used to compute sky/skyRMS values for the local sky anywhere on an image. This function uses profoundSkyEstLoc to calculate the sky statistics for the subset boxcar regions.

Usage

profoundMakeSkyMap(image, objects, mask, box = c(100,100), grid = box, skytype = "median",
skyRMStype = "quanlo", sigmasel = 1, doclip = TRUE, shiftloc = FALSE, paddim = TRUE)
profoundMakeSkyGrid(image, objects, mask, box = c(100,100), grid = box, type = 'bilinear',
skytype = "median", skyRMStype = "quanlo", sigmasel = 1, doclip = TRUE, shiftloc=FALSE,
paddim = TRUE)

Arguments

image

Numeric matrix; required, the image we want to analyse.

objects

Boolean matrix; optional, object mask where 1 is object and 0 is sky. If provided, this matrix *must* be the same dimensions as image.

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.

box

Integer vector; the dimensions of the box car filter to estimate the sky with.

grid

Integer vector; the resolution of the background grid to estimate the sky with. By default this is set to be the same as the box.

type

Character scalar; either "bilinear" for bilinear interpolation (default) or "bicubic" for bicubic interpolation. The former is safer, especially near edges where bicubic interpolation can go a bit crazy.

skytype

Character scalar; the type of sky level estimator used. Allowed options are 'median' (the default), 'mean' and 'mode' (see profoundSkyEstLoc 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.

skyRMStype

Character scalar; the type of sky level estimator used. Allowed options are 'quanlo' (the default), 'quanhi', 'quanboth', and 'sd' (see profoundSkyEstLoc 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.

sigmasel

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.

doclip

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.

shiftloc

Logical; should the cutout centre for the sky shift from loc of the desired box size extends beyond the edge of the image? (See magcutout for details).

paddim

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

Value

profoundMakeSkyMap produces a list of two lists. The first (called sky) contains a list of x,y,z values for the absolute sky, and second (called skyRMS) contains a list of x,y,z values for the sky RMS. The grids returned are as coarse as the box option provided.

profoundMakeSkyGrid produces a list of two lists. The first (called sky) is a matrix of values for the absolute sky. The second (called skyRMS) is a matrix of values for the absolute sky RMS. The image matrices returned are pixel matched to the input image using the specified interpolation scheme.

Details

The matrix generated will have many fewer pixels than the original image, so it will need to be interpolated back onto the full grid by some mechanism in order to have 1-1 values for the sky and sky RMS.

Examples

Run this code

# NOT RUN {
image=readFITS(system.file("extdata", 'VIKING/mystery_VIKING_Z.fits',
package="ProFound"))$imDat
magimage(image)
skymap = profoundMakeSkyMap(image, box=c(89,89))
magimage(skymap$sky)
magimage(skymap$skyRMS)

# }
# NOT RUN {
# Now again, masking out the known objects (will not help too much in this case):

segim=profoundMakeSegim(image, skycut=1.5, plot=TRUE)
segim_ex=profoundMakeSegimExpand(image, segim$segim, skycut=-Inf, plot=TRUE)

skymap=profoundMakeSkyMap(image, objects=segim_ex$objects, box=c(89,89))
magimage(skymap$sky, magmap=FALSE)
magimage(skymap$skyRMS, magmap=FALSE)

# We can bilinear interpolate this onto the full image grid:

skybil = profoundMakeSkyGrid(image, objects=segim_ex$objects, box=c(89,89))
magimage(skybil$sky, magmap=FALSE)
magimage(skybil$skyRMS, magmap=FALSE)

# Or we can bicubic interpolate this onto the full image grid:

skybic = profoundMakeSkyGrid(image, objects=segim_ex$objects, box=c(89,89), type='bicubic')
magimage(skybic$sky, magmap=FALSE)
magimage(skybic$skyRMS, magmap=FALSE)

# The differences tend to be at the edges:

magimage(skybil$sky-skybic$sky, magmap=FALSE)
magimage(skybil$skyRMS-skybic$skyRMS, magmap=FALSE)
# }