Configuration Options¶
Most of the example applications provided can be configured from command line arguments, as described in the Tutorial section.
Some applications, like source finding, however, require a large set of configuration options, specified inside a configuration file, passed to the application
as a command line argument --config=[FILE]
.
In this section we report a list of the main configuration options defined in CAESAR to customize tasks. The full list of options defined is kept in ConfigParser.cc
class.
To print the full list of defined options use the ConfigParser::PrintOptions() method. For example from ROOT prompt type:
Caesar::ConfigParser::Instance().PrintOptions()
or from the python CLI:
from ROOT import gSystem
gSystem.Load('libCaesar')
from ROOT import Caesar
Caesar.ConfigParser.Instance().PrintOptions()
Input Options¶
These options enable control of input data to be given to CAESAR applications.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Input image filename (.root/.fits) |
“” |
|
|
Image name to be read in input ROOT file |
“” |
|
|
Read sub-image
If false read the entire image
|
false |
true
false
|
|
Min image x pixel coordinate to be read
Used only when readTileImage is true
|
0 |
|
|
Max image x pixel coordinate to be read
Used only when readTileImage is true
|
0 |
|
|
Min image y pixel coordinate to be read
Used only when readTileImage is true
|
0 |
|
|
Max image y pixel coordinate to be read
Used only when readTileImage is true
|
0 |
Output Options¶
These options enable control of information & data reported in output by CAESAR applications.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Save results & maps to output
ROOT file
|
true |
true
false
|
|
Save config options to output
ROOT file
|
true |
true
false
|
|
Save sources to output ROOT
file
|
true |
true
false
|
|
Save input map to output
ROOT file
|
false |
true
false
|
|
Save computed background map
to output ROOT file
|
true |
true
false
|
|
Save computed rms map
to output ROOT file
|
true |
true
false
|
|
Save computed residual map
to output ROOT file
|
true |
true
false
|
|
Save computed significance map
to output ROOT file
|
true |
true
false
|
|
Save computed saliency map
to output ROOT file
|
true |
true
false
|
|
Save computed segmented map
to output ROOT file
|
true |
true
false
|
|
Name of ROOT file where to
store output data (images,
run config, sources, etc)
|
output.root |
|
|
Save island and fitted
components to ascii files
|
true |
true
false
|
|
Name of ascii file where to
store source catalog
|
catalog.dat |
|
|
Name of ascii file where to
store fitted source component
catalog
|
catalog_fitcomp.dat |
|
|
Save sources & fit components
to DS9 region files
|
true |
true
false
|
|
Name of DS9 region file where
to store source catalog
|
ds9.reg |
|
|
Name of ascii file where to
store source fitted components
|
ds9_fitcomp.reg |
|
|
Store DS9 regions in WCS
coordinates
|
false |
true
false
|
|
DS9 region WCS type to be used
if convertDS9RegionsToWCS=true
|
0 |
0=J2000
1=B1950
2=GAL
|
|
Shape to be used to store
source islands in DS9 region
|
2 |
1=ellipse
2=polygon
|
|
Save output data images to
FITS files
|
false |
true
false
|
|
Name of FITS file where
to store input map read
|
input.fits |
|
|
Name of FITS file where
to store computed bkg map
|
bkg.fits |
|
|
Name of FITS file where
to store computed rms map
|
rms.fits |
|
|
Name of FITS file where to
store computed significance map
|
significance.fits |
|
|
Name of FITS file where
to store computed residual map
|
residual.fits |
|
|
Name of FITS file where
to store computed saliency map
|
saliency.fits |
Run & Distributed Processing Options¶
These options enable control of application run (e.g. logging levels) and distributed processing (e.g. number of threads).
Option |
Description |
Default |
Values |
---|---|---|---|
|
Log level threshold |
INFO |
DEBUG
INFO
WARN
ERROR
FATAL
|
|
Number of threads used if
OPENMP is enabled. If set to
-1 a number of threads equal
to the available cores is used
|
-1 |
|
|
Split input image in tiles
for parallel processing
|
false |
true
false
|
|
Size of tile in pixels along X
coordinate used for partition
|
1000 |
|
|
Size of tile in pixels along Y
coordinate used for partition
|
1000 |
|
|
Enable tile overlap in image
partition for parallel
processing
|
false |
true
false
|
|
Tile overlap fraction along
X coordinate to partition the
input image for parallel
processing (1=no overlap,
0.5=half overlap)
|
1 |
|
|
Tile overlap fraction along
Y coordinate to partition the
input image for parallel
processing (1=no overlap,
0.5=half overlap)
|
1 |
|
|
Merge overlapping sources
found at tile edge by each
worker when aggregating the
final catalog
|
true |
true
false
|
|
Merge overlapping sources
found in each tile. If true
compact and extended sources
found by different algorithms
in a tile are merged if
overlapping. If you want to
keep sources distinct set
option to false
|
false |
true
false
|
Stats & Background Compute Options¶
These options enable control of image background calculation. Background can be either computed globally or locally. Local background maps (bkg, rms) are obtained by interpolating background estimator values computed on a grid of sampling image rectangular boxes.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Stat estimator used to compute
image background & noise
image background & noise
image background & noise
|
2 |
1=Mean/RMS
2=Median/MAD
3=BiWeight
4=Clipped Median/RMS
|
|
Use C++ parallel algorithm
to compute median estimator
|
true |
true
false
|
|
Compute local background
and noise maps and use them
instead of global bkg info
|
true |
true
false
|
|
Use 2nd pass to refine local
noise map
|
true |
true
false
|
|
Exclude pixels belonging to
detected bright blobs when
computing local background
estimators. Blob find seed thr
parameters are reported in
source finding option table
below
|
false |
true
false
|
|
Size of sampling box along x
coordinate for local bkg
calculation in pixels. Size is
instead assumed as multiple of
beam size if
useBeamInfoInBkg is true |
20 |
|
|
Size of sampling box along y
coordinate for local bkg
calculation in pixels. Size is
instead assumed as multiple of
beam size if
useBeamInfoInBkg is true |
20 |
|
|
Size of grid along x
coordinate used for local bkg
interpolation expressed as
fraction of sampling box x
size
|
0.2 |
|
|
Size of grid along y
coordinate used for local bkg
interpolation expressed as
fraction of sampling box y
size
|
0.2 |
|
|
Border pad size in pixels of
box around source bounding box
used to estimate bkg for
fitting
|
20 |
|
|
Use beam information in bkg
sampling box size definition.
Beam info are taken from image
when available, otherwise from
user beam parameter below.
|
true |
true
false
|
|
User-supplied map pixel area
in arcsec. Used when CDELT
info is not available in
image metadata
|
1 |
|
|
User-supplied circular beam
FWHM in arcsec (BMAJ=BMIN).
Used when beam info is not
available in image metadata
|
6.5 |
|
|
User-supplied beam ellipse
major axis in arcsec.
Used when beam info is not
available in image metadata
|
10 |
|
|
User-supplied beam ellipse
minor axis in arcsec.
Used when beam info is not
available in image metadata
|
5 |
|
|
User-supplied beam position
angle in degrees and measured
CCW from North (pa=0 North).
Used when beam info is not
available in image metadata
|
0 |
Source Finding Options¶
These options enable control of source detection. This is performed using a flood-fill algorithm aggregating pixels around significant seeds if above a given merge threshold. Detected blobs form a collection of candidate sources.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Enable/disable search of
compact sources
|
true |
true
false
|
|
Minimum number of pixels
to consider a blob as source
candidate
|
5 |
|
|
Seed threshold in blob finding
given as number of sigmas
above background
|
5 |
|
|
Merge/aggregation threshold
in blob finding given as
number of sigmas above
background. Pixels above this
threshold are added to the blob
|
2.6 |
|
|
Add to blob only pixels above
merge threshold but below seed
threshold
|
false |
true
false
|
|
Search for holes (i.e. blobs
with negative significance)
along with “positive” blobs
|
false |
true
false
|
|
Number of iterations to be
performed in compact source
search. At each iteration the
seed threshold is decreased by
seedThrStep |
1 |
|
|
Seed threshold decrease step
size between iterations.
Effective only when
compactSourceSearchNIters >1 |
0.5 |
Nested Source Finding Options¶
These options enable control of nested source detection. Nested sources are blobs inside another mother blobs. Detection of nested blob uses a blob detection algorithm, based on the thresholding of a filter blob map (LoG or Gaus2D smoothed), which increases the computation time, particularly if blob search is done at multiple spatial scales. In presence of extended/diffuse object you can consider turning off this calculation. If however you have extended and bright object and you turn off nested source search you may see that compact/point-source located inside the extended one will be included in the mother and not fitted.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Enable/disable search of
compact nested sources
|
true |
true
false
|
|
Filter map used in nested
blob finder to search blobs
|
2 |
1=gaus smoothed Lapl
2=multi-scale LoG
|
|
Filter kernel size factor par
so that kern size=
factor x sigma (sigma is the
filter scale par in pixels)
|
6 |
|
|
Mother source area/beam thr to
add nested sources. If
npix<=thr*beamArea no nested
sources are added to the
mother source even if detected.
If thr=0 nested sources are
always added if
searchNestedSources isenabled
|
10 |
|
|
Threshold factor param used in
blob filter map to create mask
(thr=thrFactor*<img>).
|
0 |
|
|
Minimum distance in pixels
(in x or y) between nested and
parent blob centroids below
which nested source is skipped
as most probably equal to the
parent (avoid duplicates)
|
2 |
|
|
Maximum fraction of matching
pixels between nested and
parent blob above which nested
is skipped as most probably
equal to the parent (avoid
duplicates)
|
0.5 |
|
|
Nested blob significance
seed thr in sigmas (in filter
blob map) below which nested
blob is skipped
|
5 |
|
|
Nested blob peak significance
merge thr in sigmas (in filter
blob map) below which nested
blob is skipped
|
2.5 |
|
|
Nested blob min search scale
factor parameter so that blob
filter scale in pixels is
= scaleFactor x beam width
|
1 |
|
|
Nested blob max search scale
factor parameter so that blob
filter scale in pixels is
= scaleFactor x beam width
|
3 |
|
|
Nested blob scale factor step
so that scaleFactor=
minScaleFactor + step
|
1 |
Source Selection Options¶
These options enable control of quality selection cuts applied to detected blobs to select good source candidates and tag point-source candidates (used later in source residual map and fitting stage). Options are also provided to select sources to be stored in the final catalog.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Enable/disable source
selection
|
true |
true
false
|
|
Apply minimum bounding box cut
to detected blobs
|
false |
true
false
|
|
Minimum bounding box cut value
in pixel. Blobs with minimum
bounding box size below the
threshold are tagged as bad
|
2 |
|
|
Apply cut on blob circular
ratio param to detected blobs
|
false |
true
false
|
|
Circular ratio cut value.
in pixel. Blobs with circ
ratio above this threshold
passed the point-like cut
(1=circle, 0=line)
|
0.4 |
0 1 |
|
Apply cut on blob elongation
param to detected blobs
|
false |
true
false
|
|
Elongation cut value.
Blobs with elongation param
below this threshold
passed the point-like cut
|
0.7 |
0 1 |
|
Apply cut on blob maximum
number of pixels.
|
false |
true
false
|
|
Max number of pixels cut value.
Blobs with a number of pixels
below this threshold
passed the point-like cut
|
1000 |
|
|
Apply cut on ratio between
blob area and blob ellipse
bounding box area.
|
false |
true
false
|
psEllipseAreaRatioMinThr psEllipseAreaRatioMaxThr |
Area/EllipseArea ratio min and
max cut values.
Blobs in cut range passes the
point-like cut
|
0.6 1.4 |
|
|
Apply cut on number of beams
found in detected blob
(NBeams=blob npix/beam npix)
|
false |
true
false
|
|
Max number of beams cut value.
Blobs with a number of beams
below this threshold
passed the point-like cut
|
10 |
Source Fitting Options¶
These options enable control of source fitting stage: minimization algorithm and relative parameters, starting parameters and limits, etc.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Enable/disable source
fitting stage
|
false |
true
false
|
|
Split source fitting among
multiple threads. Multithread
is not supported by Minuit
minimizer
|
false |
true
false
|
|
Scale source flux data to max
peak flux if true, otherwise
scale to mJy units
|
false |
true
false
|
|
Minimizer used in source
fitting
|
Minuit2 |
Minuit
Minuit2
|
|
Minimization algorithm used in
source fitting
|
minimize |
migrad
simplex
scan
minimize
fumili
|
|
Minimizer printout level
|
1 |
|
|
Minimizer strategy parameter
(larger means more accurate
minimization but more fcn
calls)
|
2 |
|
|
Fit function minimization
tolerance (smaller means more
accurate minimization but more
fcn calls)
|
1.e-2 |
|
|
Maximum number of iterations
that can be done by minimizer
before giving up and returning
not converged fit
|
100000 |
|
|
Try to improve convergence by
iterating fit if not converged
or converged with pars at
limits
|
true |
true
false
|
|
Number of times fit is
repeated (with enlarged
limits) if improve convergence
flag is enabled
|
1000 |
|
|
Par bound rel increase step
size set when trying to improve
convergence:
parmax= parmax_old+(1+nretry)*
fitParBoundIncreaseStepSize
*0.5*|max-min|
|
0.1 |
|
|
If enabled run HESSE minimizer
at convergence to improve
minimum and par error estimate
limits
|
true |
true
false
|
|
If fit fails to converge,
repeat it iteratively with one
component less at each cycle
until convergence or until no
more components are available
|
true |
true
false
|
|
Maximum number of beams
for a compact source to be
fitted (if above this threshold
the fit is not performed)
|
20 |
|
|
If true use nested sources
(if any) as starting fit
components, otherwise estimate
blended components in blob
using a peak finding +
segmentation algorithm
|
false |
true
false
|
|
Maximum number of components
fitted in a blob
|
5 |
|
|
Minimum dilation kernel size
in pixels used to detect start
fit components
|
3 |
|
|
Maximum dilation kernel size
in pixels used to detect start
fit components
|
7 |
|
|
Requested peak multiplicity
across different dilation
kernels. A multiplicity=-1
imposes that a peak must be
found in all given dilation
kernels (within a tolerance)
to be considered a component
|
1 |
|
|
Peak max position offset in
pixels above which two peaks
are considered distincs.
Used to compare peaks found
in different dilation kernels
|
2 |
|
|
Minimum peak flux significance
(in nsigmas wrt source avg
bkg and rms) below which peak
is skipped and not considered
as a fit component
|
1 |
|
|
Apply limits to source
centroid pars in fit
|
true |
true
false
|
|
Fix source centroid pars
in pre-fit
|
false |
true
false
|
|
Source centroid par limits
given as max offset in pixel
with respect to starting fit
centroid pars
|
3 |
|
|
Fix bkg level par in fit
|
true |
true
false
|
|
Apply limits to bkg level par
in fit
|
true |
true
false
|
|
Use estimated (avg bkg) as
starting bkg level par in fit
|
true |
true
false
|
|
Use bkg estimated in a box
around source (if available)
as bkg level par in fit
|
true |
true
false
false
|
|
Starting bkg level par in fit
(used when option
fitParBoundIncreaseStepSize is
false
|
0 |
|
|
Apply limits to amplitude par
in fit
|
true |
true
false
|
|
Fix amplitude par in pre-fit
|
true |
true
false
|
|
Amplitude par limit given as
max relative offset with
respect to starting source
component peak
Speak*(1+-fitAmplLimit))
|
0.3 |
|
|
Apply limits to sigma pars
in fit
|
true |
true
false
|
|
Fix sigma pars in pre-fit
|
false |
true
false
|
|
Sigma par limit given as max
relative offset with respect
to starting component sigma
pars
|
0.3 |
|
|
Fix sigma pars in fit
|
false |
true
false
|
|
Apply limits to theta par
in fit
|
true |
true
false
|
|
Fix theta par in pre-fit
|
false |
true
false
|
|
Fix theta par in fit
|
false |
true
false
|
|
Theta par limit given as max
offset in degrees with respect
to starting component theta
par
|
5 |
|
|
If enabled only blob pixels
above a significance threshold
are included in chi2. Pixels
below threshold are included
in a regularization chi2 term
|
false |
true
false
|
|
Blob significance
threshold below which pixels
are included in the
regularization chi2 term but
not in the chi2
|
2.5 |
|
|
Fit chi2 regularization par
so that total chi2 is given by
chi2(Z>thr)+regPar*chi2(Z<thr)
|
0 |
Source Fit Selection Cuts¶
These options enable control of source fit selection cuts. These cuts are used to assign flag to source fitted components.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Apply fit Chi2/NDF cut.
Used to set fit quality flag.
If Chi2/NDF>cut the good fit
cut is not passed
|
true |
true
false
|
|
Chi2/NDF cut value
|
5 |
|
|
Apply fit ellipse selection
cuts. Used to set component
flags. If not passed, fit
component is tagged as fake
|
false |
true
false
|
|
Ellipse eccentricity ratio
(fit/beam) min cut value
|
0.5 |
|
|
Ellipse eccentricity ratio
(fit/beam) max cut value
|
1.5 |
|
|
Ellipse area ratio
(fit/beam) min cut value
|
0.01 |
|
|
Ellipse area ratio
(fit/beam) max cut value
|
10 |
|
|
45 |
Source Residual Options¶
These options enable control of source residual map. Residual map is made by removing and/or subtracting detected sources from the input map.
Source removal is done by replacing source pixel flux values (along with surrounding pixel around them, controlled by a dilation filter) with a residual model value, chosen among: average estimated background, median of source pixels. Residual model value can be randomized if desired. Source removal is controlled by two significance thresholds.
Sources with fluxes above the higher threshold are removed regardless of any other conditions (e.g. on source type, etc). Sources with fluxes above the lower threshold (but below the higher threshold) are removed conditionally on chosen source type assigned in the finding process (e.g. point-like, compact, extended). Sources tagged as point-like can be removed with two different algorithms. The first one is described above and consists of replacing source pixel values by model values. The second method uses source fit model (if available) and subtract flux model from the input image. Removal of sources with nested components is controlled by the removeNestedSources
flag. If enabled, the removal/subtraction process is done
on nested sources and not on parent source pixels. On the contrary, sources are removed as described above and nested sources are removed, being part of the parent.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Compute compact source
residual map (after compact
source search)
|
false |
true
false
|
|
High source significance
threshold (in nsigmas wrt bkg)
used to remove sources
|
10 |
|
|
Source significance
threshold (in nsigmas wrt bkg)
used to remove sources
|
5 |
|
|
Remove nested sources instead
of parent source
is not supported by Minuit
minimizer
|
true |
true
false
|
|
Dilation filter kernel size in
pixels used to remove sources.
NB: Must be an odd number >1
This option controls the halo
size around source to be
removed
|
9 |
|
|
Type of sources to be removed
threshold (in nsigmas wrt bkg)
used to remove sources
|
2 |
-1=all types
1=compact
2=point-like
3=extended
|
|
Residual model used to replace
source pixel values
|
1 |
1=bkg
2=source median
|
|
Randomize residual model pixel
values
|
false |
true
false
|
|
Method used to subtract point
sources
|
1 |
1=model removal
2=fit model subtract
|
Extended Source Finding Options¶
These options enable control of extended source search. Specific options for the available algorithms are reported in the Tables below. Superpixel Hierarchical Clustering algorithm is not currently available (not ported yet from CAESAR old repository).
Option |
Description |
Default |
Values |
---|---|---|---|
|
Enable/disable search of
extended sources after compact
source finding
|
false |
true
false
|
|
Extended source search method
|
4 |
1=Wavelet Transform
2=SP Hier Clustering
3=Active Contour
4=Saliency Filter
|
|
Use residual map as input for
extended source search
source finding
|
true |
true
false
|
|
Apply smoothing to residual
map before performing extended
source finding
|
true |
true
false
|
|
Filter used to smooth residual
map
|
2 |
1=gaus
2=guided
|
|
Gaussian filter kernel size
in pixels. NB: Must be an odd
value
|
5 |
|
|
Gaussian filter sigma par
in pixels
|
1 |
|
|
Guided filter radius par
in pixels
|
12 |
|
|
Guided filter epsilon par
(regularization parameter)
|
0.04 |
Wavelet Transform Algorithm Options¶
These options enable control of extended source search with the Wavelet Transform method.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Minimum Wavelet scale to be
used for extended source
search
|
3 |
|
|
Maximum Wavelet scale to be
used for extended source
search
|
6 |
Active Contour Algorithm Options¶
These options enable control of extended source search with the Active Contour method. Two algorithms are provided: Chan-Vese, Linear Region-based Active Contour (LRAC).
Option |
Description |
Default |
Values |
---|---|---|---|
|
Active contour method
|
1 |
1=Chan-Vese
2=LRAC
|
|
Maximum number of iterations
|
1000 |
|
|
Level set initialization
method
|
1 |
1=circle
2=checkerboard
3=saliency
|
|
Level set size fraction wrt
to minimum image size (e.g.
circle radius=fraction x image
size)
|
0.1 |
|
|
Tolerance parameter to stop
main iteration loop
|
0.1 |
0
1
|
|
Number of iteration done in
inner cycle in Chan-Vese algo
|
5 |
|
|
Number of iteration done in
re-initialization step in
Chan-Vese algo
|
5 |
|
|
Chan-Vese time step par
|
0.007 |
|
|
Chan-Vese window size par
|
1 |
|
|
Chan-Vese lambda1 par
|
1 |
|
|
Chan-Vese lambda2 par
|
2 |
|
|
Chan-Vese mu par
|
0.5 |
|
|
Chan-Vese nu par
|
0 |
|
|
Chan-Vese p par
|
1 |
|
|
LRAC regularization par
|
0.1 |
|
|
LRAC radius of locatization
ball par
|
10 |
|
|
LRAC convergence par
|
0.01 |
Saliency Filtering Algorithm Options¶
These options enable control of extended source search with the Saliency Filtering method.
Option |
Description |
Default |
Values |
---|---|---|---|
|
Superpixel regularization
parameter
|
1 |
|
|
Superpixel min area
parameter in pixels
|
10 |
|
|
Superpixel min scale par in
pixels used in multi-scale
saliency calculation
|
20 |
|
|
Superpixel max scale par in
pixels used in multi-scale
saliency calculation
|
60 |
|
|
Superpixel scale step par in
pixels used in multi-scale
saliency calculation
|
10 |
|
|
Fraction of most similar
superpixel neighbors used
in saliency map computation
|
0.2 |
0
1
|
|
Use robust stats pars in
saliency map computation
|
false |
true
false
|
|
Superpixel dissimilarity
exponential decay parameter
used in saliency map
computation
|
100 |
|
|
Regularization parameter
controlling superpixel
spatial-intensity balance in
in distance measure used for
saliency map computation
(1 means equal weights)
|
1 |
|
|
Fraction of resolution
scales required
above threshold to
consider a pixel salient.
If set to 1 a pixel is
considered salient if its
saliency value at all
scales is above threshold
|
0.7 |
0
1
|
|
Add background map to
total saliency map
|
false |
true
false
|
|
Add noise map to
total saliency map
|
false |
true
false
|
|
Saliency threshold factor
parameter. Threshold is
computed as:
thr=<saliency>*factor
(<saliency> is the median)
if
saliencyUseOptimalThr disabled
|
2.8 |
|
|
Use optimal threshold in
multiscale saliency
thresholding. If true the
threshold is computed as
max(min(otsuThr,valleyThr),
medianThr)
|
true |
true
false
|
|
Threshold factor on input
map to consider a pixel as
salient. Threshold is set as
thr=<img>*factor (<img> is
the median). Pixel below
threshold are not set as
salient even if saliency is
above saliency threshold
|
1 |