profoundMakeSkyMap: Calculate Sky Maps
In ProFound: Photometry Tools

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

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.

profoundMakeSkyMap(image = NULL, objects = NULL, mask = NULL, sky = 0,
  box = c(100,100), grid = box, skytype = "median", skyRMStype = "quanlo", sigmasel = 1,
  skypixmin = prod(box)/2, boxadd = box/2, boxiters = 0, conviters = 100, doclip = TRUE,
  shiftloc = FALSE, paddim = TRUE, cores = 1)
  
profoundMakeSkyGrid(image = NULL, objects = NULL, mask = NULL, sky = 0, 
  box = c(100,100), grid = box, skygrid_type = 'new', type = 'bicubic',
  skytype = "median", skyRMStype = "quanlo", sigmasel = 1, skypixmin = prod(box)/2,
  boxadd = box/2, boxiters = 0, conviters = 100, doclip = TRUE, shiftloc = FALSE,
  paddim = TRUE, cores = 1)

profoundMakeSkyBlur(image = NULL, objects = NULL, box = 100,
  sigma = mean(box)*(4/pi)/sqrt(12))

`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.
`sky`	User provided estimate of the absolute sky level. Can be a scalar (value uniformly applied) or a matrix matching the dimensions of image (allows values to vary per pixel). This will be subtracted off the image internally, so only provide this if the sky does need to be subtracted! The sky statistics will be computed with sky removed, and then the input sky is added back on. By this route it is possible to refine a best effort sky measurement iteratively. For images with extreme gradients this might achieve a better solution, and in particular a more accurate skyRMS map, where it might be systematically high if the gradient is strong across the scale of the requested box (since this will appear to be enhanced variance).
`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.
`skygrid_type`	Character scalar; either 'new' (the new ADACS C++ sky grid code) or 'old' (the older R based code as used for ProFound <= v1.10).
`type`	Character scalar; either "bilinear" for bilinear interpolation or "bicubic" for bicubic interpolation. The former creates sharper edges, the later is guaranteed to be first order differentiable. As of `ProFound` v1.13.0 we use the IntpAkimaUniform2 version available from www.geometrictools.com under a Boost 1.0 license (replacing the older `Akima` package and ADACS implementations, the former being memory intensive and the latter caused some small numerical artefacts).
`skytype`	Character scalar; the type of sky level estimator used. Allowed options are 'median' (the default), 'mean', 'mode' and 'converge' (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', 'sd' and 'converge' (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.
`skypixmin`	Numeric scalar; the minimum number of sky pixels desired in our cutout. The default is that we need half the original number of pixels in the box to be sky.
`boxadd`	Integer vector; the dimensions to add to the box to capture more pixels if skypixmin has not been achieved.
`boxiters`	Integer scalar; the number of box+boxadd iterations to attempt in order to capture skypixmin sky pixels. The default means the box will not be grown at all.
`conviters`	Integer scalar; number of iterative sky convergence steps when skytype = 'converge' and/or skyRMStype = 'converge'.
`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 if 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).
`cores`	Integer scalar; how many cores should be used to calculate sky properties of the image. Given the overhead for parallel computing, this should probably only be above 1 for larger images.
`sigma`	Numeric scalar; the standard deviation of the blur (positive) used for smoothing the sky pixels to make a sky map (see `isoblur` in `imager` package).

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.

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

profoundMakeSkyBlur produces a matrix of the sky map (there is no sky RMS component). To work well sources must be well masked either with NA in the image, or using the objects matrix. Since this function can only provide the additive sky, it cannot be used in isolation to computer the necessary sky information (we need the sky RMS map for profoundProFound), but it might offer a better smoother sky (so replacing the sky component of profoundMakeSkyGrid.

Aaron Robotham

profoundSkyEst, profoundSkyEstLoc

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

# 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),
type='bilinear')
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)

## End(Not run)