[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 6133e87 2/3: MakeCatalog repots surface bright
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master 6133e87 2/3: MakeCatalog repots surface brightness in mag/arcsec squared |
|
Date: |
Tue, 23 May 2017 20:04:58 -0400 (EDT) |
branch: master
commit 6133e872bced84af82cc9338f5e4ca1fff8ff5f3
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>
MakeCatalog repots surface brightness in mag/arcsec squared
Until now, MakeCatalog would only print the dataset's surface brightness in
units of magnitudes/pixel. But that is not nicely comparable to other
datasets. Hence, using a simple calculation (from the pixel size), it now
also reports the surface brightness in magnitudes/arcsec^2 also.
The documentation has also been updated to fully describe this derivation.
IMPORTANT: MakeCatalog's `--nsigmag' option is now `--sfmagnsigma'.
---
bin/mkcatalog/args.h | 23 ++++--
bin/mkcatalog/astmkcatalog.conf | 3 +-
bin/mkcatalog/main.h | 3 +-
bin/mkcatalog/mkcatalog.c | 45 +++++++++--
bin/mkcatalog/ui.c | 3 +-
bin/mkcatalog/ui.h | 3 +-
doc/gnuastro.texi | 170 ++++++++++++++++++++++++----------------
7 files changed, 168 insertions(+), 82 deletions(-)
diff --git a/bin/mkcatalog/args.h b/bin/mkcatalog/args.h
index 55cc576..df1d29c 100644
--- a/bin/mkcatalog/args.h
+++ b/bin/mkcatalog/args.h
@@ -180,15 +180,28 @@ struct argp_option program_options[] =
/* Output. */
{
- "nsigmag",
- UI_KEY_NSIGMAG,
+ "sfmagnsigma",
+ UI_KEY_SFMAGNSIGMA,
"FLT",
0,
- "Multiple of Sky STD to report magnitude of.",
+ "Surface brightness multiple of Sky STD.",
GAL_OPTIONS_GROUP_OUTPUT,
- &p->nsigmag,
+ &p->sfmagnsigma,
GAL_TYPE_FLOAT32,
- GAL_OPTIONS_RANGE_ANY,
+ GAL_OPTIONS_RANGE_GT_0,
+ GAL_OPTIONS_NOT_MANDATORY,
+ GAL_OPTIONS_NOT_SET
+ },
+ {
+ "sfmagarea",
+ UI_KEY_SFMAGAREA,
+ "FLT",
+ 0,
+ "Surface brightness area (in arcseconds^2).",
+ GAL_OPTIONS_GROUP_OUTPUT,
+ &p->sfmagarea,
+ GAL_TYPE_FLOAT32,
+ GAL_OPTIONS_RANGE_GT_0,
GAL_OPTIONS_NOT_MANDATORY,
GAL_OPTIONS_NOT_SET
},
diff --git a/bin/mkcatalog/astmkcatalog.conf b/bin/mkcatalog/astmkcatalog.conf
index 5637b17..b2d111f 100644
--- a/bin/mkcatalog/astmkcatalog.conf
+++ b/bin/mkcatalog/astmkcatalog.conf
@@ -27,7 +27,8 @@
skysubtracted 0
# Output:
- nsigmag 1
+ sfmagnsigma 1
+ sfmagarea 1
# Upper limit magnitude:
upnum 100
diff --git a/bin/mkcatalog/main.h b/bin/mkcatalog/main.h
index 3f7f287..8aa4aeb 100644
--- a/bin/mkcatalog/main.h
+++ b/bin/mkcatalog/main.h
@@ -146,7 +146,8 @@ struct mkcatalogparams
float zeropoint; /* Zero-point magnitude of object. */
uint8_t skysubtracted; /* If image is already sky subtracted. */
float threshold; /* Only use values above this threshold.*/
- float nsigmag; /* Multiple of STD to report magnitude. */
+ float sfmagnsigma; /* Surface brightness multiple of sigma.*/
+ float sfmagarea; /* Surface brightness area (arcsec^2). */
char *upmaskfile; /* Name of upper limit mask file. */
char *upmaskhdu; /* HDU of upper limit mask file. */
diff --git a/bin/mkcatalog/mkcatalog.c b/bin/mkcatalog/mkcatalog.c
index b8d1978..71ae0f7 100644
--- a/bin/mkcatalog/mkcatalog.c
+++ b/bin/mkcatalog/mkcatalog.c
@@ -650,15 +650,17 @@ static gal_list_str_t *
mkcatalog_outputs_same_start(struct mkcatalogparams *p, int o0c1,
char *ObjClump)
{
- char *str;
float snlim;
+ char *str, *tstr;
+ double pixarea=NAN;
gal_list_str_t *comments=NULL;
char *skyfile=p->skyfile ? p->skyfile : p->inputname;
char *stdfile=p->stdfile ? p->stdfile : p->inputname;
char *clumpsfile=p->clumpsfile ? p->clumpsfile : p->inputname;
char *objectsfile=p->objectsfile ? p->objectsfile : p->inputname;
- asprintf(&str, "%s %s catalog.", PROGRAM_STRING, o0c1 ? "object" : "clump");
+ asprintf(&str, "%s catalog of %s", o0c1 ? "Object" : "Clump",
+ PROGRAM_STRING);
gal_list_str_add(&comments, str, 0);
/* If in a Git controlled directory and output isn't a FITS file (in
@@ -715,8 +717,8 @@ mkcatalog_outputs_same_start(struct mkcatalogparams *p, int
o0c1,
if(p->input->wcs)
{
- asprintf(&str, "Pixel area (arcsec^2): %g",
- gal_wcs_pixel_area_arcsec2(p->input->wcs));
+ pixarea=gal_wcs_pixel_area_arcsec2(p->input->wcs);
+ asprintf(&str, "Pixel area (arcsec^2): %g", pixarea);
gal_list_str_add(&comments, str, 0);
}
@@ -726,10 +728,39 @@ mkcatalog_outputs_same_start(struct mkcatalogparams *p,
int o0c1,
gal_list_str_add(&comments, str, 0);
}
- if( !isnan(p->zeropoint) )
+ /* Print surface brightness limits. */
+ if( !isnan(p->zeropoint) && !isnan(p->sfmagnsigma) )
{
- asprintf(&str, "Pixel %g sigma surface brightness (magnitude): %.3f",
- p->nsigmag, -2.5f*log10(p->nsigmag*p->medstd)+p->zeropoint);
+ /* Per pixel. */
+ asprintf(&str, "%g sigma surface brightness (magnitude/pixel): %.3f",
+ p->sfmagnsigma, ( -2.5f
+ *log10( p->sfmagnsigma
+ * p->medstd )
+ + p->zeropoint ) );
+ gal_list_str_add(&comments, str, 0);
+
+ /* Per given area: a pixel area could be measured (a WCS was given),
+ then also estimate the surface brightness over one
+ arcsecond^2. From the pixel area, we know how many pixels are
+ necessary to cover one arcsecond^2. We also know that as the
+ number of samples (pixels) increases (to N), the noise increases
+ by sqrt(N). */
+ if(!isnan(pixarea) && !isnan(p->sfmagarea))
+ {
+ if(p->sfmagarea==1.0f) tstr=NULL;
+ else asprintf(&tstr, "%g-", p->sfmagarea);
+ asprintf(&str, "%g sigma surface brightness (magnitude/%sarcsec^2): "
+ "%.3f", p->sfmagnsigma, tstr ? tstr : "",
+ ( -2.5f * log10( p->sfmagnsigma
+ * p->medstd
+ * sqrt( p->sfmagarea / pixarea) )
+ + p->zeropoint ) );
+ gal_list_str_add(&comments, str, 0);
+ }
+
+ /* Notice: */
+ asprintf(&str, "Pixel STD for surface brightness calculation%s: %f",
+ (!isnan(pixarea) && !isnan(p->sfmagarea))?"s":"", p->medstd);
gal_list_str_add(&comments, str, 0);
}
diff --git a/bin/mkcatalog/ui.c b/bin/mkcatalog/ui.c
index a8855c1..0bc7270 100644
--- a/bin/mkcatalog/ui.c
+++ b/bin/mkcatalog/ui.c
@@ -123,7 +123,8 @@ ui_initialize_options(struct mkcatalogparams *p,
cp->coptions = gal_commonopts_options;
/* Specific to this program. */
- p->nsigmag = NAN;
+ p->sfmagnsigma = NAN;
+ p->sfmagarea = NAN;
p->upnsigma = NAN;
p->zeropoint = NAN;
p->threshold = NAN;
diff --git a/bin/mkcatalog/ui.h b/bin/mkcatalog/ui.h
index a5f72e9..d7e789b 100644
--- a/bin/mkcatalog/ui.h
+++ b/bin/mkcatalog/ui.h
@@ -68,7 +68,8 @@ enum option_keys_enum
UI_KEY_CLUMPSHDU,
UI_KEY_SKYHDU,
UI_KEY_STDHDU,
- UI_KEY_NSIGMAG,
+ UI_KEY_SFMAGNSIGMA,
+ UI_KEY_SFMAGAREA,
UI_KEY_UPMASKFILE,
UI_KEY_UPMASKHDU,
UI_KEY_UPNUM,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 4877f69..b6de3cd 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -13019,15 +13019,17 @@ transformations on the labeled image.
@cindex Object magnitude limit
@cindex Limit, object/clump magnitude
@cindex Magnitude, object/clump detection limit
-A meaningful scientific analysis requires knowledge of the limits of your
-dataset and detection/measurement tools: different datasets (images in the
-case of MakeCatalog) have different noise properties and different
-detection methods (or one method that is run with a different set of
-parameters) will have different abilities to detect or measure certain
-kinds of objects and their properties in an image. Therefore quantifying
-the target detection and measurement limitations with the particular
-dataaset and analysis tools will be the most crutial aspect of any
-analysis.
+No measurement on a real dataset can be perfect: you can only reach a
+certain level/limit of accuracy. Therefore, a meaningful (scientific)
+analysis requires an understanding of these limits for the dataset and your
+analysis tools: different datasets (images in the case of MakeCatalog) have
+different noise properties and different detection methods (one
+method/algorith/software that is run with a different set of parameters is
+considered as a different detection method) will have different abilities
+to detect or measure certain kinds of signal (astronomical objects) and
+their properties in an image. Hence, quantifying the detection and
+measurement limitations with a particular dataset and analysis tool is the
+most crucial/critical aspect of any high-level analysis.
In this section we discuss some of the most general limits that are very
important in any astronomical data analysis and how MakeCatalog makes it
@@ -13039,29 +13041,32 @@ measurements discussed here are defined in units of
magnitudes.
@table @asis
address@hidden Dataset's depth
-As we make more observations on one region of the sky and add the images
-over each other, we are able to decrease the standard deviation of the
-noise in each address@hidden is true for any noisy data, not just
-astronomical images}. Qualitatively, this decrease manifests its self by
-making fainter (per pixel) parts of the objects in the image more
-visible. Quantitatively, it increases the Signal to noise ratio, since the
-signal is fixed but the noise is decreased. It is very important to have in
-mind that here, noise is defined per pixel (or in the units of our data
-measurement), not per object.
address@hidden Surface brightness limit (of whole dataset)
address@hidden Surface brightness
+As we make more observations on one region of the sky, and add the
+observations into one dataset, we are able to decrease the standard
+deviation of the noise in each address@hidden is true for any noisy
+data, not just astronomical images}. Qualitatively, this decrease manifests
+its self by making fainter (per pixel) parts of the objects in the image
+more visible. Technically, this is known as surface
+brightness. Quantitatively, it increases the Signal to noise ratio, since
+the signal increases faster than noise with more data. It is very important
+to have in mind that here, noise is defined per pixel (or in the units of
+our data measurement), not per object.
You can think of the noise as muddy water that is completely covering a
flat address@hidden ground is the sky value in this analogy, see
@ref{Sky value}. Note that this analogy only holds for a flat sky value
across the surface of the image or ground.} with some regions higher than
-the address@hidden peaks are (parts of) astronomical objects in this
-analogy.} in it. In this analogy, height is brightness. Let's assume that
-in your first observation the muddy water has just been stirred and you
-can't see anything through it. As you wait and make more observations, the
-mud settles down and the @emph{depth} of the transparent water increases as
-you wait. The summits of hills begin to appear. As the depth of clear water
-increases, the parts of the hills with lower heights (less surface
-brightness) can be seen more clearly.
+the address@hidden peaks are the brightest parts of astronomical
+objects in this analogy.} in it. In this analogy, height (from the ground)
+is @emph{surface brightness}. Let's assume that in your first observation
+the muddy water has just been stirred and you can't see anything through
+it. As you wait and make more observations, the mud settles down and the
address@hidden of the transparent water increases, making the summits of
+hills visible. As the depth of clear water increases, the parts of the
+hills with lower heights (less parts with lower surface brightness) can be
+seen more clearly.
@cindex Data's depth
The outputs of NoiseChisel include the Sky standard deviation
@@ -13075,8 +13080,11 @@ On different instruments pixels have different
physical sizes (for example
in micro-meters, or spatial angle over the sky), nevertheless, a pixel is
our unit of data collection. In other words, while quantifying the noise,
the physical or projected size of the pixels is irrelevant. We thus define
-the @emph{depth} of each data-set (or image) as the magnitude of
address@hidden
+the Surface brightness limit or @emph{depth}, in units of magnitude/pixel,
+of a data-set, with zeropoint magnitude @mymath{z}, with the @mymath{n}th
+multiple of @mymath{\sigma_m} as (see @ref{Flux Brightness and magnitude}):
+
address@hidden Pixel}=-2.5\times\log_{10}{(n\sigma_m)}+z}
@cindex XDF
@cindex CANDELS
@@ -13086,20 +13094,79 @@ small (@mymath{\sim4} address@hidden). On the other
hand, the CANDELS
survey, is one of the widest multi-color surveys covering several fields
(about 720 address@hidden) but its deepest fields have only 9 orbits
observation. The depth of the XDF and CANDELS-deep surveys in the near
-infrared WFC3/F160W filter are respectively 34.40 and 32.45 magnitudes. In
-a single orbit image, this same field has a depth of 31.32. Recall that a
-larger magnitude corresponds to less brightness, see @ref{Flux Brightness
-and magnitude}.
+infrared WFC3/F160W filter are respectively 34.40 and 32.45
+magnitudes/pixel. In a single orbit image, this same field has a depth of
+31.32. Recall that a larger magnitude corresponds to less brightness.
+
+The low-level magnitude/pixel measurement above is only useful when all the
+datasets you want to use belong to one instrument (telescope and
+camera). However, you will often find yourself using datasets from various
+instruments with different pixel scales (projected pixel sizes). If we know
+the pixel scale, we can obtain a more easily comparable surface brightness
+limit in units of: magnitude/address@hidden Let's assume that the
+dataset has a zeropoint value of @mymath{z}, and every pixel is @mymath{p}
address@hidden (so @mymath{A/p} is the number of pixels that cover an
+area of @mymath{A} address@hidden). If the @mymath{n}th multiple of
address@hidden is desired, then the surface brightness (in units of
+magnitudes per A address@hidden) address@hidden we have @mymath{N}
+datasets, each with noise @mymath{\sigma}, the noise of a combined dataset
+will increase as @mymath{\sqrt{N}\sigma}.}:
+
address@hidden Projected}=-2.5\times\log_{10}{\left(n\sigma_m\sqrt{A\over
+p}\right)+z}}
+
+Note that this is an extrapolation of the actually measured value of
address@hidden (which was per pixel). So it should be used with extreme
+care (for example the dataset must have an approximately flat depth). For
+each detection over the dataset, you can estimate an upper-limit magnitude
+which actually uses the detection's area/footprint. It doesn't extrapolate
+and even accounts for correlated noise features. Therefore, the upper-limit
+magnitude is a much better measure of your dataset's surface brightness
+limit for each particular object.
+
+MakeCatalog will calculate the input dataset's @mymath{SB_{\rm Pixel}} and
address@hidden Projected}} and write them as comments/meta-data in the
+output catalog(s). Just note that @mymath{SB_{\rm Projected}} is only
+calculated if the input has World Coordinate System (WCS).
+
address@hidden Completeness limit (of each detection)
address@hidden Completeness
+As the surface brightness of the objects decreases, the ability to detect
+them will also decrease. An important statistic is thus the fraction of
+objects of similar morphology and brightness that will be identified with
+our detection algorithm/parameters in the given image. This fraction is
+known as completeness. For brighter objects, completeness is 1: all bright
+objects that might exist over the image will be detected. However, as we
+go to lower surface brightness objects, we fail to detect some and
+gradually we are not able to detect anything any more. For a given profile,
+the magnitude where the completeness drops below a certain level usually
+above @mymath{90\%} is known as the completeness limit.
+
address@hidden Purity
address@hidden False detections
address@hidden Detections false
+Another important parameter in measuring completeness is purity: the
+fraction of true detections to all true detections. In effect purity is the
+measure of contamination by false detections: the higher the purity, the
+lower the contamination. Completeness and purity are anti-correlated: if we
+can allow a large number of false detections (that we might be able to
+remove by other means), we can significantly increase the completeness
+limit.
+
+One traditional way to measure the completeness and purity of a given
+sample is by embedding mock profiles in regions of the image with no
+detection. However in such a study we must be really careful to choose
+model profiles as similar to the target of interest as possible.
address@hidden Target magnitude measurement error
address@hidden Magnitude measurement error (of each detection)
Any measurement has an error and this includes the derived magnitude for an
object. Note that this value is only meaningful when the object's magnitude
is brighter than the upper-limit magnitude (see the next items in this
list). As discussed in @ref{Flux Brightness and magnitude}, the magnitude
(@mymath{M}) of an object with brightness @mymath{B} and Zeropoint
-magnitude @mymath{Z} can be written as:
+magnitude @mymath{z} can be written as:
address@hidden(B)+Z}
address@hidden(B)+z}
@noindent
Calculating the derivative with respect to @mymath{B}, we get:
@@ -13125,7 +13192,7 @@ objects (see @url{https://arxiv.org/abs/1505.01664,
Akhlaghi and Ichikawa
[2015]}), but this single equation can be used to estimate the measured
magnitude error afterwards for any type of target.
address@hidden Target's upper limit magnitude
address@hidden Upper limit magnitude (of each detection)
Due to the noisy nature of data, it is possible to get arbitrarily low
values for a faint object's brightness (or arbitrarily high
magnitudes). Given the scatter caused by the noise, such small values are
@@ -13172,35 +13239,6 @@ certain patters, so the shape of the object can also
affect the result. So
in MakeCatalog, the upper limit magnitude is found for each object in the
image separately. Not one value for the whole image.
address@hidden Object's completeness limit
address@hidden Completeness
-As the surface brightness of the objects decreases, the ability to detect
-them will also decrease. An important statistic is thus the fraction of
-objects of similar morphology and brightness that will be identified with
-our detection algorithm/parameters in the given image. This fraction is
-known as completeness. For brighter objects, completeness is 1: all bright
-objects that might exist over the image will be detected. However, as we
-go to lower surface brightness objects, we fail to detect some and
-gradually we are not able to detect anything any more. For a given profile,
-the magnitude where the completeness drops below a certain level usually
-above @mymath{90\%} is known as the completeness limit.
-
address@hidden Purity
address@hidden False detections
address@hidden Detections false
-Another important parameter in measuring completeness is purity: the
-fraction of true detections to all true detections. In effect purity is the
-measure of contamination by false detections: the higher the purity, the
-lower the contamination. Completeness and purity are anti-correlated: if we
-can allow a large number of false detections (that we might be able to
-remove by other means), we can significantly increase the completeness
-limit.
-
-One traditional way to measure the completeness and purity of a given
-sample is by embedding mock profiles in regions of the image with no
-detection. However in such a study we must be really careful to choose
-model profiles as similar to the target of interest as possible.
-
@end table