ProFound (version 1.14.1)

profoundMultiBand: Multi Band ProFound Photometry

Description

Run multiband ProFound photometry either with loaded data, or images on a local disk.

Usage

profoundMultiBand(inputlist = NULL, dir = "", segim = NULL, mask = NULL,
detectbands = "r", multibands = c("u", "g", "r", "i", "z"), iters_det = 6, iters_tot = 0,
sizes_tot = 5, magzero = 0, gain = NULL, box = 100, grid=box, boxadd=box/2, app_diam = 1,
bandappend = multibands, totappend = "t", colappend = "c", grpappend = 'g', dotot = TRUE,
docol = TRUE, dogrp = TRUE, deblend = FALSE, groupstats = FALSE,
groupby_det = 'segim_orig', groupby_mul = 'segim_orig', keepsegims = FALSE,
masking = 'and', ...)

Arguments

inputlist

A list of already loaded images. Typically of the type loaded in from FITS files by the astro package's read.fits function, or the FITSio package's readFITS function. If using the inputlist parameter the length of the list must be the same length as multibands (and the related parameters).

dir

If inputlist is left as NULL then profoundMultiBand will instead try to load in FITS images from the directory specified by dir. The images in the directory must have names like multibands[i].fits etc (so with the defaults names like u.fits and g.fits would be okay). Since multibands effectively specifies the file names much more complicated naming can be used and passed in, but it is also used by default for naming the catalogue column outputs, so shorter names/references are likely to be preferable there (i.e. mag_ut is simpler than mag_KiDS_VST_ut etc). This can be over-ridden by using bandappend.

segim

Integer matrix; a specified segmentation map of the image. This matrix *must* be the same dimensions as the detection image/s if supplied. If this option is used then profoundMultiBand will not compute its initial segmentation map using profoundMakeSegim, which is then dilated. Instead it will use the one passed through segim and dilate this according to the iters_det argument (so set this to 0 if you want the segim to be used as is).

mask

Boolean matrix or integer scalar; optional, parts of the image to mask out (i.e. ignore). If a matrix is provided, this matrix *must* be the same dimensions as image where 1 means mask out and 0 means use for analysis. if a scalar is provided it indicates the exact image values that should be treated as masked (e.g. by setting masked pixels to 0 or -999). The latter achieves the same effect as setting masked image pixels to NA, but allows for the fact not all programs can produce R legal NA values. Not that for detection masking is an OR operator, so if a pixel is masked on any input image it will be masked in the detection image. This is the more conservative way to treat the issue of multiband masking.

detectbands

Character vector; the names of the detection bands that will be stacked using profoundMakeStack and then analysed with the provided settings with profoundProFound to make a reference segmentation map for further multi band photometry. These bands must be present in multibands. Can be a scalar (i.e. a single band is used). If set to 'get' then it will use all legal FITS files in the target directory. If set to 'all' then it will use all multibands inputs.

multibands

Character vector; the names of the target multi band photometry images. If set to 'get' then it will use all legal FITS files in the target directory. If using the inputlist parameter the length of the list must be the same length as multibands. magzero must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. If specified, gain must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. If specified, catappend must either the same length and order as multibands.

iters_det

Integer scalar; the maximum number of curve of growth dilations that should be made to the detection image. This needs to be large enough to capture all the flux for sources of interest, but increasing this will increase the computation time for profoundProFound. If this is set to 0 then the undilated segim image, whether provided or computed internally via profoundMakeSegim, will be used instead.

iters_tot

Integer vector; the maximum number of curve of additional growth dilations that should be made above the dilated detection segmentation map for multi band total colour photometry. This is only relevant if dotot=TRUE. This should not be set too high (and might even be 0, the default) since the detection image should generally be fairly deep. iters_tot must either be length 1 (in which this value is used for all bands), or the same length and order as multibands.

sizes_tot

Integer vector; the size (e.g. width/diameter) of the dilation kernel in pixels. Should be an odd number else will be rounded up to the nearest odd number. See makeBrush. Passed to profoundMakeSegimDilate. sizes_tot must either be length 1 (in which this value is used for all bands), or the same length and order as multibands.

magzero

Numeric vector; the magnitude zero point of the images being used. magzero must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

gain

Numeric vector; the gain of the images being used. gain must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

box

Numeric vector; the sky estimate box size of the images being used. box must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

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. grid must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

boxadd

Integer vector; the dimensions to add to the box to capture more pixels if skypixmin has not been achieved. By default this is set to be the same as the box/2. boxadd must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

app_diam

Numeric vector; the diameter in arc seconds to use for pseudo aperture photometry. This will use the appropriate pixel scale to convert the aperture into image units. The psuedo aperture photometry is output to columns flux_app and mag_app in cat_tot. app_diam must either be length 1 (in which this value is used for all bands), or the same length and order as multibands. See also profoundProFound.

bandappend

Character vector; characters to be appended per band in the output multi band photometry catalogues. The default will create columns with names like mag_ut (total) and mag_uc (colour).

totappend

Character scalar; character to be appended in the output multi band total photometry catalogue (cat_tot). The default will create columns with names like mag_ut and R50_ut.

colappend

Character scalar; character to be appended in the output multi band colour photometry catalogue (cat_col). The default will create column with names like mag_uc and R50_uc.

grpappend

Character scalar; character to be appended in the grouped segment multi band total photometry catalogue (cat_tot). The default will create columns with names like mag_ug and R50_ug.

dotot

Logical; should dilated segment total photometry be computed for the bands specified in multibands? This will return closer to total magnitudes in all target bands.

docol

Logical; should non-dilated segment colour photometry be computed for the bands specified in multibands? This will return better colour magnitudes in all target bands (i.e. more accurate differences between bands) and will typically under-represent the total photometry.

dogrp

Logical; should group segment photometry be computed for the bands specified in multibands? This might be useful for re-assembling large galaxies that are broken up at a later date. boundstats must also be set to TRUE if dogrp=TRUE is set.

deblend

Logical; should total segment flux be deblended using profoundFluxDeblend and these columns appended to the end of the output segstats? This only applies to the cat_tot output.

groupstats

Logical; if TRUE then the IDs of grouped segments is calculated for the detection image via profoundSegimGroup and output to the returned object group. By default this option is linked to boundstats, i.e. it is assumed if you want boundary statistics then you probably also want grouped object IDs returned.

groupby_det

Character scalar; How should the grouped segmentation map be formed that will be used to produce the cat_grp output? Options are either via 'segim' or 'segim_orig'. 'segim' will create more groups, 'segim_orig' will have less.

groupby_mul

Character scalar; How should the grouped segmentation map be formed that will be used to produce the multi-band deblending for cat_tot and cat_col outputs? Options are either via 'segim' or 'segim_orig'. 'segim' will create more groups, 'segim_orig' will have less.

keepsegims

Logical; if TRUE then profoundMultiBand will return a list of per band segmentation maps in segimlist. This is useful since they can be slightly different per band.

masking

Character scalar; what to do with masked pixels (NAs in the image). If 'or' a pixel is masked if *any* of the images being stacked have a masked pixel (NA in the image_list) at that location, if 'and' then a pixel is masked if *all* of the images being stacked have a masked pixel at that location.

…

Further arguments to be passed to all instances of profoundProFound. E.g. if the sky SBdilate is set to a value (default is NULL) this will be propogated to all of the multi band photometry runs of profoundProFound.

Value

An object list of class 'profoundmulti' containing:

pro_detect

The full output of profoundProFound for the detection image (of class 'profound').

cat_tot

If dotot=TRUE, the dilated total photometry for the target bands. Effectively the output of profoundSegimStats run on pro_detect$segim.

cat_col

If docol=TRUE, the non-dilated colour photometry for the target bands. Effectively the output of profoundSegimStats run on pro_detect$segim_orig.

cat_grp

If dogrp=TRUE, the group segment photometry for the target bands. Effectively the output of profoundSegimStats run on pro_detect$group$groupim.

segimlist

If keepsegims=TRUE then this object contains a list of per band total segmentation maps. This is useful since they can be slightly different per band.

detectbands

Character vector; the names of the detection bands used.

multibands

Character vector; the names of the target multi band photometry images used.

call

The original function call.

date

The date, more specifically the output of date.

time

The elapsed run time in seconds.

Details

This very high level function simplifies a sequence of function calls that we found users typically needed to make, but when scripted they were prone to mistakes and made multi band photometry scripts hard to maintain.

In the simplest sense this script runs profoundProFound on each detection band and uses this information to make a stacked image using profoundMakeStack. profoundProFound is then run on this stacked image to make a deep segmentation map. For good total photometry the segim object from this output is used, and allowed to further dilate to account for different observing conditions (i.e. PSFs). For good colour photometry the segim_orig object from this output is used. Only the profoundSegimStats output is kept for the target multi band images, so not all of the outputs from profoundProFound since this is usually unnecessary when operating in this mode, and creates a huge quantity of data.

References

Robotham A.S.G., et al., 2018, MNRAS, 476, 3137

See Also

profoundProFound

Examples

# NOT RUN {
# Load images
GALEX_NUV=readFITS(system.file("extdata", 'GALEX_NUV.fits', package="magicaxis"))
VST_r=readFITS(system.file("extdata", 'VST_r.fits', package="magicaxis"))
VISTA_K=readFITS(system.file("extdata", 'VISTA_K.fits', package="magicaxis"))

# Warp to common WCS:
GALEX_NUV_VST=magwarp(GALEX_NUV, VST_r$hdr)
VISTA_K_VST=magwarp(VISTA_K, VST_r$hdr)

# Run profoundMultiBand on defaults:
multi=profoundMultiBand(inputlist=list(GALEX_NUV_VST, VST_r, VISTA_K_VST),
magzero=c(20.08,0,30), detectbands='r', multibands=c('NUV','r','K'))

# Notice the blue halo around the central sources:
plot(multi$pro_detect)

# Run profoundMultiBand with boxiters=2 (to avoid over-subtracting the sky):
multi=profoundMultiBand(inputlist=list(GALEX_NUV_VST, VST_r, VISTA_K_VST),
magzero=c(20.08,0,30), detectbands='r', multibands=c('NUV','r','K'), boxiters = 2)

# Looks better now:
plot(multi$pro_detect)

magplot(multi$cat_tot$mag_rt, multi$cat_col$mag_NUVc-multi$cat_col$mag_rc, ylim=c(-2,10))
points(multi$cat_tot$mag_rt, multi$cat_col$mag_rc-multi$cat_col$mag_Kc, col='red')

# Some options on passing segim:

multi2=profoundMultiBand(segim=multi$pro_detect$segim, inputlist=list(GALEX_NUV_VST,
VST_r, VISTA_K_VST), magzero=c(20.08,0,30), detectbands='r', multibands=c('NUV','r','K'),
iters_det = 0, boxiters=2)

multi3=profoundMultiBand(segim=multi$pro_detect$segim_orig, inputlist=list(GALEX_NUV_VST,
VST_r, VISTA_K_VST), magzero=c(20.08,0,30), detectbands='r', multibands=c('NUV','r','K'),
iters_det = 6, boxiters=2)

# multi and multi3 should create identical plots (since we are dilating the original
# segim_orig in the same manner), but multi2 will just be the final dilated segim without
# any dilations, hence the top-right is all green (segim=segim_orig). The final fluxes
# should be the same though for all 3 runs (left-middle, bottom-centre and bottom-right).

plot(multi$pro_detect)
plot(multi2$pro_detect)
plot(multi3$pro_detect)
# }