profoundMakeSegimExpand: Segmentation Map Expansion and Dilation

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

View source: R/profoundSegim.R

Description

A high level utility to achieve decent quality image segmentation based on the expansion of a pre-existing segmentation map. It uses smoothing and local flux weighted comparisons to grow the current segmentation map so as to better identify distinct objects for use in, e.g., profitSetupData.

Usage

1
2
3
4
5
6
7
8
9
profoundMakeSegimExpand(image = NULL, segim = NULL, mask = NULL, objects = NULL,
skycut = 1, SBlim = NULL, magzero = 0, gain = NULL, pixscale = 1, sigma = 1,
smooth = TRUE, expandsigma = 5, expand = "all", sky = NULL, skyRMS = NULL, header = NULL,
verbose = FALSE, plot = FALSE, stats = TRUE, rotstats = FALSE, boundstats = FALSE,
offset = 1, sortcol = "segID", decreasing = FALSE, ...)
profoundMakeSegimDilate(image = NULL, segim = NULL, mask = NULL, size = 9, shape = "disc",
expand = "all", magzero = 0, gain = NULL, pixscale = 1, sky = 0, skyRMS = 0,
header = NULL, verbose = FALSE, plot = FALSE, stats = TRUE, rotstats = FALSE,
boundstats = FALSE, offset = 1, sortcol = "segID", decreasing = FALSE, ...)

Arguments

image

Numeric matrix; required, the image we want to analyse. Note, image NAs are treated as masked pixels.

segim

Integer matrix; required, the segmentation map of the image. 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.

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.

skycut

Numeric scalar; the lowest threshold to make on the image in units of the skyRMS. Since we are restricted to expanding out pre-existing segmentation regions we can usually afford to make this value lower than the equivalent in profoundMakeSegim.

SBlim

Numeric scalar; the magnitude/arcsec^2 surface brightness threshold to apply. This is always used in conjunction with skycut, so set skycut to be very large (e.g. Inf) if you want a pure surface brightness threshold for the segmentation. magzero and pixscale must also be present for this to be used.

magzero

Numeric scalar; the magnitude zero point. What this implies depends on the magnitude system being used (e.g. AB or Vega). If provided along with pixscale then the flux and surface brightness outputs will represent magnitudes and mag/asec^2.

gain

Numeric scalar; the gain (in photo-electrons per ADU). This is only used to compute object shot-noise component of the flux error (else this is set to 0).

pixscale

Numeric scalar; the pixel scale, where pixscale=asec/pix (e.g. 0.4 for SDSS). If set to 1 (default), then the output is in terms of pixels, otherwise it is in arcseconds. If provided along with magzero then the flux and surface brightness outputs will represent magnitudes and mag/asec^2.

sigma

Numeric scalar; standard deviation of the blur used when smooth=TRUE.

smooth

Logical; should smoothing be done on the target image? If present, this will use the imblur function from the imager package. Otherwise it will use the gblur function from the EBImage package with a warning. These functions are very similar in output, but not strictly identical.

expandsigma

Numeric scalar; standard deviation of the blur used when expanding out the segim. Roughly speaking if skycut is set to a low number (say -5) then the expansion will not be prevented by the local sky level and it will grow by the number of pixels specified by expandsigma.

expand

Integer vector; specifies which segmentation regions should be expanded by the segID integer reference. If left with the default expand='all' then all segments will be expanded.

size

Integer scalar; 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.

shape

Character scalar; the shape of the dilation kernel. See makeBrush.

sky

User provided estimate of the absolute sky level. Can be a scalar 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!

skyRMS

User provided estimate of the RMS of the sky. Can be a scalar or a matrix matching the dimensions of image (allows values to vary per pixel).

header

Full FITS header in table or vector format. If this is provided then the segmentations statistics table will gain RAcen and Decen coordinate outputs. 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. Missing header keywords are printed out and other header option arguments are used in these cases. See magWCSxy2radec.

verbose

Logical; should verbose output be displayed to the user? Since big image can take a long time to run, you might want to monitor progress.

plot

Logical; should a diagnostic plot be generated? This is useful when you only have a small number of sources (roughly a few hundred). With more than this it can start to take a long time to make the plot!

stats

Logical; should statistics on the segmented objects be returned?

rotstats

Logical; if TRUE then the asymm, flux_reflect and mag_reflect are computed, else they are set to NA. This is because they are very expensive to compute compared to other photometric properties.

boundstats

Logical; if TRUE then various pixel boundary statistics are computed (Nedge, Nsky, Nobject, Nborder, edge_frac, edge_excess and FlagBorder). If FALSE these return NA instead (saving computation time).

offset

Integer scalar; the distance to offset when searching for nearby segments (used in profoundSegimStats).

sortcol

Character; name of the output column that the returned segmentation statistics data.frame should be sorted by (the default is segID, i.e. segment order). See below for column names and contents.

decreasing

Logical; if FALSE (default) the segmentation statistics data.frame will be sorted in increasing order, if TRUE the data.frame will be sorted in decreasing order.

...

Further arguments to be passed to magimage. Only relevant is plot=TRUE.

Details

The basic behaviour of profoundMakeSegimExpand and profoundMakeSegimDilate is to intelligently expand out image segments already identified by, e.g., profoundMakeSegim.

The profoundMakeSegimExpand defaults should work reasonably well on modern survey data (see Examples), but should the solution not be ideal try modifying these parameters (in order of impact priority): skycut (or SBlim), expandsigma, sigma.

profoundMakeSegimDilate is similar in nature to the pixel growing objmask routine in IRAF (see the ngrow and agrow description at http://iraf.noao.edu/projects/ccdmosaic/objmasks/objmasks.html). This similarity was discovered after implementation, but it is worth noting that the higher level curve of growth function profoundProFound is not trivially replicated by other astronomy tools.

The main difference between profoundMakeSegimExpand and profoundMakeSegimDilate is the former grows the expansion a bit more organically, whereas the latter always gives new pixels to the brighter object if in doubt. That said, profoundMakeSegimDilate often gives very similar solutions and runs about 10+ times faster, so might be the only option for larger images.

Value

A list containing:

segim

Integer matrix; the segmentation map matched pixel by pixel to image.

objects

Logical matrix; the object map matched pixel by pixel to image. 1 means there is an object at this pixel, 0 means it is a sky pixel. Can be used as a mask in various other functions that require objects to be masked out.

sky

The estimated sky level of the image. profoundMakeSegimExpand only).

skyRMS

The estimated sky RMS of the image. profoundMakeSegimExpand only).

segstats

If stats=TRUE this is a data.frame (see below), otherwise NULL.

header

The header provided, if missing this is NULL.

SBlim

The surface brightness limit of detected objects. Requires at least magzero to be provided and skycut>0, else NULL. profoundMakeSegimExpand only.

call

The original function call.

If stats=TRUE then the function profoundSegimStats is called and the segstats part of the returned list will contain a data.frame with columns (else NULL):

segID

Segmentation ID, which can be matched against values in segim

uniqueID

Unique ID, which is fairly static and based on the xmax and ymax position

xcen

Flux weighted x centre

ycen

Flux weighted y centre

xmax

x position of maximum flux

ymax

y position of maximum flux

RAcen

Flux weighted degrees Right Ascension centre (only present if a header is provided)

Deccen

Flux weighted degrees Declination centre (only present if a header is provided)

RAmax

Right Ascension of maximum flux (only present if a header is provided)

Decmax

Declination of maximum flux (only present if a header is provided)

sep

Radial offset between the cen and max definition of the centre (units of pixscale, so if pixscale represents the standard asec/pix this will be asec)

flux

Total flux (calculated using image-sky) in ADUs

mag

Total flux converted to mag using magzero

cenfrac

Fraction of flux in the brightest pixel

N50

Number of brightest pixels containing 50% of the flux

N90

Number of brightest pixels containing 90% of the flux

N100

Total number of pixels in this segment, i.e. contains 100% of the flux

R50

Approximate elliptical semi-major axis containing 50% of the flux (units of pixscale, so if pixscale represents the standard asec/pix this will be asec)

R90

Approximate elliptical semi-major axis containing 90% of the flux (units of pixscale, so if pixscale represents the standard asec/pix this will be asec)

R100

Approximate elliptical semi-major axis containing 100% of the flux (units of pixscale, so if pixscale represents the standard asec/pix this will be asec)

SB_N50

Mean surface brightness containing brightest 50% of the flux, calculated as flux*0.5/N50 (if pixscale has been set correctly then this column will represent mag/asec^2. Otherwise it will be mag/pix^2)

SB_N90

Mean surface brightness containing brightest 90% of the flux, calculated as flux*0.9/N90 (if pixscale has been set correctly then this column will represent mag/asec^2. Otherwise it will be mag/pix^2)

SB_N100

Mean surface brightness containing all of the flux, calculated as flux/N100 (if pixscale has been set correctly then this column will represent mag/asec^2. Otherwise it will be mag/pix^2)

xsd

Weighted standard deviation in x (always in units of pix)

ysd

Weighted standard deviation in y (always in units of pix)

covxy

Weighted covariance in xy (always in units of pix)

corxy

Weighted correlation in xy (always in units of pix)

con

Concentration, R50/R90

asymm

180 degree flux asymmetry (0-1, where 0 is perfect symmetry and 1 complete asymmetry)

flux_reflect

Flux corrected for asymmetry by doubling the contribution of flux for asymmetric pixels (defined as no matching segment pixel found when the segment is rotated through 180 degrees)

mag_reflect

flux_reflect converted to mag using magzero

semimaj

Weighted standard deviation along the major axis, i.e. the semi-major first moment, so ~2 times this would be a typical major axis Kron radius (always in units of pix)

semimin

Weighted standard deviation along the minor axis, i.e. the semi-minor first moment, so ~2 times this would be a typical minor axis Kron radius (always in units of pix)

axrat

Axial ratio as given by min/maj

ang

Orientation of the semi-major axis in degrees. This has the convention that 0= | (vertical), 45= \, 90= - (horizontal), 135= /, 180= | (vertical)

signif

Approximate singificance of the detection using the Chi-Square distribution

FPlim

Approximate false-positive significance limit below which one such source might appear spuriously on an image this large

flux_err

Estimated total error in the flux for the segment

mag_err

Estimated total error in the magnitude for the segment

flux_err_sky

Sky subtraction component of the flux error

flux_err_skyRMS

Sky RMS component of the flux error

flux_err_shot

Object shot-noise component of the flux error (only if gain is provided)

sky_mean

Mean flux of the sky over all segment pixels

sky_sum

Total flux of the sky over all segment pixels

skyRMS_mean

Mean value of the sky RMS over all segment pixels

Nedge

Number of edge segment pixels that make up the outer edge of the segment

Nsky

Number of edge segment pixels that are touching sky

Nobject

Number of edge segment pixels that are touching another object segment

Nborder

Number of edge segment pixels that are touching the image border

Nmask

Number of edge segment pixels that are touching a masked pixel (note NAs in image are also treated as masked pixels)

edge_frac

Fraction of edge segment pixels that are touching the sky i.e. NskyNedge, higher generally meaning more robust segmentation statistics

edge_excess

Ratio of the number of edge pixels to the expected number given the elliptical geometry measurements of the segment. If this is larger than 1 then it is a sign that the segment geometry is irregular, and is likely a flag for compromised photometry

flag_border

A binary flag telling the user which image borders the segment touches. The bottom of the image is flagged 1, left=2, top=4 and right=8. A summed combination of these flags indicate the segment is in a corner touching two borders: bottom-left=3, top-left=6, top-right=12, bottom-right=9.

Author(s)

Aaron Robotham

See Also

profoundMakeSegim, profoundProFound, profoundSegimStats, profoundSegimPlot

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
## Not run: 
image=readFITS(system.file("extdata", 'VIKING/mystery_VIKING_Z.fits',
package="ProFound"))$imDat
segim=profoundMakeSegim(image, plot=TRUE, skycut=2)
profoundMakeSegimExpand(image, segim$segim, plot=TRUE, skycut=1)
profoundMakeSegimDilate(image, segim$segim, plot=TRUE)

#Some other examples:

profoundMakeSegimExpand(image, segim$segim, plot=TRUE, skycut=0)
profoundMakeSegimExpand(image, segim$segim, plot=TRUE, skycut=-Inf, sigma=3)

profoundMakeSegimDilate(image, segim$segim, plot=TRUE, size = 15)
profoundMakeSegimDilate(image, segim$segim, plot=TRUE, size = 21)

#This expansion process is a *much* better idea then simply setting the original skycut
#to a low value like 1/0:
profoundMakeSegim(image, plot=TRUE, skycut = 1)
profoundMakeSegim(image, plot=TRUE, skycut = 0)

## End(Not run)

ProFound documentation built on Jan. 8, 2021, 5:37 p.m.