[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[gnuastro-commits] master 4294506 32/32: astscript-radial-profile: polis
|
From: |
Mohammad Akhlaghi |
|
Subject: |
[gnuastro-commits] master 4294506 32/32: astscript-radial-profile: polished the script and book |
|
Date: |
Wed, 24 Feb 2021 22:36:21 -0500 (EST) |
branch: master
commit 42945061f291a5c2fe4e5c571da8ddd9c3e4edff
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>
astscript-radial-profile: polished the script and book
In order to make the radial profile script more user friendly some
polishing was necessary in the script and the book as described below:
- Generally, a short description of this script has been added in the
'NEWS', 'README' and the "Gnuastro programs list" appendix of the book.
- All the scripts have been moved in a new "Installed Scripts" chapter of
the book. This makes it easier to find them, and also helps the users
feel their difference from compiled programs (for example that they
don't have configuration files). This shuffling of full sections in
various sections of the book caused a big git-diff in the book, that is
just due to ordering.
- Following the Gnuastro conding conventions, the initialization of the
variables is now ordered based on their length: When order is not
important in a serious of connected commands, it is much more easier for
the eye for them to be sorted by length. During development, we always
search for the relevant variable, so again, order is irrelevant and
ordering by context isn't much helpful either.
- The '--quiet' option is now used within the script. Until now it was set
where necessary, but not used. While adding the '--quiet' option, I
noticed that MakeProfiles still prints the output name in this mode. So
this was also fixed with this commit.
- The old '--pangle' and '--qratio' were renamed to '--positionangle' and
'--axisratio' (identical option names to MakeCatalog's options). This
greatly helps the users in remembering them.
- The default value of the '--sigmaclip' option (for setting
sigma-clipping parameters) was set to an empty string. To help in
modularity (keeping default things where they are originally set), when
its not called, this option isn't passed to MakeCatalog at all!
Therefore by default (when the user doesn't give this option), the
default value of MakeCatalog will be used.
- The values to the '--measure' option don't include a '--' any more. The
user simply gives comma-separated values, possibly in multiple calls to
this option (like all other Gnuastro programs). The script will then
merge them all into one long comman-separated list and add a '--'
between each.
- The comments were re-justified to fit the 75 character limit set by
Gnuastro's coding convention.
I should really thank Raul, Zahra and Carlos for the work on this script!
It is very useful in many scenarios.
---
NEWS | 5 +
README | 5 +
bin/mkprof/mkprof.c | 2 +-
bin/script/radial-profile.in | 183 +-
doc/gnuastro.texi | 4045 +++++++++++++++++++++---------------------
5 files changed, 2166 insertions(+), 2074 deletions(-)
diff --git a/NEWS b/NEWS
index a5af946..a1f0ebc 100644
--- a/NEWS
+++ b/NEWS
@@ -16,6 +16,11 @@ See the end of the file for license conditions.
asttable table.fits --range=MAG,18:20 --column=RA,DEC \
| astscript-make-ds9-reg --column=1,2 --radius=0.5 \
--command="ds9 image.fits"
+ - astscript-radial-profile: Measure the radial profile of an object on
+ an image. The profile can be centered anywhere in the image and any
+ circular, or elliptical distance can be defined. The output is a table
+ with the profile's value in one column and any requested measure in
+ the other columns (any MakeCatalog measurement is possible).
Arithmetic:
- New operators (the trigonometric/hyperbolic functions were previously
diff --git a/README b/README
index 03b6b93..b0da3d5 100644
--- a/README
+++ b/README
@@ -113,6 +113,11 @@ very similarly (with minor differences, as explained in
the book).
standard input), create an SAO DS9 region file from the requested
positional columns (WCS or image coordinates).
+ - astscript-radial-profile: Calculate the radial profile of an object
+ within an image. The object can be at any location in the image, using
+ various measures (median, sigma-clipped mean and etc), and the radial
+ distance can also be measured on any general ellipse.
+
- astscript-sort-by-night: Given a list of FITS files, and a HDU and
keyword name for a date, this script separates the files in the same
night (possibly over two calendar days).
diff --git a/bin/mkprof/mkprof.c b/bin/mkprof/mkprof.c
index 60d188b..de7144b 100644
--- a/bin/mkprof/mkprof.c
+++ b/bin/mkprof/mkprof.c
@@ -883,7 +883,7 @@ mkprof(struct mkprofparams *p)
}
/* If a merged image was created, let the user know.... */
- if(p->mergedimgname)
+ if(p->mergedimgname && p->cp.quiet==0)
printf(" -- Output: %s\n", p->mergedimgname);
/* Clean up. */
diff --git a/bin/script/radial-profile.in b/bin/script/radial-profile.in
index 5191506..4eb9aa5 100644
--- a/bin/script/radial-profile.in
+++ b/bin/script/radial-profile.in
@@ -34,18 +34,18 @@ set -e
# Default option values (can be changed with options on the command-line).
hdu=1
-quiet=0
-qratio=1
-pangle=0
+rmax=""
+quiet=""
tmpdir=""
+output=""
keeptmp=0
-rmax="max"
mode="img"
+measure=""
+axisratio=1
+sigmaclip=""
+positionangle=0
xcenter="center"
ycenter="center"
-measure="--mean"
-sigmaclip="3,0.2"
-output="default"
version=@VERSION@
scriptname=@SCRIPT_NAME@
@@ -89,10 +89,10 @@ $scriptname options:
-x, --xcenter=FLT Coordinate of the center along the first axis.
-y, --ycenter=FLT Coordinate of the center along the second axis.
-R, --rmax=FLT Maximum radius for the radial profile (in pixels).
- -Q, --qratio=FLT Axis ratio for ellipse profiles (A/B).
- -p, --pangle=FLT Position angle for ellipse profiles.
- -m, --measure="STR" Measurement operator ("--mean", "--median", etc.).
- -s, --sigmaclip=FLT,FLT Parameters for sigma clipping measure operators.
+ -Q, --axisratio=FLT Axis ratio for ellipse profiles (A/B).
+ -p, --positionangle=FLT Position angle for ellipse profiles.
+ -m, --measure=STR Measurement operator (mean, sigclip-mean, etc.).
+ -s, --sigmaclip=FLT,FLT Sigma-clip multiple and tolerance.
Output:
-k, --keeptmp Keep temporal/auxiliar files.
@@ -199,15 +199,15 @@ do
-R|--rmax) rmax="$2"; check_v
"$1" "$rmax"; shift;shift;;
-R=*|--rmax=*) rmax="${1#*=}"; check_v
"$1" "$rmax"; shift;;
-R*) rmax=$(echo "$1" | sed -e's/-R//'); check_v
"$1" "$rmax"; shift;;
- -Q|--qratio) qratio="$2"; check_v
"$1" "$qratio"; shift;shift;;
- -Q=*|--qratio=*) qratio="${1#*=}"; check_v
"$1" "$qratio"; shift;;
- -Q*) qratio=$(echo "$1" | sed -e's/-Q//'); check_v
"$1" "$qratio"; shift;;
- -p|--pangle) pangle="$2"; check_v
"$1" "$pangle"; shift;shift;;
- -p=*|--pangle=*) pangle="${1#*=}"; check_v
"$1" "$pangle"; shift;;
- -p*) pangle=$(echo "$1" | sed -e's/-p//'); check_v
"$1" "$pangle"; shift;;
- -m|--measure) measure="$2"; check_v
"$1" "$measure"; shift;shift;;
- -m=*|--measure=*) measure="${1#*=}"; check_v
"$1" "$measure"; shift;;
- -m*) measure=$(echo "$1" | sed -e's/-m//'); check_v
"$1" "$measure"; shift;;
+ -Q|--axisratio) axisratio="$2"; check_v
"$1" "$axisratio"; shift;shift;;
+ -Q=*|--axisratio=*) axisratio="${1#*=}"; check_v
"$1" "$axisratio"; shift;;
+ -Q*) axisratio=$(echo "$1" | sed -e's/-Q//'); check_v
"$1" "$axisratio"; shift;;
+ -p|--positionangle) positionangle="$2"; check_v
"$1" "$positionangle"; shift;shift;;
+ -p=*|--positionangle=*) positionangle="${1#*=}"; check_v
"$1" "$positionangle"; shift;;
+ -p*) positionangle=$(echo "$1" | sed -e's/-p//');
check_v "$1" "$positionangle"; shift;;
+ -m|--measure) measuretmp="$2"; check_v
"$1" "$measuretmp"; shift;shift;;
+ -m=*|--measure=*) measuretmp="${1#*=}"; check_v
"$1" "$measuretmp"; shift;;
+ -m*) measuretmp=$(echo "$1" | sed -e's/-m//'); check_v
"$1" "$measuretmp"; shift;;
-s|--sigmaclip) sigmaclip="$2"; check_v
"$1" "$sigmaclip"; shift;shift;;
-s=*|--sigmaclip=*) sigmaclip="${1#*=}"; check_v
"$1" "$sigmaclip"; shift;;
-s*) sigmaclip=$(echo "$1" | sed -e's/-s//'); check_v
"$1" "$sigmaclip"; shift;;
@@ -224,7 +224,7 @@ do
-o*) output=$(echo "$1" | sed -e's/-o//'); check_v "$1"
"$output"; shift;;
# Non-operating options.
- -q|--quiet) quiet=1; shift;;
+ -q|--quiet) quiet="--quiet"; shift;;
-q*|--quiet=*) on_off_option_error --quiet -q;;
-?|--help) print_help; exit 0;;
-'?'*|--help=*) on_off_option_error --help -?;;
@@ -240,22 +240,30 @@ do
# file name.
*) inputs="$1 $inputs"; shift;;
esac
+
+ # If a measurment was given, add it to possibly existing previous
+ # measurements into a comma-separate list.
+ if [ x"$measuretmp" != x ]; then
+ if [ x"$measure" = x ]; then measure=$measuretmp;
+ else measure="$measure,$measuretmp";
+ fi
+ fi
done
-# Basic sanity checks on arguments.
+# Basic sanity checks
+# ===================
+
+# If an input image is given at all.
if [ x"$inputs" = x ]; then
- echo "$scriptname: no input FITS files."
+ echo "$scriptname: no input FITS image files."
echo "Run with '--help' for more information on how to run."
exit 1
fi
-
-
-
# If one of X or Y are given the other also needs to be given.
if [ "z$xcenter" = zcenter ]; then
if ! [ "z$ycenter" = zcenter ]; then
@@ -269,6 +277,9 @@ else
fi
fi
+# If no specific measurement has been requested, use the mean.
+if [ x"$measure" = x ]; then measure=mean; fi
+
@@ -276,9 +287,10 @@ fi
# Convert center to image coordinates if necessary
# ------------------------------------------------
#
-# If the user provides specific coordinates in WCS (--mode=wcs), then convert
-# them to image mode so we can safely assume image coordianates from now on. To
-# do that, WCS information from the input header image is used.
+# If the user provides specific coordinates in WCS (--mode=wcs), then
+# convert them to image mode so we can safely assume image coordianates
+# from now on. To do that, WCS information from the input header image is
+# used.
if ! [ "z$xcenter" = zcenter ]; then
if [ $mode = wcs ]; then
xy=$(echo "$xcenter $ycenter" \
@@ -298,8 +310,8 @@ fi
#
# If the user does not set the x and y coordinates to be `center' (the
# coordinates of the object), then compute the center of the image for
-# constructing the profiles. Here, we are assuming that the object is already
-# centered on the input image.
+# constructing the profiles. Here, we are assuming that the object is
+# already centered on the input image.
#
# In the FITS standard, pixels are counted from 1, and the integers are in
# the center of the pixel. So after dividing the pixel size of the image by
@@ -316,7 +328,7 @@ fi
# Calculate the maximum radius
# ----------------------------
#
-# If the user set the --rmax parameter to `max', then compute the maximum
+# If the user didn't set the '--rmax' parameter, then compute the maximum
# radius possible on the image.
#
# If the user has not given any maximum radius, we give the most reliable
@@ -334,7 +346,7 @@ fi
# --------------
# 0 x X
#
-if [ "z$rmax" = zmax ]; then
+if [ x"$rmax" = x ]; then
rmax=$(astfits $inputs --hdu=$hdu \
| awk '/^NAXIS1/{X=$3} /^NAXIS2/{Y=$3} \
END{ x='$xcenter'; y='$ycenter'; \
@@ -351,17 +363,18 @@ fi
#
# Here, it is defined the final output file containing the radial profile.
# If the user has defined a specific path/name for the output, it will be
-# used for saving the output file. If the user does not specify a output name,
-# then a default value containing the center and mode will be generated.
+# used for saving the output file. If the user does not specify a output
+# name, then a default value containing the center and mode will be
+# generated.
bname_prefix=$(basename $inputs | sed 's/\.fits/ /' | awk '{print $1}')
defaultname=$(pwd)/"$bname_prefix"_rprofile_$mode"_$xcenter"_"$ycenter"
-if [ z$output = zdefault ]; then output="$defaultname.fits"; fi
+if [ x$output = x ]; then output="$defaultname.fits"; fi
-# Construct the temporal directory. If the user does not specify any directory,
-# then a default one with the base name of the input image will be constructed.
-# If the user set the directory, then make it. This directory will be deleted
-# at the end of the script if the user does not want to keep it (with the
-# `--keeptmp' option).
+# Construct the temporal directory. If the user does not specify any
+# directory, then a default one with the base name of the input image will
+# be constructed. If the user set the directory, then make it. This
+# directory will be deleted at the end of the script if the user does not
+# want to keep it (with the `--keeptmp' option).
if [ z$tmpdir = z ]; then tmpdir=$defaultname; fi
mkdir -p $tmpdir
@@ -372,24 +385,29 @@ mkdir -p $tmpdir
# Crop image
# ----------
#
-# Crop the input image around the desired point so we can continue processing
-# only on those pixels (we do not need the other pixels).
+# Crop the input image around the desired point so we can continue
+# processing only on those pixels (we do not need the other pixels).
#
-# The crop's output always has the range of pixels from the original image used
-# in the `ICF1PIX' keyword value. So, to find the new center (important if it
-# is sub-pixel precission), we can simply get the first and third value of that
-# string, and convert to the cropped coordinate system. Note that because FITS
-# pixel couting starts from 1, we need to subtract `1'.
+# The crop's output always has the range of pixels from the original image
+# used in the `ICF1PIX' keyword value. So, to find the new center
+# (important if it is sub-pixel precission), we can simply get the first
+# and third value of that string, and convert to the cropped coordinate
+# system. Note that because FITS pixel couting starts from 1, we need to
+# subtract `1'.
crop=$tmpdir/crop.fits
cropwidth=$(echo $rmax | awk '{print $1*2+1}')
astcrop $inputs --hdu=$hdu --center=$xcenter,$ycenter --mode=img \
- --width=$cropwidth --output=$crop
+ --width=$cropwidth --output=$crop $quiet
dxy=$(astfits $crop -h1 \
| grep ICF1PIX \
| sed -e"s/'/ /g" -e's/\:/ /g' -e's/,/ /' \
| awk '{print $3-1, $5-1}')
-xcenter=$(echo "$xcenter $cropwidth $dxy" | awk '{if($1>int($2/2)) print
$1-$3; else print int($2/2)+$1-int($1)}')
-ycenter=$(echo "$ycenter $cropwidth $dxy" | awk '{if($1>int($2/2)) print
$1-$4; else print int($2/2)+$1-int($1)}')
+xcenter=$(echo "$xcenter $cropwidth $dxy" \
+ | awk '{ if($1>int($2/2)) print $1-$3; \
+ else print int($2/2)+$1-int($1) }')
+ycenter=$(echo "$ycenter $cropwidth $dxy" \
+ | awk '{ if($1>int($2/2)) print $1-$4; \
+ else print int($2/2)+$1-int($1) }')
@@ -401,20 +419,51 @@ ycenter=$(echo "$ycenter $cropwidth $dxy" | awk
'{if($1>int($2/2)) print $1-$4;
# The apertures image is generated using MakeProfiles with the parameters
# specified in the echo statement:
-# rmax -- maximum radius value (in pixels)
-# xcenter -- X center position (in pixels).
-# ycenter -- Y center position (in pixels).
-# 7 -- type of the profiles (radial distance).
-# 1 -- the Sersic or Moffat index.
-# pangle -- position angle.
-# qratio -- axis ratio.
-# rmax -- magnitude of the profile within the truncation radius (rmax).
-# 1 -- Truncation in radius unit.
+# rmax -- maximum radius value (in pixels)
+# xcenter -- X center position (in pixels).
+# ycenter -- Y center position (in pixels).
+# 7 -- type of the profiles (radial distance).
+# 1 -- the Sersic or Moffat index.
+# positionangle -- position angle.
+# axisratio -- axis ratio.
+# rmax -- magnitude of the profile within the truncation radius
(rmax).
+# 1 -- Truncation in radius unit.
apertures=$tmpdir/apertures.fits
-echo "$rmax $xcenter $ycenter 7 $rmax 1 $pangle $qratio $rmax 1" \
+echo "$rmax $xcenter $ycenter 7 $rmax 1 $positionangle $axisratio $rmax 1" \
| astmkprof --background=$crop --backhdu=1 --mforflatpix \
--mode=img --clearcanvas --type=int16 \
- --circumwidth=1 --replace --output=$apertures
+ --circumwidth=1 --replace --output=$apertures \
+ $quiet
+
+
+
+
+
+# Extract each measurement column into a MakeCatalog option
+# ---------------------------------------------------------
+#
+# The user of this script gives each desired MakeCatalog option name as a
+# value to the '--measure' option here as a comma-separated list of
+# values. But we want to feed them into MakeCatalog (which needs each one
+# of them to be prefixed with '--' and separated by a space).
+finalmeasure=$(echo "$measure" \
+ | awk 'BEGIN{FS=","} \
+ END{for(i=1;i<=NF;++i) printf "--%s ", $i}')
+
+
+
+
+
+# Set the used sigma-clipping parameters
+# --------------------------------------
+#
+# If not given, don't use anything and just use MakeCatalog's default
+# values.
+if [ x"$sigmaclip" = x ]; then
+ finalsigmaclip=""
+else
+ finalsigmaclip="--sigmaclip=$sigmaclip";
+fi
@@ -423,11 +472,13 @@ echo "$rmax $xcenter $ycenter 7 $rmax 1 $pangle $qratio
$rmax 1" \
# Obtain the radial profile
# -------------------------
#
-# The radial profile is obtained using Catalog. In practice, what is done is to
-# obtain a catalogue using the segmentation image previously generated (the
-# elliptical apertures) and the original input image for measuring the values.
+# The radial profile is obtained using MakeCatalog. In practice, we obtain
+# a catalogue using the segmentation image previously generated (the
+# elliptical apertures) and the original input image for measuring the
+# values.
astmkcatalog $apertures -h1 --valuesfile=$crop --valueshdu=1 \
- --ids $measure --sigmaclip=$sigmaclip --output=$output
+ --ids $finalmeasure $finalsigmaclip --output=$output \
+ $quiet
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 548eefa..8a8b412 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -202,6 +202,7 @@ To go to the sections or subsections, you have to click on
the menu entries that
* Data analysis:: Analyze images.
* Modeling and fittings:: Make and fit models.
* High-level calculations:: Physical calculations.
+* Installed scripts:: Installed scripts that operate like programs.
* Library:: Gnuastro's library of useful functions.
* Developing:: The development environment.
* Gnuastro programs list:: List and short summary of Gnuastro.
@@ -328,7 +329,6 @@ Common program behavior
* Command-line:: How to use the command-line.
* Configuration files:: Values for unspecified variables.
* Getting help:: Getting more information on the go.
-* Installed scripts:: Installed Bash scripts, not compiled programs.
* Multi-threaded operations:: How threads are managed in Gnuastro.
* Numeric data types:: Different types and how to specify them.
* Memory management:: How memory is allocated (in RAM or HDD/SSD).
@@ -481,9 +481,6 @@ Data analysis
* Segment:: Segment detections based on signal structure.
* MakeCatalog:: Catalog from input and labeled images.
* Match:: Match two datasets.
-* Sort FITS files by night:: Sort and classify images in separate nights.
-* SAO DS9 region files from table:: Table's positional columns into DS9
region file.
-* Generate radial profile:: Generate the radial profile of a target.
Statistics
@@ -544,18 +541,6 @@ Match
* Invoking astmatch:: Inputs, outputs and options of Match
-Sort FITS files by night
-
-* Invoking astscript-sort-by-night:: Inputs and outputs to this script.
-
-SAO DS9 region files from table
-
-* Invoking astscript-make-ds9-reg:: How to call astscript-make-ds9-reg
-
-Generate radial profile
-
-* Invoking astscript-radial-profile:: How to call astscript-radial-profile
-
Modeling and fitting
* MakeProfiles:: Making mock galaxies and stars.
@@ -613,6 +598,24 @@ Invoking CosmicCalculator
* CosmicCalculator basic cosmology calculations:: Like distance modulus,
distances and etc.
* CosmicCalculator spectral line calculations:: How they get affected by
redshift.
+Installed scripts
+
+* Sort FITS files by night:: Sort many files by date.
+* SAO DS9 region files from table:: Create ds9 region file from a table.
+* Generate radial profile:: Radial profile of an object in an image.
+
+Sort FITS files by night
+
+* Invoking astscript-sort-by-night:: Inputs and outputs to this script.
+
+SAO DS9 region files from table
+
+* Invoking astscript-make-ds9-reg:: How to call astscript-make-ds9-reg
+
+Generate radial profile
+
+* Invoking astscript-radial-profile:: How to call astscript-radial-profile
+
Library
* Review of library fundamentals:: Guide on libraries and linking.
@@ -6521,7 +6524,6 @@ When the output is a FITS file, all the programs also
store some very useful inf
* Command-line:: How to use the command-line.
* Configuration files:: Values for unspecified variables.
* Getting help:: Getting more information on the go.
-* Installed scripts:: Installed Bash scripts, not compiled programs.
* Multi-threaded operations:: How threads are managed in Gnuastro.
* Numeric data types:: Different types and how to specify them.
* Memory management:: How memory is allocated (in RAM or HDD/SSD).
@@ -7416,7 +7418,7 @@ The prefix of @file{/usr/local/} is conventionally used
for programs you install
-@node Getting help, Installed scripts, Configuration files, Common program
behavior
+@node Getting help, Multi-threaded operations, Configuration files, Common
program behavior
@section Getting help
@cindex Help
@@ -7668,75 +7670,7 @@ We have other mailing lists and tools for those
purposes, see @ref{Report a bug}
-
-
-
-
-
-@node Installed scripts, Multi-threaded operations, Getting help, Common
program behavior
-@section Installed scripts
-
-Gnuastro's programs (introduced in previous chapters) are designed to be
highly modular and thus mainly contain lower-level operations on the data.
-However, in many contexts, higher-level operations (for example a sequence of
calls to multiple Gnuastro programs, or a special way of running a program and
using the outputs) are also very similar between various projects.
-
-To facilitate data analysis on these higher-level steps also, Gnuastro also
installs some scripts on your system with the (@code{astscript-}) prefix (in
contrast to the other programs that only have the @code{ast} prefix).
-
-@cindex GNU Bash
-Like all of Gnuastro's source code, these scripts are also heavily commented.
-They are written in GNU Bash, which doesn't need compilation.
-Therefore, if you open the installed scripts in a text editor, you can
actually read them@footnote{Gnuastro's installed programs (those only starting
with @code{ast}) aren't human-readable.
-They are written in C and are thus compiled (optimized in binary CPU
instructions that will be given directly to your CPU).
-Because they don't need an interpreter like Bash on every run, they are much
faster and more independent than scripts.
-To read the source code of the programs, look into the @file{bin/progname}
directory of Gnuastro's source (@ref{Downloading the source}).
-If you would like to read more about why C was chosen for the programs, please
see @ref{Why C}.}.
-Bash is the same language that is mainly used when typing on the command-line.
-Because of these factors, Bash is much more widely known and used than C (the
language of other Gnuastro programs).
-Gnuastro's installed scripts also do higher-level operations, so customizing
these scripts for a special project will be more common than the programs.
-You can always inspect them (to customize, check, or educate your self) with
this command (just replace @code{emacs} with your favorite text editor):
-
-@example
-$ emacs $(which astscript-NAME)
-@end example
-
-These scripts also accept options and are in many ways similar to the programs
(see @ref{Common options}) with some minor differences:
-
-@itemize
-@item
-Currently they don't accept configuration files themselves.
-However, the configuration files of the Gnuastro programs they call are indeed
parsed and used by those programs.
-
-As a result, they don't have the following options: @option{--checkconfig},
@option{--config}, @option{--lastconfig}, @option{--onlyversion},
@option{--printparams}, @option{--setdirconf} and @option{--setusrconf}.
-
-@item
-They don't directly allocate any memory, so there is no @option{--minmapsize}.
-
-@item
-They don't have an independent @option{--usage} option: when called with
@option{--usage}, they just recommend running @option{--help}.
-
-@item
-The output of @option{--help} is not configurable like the programs (see
@ref{--help}).
-
-@item
-@cindex GNU AWK
-@cindex GNU SED
-The scripts will commonly use your installed Bash and other basic command-line
tools (for example AWK or SED).
-Different systems have different versions and implementations of these basic
tools (for example GNU/Linux systems use GNU AWK and GNU SED which are far more
advanced and up to date then the minimalist AWK and SED of most other systems).
-Therefore, unexpected errors in these tools might come up when you run these
scripts.
-We will try our best to write these scripts in a portable way.
-However, if you do confront such strange errors, please submit a bug report so
we fix it (see @ref{Report a bug}).
-
-@end itemize
-
-
-
-
-
-
-
-
-
-
-@node Multi-threaded operations, Numeric data types, Installed scripts, Common
program behavior
+@node Multi-threaded operations, Numeric data types, Getting help, Common
program behavior
@section Multi-threaded operations
@pindex nproc
@@ -14124,9 +14058,6 @@ For example getting general or specific statistics of
the dataset (with @ref{Sta
* Segment:: Segment detections based on signal structure.
* MakeCatalog:: Catalog from input and labeled images.
* Match:: Match two datasets.
-* Sort FITS files by night:: Sort and classify images in separate nights.
-* SAO DS9 region files from table:: Table's positional columns into DS9
region file.
-* Generate radial profile:: Generate the radial profile of a target.
@end menu
@node Statistics, NoiseChisel, Data analysis, Data analysis
@@ -17801,7 +17732,7 @@ For random measurements on any area, please use the
upper-limit columns of MakeC
-@node Match, Sort FITS files by night, MakeCatalog, Data analysis
+@node Match, , MakeCatalog, Data analysis
@section Match
Data can come come from different telescopes, filters, software and even
different configurations for a single software.
@@ -18061,2599 +17992,2694 @@ The last three are the three Euler angles in
units of degrees in the ZXZ order a
-@node Sort FITS files by night, SAO DS9 region files from table, Match, Data
analysis
-@section Sort FITS files by night
+@node Modeling and fittings, High-level calculations, Data analysis, Top
+@chapter Modeling and fitting
-@cindex Calendar
-FITS images usually contain (several) keywords for preserving important dates.
-In particular, for lower-level data, this is usually the observation date and
time (for example, stored in the @code{DATE-OBS} keyword value).
-When analyzing observed datasets, many calibration steps (like the dark, bias
or flat-field), are commonly calculated on a per-observing-night basis.
+@cindex Fitting
+@cindex Modeling
+In order to fully understand observations after initial analysis on the image,
it is very important to compare them with the existing models to be able to
further understand both the models and the data.
+The tools in this chapter create model galaxies and will provide 2D fittings
to be able to understand the detections.
-However, the FITS standard's date format (@code{YYYY-MM-DDThh:mm:ss.ddd}) is
based on the western (Gregorian) calendar.
-Dates that are stored in this format are complicated for automatic processing:
a night starts in the final hours of one calendar day, and extends to the early
hours of the next calendar day.
-As a result, to identify datasets from one night, we commonly need to search
for two dates.
-However calendar peculiarities can make this identification very difficult.
-For example when an observation is done on the night separating two months
(like the night starting on March 31st and going into April 1st), or two years
(like the night starting on December 31st 2018 and going into January 1st,
2019).
-To account for such situations, it is necessary to keep track of how many days
are in a month, and leap years, etc.
+@menu
+* MakeProfiles:: Making mock galaxies and stars.
+* MakeNoise:: Make (add) noise to an image.
+@end menu
-@cindex Unix epoch time
-@cindex Time, Unix epoch
-@cindex Epoch, Unix time
-Gnuastro's @file{astscript-sort-by-night} script is created to help in such
important scenarios.
-It uses @ref{Fits} to convert the FITS date format into the Unix epoch time
(number of seconds since 00:00:00 of January 1st, 1970), using the
@option{--datetosec} option.
-The Unix epoch time is a single number (integer, if not given in sub-second
precision), enabling easy comparison and sorting of dates after January 1st,
1970.
-You can use this script as a basis for making a much more highly customized
sorting script.
-Here are some examples
-@itemize
+
+@node MakeProfiles, MakeNoise, Modeling and fittings, Modeling and fittings
+@section MakeProfiles
+
+@cindex Checking detection algorithms
+@pindex @r{MakeProfiles (}astmkprof@r{)}
+MakeProfiles will create mock astronomical profiles from a catalog, either
individually or together in one output image.
+In data analysis, making a mock image can act like a calibration tool, through
which you can test how successfully your detection technique is able to detect
a known set of objects.
+There are commonly two aspects to detecting: the detection of the fainter
parts of bright objects (which in the case of galaxies fade into the noise very
slowly) or the complete detection of an over-all faint object.
+Making mock galaxies is the most accurate (and idealistic) way these two
aspects of a detection algorithm can be tested.
+You also need mock profiles in fitting known functional profiles with
observations.
+
+MakeProfiles was initially built for extra galactic studies, so currently the
only astronomical objects it can produce are stars and galaxies.
+We welcome the simulation of any other astronomical object.
+The general outline of the steps that MakeProfiles takes are the following:
+
+@enumerate
+
@item
-If you need to copy the files, but only need a single extension (not the whole
file), you can add a step just before the making of the symbolic links, or
copies, and change it to only copy a certain extension of the FITS file using
the Fits program's @option{--copy} option, see @ref{HDU information and
manipulation}.
+Build the full profile out to its truncation radius in a possibly over-sampled
array.
@item
-If you need to classify the files with finer detail (for example the purpose
of the dataset), you can add a step just before the making of the symbolic
links, or copies, to specify a file-name prefix based on other certain keyword
values in the files.
-For example when the FITS files have a keyword to specify if the dataset is a
science, bias, or flat-field image.
-You can read it and to add a @code{sci-}, @code{bias-}, or @code{flat-} to the
created file (after the @option{--prefix}) automatically.
+Multiply all the elements by a fixed constant so its total magnitude equals
the desired total magnitude.
-For example, let's assume the observing mode is stored in the hypothetical
@code{MODE} keyword, which can have three values of @code{BIAS-IMAGE},
@code{SCIENCE-IMAGE} and @code{FLAT-EXP}.
-With the step below, you can generate a mode-prefix, and add it to the
generated link/copy names (just correct the filename and extension of the first
line to the script's variables):
+@item
+If @option{--individual} is called, save the array for each profile to a FITS
file.
-@example
-modepref=$(astfits infile.fits -h1 \
- | sed -e"s/'/ /g" \
- | awk '$1=="MODE"@{ \
- if($3=="BIAS-IMAGE") print "bias-"; \
- else if($3=="SCIENCE-IMAGE") print "sci-"; \
- else if($3==FLAT-EXP) print "flat-"; \
- else print $3, "NOT recognized"; exit 1@}')
-@end example
+@item
+If @option{--nomerged} is not called, add the overlapping pixels of all the
created profiles to the output image and abort.
-@cindex GNU AWK
-@cindex GNU Sed
-Here is a description of it.
-We first use @command{astfits} to print all the keywords in extension @code{1}
of @file{infile.fits}.
-In the FITS standard, string values (that we are assuming here) are placed in
single quotes (@key{'}) which are annoying in this context/use-case.
-Therefore, we pipe the output of @command{astfits} into @command{sed} to
remove all such quotes (substituting them with a blank space).
-The result is then piped to AWK for giving us the final mode-prefix: with
@code{$1=="MODE"}, we ask AWK to only consider the line where the first column
is @code{MODE}.
-There is an equal sign between the key name and value, so the value is the
third column (@code{$3} in AWK).
-We thus use a simple @code{if-else} structure to look into this value and
print our custom prefix based on it.
-The output of AWK is then stored in the @code{modepref} shell variable which
you can add to the link/copy name.
+@end enumerate
-With the solution above, the increment of the file counter for each night will
be independent of the mode.
-If you want the counter to be mode-dependent, you can add a different counter
for each mode and use that counter instead of the generic counter for each
night (based on the value of @code{modepref}).
-But we'll leave the implementation of this step to you as an exercise.
+Using input values, MakeProfiles adds the World Coordinate System (WCS)
headers of the FITS standard to all its outputs (except PSF images!).
+For a simple test on a set of mock galaxies in one image, there is no need for
the third step or the WCS information.
-@end itemize
+@cindex Transform image
+@cindex Lensing simulations
+@cindex Image transformations
+However in complicated simulations like weak lensing simulations, where each
galaxy undergoes various types of individual transformations based on their
position, those transformations can be applied to the different individual
images with other programs.
+After all the transformations are applied, using the WCS information in each
individual profile image, they can be merged into one output image for
convolution and adding noise.
@menu
-* Invoking astscript-sort-by-night:: Inputs and outputs to this script.
+* Modeling basics:: Astronomical modeling basics.
+* If convolving afterwards:: Considerations for convolving later.
+* Brightness flux magnitude:: About these measures of energy.
+* Profile magnitude:: Definition of total profile magnitude.
+* Invoking astmkprof:: Inputs and Options for MakeProfiles.
@end menu
-@node Invoking astscript-sort-by-night, , Sort FITS files by night, Sort FITS
files by night
-@subsection Invoking astscript-sort-by-night
-This installed script will read a FITS date formatted value from the given
keyword, and classify the input FITS files into individual nights.
-For more on installed scripts please see (see @ref{Installed scripts}).
-This script can be used with the following general template:
-@example
-$ astscript-sort-by-night [OPTION...] FITS-files
-@end example
+@node Modeling basics, If convolving afterwards, MakeProfiles, MakeProfiles
+@subsection Modeling basics
-@noindent
-One line examples:
+In the subsections below, first a review of some very basic information and
concepts behind modeling a real astronomical image is given.
+You can skip this subsection if you are already sufficiently familiar with
these concepts.
-@example
-## Use the DATE-OBS keyword
-$ astscript-sort-by-night --key=DATE-OBS /path/to/data/*.fits
+@menu
+* Defining an ellipse and ellipsoid:: Definition of these important shapes.
+* PSF:: Radial profiles for the PSF.
+* Stars:: Making mock star profiles.
+* Galaxies:: Radial profiles for galaxies.
+* Sampling from a function:: Sample a function on a pixelated canvas.
+* Oversampling:: Oversampling the model.
+@end menu
-## Make links to the input files with the `img-' prefix
-$ astscript-sort-by-night --link --prefix=img- /path/to/data/*.fits
-@end example
+@node Defining an ellipse and ellipsoid, PSF, Modeling basics, Modeling basics
+@subsubsection Defining an ellipse and ellipsoid
-This script will look into a HDU/extension (@option{--hdu}) for a keyword
(@option{--key}) in the given FITS files and interpret the value as a date.
-The inputs will be separated by "night"s (11:00a.m to next day's 10:59:59a.m,
spanning two calendar days, exact hour can be set with @option{--hour}).
+@cindex Ellipse
+@cindex Axis ratio
+@cindex Position angle
+The PSF, see @ref{PSF}, and galaxy radial profiles are generally defined on an
ellipse.
+Therefore, in this section we'll start defining an ellipse on a pixelated 2D
surface.
+Labeling the major axis of an ellipse @mymath{a}, and its minor axis with
@mymath{b}, the @emph{axis ratio} is defined as: @mymath{q\equiv b/a}.
+The major axis of an ellipse can be aligned in any direction, therefore the
angle of the major axis with respect to the horizontal axis of the image is
defined to be the @emph{position angle} of the ellipse and in this book, we
show it with @mymath{\theta}.
-The default output is a list of all the input files along with the following
two columns: night number and file number in that night (sorted by time).
-With @option{--link} a symbolic link will be made (one for each input) that
contains the night number, and number of file in that night (sorted by time),
see the description of @option{--link} for more.
-When @option{--copy} is used instead of a link, a copy of the inputs will be
made instead of symbolic link.
+@cindex Radial profile on ellipse
+Our aim is to put a radial profile of any functional form @mymath{f(r)} over
an ellipse.
+Hence we need to associate a radius/distance to every point in space.
+Let's define the radial distance @mymath{r_{el}} as the distance on the major
axis to the center of an ellipse which is located at @mymath{i_c} and
@mymath{j_c} (in other words @mymath{r_{el}\equiv{a}}).
+We want to find @mymath{r_{el}} of a point located at @mymath{(i,j)} (in the
image coordinate system) from the center of the ellipse with axis ratio
@mymath{q} and position angle @mymath{\theta}.
+First the coordinate system is rotated@footnote{Do not confuse the signs of
@mymath{sin} with the rotation matrix defined in @ref{Warping basics}.
+In that equation, the point is rotated, here the coordinates are rotated and
the point is fixed.} by @mymath{\theta} to get the new rotated coordinates of
that point @mymath{(i_r,j_r)}:
-Below you can see one example where all the @file{target-*.fits} files in the
@file{data} directory should be separated by observing night according to the
@code{DATE-OBS} keyword value in their second extension (number @code{1},
recall that HDU counting starts from 0).
-You can see the output after the @code{ls} command.
+@dispmath{i_r(i,j)=+(i_c-i)\cos\theta+(j_c-j)\sin\theta}
+@dispmath{j_r(i,j)=-(i_c-i)\sin\theta+(j_c-j)\cos\theta}
-@example
-$ astscript-sort-by-night -pimg- -h1 -kDATE-OBS data/target-*.fits
-$ ls
-img-n1-1.fits img-n1-2.fits img-n2-1.fits ...
-@end example
+@cindex Elliptical distance
+@noindent Recall that an ellipse is defined by @mymath{(i_r/a)^2+(j_r/b)^2=1}
and that we defined @mymath{r_{el}\equiv{a}}.
+Hence, multiplying all elements of the ellipse definition with
@mymath{r_{el}^2} we get the elliptical distance at this point point located:
@mymath{r_{el}=\sqrt{i_r^2+(j_r/q)^2}}.
+To place the radial profiles explained below over an ellipse,
@mymath{f(r_{el})} is calculated based on the functional radial profile desired.
-The outputs can be placed in a different (already existing) directory by
including that directory's name in the @option{--prefix} value, for example
@option{--prefix=sorted/img-} will put them all under the @file{sorted}
directory.
+@cindex Ellipsoid
+@cindex Euler angles
+An ellipse in 3D, or an @url{https://en.wikipedia.org/wiki/Ellipsoid,
ellipsoid}, can be defined following similar principles as before.
+Labeling the major (largest) axis length as @mymath{a}, the second and third
(in a right-handed coordinate system) axis lengths can be labeled as @mymath{b}
and @mymath{c}.
+Hence we have two axis ratios: @mymath{q_1\equiv{b/a}} and
@mymath{q_2\equiv{c/a}}.
+The orientation of the ellipsoid can be defined from the orientation of its
major axis.
+There are many ways to define 3D orientation and order matters.
+So to be clear, here we use the ZXZ (or @mymath{Z_1X_2Z_3}) proper
@url{https://en.wikipedia.org/wiki/Euler_angles, Euler angles} to define the 3D
orientation.
+In short, when a point is rotated in this order, we first rotate it around the
Z axis (third axis) by @mymath{\alpha}, then about the (rotated) X axis by
@mymath{\beta} and finally about the (rotated) Z axis by @mymath{\gamma}.
-This script can be configured like all Gnuastro's programs (through
command-line options, see @ref{Common options}), with some minor differences
that are described in @ref{Installed scripts}.
-The particular options to this script are listed below:
+Following the discussion in @ref{Merging multiple warpings}, we can define the
full rotation with the following matrix multiplication.
+However, here we are rotating the coordinates, not the point.
+Therefore, both the rotation angles and rotation order are reversed.
+We are also not using homogeneous coordinates (see @ref{Warping basics}) since
we aren't concerned with translation in this context:
-@table @option
-@item -h STR
-@itemx --hdu=STR
-The HDU/extension to use in all the given FITS files.
-All of the given FITS files must have this extension.
-
-@item -k STR
-@itemx --key=STR
-The keyword name that contains the FITS date format to classify/sort by.
-
-@item -H FLT
-@itemx --hour=FLT
-The hour that defines the next ``night''.
-By default, all times before 11:00a.m are considered to belong to the previous
calendar night.
-If a sub-hour value is necessary, it should be given in units of hours, for
example @option{--hour=9.5} corresponds to 9:30a.m.
+@dispmath{\left[\matrix{i_r\cr j_r\cr k_r}\right] =
+ \left[\matrix{cos\gamma&sin\gamma&0\cr -sin\gamma&cos\gamma&0\cr
0&0&1}\right]
+ \left[\matrix{1&0&0\cr 0&cos\beta&sin\beta\cr
0&-sin\beta&cos\beta }\right]
+ \left[\matrix{cos\alpha&sin\alpha&0\cr -sin\alpha&cos\alpha&0\cr
0&0&1}\right]
+ \left[\matrix{i_c-i\cr j_c-j\cr k_c-k}\right] }
-@cartouche
@noindent
-@cindex Time zone
-@cindex UTC (Universal time coordinate)
-@cindex Universal time coordinate (UTC)
-@strong{Dealing with time zones:}
-The time that is recorded in @option{--key} may be in UTC (Universal Time
Coordinate).
-However, the organization of the images taken during the night depends on the
local time.
-It is possible to take this into account by setting the @option{--hour} option
to the local time in UTC.
+Recall that an ellipsoid can be characterized with
+@mymath{(i_r/a)^2+(j_r/b)^2+(k_r/c)^2=1}, so similar to before
+(@mymath{r_{el}\equiv{a}}), we can find the ellipsoidal radius at pixel
+@mymath{(i,j,k)} as: @mymath{r_{el}=\sqrt{i_r^2+(j_r/q_1)^2+(k_r/q_2)^2}}.
-For example, consider a set of images taken in Auckland (New Zealand, UTC+12)
during different nights.
-If you want to classify these images by night, you have to know at which time
(in UTC time) the Sun rises (or any other separator/definition of a different
night).
-For example if your observing night finishes before 9:00a.m in Auckland, you
can use @option{--hour=21}.
-Because in Auckland the local time of 9:00 corresponds to 21:00 UTC.
-@end cartouche
+@cindex Breadth first search
+@cindex Inside-out construction
+@cindex Making profiles pixel by pixel
+@cindex Pixel by pixel making of profiles
+MakeProfiles builds the profile starting from the nearest element (pixel in an
image) in the dataset to the profile center.
+The profile value is calculated for that central pixel using monte carlo
integration, see @ref{Sampling from a function}.
+The next pixel is the next nearest neighbor to the central pixel as defined by
@mymath{r_{el}}.
+This process goes on until the profile is fully built upto the truncation
radius.
+This is done fairly efficiently using a breadth first parsing
strategy@footnote{@url{http://en.wikipedia.org/wiki/Breadth-first_search}}
which is implemented through an ordered linked list.
-@item -l
-@itemx --link
-Create a symbolic link for each input FITS file.
-This option cannot be used with @option{--copy}.
-The link will have a standard name in the following format (variable parts are
written in @code{CAPITAL} letters and described after it):
+Using this approach, we build the profile by expanding the circumference.
+Not one more extra pixel has to be checked (the calculation of @mymath{r_{el}}
from above is not cheap in CPU terms).
+Another consequence of this strategy is that extending MakeProfiles to three
dimensions becomes very simple: only the neighbors of each pixel have to be
changed.
+Everything else after that (when the pixel index and its radial profile have
entered the linked list) is the same, no matter the number of dimensions we are
dealing with.
-@example
-PnN-I.fits
-@end example
-@table @code
-@item P
-This is the value given to @option{--prefix}.
-By default, its value is @code{./} (to store the links in the directory this
script was run in).
-See the description of @code{--prefix} for more.
-@item N
-This is the night-counter: starting from 1.
-@code{N} is just incremented by 1 for the next night, no matter how many
nights (without any dataset) there are between two subsequent observing nights
(its just an identifier for each night which you can easily map to different
calendar nights).
-@item I
-File counter in that night, sorted by time.
-@end table
-@item -c
-@itemx --copy
-Make a copy of each input FITS file with the standard naming convention
described in @option{--link}.
-With this option, instead of making a link, a copy is made.
-This option cannot be used with @option{--link}.
-@item -p STR
-@itemx --prefix=STR
-Prefix to append before the night-identifier of each newly created link or
copy.
-This option is thus only relevant with the @option{--copy} or @option{--link}
options.
-See the description of @option{--link} for how its used.
-For example, with @option{--prefix=img-}, all the created file names in the
current directory will start with @code{img-}, making outputs like
@file{img-n1-1.fits} or @file{img-n3-42.fits}.
-@option{--prefix} can also be used to store the links/copies in another
directory relative to the directory this script is being run (it must already
exist).
-For example @code{--prefix=/path/to/processing/img-} will put all the
links/copies in the @file{/path/to/processing} directory, and the files (in
that directory) will all start with @file{img-}.
-@end table
+@node PSF, Stars, Defining an ellipse and ellipsoid, Modeling basics
+@subsubsection Point spread function
+@cindex PSF
+@cindex Point source
+@cindex Diffraction limited
+@cindex Point spread function
+@cindex Spread of a point source
+Assume we have a `point' source, or a source that is far smaller than the
maximum resolution (a pixel).
+When we take an image of it, it will `spread' over an area.
+To quantify that spread, we can define a `function'.
+This is how the point spread function or the PSF of an image is defined.
+This `spread' can have various causes, for example in ground based astronomy,
due to the atmosphere.
+In practice we can never surpass the `spread' due to the diffraction of the
lens aperture.
+Various other effects can also be quantified through a PSF.
+For example, the simple fact that we are sampling in a discrete space, namely
the pixels, also produces a very small `spread' in the image.
+@cindex Blur image
+@cindex Convolution
+@cindex Image blurring
+@cindex PSF image size
+Convolution is the mathematical process by which we can apply a `spread' to an
image, or in other words blur the image, see @ref{Convolution process}.
+The Brightness of an object should remain unchanged after convolution, see
@ref{Brightness flux magnitude}.
+Therefore, it is important that the sum of all the pixels of the PSF be unity.
+The PSF image also has to have an odd number of pixels on its sides so one
pixel can be defined as the center.
+In MakeProfiles, the PSF can be set by the two methods explained below.
+@table @asis
+@item Parametric functions
+@cindex FWHM
+@cindex PSF width
+@cindex Parametric PSFs
+@cindex Full Width at Half Maximum
+A known mathematical function is used to make the PSF.
+In this case, only the parameters to define the functions are necessary and
MakeProfiles will make a PSF based on the given parameters for each function.
+In both cases, the center of the profile has to be exactly in the middle of
the central pixel of the PSF (which is automatically done by MakeProfiles).
+When talking about the PSF, usually, the full width at half maximum or FWHM is
used as a scale of the width of the PSF.
+@table @cite
+@item Gaussian
+@cindex Gaussian distribution
+In the older papers, and to a lesser extent even today, some researchers use
the 2D Gaussian function to approximate the PSF of ground based images.
+In its most general form, a Gaussian function can be written as:
+@dispmath{f(r)=a \exp \left( -(x-\mu)^2 \over 2\sigma^2 \right)+d}
+Since the center of the profile is pre-defined, @mymath{\mu} and @mymath{d}
are constrained.
+@mymath{a} can also be found because the function has to be normalized.
+So the only important parameter for MakeProfiles is the @mymath{\sigma}.
+In the Gaussian function we have this relation between the FWHM and
@mymath{\sigma}:
+@cindex Gaussian FWHM
+@dispmath{\rm{FWHM}_g=2\sqrt{2\ln{2}}\sigma \approx 2.35482\sigma}
+@item Moffat
+@cindex Moffat function
+The Gaussian profile is much sharper than the images taken from stars on
photographic plates or CCDs.
+Therefore in 1969, Moffat proposed this functional form for the image of stars:
+@dispmath{f(r)=a \left[ 1+\left( r\over \alpha \right)^2 \right]^{-\beta}}
+@cindex Moffat beta
+Again, @mymath{a} is constrained by the normalization, therefore two
parameters define the shape of the Moffat function: @mymath{\alpha} and
@mymath{\beta}.
+The radial parameter is @mymath{\alpha} which is related to the FWHM by
+@cindex Moffat FWHM
+@dispmath{\rm{FWHM}_m=2\alpha\sqrt{2^{1/\beta}-1}}
+@cindex Compare Moffat and Gaussian
+@cindex PSF, Moffat compared Gaussian
+@noindent
+Comparing with the PSF predicted from atmospheric turbulence theory with a
Moffat function, Trujillo et al.@footnote{
+Trujillo, I., J. A. L. Aguerri, J. Cepa, and C. M. Gutierrez (2001). ``The
effects of seeing on S@'ersic profiles - II. The Moffat PSF''. In: MNRAS 328,
pp. 977---985.}
+claim that @mymath{\beta} should be 4.765.
+They also show how the Moffat PSF contains the Gaussian PSF as a limiting case
when @mymath{\beta\to\infty}.
+@end table
+@item An input FITS image
+An input image file can also be specified to be used as a PSF.
+If the sum of its pixels are not equal to 1, the pixels will be multiplied by
a fraction so the sum does become 1.
+@end table
+While the Gaussian is only dependent on the FWHM, the Moffat function is also
dependent on @mymath{\beta}.
+Comparing these two functions with a fixed FWHM gives the following results:
+@itemize
+@item
+Within the FWHM, the functions don't have significant differences.
+@item
+For a fixed FWHM, as @mymath{\beta} increases, the Moffat function becomes
sharper.
+@item
+The Gaussian function is much sharper than the Moffat functions, even when
@mymath{\beta} is large.
+@end itemize
-@node SAO DS9 region files from table, Generate radial profile, Sort FITS
files by night, Data analysis
-@section SAO DS9 region files from table
-Once your desired catalog (containing the positions of some objects) is
created (for example with @ref{MakeCatalog}, @ref{Match}, or @ref{Table}) it
often happens that you want to see your selected objects on an image for a
feeling of the spatial properties of your objects.
-For example you want to see their positions relative to each other.
-In this section we describe a simple installed script that is provided within
Gnuastro for converting your given columns to an SAO DS9 region file to help in
this process.
-SAO DS9@footnote{@url{https://sites.google.com/cfa.harvard.edu/saoimageds9}}
is one of the most common FITS image vizualization tools in astronomy and is
free software.
+@node Stars, Galaxies, PSF, Modeling basics
+@subsubsection Stars
-@menu
-* Invoking astscript-make-ds9-reg:: How to call astscript-make-ds9-reg
-@end menu
+@cindex Modeling stars
+@cindex Stars, modeling
+In MakeProfiles, stars are generally considered to be a point source.
+This is usually the case for extra galactic studies, were nearby stars are
also in the field.
+Since a star is only a point source, we assume that it only fills one pixel
prior to convolution.
+In fact, exactly for this reason, in astronomical images the light profiles of
stars are one of the best methods to understand the shape of the PSF and a very
large fraction of scientific research is preformed by assuming the shapes of
stars to be the PSF of the image.
-@node Invoking astscript-make-ds9-reg, , SAO DS9 region files from table, SAO
DS9 region files from table
-@subsection Invoking astscript-make-ds9-reg
-This installed script will read two positional columns within an input table
and generate an SAO DS9 region file to visualize the position of the given
objects over an image.
-For more on installed scripts please see (see @ref{Installed scripts}).
-This script can be used with the following general template:
-@example
-## Use the RA and DEC columns of 'table.fits' for the region file.
-$ astscript-make-ds9-reg table.fits --column=RA,DEC \
- --output=ds9.reg
-## Select objects with a magnitude between 18 to 20, and generate the
-## region file directly (through a pipe), each region with radius of
-## 0.5 arcseconds.
-$ asttable table.fits --range=MAG,18:20 --column=RA,DEC \
- | astscript-make-ds9-reg --column=1,2 --radius=0.5
-## With the first command, select objects with a magnitude of 25 to 26
-## as red regions in 'bright.reg'. With the second command, select
-## objects with a magnitude between 28 to 29 as a green region and
-## show both.
-$ asttable cat.fits --range=MAG_F160W,25:26 -cRA,DEC \
- | ./astscript-make-ds9-reg -c1,2 --color=red -obright.reg
-$ asttable cat.fits --range=MAG_F160W,28:29 -cRA,DEC \
- | ./astscript-make-ds9-reg -c1,2 --color=green \
- --command="ds9 image.fits -regions bright.reg"
-@end example
+@node Galaxies, Sampling from a function, Stars, Modeling basics
+@subsubsection Galaxies
-The input can either be passed as a named file, or from standard input (a
pipe).
-Only the @option{--column} option is mandatory (to specify the input table
columns): two colums from the input table must be specified, either by name
(recommended) or number.
-You can optionally also specify the region's radius, width and color of the
regions with the @option{--radius}, @option{--width} and @option{--color}
options, otherwise default values will be used for these (described under each
option).
+@cindex Galaxy profiles
+@cindex S@'ersic profile
+@cindex Profiles, galaxies
+@cindex Generalized de Vaucouleur profile
+Today, most practitioners agree that the flux of galaxies can be modeled with
one or a few generalized de Vaucouleur's (or S@'ersic) profiles.
-The created region file will be written into the file name given to
@option{--output}.
-When @option{--output} isn't called, the default name of @file{ds9.reg} will
be used (in the running directory).
-If the file exists before calling this script, it will be overwritten, unless
you pass the @option{--dontdelete} option.
-Optionally you can also use the @option{--command} option to give the full
command that should be run to execute SAO DS9 (see example above and
description below).
-In this mode, the created region file will be deleted once DS9 is closed
(unless you pass the @option{--dontdelete} option).
-A full description of each option is given below.
+@dispmath{I(r) = I_e \exp \left ( -b_n \left[ \left( r \over r_e \right)^{1/n}
-1 \right] \right )}
-@table @option
+@cindex Brightness
+@cindex S@'ersic, J. L.
+@cindex S@'ersic index
+@cindex Effective radius
+@cindex Radius, effective
+@cindex de Vaucouleur profile
+@cindex G@'erard de Vaucouleurs
+G@'erard de Vaucouleurs (1918-1995) was first to show in 1948 that this
function resembles the galaxy light profiles, with the only difference that he
held @mymath{n} fixed to a value of 4.
+Twenty years later in 1968, J. L. S@'ersic showed that @mymath{n} can have a
variety of values and does not necessarily need to be 4.
+This profile depends on the effective radius (@mymath{r_e}) which is defined
as the radius which contains half of the profile brightness (see @ref{Profile
magnitude}).
+@mymath{I_e} is the flux at the effective radius.
+The S@'ersic index @mymath{n} is used to define the concentration of the
profile within @mymath{r_e} and @mymath{b_n} is a constant dependent on
@mymath{n}.
+MacArthur et al.@footnote{MacArthur, L. A., S. Courteau, and J. A. Holtzman
(2003). ``Structure of Disk-dominated Galaxies. I. Bulge/Disk Parameters,
Simulations, and Secular Evolution''. In: ApJ 582, pp. 689---722.} show that
for @mymath{n>0.35}, @mymath{b_n} can be accurately approximated using this
equation:
-@item -h INT/STR
-@item --hdu INT/STR
-The HDU of the input table when a named FITS file is given as input.
-The HDU (or extension) can be either a name or number (counting from zero).
-For more on this option, see @ref{Input output options}.
+@dispmath{b_n=2n - {1\over 3} + {4\over 405n} + {46\over 25515n^2} + {131\over
1148175n^3}-{2194697\over 30690717750n^4}}
-@item -c STR,STR
-@itemx --column=STR,STR
-Identifiers of the two positional columns to use in the DS9 region file from
the table.
-They can either be in WCS (RA and Dec) or image (pixel) coordiantes.
-The mode can be specified with the @option{--mode} option, described below.
-@item -n STR
-@itemx --namecol=STR
-The column containing the name (or label) of each region.
-The type of the column (numeric or a character-based string) is irrelevant:
you can use both types of columns as a name or label for the region.
-This feature is useful when you need to recognize each region with a certain
ID or property (for example magnitude or redshift).
-@item -m wcs|img
-@itemx --mode=wcs|org
-The coordinate system of the positional columns (can be either
@option{--mode=wcs} and @option{--mode=img}).
-In the WCS mode, the values within the columns are interpreted to be RA and
Dec.
-In the image mode, they are interpreted to be pixel X and Y positions.
-This option also affects the interpretation of the value given to
@option{--radius}.
-When this option isn't explicitly given, the columns are assumed to be in WCS
mode.
-@item -C STR
-@itemx --color=STR
-The color to use for created regions.
-These will be directly interpreted by SAO DS9 when it wants to open the region
file so it must be recognizable by SAO DS9.
-As of SAO DS9 8.2, the recognized color names are @code{black}, @code{white},
@code{red}, @code{green}, @code{blue}, @code{cyan}, @code{magenta} and
@code{yellow}.
-The default color (when this option is not called) is @code{green}
-@item -w INT
-@itemx --width=INT
-The line width of the regions.
-These will be directly interpreted by SAO DS9 when it wants to open the region
file so it must be recognizable by SAO DS9.
-The default value is @code{1}.
+@node Sampling from a function, Oversampling, Galaxies, Modeling basics
+@subsubsection Sampling from a function
-@item -r FLT
-@itemx --radius=FLT
-The radius of all the regions.
-In WCS mode, the radius is assumed to be in arc-seconds, in image mode, it is
in pixel units.
-If this option is not explicitly given, in WCS mode the default radius is 1
arc-seconds and in image mode it is 3 pixels.
+@cindex Sampling
+A pixel is the ultimate level of accuracy to gather data, we can't get any
more accurate in one image, this is known as sampling in signal processing.
+However, the mathematical profiles which describe our models have infinite
accuracy.
+Over a large fraction of the area of astrophysically interesting profiles (for
example galaxies or PSFs), the variation of the profile over the area of one
pixel is not too significant.
+In such cases, the elliptical radius (@mymath{r_{el}} of the center of the
pixel can be assigned as the final value of the pixel, see @ref{Defining an
ellipse and ellipsoid}).
-@item --dontdelete
-If the output file name exists, abort the program and don't over-write the
contents of the file.
-This option is thus good if you want to avoid accidentally writing over an
important file.
-Also, don't delete the created region file when @option{--command} is given
(by default, when @option{--command} is given, the created region file will be
deleted after SAO DS9 closes).
+@cindex Integration over pixel
+@cindex Gradient over pixel area
+@cindex Function gradient over pixel area
+As you approach their center, some galaxies become very sharp (their value
significantly changes over one pixel's area).
+This sharpness increases with smaller effective radius and larger S@'ersic
values.
+Thus rendering the central value extremely inaccurate.
+The first method that comes to mind for solving this problem is integration.
+The functional form of the profile can be integrated over the pixel area in a
2D integration process.
+However, unfortunately numerical integration techniques also have their
limitations and when such sharp profiles are needed they can become extremely
inaccurate.
-@item -o STR
-@itemx --output=STR
-Write the created SAO DS9 region file into the name given to this option.
-If not explicity given on the command-line, a default name of @file{ds9.reg}
will be used.
-If the file already exists, it will be over-written, you can avoid the
deletion (or over-writing) of an existing file with the @option{--dontdelete}.
+@cindex Monte carlo integration
+The most accurate method of sampling a continuous profile on a discrete space
is by choosing a large number of random points within the boundaries of the
pixel and taking their average value (or Monte Carlo integration).
+This is also, generally speaking, what happens in practice with the photons on
the pixel.
+The number of random points can be set with @option{--numrandom}.
-@item --command="STR"
-After creating the region file, run the string given to this option as a
command-line command.
-The SAO DS9 region command will be appended to the end of the given command.
-Because the command will mostly likely contain white-space characters it is
recommended to put the given string in double quotations.
+Unfortunately, repeating this Monte Carlo process would be extremely time and
CPU consuming if it is to be applied to every pixel.
+In order to not loose too much accuracy, in MakeProfiles, the profile is built
using both methods explained below.
+The building of the profile begins from its central pixel and continues
(radially) outwards.
+Monte Carlo integration is first applied (which yields @mymath{F_r}), then the
central pixel value (@mymath{F_c}) is calculated on the same pixel.
+If the fractional difference (@mymath{|F_r-F_c|/F_r}) is lower than a given
tolerance level (specified with @option{--tolerance}) MakeProfiles will stop
using Monte Carlo integration and only use the central pixel value.
-For example, let's assume @option{--command="ds9 image.fits -zscale"}.
-After making the region file (assuming it is called @file{ds9.reg}), the
following command will be executed:
+@cindex Inside-out construction
+The ordering of the pixels in this inside-out construction is based on
@mymath{r=\sqrt{(i_c-i)^2+(j_c-j)^2}}, not @mymath{r_{el}}, see @ref{Defining
an ellipse and ellipsoid}.
+When the axis ratios are large (near one) this is fine.
+But when they are small and the object is highly elliptical, it might seem
more reasonable to follow @mymath{r_{el}} not @mymath{r}.
+The problem is that the gradient is stronger in pixels with smaller @mymath{r}
(and larger @mymath{r_{el}}) than those with smaller @mymath{r_{el}}.
+In other words, the gradient is strongest along the minor axis.
+So if the next pixel is chosen based on @mymath{r_{el}}, the tolerance level
will be reached sooner and lots of pixels with large fractional differences
will be missed.
-@example
-ds9 image.fits -zscale -regions ds9.reg
-@end example
+Monte Carlo integration uses a random number of points.
+Thus, every time you run it, by default, you will get a different distribution
of points to sample within the pixel.
+In the case of large profiles, this will result in a slight difference of the
pixels which use Monte Carlo integration each time MakeProfiles is run.
+To have a deterministic result, you have to fix the random number generator
properties which is used to build the random distribution.
+This can be done by setting the @code{GSL_RNG_TYPE} and @code{GSL_RNG_SEED}
environment variables and calling MakeProfiles with the @option{--envseed}
option.
+To learn more about the process of generating random numbers, see
@ref{Generating random numbers}.
-You can customize all aspects of SAO DS9 with its command-line options,
therefore the value of this option can be as long and complicated as you like.
-For example if you also want the image to fit into the window, this option
will be: @command{--command="ds9 image.fits -zscale -zoom to fit"}.
-You can see the SAO DS9 command-line descriptions by clicking on the ``Help''
menu and selecting ``Reference Manual''.
-In the opened window, click on ``Command Line Options''.
-@end table
+@cindex Seed, Random number generator
+@cindex Random number generator, Seed
+The seed values are fixed for every profile: with @option{--envseed}, all the
profiles have the same seed and without it, each will get a different seed
using the system clock (which is accurate to within one microsecond).
+The same seed will be used to generate a random number for all the sub-pixel
positions of all the profiles.
+So in the former, the sub-pixel points checked for all the pixels undergoing
Monte carlo integration in all profiles will be identical.
+In other words, the sub-pixel points in the first (closest to the center)
pixel of all the profiles will be identical with each other.
+All the second pixels studied for all the profiles will also receive an
identical (different from the first pixel) set of sub-pixel points and so on.
+As long as the number of random points used is large enough or the profiles
are not identical, this should not cause any systematic bias.
+@node Oversampling, , Sampling from a function, Modeling basics
+@subsubsection Oversampling
+@cindex Oversampling
+The steps explained in @ref{Sampling from a function} do give an accurate
representation of a profile prior to convolution.
+However, in an actual observation, the image is first convolved with or
blurred by the atmospheric and instrument PSF in a continuous space and then it
is sampled on the discrete pixels of the camera.
+@cindex PSF over-sample
+In order to more accurately simulate this process, the unconvolved image and
the PSF are created on a finer pixel grid.
+In other words, the output image is a certain odd-integer multiple of the
desired size, we can call this `oversampling'.
+The user can specify this multiple as a command-line option.
+The reason this has to be an odd number is that the PSF has to be centered on
the center of its image.
+An image with an even number of pixels on each side does not have a central
pixel.
+The image can then be convolved with the PSF (which should also be oversampled
on the same scale).
+Finally, image can be sub-sampled to get to the initial desired pixel size of
the output image.
+After this, mock noise can be added as explained in the next section.
+This is because unlike the PSF, the noise occurs in each output pixel, not on
a continuous space like all the prior steps.
+@node If convolving afterwards, Brightness flux magnitude, Modeling basics,
MakeProfiles
+@subsection If convolving afterwards
+In case you want to convolve the image later with a given point spread
function, make sure to use a larger image size.
+After convolution, the profiles become larger and a profile that is normally
completely outside of the image might fall within it.
+On one axis, if you want your final (convolved) image to be @mymath{m} pixels
and your PSF is @mymath{2n+1} pixels wide, then when calling MakeProfiles, set
the axis size to @mymath{m+2n}, not @mymath{m}.
+You also have to shift all the pixel positions of the profile centers on the
that axis by @mymath{n} pixels to the positive.
+After convolution, you can crop the outer @mymath{n} pixels with the section
crop box specification of Crop: @option{--section=n:*-n,n:*-n} assuming your
PSF is a square, see @ref{Crop section syntax}.
+This will also remove all discrete Fourier transform artifacts (blurred sides)
from the final image.
+To facilitate this shift, MakeProfiles has the options @option{--xshift},
@option{--yshift} and @option{--prepforconv}, see @ref{Invoking astmkprof}.
+@node Brightness flux magnitude, Profile magnitude, If convolving afterwards,
MakeProfiles
+@subsection Brightness, Flux, Magnitude and Surface brightness
+@cindex ADU
+@cindex Gain
+@cindex Counts
+Astronomical data pixels are usually in units of counts@footnote{Counts are
also known as analog to digital units (ADU).} or electrons or either one
divided by seconds.
+To convert from the counts to electrons, you will need to know the instrument
gain.
+In any case, they can be directly converted to energy or energy/time using the
basic hardware (telescope, camera and filter) information.
+We will continue the discussion assuming the pixels are in units of
energy/time.
+@cindex Flux
+@cindex Luminosity
+@cindex Brightness
+The @emph{brightness} of an object is defined as its total detected energy per
time.
+In the case of an imaged source, this is simply the sum of the pixels that are
associated with that detection by our detection tool (for example
@ref{NoiseChisel}@footnote{If further processing is done, for example the Kron
or Petrosian radii are calculated, then the detected area is not sufficient and
the total area that was within the respective radius must be used.}).
+The @emph{flux} of an object is defined in units of
energy/time/collecting-area.
+For an astronomical target, the flux is therefore defined as its brightness
divided by the area used to collect the light from the source: or the telescope
aperture (for example in units of @mymath{cm^2}).
+Knowing the flux (@mymath{f}) and distance to the object (@mymath{r}), we can
define its @emph{luminosity}: @mymath{L=4{\pi}r^2f}.
+Therefore, while flux and luminosity are intrinsic properties of the object,
brightness depends on our detecting tools (hardware and software).
+In low-level observational astronomy data analysis, we are usually more
concerned with measuring the brightness, because it is the thing we directly
measure from the image pixels and create in catalogs.
+On the other hand, luminosity is used in higher-level analysis (after image
contents are measured as catalogs to deduce physical interpretations).
+It is just important avoid possible confusion between luminosity and
brightness because both have the same units of energy per seconds.
-@node Generate radial profile, , SAO DS9 region files from table, Data
analysis
-@section Generate radial profile
+@cindex Magnitudes from flux
+@cindex Flux to magnitude conversion
+@cindex Astronomical Magnitude system
+Images of astronomical objects span over a very large range of brightness.
+With the Sun (as the brightest object) being roughly @mymath{2.5^{60}=10^{24}}
times brighter than the fainter galaxies we can currently detect in the deepest
images.
+Therefore discussing brightness directly will involve a large range of values
which is inconvenient.
+So astronomers have chosen to use a logarithmic scale to talk about the
brightness of astronomical objects.
-@cindex Radial profile
-@cindex Profile, profile
-Sometimes it is necessary to compute a radial profile of an astronomical
object.
-For example, imagine you want to study how the light of a galaxy is
distributed as a function of the radial distance from the center.
-This is exactly what a radial profile is.
-Gnuastro's @file{astscript-radial-profile} script is created to obtain such
radial profiles.
-It uses @command{astmkprof} to generate elliptical apertures with the values
equal to the distance from the center of the object and @command{astmkcatalog}
for measuring the values over the apertures.
-With the default options, the script will generate a circular radial profile
using the mean value and centered at the center of the image.
-In order to have more flexibility, several options are available and the user
can play with them in order to obtain the wanted radial profile.
-In this sense, it can be changed the center position, the maximum radius, the
axis ratio and the position angle (elliptical apertures are considered), the
operator for obtaining the values, and some other options.
+@cindex Hipparchus of Nicaea
+But the logarithm can only be usable with a dimensionless value that is always
positive.
+Fortunately brightness is always positive (at least in theory@footnote{In
practice, for very faint objects, if the background brightness is
over-subtracted, we may end up with a negative brightness in a real object.}).
+To remove the dimensions, we divide the brightness of the object (@mymath{B})
by a reference brightness (@mymath{B_r}).
+We then define a logarithmic scale as @mymath{magnitude} through the relation
below.
+The @mymath{-2.5} factor in the definition of magnitudes is a legacy of the
our ancient colleagues and in particular Hipparchus of Nicaea (190-120 BC).
-@menu
-* Invoking astscript-radial-profile:: How to call astscript-radial-profile
-@end menu
+@dispmath{m-m_r=-2.5\log_{10} \left( B \over B_r \right)}
-@node Invoking astscript-radial-profile, , Generate radial profile, Generate
radial profile
-@subsection Invoking astscript-radial-profile
+@cindex Zero point magnitude
+@cindex Magnitude zero point
+@noindent
+@mymath{m} is defined as the magnitude of the object and @mymath{m_r} is the
pre-defined magnitude of the reference brightness.
+One particularly easy condition is when the reference brightness is unity
(@mymath{B_r=1}).
+This brightness will thus summarize all the hardware-specific parameters
discussed above (like the conversion of pixel values to physical units) into
one number.
+That reference magnitude which is commonly known as the @emph{Zero point}
magnitude (because when @mymath{B=Br=1}, the right side of the magnitude
definition above will be zero).
+Using the zero point magnitude (@mymath{Z}), we can write the magnitude
relation above in a more simpler format:
-For more on installed scripts please see (see @ref{Installed scripts}).
-This script can be used with the following general template:
+@dispmath{m = -2.5\log_{10}(B) + Z}
+
+@cindex Janskys (Jy)
+@cindex AB magnitude
+@cindex Magnitude, AB
+Having the zero point of an image, you can convert its pixel values to
physical units of microJanskys (or @mymath{\mu{}Jy}) to enable direct
pixel-based comparisons with images from other instruments (just note that this
assumes instrument and observation signatures are corrected, things like the
flat-field or the Sky).
+This conversion can be done with the fact that in the AB magnitude
standard@footnote{@url{https://en.wikipedia.org/wiki/AB_magnitude}},
@mymath{3631Jy} corresponds to the zero-th magnitude, therefore
@mymath{B\equiv3631\times10^{6}\mu{Jy}} and @mymath{m\equiv0}.
+We can therefore estimate the brightness (@mymath{B_z}, in @mymath{\mu{Jy}})
corresponding to the image zero point (@mymath{Z}) using this equation:
+
+@dispmath{m - Z = -2.5\log_{10}(B/B_z)}
+@dispmath{0 - Z = -2.5\log_{10}({3631\times10^{6}\over B_z})}
+@dispmath{B_z = 3631\times10^{\left(6 - {Z \over 2.5} \right)} \mu{Jy}}
+
+@cindex SDSS
+Because the image zero point corresponds to a pixel value of @mymath{1}, the
@mymath{B_z} value calculated above also corresponds to a pixel value of
@mymath{1}.
+Therefore you simply have to multiply your image by @mymath{B_z} to convert it
to @mymath{\mu{Jy}}.
+Don't forget that this only applies when your zero point was also estimated in
the AB magnitude system.
+On the command-line, you can easily estimate this value for a certain zero
point with AWK, then multiply it to all the pixels in the image with
@ref{Arithmetic}.
+For example let's assume you are using an SDSS image with a zero point of 22.5:
@example
-$ astscript-radial-profile [OPTION...] FITS-file
+bz=$(echo 22.5 | awk '@{print 3631 * 10^(6-$1/2.5)@}')
+astarithmetic sdss.fits $bz x --output=sdss-in-muJy.fits
@end example
-@noindent
-Examples:
+@cindex Steradian
+@cindex Angular coverage
+@cindex Celestial sphere
+@cindex Surface brightness
+@cindex SI (International System of Units)
+Another important concept is the distribution of an object's brightness over
its area.
+For this, we define the @emph{surface brightness} to be the magnitude of an
object's brightness divided by its solid angle over the celestial sphere (or
coverage in the sky, commonly in units of arcsec@mymath{^2}).
+The solid angle is expressed in units of arcsec@mymath{^2} because
astronomical targets are usually much smaller than one steradian.
+Recall that the steradian is the dimension-less SI unit of a solid angle and 1
steradian covers @mymath{1/4\pi} (almost @mymath{8\%}) of the full celestial
sphere.
-@example
-## Generate the radial profile with default options
-$ astscript-radial-profile image.fits
+Surface brightness is therefore most commonly expressed in units of
mag/arcsec@mymath{2}.
+For example when the brightness is measured over an area of A
arcsec@mymath{^2}, then the surface brightness becomes:
-## Generate the radial profile centered at x=44 and y=37 (in pixels),
-## up to a radial distance of 19 pixels, use the mean value.
-$ astscript-radial-profile image.fits \
- --xcenter=44 \
- --ycenter=37 \
- --rmax=19
+@dispmath{S = -2.5\log_{10}(B/A) + Z = -2.5\log_{10}(B) + 2.5\log_{10}(A) + Z}
-## Generate the radial profile centered at x=44 and y=37 (in pixels),
-## up to a radial distance of 100 pixels, compute sigma clipped
-## mean and standard deviation (sigclip-mean and sigclip-std) using
-## 3 sigma and 10 iterations.
-$ astscript-radial-profile image.fits \
- --xcenter=44 \
- --ycenter=37 \
- --rmax=100 \
- --sigmaclip=3,10 \
- --measure="sigclip-mean sigclip-std"
+@noindent
+In other words, the surface brightness (in units of mag/arcsec@mymath{^2}) is
related to the object's magnitude (@mymath{m}) and area (@mymath{A}, in units
of arcsec@mymath{^2}) through this equation:
-## Generate the radial profile centered at RA=20.53751695,
-## DEC=0.9454292263, up to a radial distance of 88 pixels,
-## axis ratio equal to 0.32, and position angle of 148 deg.
-## Name the output table as `radial-profile.fits'
-$ astscript-radial-profile image.fits --mode=wcs \
- --xcenter=20.53751695 \
- --ycenter=0.9454292263 \
- --rmax=88 --qratio=0.32 \
- --pangle=148 -oradial-profile.fits
+@dispmath{S = m + 2.5\log_{10}(A)}
-@end example
+A common mistake is to follow the mag/arcsec@mymath{^2} unit literally, and
divide the object's magnitude by its area.
+But this is wrong because magnitude is a logarithmic scale while area is
linear.
+It is the brightness that should be divided by the solid angle because both
have linear scales.
+The magnitude of that ratio is then defined to be the surface brightness.
-This installed script will read a FITS image and will use it as the basis for
constructing the radial profile.
-The output radial profile consists in a FITS table containing the radial
distance from the center in the first column and the specified measurements in
the other columns (mean, median, sigclip-mean, sigclip-median, etc.).
+@node Profile magnitude, Invoking astmkprof, Brightness flux magnitude,
MakeProfiles
+@subsection Profile magnitude
-@table @option
-@item -h STR
-@itemx --hdu=STR
-The HDU/extension to use.
+@cindex Brightness
+@cindex Truncation radius
+@cindex Sum for total flux
+To find the profile brightness or its magnitude, (see @ref{Brightness flux
magnitude}), it is customary to use the 2D integration of the flux to infinity.
+However, in MakeProfiles we do not follow this idealistic approach and apply a
more realistic method to find the total brightness or magnitude: the sum of all
the pixels belonging to a profile within its predefined truncation radius.
+Note that if the truncation radius is not large enough, this can be
significantly different from the total integrated light to infinity.
-@item -O STR
-@itemx --mode=STR
-Interpret the center position of the object (@option{--xcenter} and
@option{--ycenter}) in image or WCS coordinates.
-This option thus accepts only two values: @option{img} or @option{wcs}.
-By default, it is @option{--mode=img}.
+@cindex Integration to infinity
+An integration to infinity is not a realistic condition because no galaxy
extends indefinitely (important for high S@'ersic index profiles), pixelation
can also cause a significant difference between the actual total pixel sum
value of the profile and that of integration to infinity, especially in small
and high S@'ersic index profiles.
+To be safe, you can specify a large enough truncation radius for such compact
high S@'ersic index profiles.
-@item -x FLT
-@itemx --xcenter=FLT
-Center coordinate along the first dimension.
-This option will be used for placing the center of the profiles.
-If @option{--mode=img} is considered, then @option{--xcenter} has to be in
image units (pixels).
-If @option{--mode=wcs} is considered, then @option{--xcenter} has to be in WCS
units.
-By default, it is @option{--xcenter=center}, which means that it will put the
center of the radial profiles in the center of the image.
-This parameter is used as the @option{--ccol} option for generating the
apertures with @command{astmkprof}.
+If oversampling is used then the brightness is calculated using the
over-sampled image, see @ref{Oversampling} which is much more accurate.
+The profile is first built in an array completely bounding it with a
normalization constant of unity (see @ref{Galaxies}).
+Taking @mymath{B} to be the desired brightness and @mymath{S} to be the sum of
the pixels in the created profile, every pixel is then multiplied by
@mymath{B/S} so the sum is exactly @mymath{B}.
-@item -y FLT
-@itemx --ycenter=FLT
-Center coordinate along the second dimension.
-Same than @option{--xcenter} argument, but for the second dimension (see above
for details).
+If the @option{--individual} option is called, this same array is written to a
FITS file.
+If not, only the overlapping pixels of this array and the output image are
kept and added to the output array.
-@item -R FLT
-@itemx --rmax=FLT
-Maximum radius for the radial profile (in pixels).
-By default, it is @option{--rmax=max}, which means that the radial profile
will be computed up to a radial distance equal to the maximum radius that fits
into the image (assuming circular shape).
-This parameter is used as the options @option{--fcol} and @option{--tcol} in
the generation of the apertures with @command{astmkprof}.
-@item -Q FLT
-@itemx --qratio=FLT
-The axis ratio of the apertures (minor axis divided by the major axis in a 2D
ellipse).
-By default, it is @option{--qratio=1}, which means that the radial profile
will be circular.
-This parameter is used as the option @option{--qcol} in the generation of the
apertures with @command{astmkprof}.
-@item -p FLT
-@itemx --pangle=FLT
-The position angle (in degrees) of the profiles relative to the first FITS
axis (horizontal when viewed in SAO ds9).
-By default, it is @option{--pangle=0}, which means that the semi-major axis of
the profiles will be parallel to the first FITS axis.
-This parameter is used as the option @option{--pcol} in the generation of the
apertures with @command{astmkprof}.
-
-@item -m "STR"
-@itemx --measure="STR"
-The operator for measuring the values over each different aperture.
-By default, it is @option{--measure="--mean"}, which means that the mean of
all pixels inside each aperture will be computed.
-This parameter is used for measuring the values with @command{astmkcatalog}.
-As a consequence, all operators like median, mean, std, sigclip-mean,
sigclip-number, etc. can be used here.
-Multiple operators can be specified at once.
-For example, by setting @option{--measure="--mean --median"} the mean and
median values will be computed.
-In this case, the output radial profile will have 3 columns: radial distance,
mean, and median.
-@item -s FLT,FLT
-@itemx --sigmaclip=FLT,FLT
-Sigma clipping parameters if @option{--measure} operator requested is any of
the available sigma-clipping operators.
-By default, it is @option{--sigmaclip=3,0.2}, see @ref{Arithmetic operators}
for more details.
-@item -t
-@itemx --tmpdir=STR
-Several intermediate files are necessary to obtain the radial profile.
-All of these temporal files are saved into a temporal directory.
-With the option @option{--tmpdir} the user can specify this directory.
-Once the radial profile has been obtained, this directory is removed if the
option @option{--keeptmp} is not used (see below for more details).
-@item -k
-@itemx --keeptmp
-With the option @option{--keeptmp} (no argument is required) all temporal
files generated into the temporal directory @option{--keeptmp} will not be
removed.
-This option is useful for debugging.
-For example, to check that the profiles generated for obtaining the radial
profile have the same shape and orientation than the source.
-@end table
+@node Invoking astmkprof, , Profile magnitude, MakeProfiles
+@subsection Invoking MakeProfiles
+MakeProfiles will make any number of profiles specified in a catalog either
individually or in one image.
+The executable name is @file{astmkprof} with the following general template
+@example
+$ astmkprof [OPTION ...] [Catalog]
+@end example
+@noindent
+One line examples:
+@example
+## Make an image with profiles in catalog.txt (with default size):
+$ astmkprof catalog.txt
+## Make the profiles in catalog.txt over image.fits:
+$ astmkprof --background=image.fits catalog.txt
+## Make a Moffat PSF with FWHM 3pix, beta=2.8, truncation=5
+$ astmkprof --kernel=moffat,3,2.8,5 --oversample=1
+## Make profiles in catalog, using RA and Dec in the given column:
+$ astmkprof --ccol=RA_CENTER --ccol=DEC_CENTER --mode=wcs catalog.txt
+## Make a 1500x1500 merged image (oversampled 500x500) image along
+## with an individual image for all the profiles in catalog:
+$ astmkprof --individual --oversample 3 --mergedsize=500,500 cat.txt
+@end example
+@noindent
+The parameters of the mock profiles can either be given through a catalog
(which stores the parameters of many mock profiles, see @ref{MakeProfiles
catalog}), or the @option{--kernel} option (see @ref{MakeProfiles output
dataset}).
+The catalog can be in the FITS ASCII, FITS binary format, or plain text
formats (see @ref{Tables}).
+A plain text catalog can also be provided using the Standard input (see
@ref{Standard input}).
+The columns related to each parameter can be determined both by number, or by
match/search criteria using the column names, units, or comments, with the
options ending in @option{col}, see below.
+Without any file given to the @option{--background} option, MakeProfiles will
make a zero-valued image and build the profiles on that (its size and main WCS
parameters can also be defined through the options described in
@ref{MakeProfiles output dataset}).
+Besides the main/merged image containing all the profiles in the catalog, it
is also possible to build individual images for each profile (only enclosing
one full profile to its truncation radius) with the @option{--individual}
option.
+If an image is given to the @option{--background} option, the pixels of that
image are used as the background value for every pixel hence flux value of each
profile pixel will be added to the pixel in that background value.
+You can disable this with the @code{--clearcanvas} option (which will
initialize the background to zero-valued pixels and build profiles over that).
+With the @option{--background} option, the values to all options relating to
the ``canvas'' (output size and WCS) will be ignored if specified, for example
@option{--oversample}, @option{--mergedsize}, and @option{--prepforconv}.
+The sections below discuss the options specific to MakeProfiles based on
context: the input catalog settings which can have many rows for different
profiles are discussed in @ref{MakeProfiles catalog}, in @ref{MakeProfiles
profile settings}, we discuss how you can set general profile settings (that
are the same for all the profiles in the catalog).
+Finally @ref{MakeProfiles output dataset} and @ref{MakeProfiles log file}
discuss the outputs of MakeProfiles and how you can configure them.
+Besides these, MakeProfiles also supports all the common Gnuastro program
options that are discussed in @ref{Common options}, so please flip through them
is well for a more comfortable usage.
+When building 3D profiles, there are more degrees of freedom.
+Hence, more columns are necessary and all the values related to dimensions
(for example size of dataset in each dimension and the WCS properties) must
also have 3 values.
+To allow having an independent set of default values for creating 3D profiles,
MakeProfiles also installs a @file{astmkprof-3d.conf} configuration file (see
@ref{Configuration files}).
+You can use this for default 3D profile values.
+For example, if you installed Gnuastro with the prefix @file{/usr/local} (the
default location, see @ref{Installation directory}), you can benefit from this
configuration file by running MakeProfiles like the example below.
+As with all configuration files, if you want to customize a given option, call
it before the configuration file.
+@example
+$ astmkprof --config=/usr/local/etc/astmkprof-3d.conf catalog.txt
+@end example
+@cindex Shell alias
+@cindex Alias, shell
+@cindex Shell startup
+@cindex Startup, shell
+To further simplify the process, you can define a shell alias in any startup
file (for example @file{~/.bashrc}, see @ref{Installation directory}).
+Assuming that you installed Gnuastro in @file{/usr/local}, you can add this
line to the startup file (you may put it all in one line, it is broken into two
lines here for fitting within page limits).
+@example
+alias astmkprof-3d="astmkprof --config=/usr/local/etc/astmkprof-3d.conf"
+@end example
+@noindent
+Using this alias, you can call MakeProfiles with the name
@command{astmkprof-3d} (instead of @command{astmkprof}).
+It will automatically load the 3D specific configuration file first, and then
parse any other arguments, options or configuration files.
+You can change the default values in this 3D configuration file by calling
them on the command-line as you do with @command{astmkprof}@footnote{Recall
that for single-invocation options, the last command-line invocation takes
precedence over all previous invocations (including those in the 3D
configuration file).
+See the description of @option{--config} in @ref{Operating mode options}.}.
+Please see @ref{Sufi simulates a detection} for a very complete tutorial
explaining how one could use MakeProfiles in conjunction with other Gnuastro's
programs to make a complete simulated image of a mock galaxy.
+@menu
+* MakeProfiles catalog:: Required catalog properties.
+* MakeProfiles profile settings:: Configuration parameters for all profiles.
+* MakeProfiles output dataset:: The canvas/dataset to build profiles over.
+* MakeProfiles log file:: A description of the optional log file.
+@end menu
-@node Modeling and fittings, High-level calculations, Data analysis, Top
-@chapter Modeling and fitting
+@node MakeProfiles catalog, MakeProfiles profile settings, Invoking astmkprof,
Invoking astmkprof
+@subsubsection MakeProfiles catalog
+The catalog containing information about each profile can be in the FITS
ASCII, FITS binary, or plain text formats (see @ref{Tables}).
+The latter can also be provided using standard input (see @ref{Standard
input}).
+Its columns can be ordered in any desired manner.
+You can specify which columns belong to which parameters using the set of
options discussed below.
+For example through the @option{--rcol} and @option{--tcol} options, you can
specify the column that contains the radial parameter for each profile and its
truncation respectively.
+See @ref{Selecting table columns} for a thorough discussion on the values to
these options.
-@cindex Fitting
-@cindex Modeling
-In order to fully understand observations after initial analysis on the image,
it is very important to compare them with the existing models to be able to
further understand both the models and the data.
-The tools in this chapter create model galaxies and will provide 2D fittings
to be able to understand the detections.
+The value for the profile center in the catalog (the @option{--ccol} option)
can be a floating point number so the profile center can be on any sub-pixel
position.
+Note that pixel positions in the FITS standard start from 1 and an integer is
the pixel center.
+So a 2D image actually starts from the position (0.5, 0.5), which is the
bottom-left corner of the first pixel.
+When a @option{--background} image with WCS information is provided or you
specify the WCS parameters with the respective options, you may also use RA and
Dec to identify the center of each profile (see the @option{--mode} option
below).
-@menu
-* MakeProfiles:: Making mock galaxies and stars.
-* MakeNoise:: Make (add) noise to an image.
-@end menu
+In MakeProfiles, profile centers do not have to be in (overlap with) the final
image.
+Even if only one pixel of the profile within the truncation radius overlaps
with the final image size, the profile is built and included in the final image
image.
+Profiles that are completely out of the image will not be created (unless you
explicitly ask for it with the @option{--individual} option).
+You can use the output log file (created with @option{--log} to see which
profiles were within the image, see @ref{Common options}.
+If PSF profiles (Moffat or Gaussian, see @ref{PSF}) are in the catalog and the
profiles are to be built in one image (when @option{--individual} is not used),
it is assumed they are the PSF(s) you want to convolve your created image with.
+So by default, they will not be built in the output image but as separate
files.
+The sum of pixels of these separate files will also be set to unity (1) so you
are ready to convolve, see @ref{Convolution process}.
+As a summary, the position and magnitude of PSF profile will be ignored.
+This behavior can be disabled with the @option{--psfinimg} option.
+If you want to create all the profiles separately (with @option{--individual})
and you want the sum of the PSF profile pixels to be unity, you have to set
their magnitudes in the catalog to the zero point magnitude and be sure that
the central positions of the profiles don't have any fractional part (the PSF
center has to be in the center of the pixel).
+The list of options directly related to the input catalog columns is shown
below.
+@table @option
-@node MakeProfiles, MakeNoise, Modeling and fittings, Modeling and fittings
-@section MakeProfiles
+@item --ccol=STR/INT
+Center coordinate column for each dimension.
+This option must be called two times to define the center coordinates in an
image.
+For example @option{--ccol=RA} and @option{--ccol=DEC} (along with
@option{--mode=wcs}) will inform MakeProfiles to look into the catalog columns
named @option{RA} and @option{DEC} for the Right Ascension and Declination of
the profile centers.
-@cindex Checking detection algorithms
-@pindex @r{MakeProfiles (}astmkprof@r{)}
-MakeProfiles will create mock astronomical profiles from a catalog, either
individually or together in one output image.
-In data analysis, making a mock image can act like a calibration tool, through
which you can test how successfully your detection technique is able to detect
a known set of objects.
-There are commonly two aspects to detecting: the detection of the fainter
parts of bright objects (which in the case of galaxies fade into the noise very
slowly) or the complete detection of an over-all faint object.
-Making mock galaxies is the most accurate (and idealistic) way these two
aspects of a detection algorithm can be tested.
-You also need mock profiles in fitting known functional profiles with
observations.
+@item --fcol=INT/STR
+The functional form of the profile with one of the values below depending on
the desired profile.
+The column can contain either the numeric codes (for example `@code{1}') or
string characters (for example `@code{sersic}').
+The numeric codes are easier to use in scripts which generate catalogs with
hundreds or thousands of profiles.
-MakeProfiles was initially built for extra galactic studies, so currently the
only astronomical objects it can produce are stars and galaxies.
-We welcome the simulation of any other astronomical object.
-The general outline of the steps that MakeProfiles takes are the following:
+The string format can be easier when the catalog is to be written/checked by
hand/eye before running MakeProfiles.
+It is much more readable and provides a level of documentation.
+All Gnuastro's recognized table formats (see @ref{Recognized table formats})
accept string type columns.
+To have string columns in a plain text table/catalog, see @ref{Gnuastro text
table format}.
-@enumerate
+@itemize
+@item
+S@'ersic profile with `@code{sersic}' or `@code{1}'.
@item
-Build the full profile out to its truncation radius in a possibly over-sampled
array.
+Moffat profile with `@code{moffat}' or `@code{2}'.
@item
-Multiply all the elements by a fixed constant so its total magnitude equals
the desired total magnitude.
+Gaussian profile with `@code{gaussian}' or `@code{3}'.
@item
-If @option{--individual} is called, save the array for each profile to a FITS
file.
+Point source with `@code{point}' or `@code{4}'.
@item
-If @option{--nomerged} is not called, add the overlapping pixels of all the
created profiles to the output image and abort.
+Flat profile with `@code{flat}' or `@code{5}'.
-@end enumerate
+@item
+Circumference profile with `@code{circum}' or `@code{6}'.
+A fixed value will be used for all pixels less than or equal to the truncation
radius (@mymath{r_t}) and greater than @mymath{r_t-w} (@mymath{w} is the value
to the @option{--circumwidth}).
-Using input values, MakeProfiles adds the World Coordinate System (WCS)
headers of the FITS standard to all its outputs (except PSF images!).
-For a simple test on a set of mock galaxies in one image, there is no need for
the third step or the WCS information.
+@item
+Radial distance profile with `@code{distance}' or `@code{7}'.
+At the lowest level, each pixel only has an elliptical radial distance given
the profile's shape and orientation (see @ref{Defining an ellipse and
ellipsoid}).
+When this profile is chosen, the pixel's elliptical radial distance from the
profile center is written as its value.
+For this profile, the value in the magnitude column (@option{--mcol}) will be
ignored.
-@cindex Transform image
-@cindex Lensing simulations
-@cindex Image transformations
-However in complicated simulations like weak lensing simulations, where each
galaxy undergoes various types of individual transformations based on their
position, those transformations can be applied to the different individual
images with other programs.
-After all the transformations are applied, using the WCS information in each
individual profile image, they can be merged into one output image for
convolution and adding noise.
+You can use this for checks or as a first approximation to define your own
higher-level radial function.
+In the latter case, just note that the central values are going to be
incorrect (see @ref{Sampling from a function}).
-@menu
-* Modeling basics:: Astronomical modeling basics.
-* If convolving afterwards:: Considerations for convolving later.
-* Brightness flux magnitude:: About these measures of energy.
-* Profile magnitude:: Definition of total profile magnitude.
-* Invoking astmkprof:: Inputs and Options for MakeProfiles.
-@end menu
+@item
+Custom profile with `@code{custom}' or `@code{8}'.
+The values to use for each radial interval should be in the table given to
@option{--customtable}. For more, see @ref{MakeProfiles profile settings}.
+@end itemize
+@item --rcol=STR/INT
+The radius parameter of the profiles.
+Effective radius (@mymath{r_e}) if S@'ersic, FWHM if Moffat or Gaussian.
+@item --ncol=STR/INT
+The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
-@node Modeling basics, If convolving afterwards, MakeProfiles, MakeProfiles
-@subsection Modeling basics
+@item --pcol=STR/INT
+The position angle (in degrees) of the profiles relative to the first FITS
axis (horizontal when viewed in SAO ds9).
+When building a 3D profile, this is the first Euler angle: first rotation of
the ellipsoid major axis from the first FITS axis (rotating about the third
axis).
+See @ref{Defining an ellipse and ellipsoid}.
-In the subsections below, first a review of some very basic information and
concepts behind modeling a real astronomical image is given.
-You can skip this subsection if you are already sufficiently familiar with
these concepts.
+@item --p2col=STR/INT
+Second Euler angle (in degrees) when building a 3D ellipsoid.
+This is the second rotation of the ellipsoid major axis (following
@option{--pcol}) about the (rotated) X axis.
+See @ref{Defining an ellipse and ellipsoid}.
+This column is ignored when building a 2D profile.
-@menu
-* Defining an ellipse and ellipsoid:: Definition of these important shapes.
-* PSF:: Radial profiles for the PSF.
-* Stars:: Making mock star profiles.
-* Galaxies:: Radial profiles for galaxies.
-* Sampling from a function:: Sample a function on a pixelated canvas.
-* Oversampling:: Oversampling the model.
-@end menu
+@item --p3col=STR/INT
+Third Euler angle (in degrees) when building a 3D ellipsoid.
+This is the third rotation of the ellipsoid major axis (following
@option{--pcol} and @option{--p2col}) about the (rotated) Z axis.
+See @ref{Defining an ellipse and ellipsoid}.
+This column is ignored when building a 2D profile.
-@node Defining an ellipse and ellipsoid, PSF, Modeling basics, Modeling basics
-@subsubsection Defining an ellipse and ellipsoid
+@item --qcol=STR/INT
+The axis ratio of the profiles (minor axis divided by the major axis in a 2D
ellipse).
+When building a 3D ellipse, this is the ratio of the major axis to the
semi-axis length of the second dimension (in a right-handed coordinate system).
+See @mymath{q1} in @ref{Defining an ellipse and ellipsoid}.
-@cindex Ellipse
-@cindex Axis ratio
-@cindex Position angle
-The PSF, see @ref{PSF}, and galaxy radial profiles are generally defined on an
ellipse.
-Therefore, in this section we'll start defining an ellipse on a pixelated 2D
surface.
-Labeling the major axis of an ellipse @mymath{a}, and its minor axis with
@mymath{b}, the @emph{axis ratio} is defined as: @mymath{q\equiv b/a}.
-The major axis of an ellipse can be aligned in any direction, therefore the
angle of the major axis with respect to the horizontal axis of the image is
defined to be the @emph{position angle} of the ellipse and in this book, we
show it with @mymath{\theta}.
+@item --q2col=STR/INT
+The ratio of the ellipsoid major axis to the third semi-axis length (in a
right-handed coordinate system) of a 3D ellipsoid.
+See @mymath{q1} in @ref{Defining an ellipse and ellipsoid}.
+This column is ignored when building a 2D profile.
-@cindex Radial profile on ellipse
-Our aim is to put a radial profile of any functional form @mymath{f(r)} over
an ellipse.
-Hence we need to associate a radius/distance to every point in space.
-Let's define the radial distance @mymath{r_{el}} as the distance on the major
axis to the center of an ellipse which is located at @mymath{i_c} and
@mymath{j_c} (in other words @mymath{r_{el}\equiv{a}}).
-We want to find @mymath{r_{el}} of a point located at @mymath{(i,j)} (in the
image coordinate system) from the center of the ellipse with axis ratio
@mymath{q} and position angle @mymath{\theta}.
-First the coordinate system is rotated@footnote{Do not confuse the signs of
@mymath{sin} with the rotation matrix defined in @ref{Warping basics}.
-In that equation, the point is rotated, here the coordinates are rotated and
the point is fixed.} by @mymath{\theta} to get the new rotated coordinates of
that point @mymath{(i_r,j_r)}:
+@item --mcol=STR/INT
+The total pixelated magnitude of the profile within the truncation radius, see
@ref{Profile magnitude}.
-@dispmath{i_r(i,j)=+(i_c-i)\cos\theta+(j_c-j)\sin\theta}
-@dispmath{j_r(i,j)=-(i_c-i)\sin\theta+(j_c-j)\cos\theta}
+@item --tcol=STR/INT
+The truncation radius of this profile.
+By default it is in units of the radial parameter of the profile (the value in
the @option{--rcol} of the catalog).
+If @option{--tunitinp} is given, this value is interpreted in units of pixels
(prior to oversampling) irrespective of the profile.
-@cindex Elliptical distance
-@noindent Recall that an ellipse is defined by @mymath{(i_r/a)^2+(j_r/b)^2=1}
and that we defined @mymath{r_{el}\equiv{a}}.
-Hence, multiplying all elements of the ellipse definition with
@mymath{r_{el}^2} we get the elliptical distance at this point point located:
@mymath{r_{el}=\sqrt{i_r^2+(j_r/q)^2}}.
-To place the radial profiles explained below over an ellipse,
@mymath{f(r_{el})} is calculated based on the functional radial profile desired.
+@end table
-@cindex Ellipsoid
-@cindex Euler angles
-An ellipse in 3D, or an @url{https://en.wikipedia.org/wiki/Ellipsoid,
ellipsoid}, can be defined following similar principles as before.
-Labeling the major (largest) axis length as @mymath{a}, the second and third
(in a right-handed coordinate system) axis lengths can be labeled as @mymath{b}
and @mymath{c}.
-Hence we have two axis ratios: @mymath{q_1\equiv{b/a}} and
@mymath{q_2\equiv{c/a}}.
-The orientation of the ellipsoid can be defined from the orientation of its
major axis.
-There are many ways to define 3D orientation and order matters.
-So to be clear, here we use the ZXZ (or @mymath{Z_1X_2Z_3}) proper
@url{https://en.wikipedia.org/wiki/Euler_angles, Euler angles} to define the 3D
orientation.
-In short, when a point is rotated in this order, we first rotate it around the
Z axis (third axis) by @mymath{\alpha}, then about the (rotated) X axis by
@mymath{\beta} and finally about the (rotated) Z axis by @mymath{\gamma}.
-
-Following the discussion in @ref{Merging multiple warpings}, we can define the
full rotation with the following matrix multiplication.
-However, here we are rotating the coordinates, not the point.
-Therefore, both the rotation angles and rotation order are reversed.
-We are also not using homogeneous coordinates (see @ref{Warping basics}) since
we aren't concerned with translation in this context:
-
-@dispmath{\left[\matrix{i_r\cr j_r\cr k_r}\right] =
- \left[\matrix{cos\gamma&sin\gamma&0\cr -sin\gamma&cos\gamma&0\cr
0&0&1}\right]
- \left[\matrix{1&0&0\cr 0&cos\beta&sin\beta\cr
0&-sin\beta&cos\beta }\right]
- \left[\matrix{cos\alpha&sin\alpha&0\cr -sin\alpha&cos\alpha&0\cr
0&0&1}\right]
- \left[\matrix{i_c-i\cr j_c-j\cr k_c-k}\right] }
-
-@noindent
-Recall that an ellipsoid can be characterized with
-@mymath{(i_r/a)^2+(j_r/b)^2+(k_r/c)^2=1}, so similar to before
-(@mymath{r_{el}\equiv{a}}), we can find the ellipsoidal radius at pixel
-@mymath{(i,j,k)} as: @mymath{r_{el}=\sqrt{i_r^2+(j_r/q_1)^2+(k_r/q_2)^2}}.
-
-@cindex Breadth first search
-@cindex Inside-out construction
-@cindex Making profiles pixel by pixel
-@cindex Pixel by pixel making of profiles
-MakeProfiles builds the profile starting from the nearest element (pixel in an
image) in the dataset to the profile center.
-The profile value is calculated for that central pixel using monte carlo
integration, see @ref{Sampling from a function}.
-The next pixel is the next nearest neighbor to the central pixel as defined by
@mymath{r_{el}}.
-This process goes on until the profile is fully built upto the truncation
radius.
-This is done fairly efficiently using a breadth first parsing
strategy@footnote{@url{http://en.wikipedia.org/wiki/Breadth-first_search}}
which is implemented through an ordered linked list.
+@node MakeProfiles profile settings, MakeProfiles output dataset, MakeProfiles
catalog, Invoking astmkprof
+@subsubsection MakeProfiles profile settings
-Using this approach, we build the profile by expanding the circumference.
-Not one more extra pixel has to be checked (the calculation of @mymath{r_{el}}
from above is not cheap in CPU terms).
-Another consequence of this strategy is that extending MakeProfiles to three
dimensions becomes very simple: only the neighbors of each pixel have to be
changed.
-Everything else after that (when the pixel index and its radial profile have
entered the linked list) is the same, no matter the number of dimensions we are
dealing with.
+The profile parameters that differ between each created profile are specified
through the columns in the input catalog and described in @ref{MakeProfiles
catalog}.
+Besides those there are general settings for some profiles that don't differ
between one profile and another, they are a property of the general process.
+For example how many random points to use in the monte-carlo integration, this
value is fixed for all the profiles.
+The options described in this section are for configuring such properties.
+@table @option
+@item --mode=STR
+Interpret the center position columns (@option{--ccol} in @ref{MakeProfiles
catalog}) in image or WCS coordinates.
+This option thus accepts only two values: @option{img} and @option{wcs}.
+It is mandatory when a catalog is being used as input.
+@item -r
+@itemx --numrandom
+The number of random points used in the central regions of the profile, see
@ref{Sampling from a function}.
+@item -e
+@itemx --envseed
+@cindex Seed, Random number generator
+@cindex Random number generator, Seed
+Use the value to the @code{GSL_RNG_SEED} environment variable to generate the
random Monte Carlo sampling distribution, see @ref{Sampling from a function}
and @ref{Generating random numbers}.
-@node PSF, Stars, Defining an ellipse and ellipsoid, Modeling basics
-@subsubsection Point spread function
+@item -t FLT
+@itemx --tolerance=FLT
+The tolerance to switch from Monte Carlo integration to the central pixel
value, see @ref{Sampling from a function}.
-@cindex PSF
-@cindex Point source
-@cindex Diffraction limited
-@cindex Point spread function
-@cindex Spread of a point source
-Assume we have a `point' source, or a source that is far smaller than the
maximum resolution (a pixel).
-When we take an image of it, it will `spread' over an area.
-To quantify that spread, we can define a `function'.
-This is how the point spread function or the PSF of an image is defined.
-This `spread' can have various causes, for example in ground based astronomy,
due to the atmosphere.
-In practice we can never surpass the `spread' due to the diffraction of the
lens aperture.
-Various other effects can also be quantified through a PSF.
-For example, the simple fact that we are sampling in a discrete space, namely
the pixels, also produces a very small `spread' in the image.
+@item -p
+@itemx --tunitinp
+The truncation column of the catalog is in units of pixels.
+By default, the truncation column is considered to be in units of the radial
parameters of the profile (@option{--rcol}).
+Read it as `t-unit-in-p' for `truncation unit in pixels'.
-@cindex Blur image
-@cindex Convolution
-@cindex Image blurring
-@cindex PSF image size
-Convolution is the mathematical process by which we can apply a `spread' to an
image, or in other words blur the image, see @ref{Convolution process}.
-The Brightness of an object should remain unchanged after convolution, see
@ref{Brightness flux magnitude}.
-Therefore, it is important that the sum of all the pixels of the PSF be unity.
-The PSF image also has to have an odd number of pixels on its sides so one
pixel can be defined as the center.
-In MakeProfiles, the PSF can be set by the two methods explained below.
+@item -f
+@itemx --mforflatpix
+When making fixed value profiles (flat and circumference, see
`@option{--fcol}'), don't use the value in the column specified by
`@option{--mcol}' as the magnitude.
+Instead use it as the exact value that all the pixels of these profiles should
have.
+This option is irrelevant for other types of profiles.
+This option is very useful for creating masks, or labeled regions in an image.
+Any integer, or floating point value can used in this column with this option,
including @code{NaN} (or `@code{nan}', or `@code{NAN}', case is irrelevant),
and infinities (@code{inf}, @code{-inf}, or @code{+inf}).
-@table @asis
+For example, with this option if you set the value in the magnitude column
(@option{--mcol}) to @code{NaN}, you can create an elliptical or circular mask
over an image (which can be given as the argument), see @ref{Blank pixels}.
+Another useful application of this option is to create labeled elliptical or
circular apertures in an image.
+To do this, set the value in the magnitude column to the label you want for
this profile.
+This labeled image can then be used in combination with NoiseChisel's output
(see @ref{NoiseChisel output}) to do aperture photometry with MakeCatalog (see
@ref{MakeCatalog}).
-@item Parametric functions
-@cindex FWHM
-@cindex PSF width
-@cindex Parametric PSFs
-@cindex Full Width at Half Maximum
-A known mathematical function is used to make the PSF.
-In this case, only the parameters to define the functions are necessary and
MakeProfiles will make a PSF based on the given parameters for each function.
-In both cases, the center of the profile has to be exactly in the middle of
the central pixel of the PSF (which is automatically done by MakeProfiles).
-When talking about the PSF, usually, the full width at half maximum or FWHM is
used as a scale of the width of the PSF.
+Alternatively, if you want to mark regions of the image (for example with an
elliptical circumference) and you don't want to use NaN values (as explained
above) for some technical reason, you can get the minimum or maximum value in
the image @footnote{
+The minimum will give a better result, because the maximum can be too high
compared to most pixels in the image, making it harder to display.}
+using Arithmetic (see @ref{Arithmetic}), then use that value in the magnitude
column along with this option for all the profiles.
-@table @cite
-@item Gaussian
-@cindex Gaussian distribution
-In the older papers, and to a lesser extent even today, some researchers use
the 2D Gaussian function to approximate the PSF of ground based images.
-In its most general form, a Gaussian function can be written as:
+Please note that when using MakeProfiles on an already existing image, you
have to set `@option{--oversample=1}'.
+Otherwise all the profiles will be scaled up based on the oversampling scale
in your configuration files (see @ref{Configuration files}) unless you have
accounted for oversampling in your catalog.
-@dispmath{f(r)=a \exp \left( -(x-\mu)^2 \over 2\sigma^2 \right)+d}
+@item --mcolisbrightness
+The value given in the ``magnitude column'' (specified by @option{--mcol}, see
@ref{MakeProfiles catalog}) must be interpreted as brightness, not magnitude.
+The zero point magnitude (value to the @option{--zeropoint} option) is ignored
and the given value must have the same units as the input dataset's pixels.
-Since the center of the profile is pre-defined, @mymath{\mu} and @mymath{d}
are constrained.
-@mymath{a} can also be found because the function has to be normalized.
-So the only important parameter for MakeProfiles is the @mymath{\sigma}.
-In the Gaussian function we have this relation between the FWHM and
@mymath{\sigma}:
+Recall that the total profile magnitude or brightness that is specified with
in the @option{--mcol} column of the input catalog is not an integration to
infinity, but the actual sum of pixels in the profile (until the desired
truncation radius).
+See @ref{Profile magnitude} for more on this point.
-@cindex Gaussian FWHM
-@dispmath{\rm{FWHM}_g=2\sqrt{2\ln{2}}\sigma \approx 2.35482\sigma}
+@item --magatpeak
+The magnitude column in the catalog (see @ref{MakeProfiles catalog}) will be
used to find the brightness only for the peak profile pixel, not the full
profile.
+Note that this is the flux of the profile's peak pixel in the final output of
MakeProfiles.
+So beware of the oversampling, see @ref{Oversampling}.
-@item Moffat
-@cindex Moffat function
-The Gaussian profile is much sharper than the images taken from stars on
photographic plates or CCDs.
-Therefore in 1969, Moffat proposed this functional form for the image of stars:
+This option can be useful if you want to check a mock profile's total
magnitude at various truncation radii.
+Without this option, no matter what the truncation radius is, the total
magnitude will be the same as that given in the catalog.
+But with this option, the total magnitude will become brighter as you increase
the truncation radius.
-@dispmath{f(r)=a \left[ 1+\left( r\over \alpha \right)^2 \right]^{-\beta}}
+In sharper profiles, sometimes the accuracy of measuring the peak profile flux
is more than the overall object brightness.
+In such cases, with this option, the final profile will be built such that its
peak has the given magnitude, not the total profile.
-@cindex Moffat beta
-Again, @mymath{a} is constrained by the normalization, therefore two
parameters define the shape of the Moffat function: @mymath{\alpha} and
@mymath{\beta}.
-The radial parameter is @mymath{\alpha} which is related to the FWHM by
+@cartouche
+@strong{CAUTION:} If you want to use this option for comparing with
observations, please note that MakeProfiles does not do convolution.
+Unless you have de-convolved your data, your images are convolved with the
instrument and atmospheric PSF, see @ref{PSF}.
+Particularly in sharper profiles, the flux in the peak pixel is strongly
decreased after convolution.
+Also note that in such cases, besides de-convolution, you will have to set
@option{--oversample=1} otherwise after resampling your profile with Warp (see
@ref{Warp}), the peak flux will be different.
+@end cartouche
-@cindex Moffat FWHM
-@dispmath{\rm{FWHM}_m=2\alpha\sqrt{2^{1/\beta}-1}}
+@item --customtable FITS/TXT
+The filename of the table to use in the custom profiles (see description of
@option{--fcol} in @ref{MakeProfiles catalog}.
+This can be a plain-text table, or FITS table, see @ref{Tables}, if its a FITS
table, you can use @option{--customtablehdu} to specify which HDU should be
used (described below).
-@cindex Compare Moffat and Gaussian
-@cindex PSF, Moffat compared Gaussian
-@noindent
-Comparing with the PSF predicted from atmospheric turbulence theory with a
Moffat function, Trujillo et al.@footnote{
-Trujillo, I., J. A. L. Aguerri, J. Cepa, and C. M. Gutierrez (2001). ``The
effects of seeing on S@'ersic profiles - II. The Moffat PSF''. In: MNRAS 328,
pp. 977---985.}
-claim that @mymath{\beta} should be 4.765.
-They also show how the Moffat PSF contains the Gaussian PSF as a limiting case
when @mymath{\beta\to\infty}.
+A custom profile can have any value you want for a given radial profile.
+Each interval is defined by its minimum (inclusive) and maximum (exclusive)
radius, when a pixel falls within this radius the value specified for that
interval will be used.
+If a pixel is not in the given intervals, a value of 0 will be used for it.
-@end table
+The table should have 3 columns as shown below.
+If the intervals are contiguous (the maximum value of the previous interval is
equal to the minimum value of an interval) and the intervals all have the same
size (difference between minimum and maximum values) the creation of these
profiles will be fast.
+However, if the intervals are not sorted and contiguous, Makeprofiles will
parse the intervals from the top of the table and use the first interval that
contains the pixel center.
-@item An input FITS image
-An input image file can also be specified to be used as a PSF.
-If the sum of its pixels are not equal to 1, the pixels will be multiplied by
a fraction so the sum does become 1.
+@table @asis
+@item Column 1:
+The interval's minimum radius.
+@item Column 2:
+The interval's maximum radius.
+@item Column 3:
+The value to be used for pixels within the given interval.
@end table
+For example let's assume you have the radial profile below in a file called
@file{radial.txt}.
+The first column is the larger interval radius and the second column is the
value in that interval:
-While the Gaussian is only dependent on the FWHM, the Moffat function is also
dependent on @mymath{\beta}.
-Comparing these two functions with a fixed FWHM gives the following results:
+@example
+1 100
+2 90
+3 50
+4 10
+5 2
+6 0.1
+7 0.05
+@end example
-@itemize
-@item
-Within the FWHM, the functions don't have significant differences.
-@item
-For a fixed FWHM, as @mymath{\beta} increases, the Moffat function becomes
sharper.
-@item
-The Gaussian function is much sharper than the Moffat functions, even when
@mymath{\beta} is large.
-@end itemize
+@noindent
+You can construct the table to give to @option{--customtable} with either of
the commands below: the first one with Gnuastro's @ref{Column arithmetic} which
can also work on FITS tables, and the second one with an AWK command that only
works on plain-text tables..
+@example
+asttable radial.fits -c'arith $1 1 -' -c1,2 -ocustom.fits
+awk '@{print $1-1, $1, $2@}' radial.txt > custom.txt
+@end example
+@noindent
+In case the intervals are different from 1 (for example 0.5), change them
respectively: for Gnuastro's table change @code{$1 1 -} to @code{$1 0.5 -} and
for AWK change @code{$1-1} to @code{$1-0.5}.
-@node Stars, Galaxies, PSF, Modeling basics
-@subsubsection Stars
+@item --customtablehdu INT/STR
+The HDU/extension in the FITS file given to @option{--customtable}.
-@cindex Modeling stars
-@cindex Stars, modeling
-In MakeProfiles, stars are generally considered to be a point source.
-This is usually the case for extra galactic studies, were nearby stars are
also in the field.
-Since a star is only a point source, we assume that it only fills one pixel
prior to convolution.
-In fact, exactly for this reason, in astronomical images the light profiles of
stars are one of the best methods to understand the shape of the PSF and a very
large fraction of scientific research is preformed by assuming the shapes of
stars to be the PSF of the image.
+@item -X INT,INT
+@itemx --shift=INT,INT
+Shift all the profiles and enlarge the image along each dimension.
+To better understand this option, please see @mymath{n} in @ref{If convolving
afterwards}.
+This is useful when you want to convolve the image afterwards.
+If you are using an external PSF, be sure to oversample it to the same scale
used for creating the mock images.
+If a background image is specified, any possible value to this option is
ignored.
+@item -c
+@itemx --prepforconv
+Shift all the profiles and enlarge the image based on half the width of the
first Moffat or Gaussian profile in the catalog, considering any possible
oversampling see @ref{If convolving afterwards}.
+@option{--prepforconv} is only checked and possibly activated if
@option{--xshift} and @option{--yshift} are both zero (after reading the
command-line and configuration files).
+If a background image is specified, any possible value to this option is
ignored.
+@item -z FLT
+@itemx --zeropoint=FLT
+The zero point magnitude of the input.
+For more on the zero point magnitude, see @ref{Brightness flux magnitude}.
+@item -w FLT
+@itemx --circumwidth=FLT
+The width of the circumference if the profile is to be an elliptical
circumference or annulus.
+See the explanations for this type of profile in @option{--fcol}.
+@item -R
+@itemx --replace
+Do not add the pixels of each profile over the background, or other profiles.
+But replace the values.
-@node Galaxies, Sampling from a function, Stars, Modeling basics
-@subsubsection Galaxies
+By default, when two profiles overlap, the final pixel value is the sum of all
the profiles that overlap on that pixel.
+This is the expected situation when dealing with physical object profiles like
galaxies or stars/PSF.
+However, when MakeProfiles is used to build integer labeled images (for
example in @ref{Aperture photometry}), this is not the expected situation: the
sum of two labels will be a new label.
+With this option, the pixels are not added but the largest (maximum) value
over that pixel is used.
+Because the maximum operator is independent of the order of values, the output
is also thread-safe.
-@cindex Galaxy profiles
-@cindex S@'ersic profile
-@cindex Profiles, galaxies
-@cindex Generalized de Vaucouleur profile
-Today, most practitioners agree that the flux of galaxies can be modeled with
one or a few generalized de Vaucouleur's (or S@'ersic) profiles.
+@end table
-@dispmath{I(r) = I_e \exp \left ( -b_n \left[ \left( r \over r_e \right)^{1/n}
-1 \right] \right )}
+@node MakeProfiles output dataset, MakeProfiles log file, MakeProfiles profile
settings, Invoking astmkprof
+@subsubsection MakeProfiles output dataset
+MakeProfiles takes an input catalog uses basic properties that are defined
there to build a dataset, for example a 2D image containing the profiles in the
catalog.
+In @ref{MakeProfiles catalog} and @ref{MakeProfiles profile settings}, the
catalog and profile settings were discussed.
+The options of this section, allow you to configure the output dataset (or the
canvas that will host the built profiles).
-@cindex Brightness
-@cindex S@'ersic, J. L.
-@cindex S@'ersic index
-@cindex Effective radius
-@cindex Radius, effective
-@cindex de Vaucouleur profile
-@cindex G@'erard de Vaucouleurs
-G@'erard de Vaucouleurs (1918-1995) was first to show in 1948 that this
function resembles the galaxy light profiles, with the only difference that he
held @mymath{n} fixed to a value of 4.
-Twenty years later in 1968, J. L. S@'ersic showed that @mymath{n} can have a
variety of values and does not necessarily need to be 4.
-This profile depends on the effective radius (@mymath{r_e}) which is defined
as the radius which contains half of the profile brightness (see @ref{Profile
magnitude}).
-@mymath{I_e} is the flux at the effective radius.
-The S@'ersic index @mymath{n} is used to define the concentration of the
profile within @mymath{r_e} and @mymath{b_n} is a constant dependent on
@mymath{n}.
-MacArthur et al.@footnote{MacArthur, L. A., S. Courteau, and J. A. Holtzman
(2003). ``Structure of Disk-dominated Galaxies. I. Bulge/Disk Parameters,
Simulations, and Secular Evolution''. In: ApJ 582, pp. 689---722.} show that
for @mymath{n>0.35}, @mymath{b_n} can be accurately approximated using this
equation:
+@table @option
-@dispmath{b_n=2n - {1\over 3} + {4\over 405n} + {46\over 25515n^2} + {131\over
1148175n^3}-{2194697\over 30690717750n^4}}
+@item -k FITS
+@itemx --background=FITS
+A background image FITS file to build the profiles on.
+The extension that contains the image should be specified with the
@option{--backhdu} option, see below.
+When a background image is specified, it will be used to derive all the
information about the output image.
+Hence, the following options will be ignored: @option{--mergedsize},
@option{--oversample}, @option{--crpix}, @option{--crval} (generally, all other
WCS related parameters) and the output's data type (see @option{--type} in
@ref{Input output options}).
+The image will act like a canvas to build the profiles on: profile pixel
values will be summed with the background image pixel values.
+With the @option{--replace} option you can disable this behavior and replace
the profile pixels with the background pixels.
+If you want to use all the image information above, except for the pixel
values (you want to have a blank canvas to build the profiles on, based on an
input image), you can call @option{--clearcanvas}, to set all the input image's
pixels to zero before starting to build the profiles over it (this is done in
memory after reading the input, so nothing will happen to your input file).
+@item -B STR/INT
+@itemx --backhdu=STR/INT
+The header data unit (HDU) of the file given to @option{--background}.
+@item -C
+@itemx --clearcanvas
+When an input image is specified (with the @option{--background} option, set
all its pixels to 0.0 immediately after reading it into memory.
+Effectively, this will allow you to use all its properties (described under
the @option{--background} option), without having to worry about the pixel
values.
+@option{--clearcanvas} can come in handy in many situations, for example if
you want to create a labeled image (segmentation map) for creating a catalog
(see @ref{MakeCatalog}).
+In other cases, you might have modeled the objects in an image and want to
create them on the same frame, but without the original pixel values.
-@node Sampling from a function, Oversampling, Galaxies, Modeling basics
-@subsubsection Sampling from a function
+@item -E STR/INT,FLT[,FLT,[...]]
+@itemx --kernel=STR/INT,FLT[,FLT,[...]]
+Only build one kernel profile with the parameters given as the values to this
option.
+The different values must be separated by a comma (@key{,}).
+The first value identifies the radial function of the profile, either through
a string or through a number (see description of @option{--fcol} in
@ref{MakeProfiles catalog}).
+Each radial profile needs a different total number of parameters: S@'ersic and
Moffat functions need 3 parameters: radial, S@'ersic index or Moffat
@mymath{\beta}, and truncation radius.
+The Gaussian function needs two parameters: radial and truncation radius.
+The point function doesn't need any parameters and flat and circumference
profiles just need one parameter (truncation radius).
-@cindex Sampling
-A pixel is the ultimate level of accuracy to gather data, we can't get any
more accurate in one image, this is known as sampling in signal processing.
-However, the mathematical profiles which describe our models have infinite
accuracy.
-Over a large fraction of the area of astrophysically interesting profiles (for
example galaxies or PSFs), the variation of the profile over the area of one
pixel is not too significant.
-In such cases, the elliptical radius (@mymath{r_{el}} of the center of the
pixel can be assigned as the final value of the pixel, see @ref{Defining an
ellipse and ellipsoid}).
+The PSF or kernel is a unique (and highly constrained) type of profile: the
sum of its pixels must be one, its center must be the center of the central
pixel (in an image with an odd number of pixels on each side), and commonly it
is circular, so its axis ratio and position angle are one and zero respectively.
+Kernels are commonly necessary for various data analysis and data manipulation
steps (for example see @ref{Convolve}, and @ref{NoiseChisel}.
+Because of this it is inconvenient to define a catalog with one row and many
zero valued columns (for all the non-necessary parameters).
+Hence, with this option, it is possible to create a kernel with MakeProfiles
without the need to create a catalog.
+Here are some examples:
-@cindex Integration over pixel
-@cindex Gradient over pixel area
-@cindex Function gradient over pixel area
-As you approach their center, some galaxies become very sharp (their value
significantly changes over one pixel's area).
-This sharpness increases with smaller effective radius and larger S@'ersic
values.
-Thus rendering the central value extremely inaccurate.
-The first method that comes to mind for solving this problem is integration.
-The functional form of the profile can be integrated over the pixel area in a
2D integration process.
-However, unfortunately numerical integration techniques also have their
limitations and when such sharp profiles are needed they can become extremely
inaccurate.
+@table @option
+@item --kernel=moffat,3,2.8,5
+A Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is truncated
at 5 times the FWHM.
-@cindex Monte carlo integration
-The most accurate method of sampling a continuous profile on a discrete space
is by choosing a large number of random points within the boundaries of the
pixel and taking their average value (or Monte Carlo integration).
-This is also, generally speaking, what happens in practice with the photons on
the pixel.
-The number of random points can be set with @option{--numrandom}.
+@item --kernel=gaussian,2,3
+A circular Gaussian kernel with FWHM of 2 pixels and truncated at 3 times
+the FWHM.
+@end table
-Unfortunately, repeating this Monte Carlo process would be extremely time and
CPU consuming if it is to be applied to every pixel.
-In order to not loose too much accuracy, in MakeProfiles, the profile is built
using both methods explained below.
-The building of the profile begins from its central pixel and continues
(radially) outwards.
-Monte Carlo integration is first applied (which yields @mymath{F_r}), then the
central pixel value (@mymath{F_c}) is calculated on the same pixel.
-If the fractional difference (@mymath{|F_r-F_c|/F_r}) is lower than a given
tolerance level (specified with @option{--tolerance}) MakeProfiles will stop
using Monte Carlo integration and only use the central pixel value.
+This option may also be used to create a 3D kernel.
+To do that, two small modifications are necessary: add a @code{-3d} (or
@code{-3D}) to the profile name (for example @code{moffat-3d}) and add a number
(axis-ratio along the third dimension) to the end of the parameters for all
profiles except @code{point}.
+The main reason behind providing an axis ratio in the third dimension is that
in 3D astronomical datasets, commonly the third dimension doesn't have the same
nature (units/sampling) as the first and second.
-@cindex Inside-out construction
-The ordering of the pixels in this inside-out construction is based on
@mymath{r=\sqrt{(i_c-i)^2+(j_c-j)^2}}, not @mymath{r_{el}}, see @ref{Defining
an ellipse and ellipsoid}.
-When the axis ratios are large (near one) this is fine.
-But when they are small and the object is highly elliptical, it might seem
more reasonable to follow @mymath{r_{el}} not @mymath{r}.
-The problem is that the gradient is stronger in pixels with smaller @mymath{r}
(and larger @mymath{r_{el}}) than those with smaller @mymath{r_{el}}.
-In other words, the gradient is strongest along the minor axis.
-So if the next pixel is chosen based on @mymath{r_{el}}, the tolerance level
will be reached sooner and lots of pixels with large fractional differences
will be missed.
+For example in IFU datacubes, the first and second dimensions are
angularpositions (like RA and Dec) but the third is in units of Angstroms for
wavelength.
+Because of this different nature (which also affects theprocessing), it may be
necessary for the kernel to have a different extent in that direction.
-Monte Carlo integration uses a random number of points.
-Thus, every time you run it, by default, you will get a different distribution
of points to sample within the pixel.
-In the case of large profiles, this will result in a slight difference of the
pixels which use Monte Carlo integration each time MakeProfiles is run.
-To have a deterministic result, you have to fix the random number generator
properties which is used to build the random distribution.
-This can be done by setting the @code{GSL_RNG_TYPE} and @code{GSL_RNG_SEED}
environment variables and calling MakeProfiles with the @option{--envseed}
option.
-To learn more about the process of generating random numbers, see
@ref{Generating random numbers}.
+If the 3rd dimension axis ratio is equal to @mymath{1.0}, then the kernel will
be a spheroid.
+If its smaller than @mymath{1.0}, the kernel will be button-shaped: extended
less in the third dimension.
+However, when it islarger than @mymath{1.0}, the kernel will be bullet-shaped:
extended more in the third dimension.
+In the latter case, the radial parameter will correspond to the length along
the 3rd dimension.
+For example, let's have a look at the two examples above but in 3D:
-@cindex Seed, Random number generator
-@cindex Random number generator, Seed
-The seed values are fixed for every profile: with @option{--envseed}, all the
profiles have the same seed and without it, each will get a different seed
using the system clock (which is accurate to within one microsecond).
-The same seed will be used to generate a random number for all the sub-pixel
positions of all the profiles.
-So in the former, the sub-pixel points checked for all the pixels undergoing
Monte carlo integration in all profiles will be identical.
-In other words, the sub-pixel points in the first (closest to the center)
pixel of all the profiles will be identical with each other.
-All the second pixels studied for all the profiles will also receive an
identical (different from the first pixel) set of sub-pixel points and so on.
-As long as the number of random points used is large enough or the profiles
are not identical, this should not cause any systematic bias.
+@table @option
+@item --kernel=moffat-3d,3,2.8,5,0.5
+An ellipsoid Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is
truncated at 5 times the FWHM.
+The ellipsoid is circular in the first two dimensions, but in the third
dimension its extent is half the first two.
+@item --kernel=gaussian-3d,2,3,1
+A spherical Gaussian kernel with FWHM of 2 pixels and truncated at 3 times
+the FWHM.
+@end table
-@node Oversampling, , Sampling from a function, Modeling basics
-@subsubsection Oversampling
+Ofcourse, if a specific kernel is needed that doesn't fit the constraints
imposed by this option, you can always use a catalog to define any arbitrary
kernel.
+Just call the @option{--individual} and @option{--nomerged} options to make
sure that it is built as a separate file (individually) and no ``merged'' image
of the input profiles is created.
-@cindex Oversampling
-The steps explained in @ref{Sampling from a function} do give an accurate
representation of a profile prior to convolution.
-However, in an actual observation, the image is first convolved with or
blurred by the atmospheric and instrument PSF in a continuous space and then it
is sampled on the discrete pixels of the camera.
+@item -x INT,INT
+@itemx --mergedsize=INT,INT
+The number of pixels along each axis of the output, in FITS order.
+This is before over-sampling.
+For example if you call MakeProfiles with @option{--mergedsize=100,150
--oversample=5} (assuming no shift due for later convolution), then the final
image size along the first axis will be 500 by 750 pixels.
+Fractions are acceptable as values for each dimension, however, they must
reduce to an integer, so @option{--mergedsize=150/3,300/3} is acceptable but
@option{--mergedsize=150/4,300/4} is not.
-@cindex PSF over-sample
-In order to more accurately simulate this process, the unconvolved image and
the PSF are created on a finer pixel grid.
-In other words, the output image is a certain odd-integer multiple of the
desired size, we can call this `oversampling'.
-The user can specify this multiple as a command-line option.
-The reason this has to be an odd number is that the PSF has to be centered on
the center of its image.
-An image with an even number of pixels on each side does not have a central
pixel.
+When viewing a FITS image in DS9, the first FITS dimension is in the
horizontal direction and the second is vertical.
+As an example, the image created with the example above will have 500 pixels
horizontally and 750 pixels vertically.
-The image can then be convolved with the PSF (which should also be oversampled
on the same scale).
-Finally, image can be sub-sampled to get to the initial desired pixel size of
the output image.
-After this, mock noise can be added as explained in the next section.
-This is because unlike the PSF, the noise occurs in each output pixel, not on
a continuous space like all the prior steps.
+If a background image is specified, this option is ignored.
+@item -s INT
+@itemx --oversample=INT
+The scale to over-sample the profiles and final image.
+If not an odd number, will be added by one, see @ref{Oversampling}.
+Note that this @option{--oversample} will remain active even if an input image
is specified.
+If your input catalog is based on the background image, be sure to set
@option{--oversample=1}.
+@item --psfinimg
+Build the possibly existing PSF profiles (Moffat or Gaussian) in the catalog
into the final image.
+By default they are built separately so you can convolve your images with
them, thus their magnitude and positions are ignored.
+With this option, they will be built in the final image like every other
galaxy profile.
+To have a final PSF in your image, make a point profile where you want the PSF
and after convolution it will be the PSF.
+@item -i
+@itemx --individual
+@cindex Individual profiles
+@cindex Build individual profiles
+If this option is called, each profile is created in a separate FITS file
within the same directory as the output and the row number of the profile
(starting from zero) in the name.
+The file for each row's profile will be in the same directory as the final
combined image of all the profiles and will have the final image's name as a
suffix.
+So for example if the final combined image is named
@file{./out/fromcatalog.fits}, then the first profile that will be created with
this option will be named @file{./out/0_fromcatalog.fits}.
-@node If convolving afterwards, Brightness flux magnitude, Modeling basics,
MakeProfiles
-@subsection If convolving afterwards
+Since each image only has one full profile out to the truncation radius the
profile is centered and so, only the sub-pixel position of the profile center
is important for the outputs of this option.
+The output will have an odd number of pixels.
+If there is no oversampling, the central pixel will contain the profile center.
+If the value to @option{--oversample} is larger than unity, then the profile
center is on any of the central @option{--oversample}'d pixels depending on the
fractional value of the profile center.
-In case you want to convolve the image later with a given point spread
function, make sure to use a larger image size.
-After convolution, the profiles become larger and a profile that is normally
completely outside of the image might fall within it.
+If the fractional value is larger than half, it is on the bottom half of the
central region.
+This is due to the FITS definition of a real number position: The center of a
pixel has fractional value @mymath{0.00} so each pixel contains these
fractions: .5 -- .75 -- .00 (pixel center) -- .25 -- .5.
-On one axis, if you want your final (convolved) image to be @mymath{m} pixels
and your PSF is @mymath{2n+1} pixels wide, then when calling MakeProfiles, set
the axis size to @mymath{m+2n}, not @mymath{m}.
-You also have to shift all the pixel positions of the profile centers on the
that axis by @mymath{n} pixels to the positive.
+@item -m
+@itemx --nomerged
+Don't make a merged image.
+By default after making the profiles, they are added to a final image with
side lengths specified by @option{--mergedsize} if they overlap with it.
-After convolution, you can crop the outer @mymath{n} pixels with the section
crop box specification of Crop: @option{--section=n:*-n,n:*-n} assuming your
PSF is a square, see @ref{Crop section syntax}.
-This will also remove all discrete Fourier transform artifacts (blurred sides)
from the final image.
-To facilitate this shift, MakeProfiles has the options @option{--xshift},
@option{--yshift} and @option{--prepforconv}, see @ref{Invoking astmkprof}.
+@end table
+@noindent
+The options below can be used to define the world coordinate system (WCS)
properties of the MakeProfiles outputs.
+The option names are deliberately chosen to be the same as the FITS standard
WCS keywords.
+See Section 8 of @url{https://doi.org/10.1051/0004-6361/201015362, Pence et al
[2010]} for a short introduction to WCS in the FITS standard@footnote{The world
coordinate standard in FITS is a very beautiful and powerful concept to
link/associate datasets with the outside world (other datasets).
+The description in the FITS standard (link above) only touches the tip of the
ice-burg.
+To learn more please see @url{https://doi.org/10.1051/0004-6361:20021326,
Greisen and Calabretta [2002]},
@url{https://doi.org/10.1051/0004-6361:20021327, Calabretta and Greisen
[2002]}, @url{https://doi.org/10.1051/0004-6361:20053818, Greisen et al.
[2006]}, and
@url{http://www.atnf.csiro.au/people/mcalabre/WCS/dcs_20040422.pdf, Calabretta
et al.}}.
+If you look into the headers of a FITS image with WCS for example you will see
all these names but in uppercase and with numbers to represent the dimensions,
for example @code{CRPIX1} and @code{PC2_1}.
+You can see the FITS headers with Gnuastro's @ref{Fits} program using a
command like this: @command{$ astfits -p image.fits}.
-@node Brightness flux magnitude, Profile magnitude, If convolving afterwards,
MakeProfiles
-@subsection Brightness, Flux, Magnitude and Surface brightness
+If the values given to any of these options does not correspond to the number
of dimensions in the output dataset, then no WCS information will be added.
-@cindex ADU
-@cindex Gain
-@cindex Counts
-Astronomical data pixels are usually in units of counts@footnote{Counts are
also known as analog to digital units (ADU).} or electrons or either one
divided by seconds.
-To convert from the counts to electrons, you will need to know the instrument
gain.
-In any case, they can be directly converted to energy or energy/time using the
basic hardware (telescope, camera and filter) information.
-We will continue the discussion assuming the pixels are in units of
energy/time.
+@table @option
-@cindex Flux
-@cindex Luminosity
-@cindex Brightness
-The @emph{brightness} of an object is defined as its total detected energy per
time.
-In the case of an imaged source, this is simply the sum of the pixels that are
associated with that detection by our detection tool (for example
@ref{NoiseChisel}@footnote{If further processing is done, for example the Kron
or Petrosian radii are calculated, then the detected area is not sufficient and
the total area that was within the respective radius must be used.}).
-The @emph{flux} of an object is defined in units of
energy/time/collecting-area.
-For an astronomical target, the flux is therefore defined as its brightness
divided by the area used to collect the light from the source: or the telescope
aperture (for example in units of @mymath{cm^2}).
-Knowing the flux (@mymath{f}) and distance to the object (@mymath{r}), we can
define its @emph{luminosity}: @mymath{L=4{\pi}r^2f}.
+@item --crpix=FLT,FLT
+The pixel coordinates of the WCS reference point.
+Fractions are acceptable for the values of this option.
-Therefore, while flux and luminosity are intrinsic properties of the object,
brightness depends on our detecting tools (hardware and software).
-In low-level observational astronomy data analysis, we are usually more
concerned with measuring the brightness, because it is the thing we directly
measure from the image pixels and create in catalogs.
-On the other hand, luminosity is used in higher-level analysis (after image
contents are measured as catalogs to deduce physical interpretations).
-It is just important avoid possible confusion between luminosity and
brightness because both have the same units of energy per seconds.
+@item --crval=FLT,FLT
+The WCS coordinates of the Reference point.
+Fractions are acceptable for the values of this option.
-@cindex Magnitudes from flux
-@cindex Flux to magnitude conversion
-@cindex Astronomical Magnitude system
-Images of astronomical objects span over a very large range of brightness.
-With the Sun (as the brightest object) being roughly @mymath{2.5^{60}=10^{24}}
times brighter than the fainter galaxies we can currently detect in the deepest
images.
-Therefore discussing brightness directly will involve a large range of values
which is inconvenient.
-So astronomers have chosen to use a logarithmic scale to talk about the
brightness of astronomical objects.
+@item --cdelt=FLT,FLT
+The resolution (size of one data-unit or pixel in WCS units) of the
non-oversampled dataset.
+Fractions are acceptable for the values of this option.
-@cindex Hipparchus of Nicaea
-But the logarithm can only be usable with a dimensionless value that is always
positive.
-Fortunately brightness is always positive (at least in theory@footnote{In
practice, for very faint objects, if the background brightness is
over-subtracted, we may end up with a negative brightness in a real object.}).
-To remove the dimensions, we divide the brightness of the object (@mymath{B})
by a reference brightness (@mymath{B_r}).
-We then define a logarithmic scale as @mymath{magnitude} through the relation
below.
-The @mymath{-2.5} factor in the definition of magnitudes is a legacy of the
our ancient colleagues and in particular Hipparchus of Nicaea (190-120 BC).
+@item --pc=FLT,FLT,FLT,FLT
+The PC matrix of the WCS rotation, see the FITS standard (link above) to
better understand the PC matrix.
-@dispmath{m-m_r=-2.5\log_{10} \left( B \over B_r \right)}
+@item --cunit=STR,STR
+The units of each WCS axis, for example @code{deg}.
+Note that these values are part of the FITS standard (link above).
+MakeProfiles won't complain if you use non-standard values, but later usage of
them might cause trouble.
-@cindex Zero point magnitude
-@cindex Magnitude zero point
-@noindent
-@mymath{m} is defined as the magnitude of the object and @mymath{m_r} is the
pre-defined magnitude of the reference brightness.
-One particularly easy condition is when the reference brightness is unity
(@mymath{B_r=1}).
-This brightness will thus summarize all the hardware-specific parameters
discussed above (like the conversion of pixel values to physical units) into
one number.
-That reference magnitude which is commonly known as the @emph{Zero point}
magnitude (because when @mymath{B=Br=1}, the right side of the magnitude
definition above will be zero).
-Using the zero point magnitude (@mymath{Z}), we can write the magnitude
relation above in a more simpler format:
+@item --ctype=STR,STR
+The type of each WCS axis, for example @code{RA---TAN} and @code{DEC--TAN}.
+Note that these values are part of the FITS standard (link above).
+MakeProfiles won't complain if you use non-standard values, but later usage of
them might cause trouble.
-@dispmath{m = -2.5\log_{10}(B) + Z}
+@end table
-@cindex Janskys (Jy)
-@cindex AB magnitude
-@cindex Magnitude, AB
-Having the zero point of an image, you can convert its pixel values to
physical units of microJanskys (or @mymath{\mu{}Jy}) to enable direct
pixel-based comparisons with images from other instruments (just note that this
assumes instrument and observation signatures are corrected, things like the
flat-field or the Sky).
-This conversion can be done with the fact that in the AB magnitude
standard@footnote{@url{https://en.wikipedia.org/wiki/AB_magnitude}},
@mymath{3631Jy} corresponds to the zero-th magnitude, therefore
@mymath{B\equiv3631\times10^{6}\mu{Jy}} and @mymath{m\equiv0}.
-We can therefore estimate the brightness (@mymath{B_z}, in @mymath{\mu{Jy}})
corresponding to the image zero point (@mymath{Z}) using this equation:
+@node MakeProfiles log file, , MakeProfiles output dataset, Invoking astmkprof
+@subsubsection MakeProfiles log file
+
+Besides the final merged dataset of all the profiles, or the individual
datasets (see @ref{MakeProfiles output dataset}), if the @option{--log} option
is called MakeProfiles will also create a log file in the current directory
(where you run MockProfiles).
+See @ref{Common options} for a full description of @option{--log} and other
options that are shared between all Gnuastro programs.
+The values for each column are explained in the first few commented lines of
the log file (starting with @command{#} character).
+Here is a more complete description.
+
+@itemize
+@item
+An ID (row number of profile in input catalog).
-@dispmath{m - Z = -2.5\log_{10}(B/B_z)}
-@dispmath{0 - Z = -2.5\log_{10}({3631\times10^{6}\over B_z})}
-@dispmath{B_z = 3631\times10^{\left(6 - {Z \over 2.5} \right)} \mu{Jy}}
+@item
+The total magnitude of the profile in the output dataset.
+When the profile does not completely overlap with the output dataset, this
will be different from your input magnitude.
-@cindex SDSS
-Because the image zero point corresponds to a pixel value of @mymath{1}, the
@mymath{B_z} value calculated above also corresponds to a pixel value of
@mymath{1}.
-Therefore you simply have to multiply your image by @mymath{B_z} to convert it
to @mymath{\mu{Jy}}.
-Don't forget that this only applies when your zero point was also estimated in
the AB magnitude system.
-On the command-line, you can easily estimate this value for a certain zero
point with AWK, then multiply it to all the pixels in the image with
@ref{Arithmetic}.
-For example let's assume you are using an SDSS image with a zero point of 22.5:
+@item
+The number of pixels (in the oversampled image) which used Monte Carlo
integration and not the central pixel value, see @ref{Sampling from a function}.
-@example
-bz=$(echo 22.5 | awk '@{print 3631 * 10^(6-$1/2.5)@}')
-astarithmetic sdss.fits $bz x --output=sdss-in-muJy.fits
-@end example
+@item
+The fraction of flux in the Monte Carlo integrated pixels.
-@cindex Steradian
-@cindex Angular coverage
-@cindex Celestial sphere
-@cindex Surface brightness
-@cindex SI (International System of Units)
-Another important concept is the distribution of an object's brightness over
its area.
-For this, we define the @emph{surface brightness} to be the magnitude of an
object's brightness divided by its solid angle over the celestial sphere (or
coverage in the sky, commonly in units of arcsec@mymath{^2}).
-The solid angle is expressed in units of arcsec@mymath{^2} because
astronomical targets are usually much smaller than one steradian.
-Recall that the steradian is the dimension-less SI unit of a solid angle and 1
steradian covers @mymath{1/4\pi} (almost @mymath{8\%}) of the full celestial
sphere.
+@item
+If an individual image was created, this column will have a value of @code{1},
otherwise it will have a value of @code{0}.
+@end itemize
-Surface brightness is therefore most commonly expressed in units of
mag/arcsec@mymath{2}.
-For example when the brightness is measured over an area of A
arcsec@mymath{^2}, then the surface brightness becomes:
-@dispmath{S = -2.5\log_{10}(B/A) + Z = -2.5\log_{10}(B) + 2.5\log_{10}(A) + Z}
-@noindent
-In other words, the surface brightness (in units of mag/arcsec@mymath{^2}) is
related to the object's magnitude (@mymath{m}) and area (@mymath{A}, in units
of arcsec@mymath{^2}) through this equation:
-@dispmath{S = m + 2.5\log_{10}(A)}
-A common mistake is to follow the mag/arcsec@mymath{^2} unit literally, and
divide the object's magnitude by its area.
-But this is wrong because magnitude is a logarithmic scale while area is
linear.
-It is the brightness that should be divided by the solid angle because both
have linear scales.
-The magnitude of that ratio is then defined to be the surface brightness.
-@node Profile magnitude, Invoking astmkprof, Brightness flux magnitude,
MakeProfiles
-@subsection Profile magnitude
-@cindex Brightness
-@cindex Truncation radius
-@cindex Sum for total flux
-To find the profile brightness or its magnitude, (see @ref{Brightness flux
magnitude}), it is customary to use the 2D integration of the flux to infinity.
-However, in MakeProfiles we do not follow this idealistic approach and apply a
more realistic method to find the total brightness or magnitude: the sum of all
the pixels belonging to a profile within its predefined truncation radius.
-Note that if the truncation radius is not large enough, this can be
significantly different from the total integrated light to infinity.
-@cindex Integration to infinity
-An integration to infinity is not a realistic condition because no galaxy
extends indefinitely (important for high S@'ersic index profiles), pixelation
can also cause a significant difference between the actual total pixel sum
value of the profile and that of integration to infinity, especially in small
and high S@'ersic index profiles.
-To be safe, you can specify a large enough truncation radius for such compact
high S@'ersic index profiles.
-If oversampling is used then the brightness is calculated using the
over-sampled image, see @ref{Oversampling} which is much more accurate.
-The profile is first built in an array completely bounding it with a
normalization constant of unity (see @ref{Galaxies}).
-Taking @mymath{B} to be the desired brightness and @mymath{S} to be the sum of
the pixels in the created profile, every pixel is then multiplied by
@mymath{B/S} so the sum is exactly @mymath{B}.
-If the @option{--individual} option is called, this same array is written to a
FITS file.
-If not, only the overlapping pixels of this array and the output image are
kept and added to the output array.
+@node MakeNoise, , MakeProfiles, Modeling and fittings
+@section MakeNoise
+@cindex Noise
+Real data are always buried in noise, therefore to finalize a simulation of
real data (for example to test our observational algorithms) it is essential to
add noise to the mock profiles created with MakeProfiles, see
@ref{MakeProfiles}.
+Below, the general principles and concepts to help understand how noise is
quantified is discussed.
+MakeNoise options and argument are then discussed in @ref{Invoking astmknoise}.
+@menu
+* Noise basics:: Noise concepts and definitions.
+* Invoking astmknoise:: Options and arguments to MakeNoise.
+@end menu
-@node Invoking astmkprof, , Profile magnitude, MakeProfiles
-@subsection Invoking MakeProfiles
-MakeProfiles will make any number of profiles specified in a catalog either
individually or in one image.
-The executable name is @file{astmkprof} with the following general template
+@node Noise basics, Invoking astmknoise, MakeNoise, MakeNoise
+@subsection Noise basics
-@example
-$ astmkprof [OPTION ...] [Catalog]
-@end example
+@cindex Noise
+@cindex Image noise
+Deep astronomical images, like those used in extragalactic studies, seriously
suffer from noise in the data.
+Generally speaking, the sources of noise in an astronomical image are photon
counting noise and Instrumental noise which are discussed in @ref{Photon
counting noise} and @ref{Instrumental noise}.
+This review finishes with @ref{Generating random numbers} which is a short
introduction on how random numbers are generated.
+We will see that while software random number generators are not perfect, they
allow us to obtain a reproducible series of random numbers through setting the
random number generator function and seed value.
+Therefore in this section, we'll also discuss how you can set these two
parameters in Gnuastro's programs (including MakeNoise).
-@noindent
-One line examples:
+@menu
+* Photon counting noise:: Poisson noise
+* Instrumental noise:: Readout, dark current and other sources.
+* Final noised pixel value:: How the final noised value is calculated.
+* Generating random numbers:: How random numbers are generated.
+@end menu
-@example
-## Make an image with profiles in catalog.txt (with default size):
-$ astmkprof catalog.txt
+@node Photon counting noise, Instrumental noise, Noise basics, Noise basics
+@subsubsection Photon counting noise
-## Make the profiles in catalog.txt over image.fits:
-$ astmkprof --background=image.fits catalog.txt
+@cindex Counting error
+@cindex de Moivre, Abraham
+@cindex Poisson distribution
+@cindex Photon counting noise
+@cindex Poisson, Sim@'eon Denis
+With the very accurate electronics used in today's detectors, photon counting
noise@footnote{In practice, we are actually counting the electrons that are
produced by each photon, not the actual photons.} is the most significant
source of uncertainty in most datasets.
+To understand this noise (error in counting), we need to take a closer look at
how a distribution produced by counting can be modeled as a parametric function.
-## Make a Moffat PSF with FWHM 3pix, beta=2.8, truncation=5
-$ astmkprof --kernel=moffat,3,2.8,5 --oversample=1
+Counting is an inherently discrete operation, which can only produce positive
(including zero) integer outputs.
+For example we can't count @mymath{3.2} or @mymath{-2} of anything.
+We only count @mymath{0}, @mymath{1}, @mymath{2}, @mymath{3} and so on.
+The distribution of values, as a result of counting efforts is formally known
as the @url{https://en.wikipedia.org/wiki/Poisson_distribution, Poisson
distribution}.
+It is associated to Sim@'eon Denis Poisson, because he discussed it while
working on the number of wrongful convictions in court cases in his 1837
book@footnote{[From Wikipedia] Poisson's result was also derived in a previous
study by Abraham de Moivre in 1711.
+Therefore some people suggest it should rightly be called the de Moivre
distribution.}.
-## Make profiles in catalog, using RA and Dec in the given column:
-$ astmkprof --ccol=RA_CENTER --ccol=DEC_CENTER --mode=wcs catalog.txt
+@cindex Probability density function
+Let's take @mymath{\lambda} to represent the expected mean count of something.
+Furthermore, let's take @mymath{k} to represent the result of one particular
counting attempt.
+The probability density function of getting @mymath{k} counts (in each
attempt, given the expected/mean count of @mymath{\lambda}) can be written as:
-## Make a 1500x1500 merged image (oversampled 500x500) image along
-## with an individual image for all the profiles in catalog:
-$ astmkprof --individual --oversample 3 --mergedsize=500,500 cat.txt
-@end example
+@cindex Poisson distribution
+@dispmath{f(k)={\lambda^k \over k!} e^{-\lambda},\quad k\in @{0, 1, 2, 3,
\dots @}}
-@noindent
-The parameters of the mock profiles can either be given through a catalog
(which stores the parameters of many mock profiles, see @ref{MakeProfiles
catalog}), or the @option{--kernel} option (see @ref{MakeProfiles output
dataset}).
-The catalog can be in the FITS ASCII, FITS binary format, or plain text
formats (see @ref{Tables}).
-A plain text catalog can also be provided using the Standard input (see
@ref{Standard input}).
-The columns related to each parameter can be determined both by number, or by
match/search criteria using the column names, units, or comments, with the
options ending in @option{col}, see below.
+@cindex Skewed Poisson distribution
+Because the Poisson distribution is only applicable to positive values (note
the factorial operator, which only applies to non-negative integers), naturally
it is very skewed when @mymath{\lambda} is near zero.
+One qualitative way to understand this behavior is that there simply aren't
enough integers smaller than @mymath{\lambda}, than integers that are larger
than it.
+Therefore to accommodate all possibilities/counts, it has to be strongly
skewed when @mymath{\lambda} is small.
-Without any file given to the @option{--background} option, MakeProfiles will
make a zero-valued image and build the profiles on that (its size and main WCS
parameters can also be defined through the options described in
@ref{MakeProfiles output dataset}).
-Besides the main/merged image containing all the profiles in the catalog, it
is also possible to build individual images for each profile (only enclosing
one full profile to its truncation radius) with the @option{--individual}
option.
+@cindex Compare Poisson and Gaussian
+As @mymath{\lambda} becomes larger, the distribution becomes more and more
symmetric.
+A very useful property of the Poisson distribution is that the mean value is
also its variance.
+When @mymath{\lambda} is very large, say @mymath{\lambda>1000}, then the
@url{https://en.wikipedia.org/wiki/Normal_distribution, Normal (Gaussian)
distribution}, is an excellent approximation of the Poisson distribution with
mean @mymath{\mu=\lambda} and standard deviation @mymath{\sigma=\sqrt{\lambda}}.
+In other words, a Poisson distribution (with a sufficiently large
@mymath{\lambda}) is simply a Gaussian that only has one free parameter
(@mymath{\mu=\lambda} and @mymath{\sigma=\sqrt{\lambda}}), instead of the two
parameters (independent @mymath{\mu} and @mymath{\sigma}) that it originally
has.
-If an image is given to the @option{--background} option, the pixels of that
image are used as the background value for every pixel hence flux value of each
profile pixel will be added to the pixel in that background value.
-You can disable this with the @code{--clearcanvas} option (which will
initialize the background to zero-valued pixels and build profiles over that).
-With the @option{--background} option, the values to all options relating to
the ``canvas'' (output size and WCS) will be ignored if specified, for example
@option{--oversample}, @option{--mergedsize}, and @option{--prepforconv}.
+@cindex Sky value
+@cindex Background flux
+@cindex Undetected objects
+In real situations, the photons/flux from our targets are added to a certain
background flux (observationally, the @emph{Sky} value).
+The Sky value is defined to be the average flux of a region in the dataset
with no targets.
+Its physical origin can be the brightness of the atmosphere (for ground-based
instruments), possible stray light within the imaging instrument, the average
flux of undetected targets, etc.
+The Sky value is thus an ideal definition, because in real datasets, what lies
deep in the noise (far lower than the detection limit) is never
known@footnote{In a real image, a relatively large number of very faint objects
can been fully buried in the noise and never detected.
+These undetected objects will bias the background measurement to slightly
larger values.
+Our best approximation is thus to simply assume they are uniform, and consider
their average effect.
+See Figure 1 (a.1 and a.2) and Section 2.2 in
@url{https://arxiv.org/abs/1505.01664, Akhlaghi and Ichikawa [2015]}.}.
+To account for all of these, the sky value is defined to be the average
count/value of the undetected regions in the image.
+In a mock image/dataset, we have the luxury of setting the background (Sky)
value.
-The sections below discuss the options specific to MakeProfiles based on
context: the input catalog settings which can have many rows for different
profiles are discussed in @ref{MakeProfiles catalog}, in @ref{MakeProfiles
profile settings}, we discuss how you can set general profile settings (that
are the same for all the profiles in the catalog).
-Finally @ref{MakeProfiles output dataset} and @ref{MakeProfiles log file}
discuss the outputs of MakeProfiles and how you can configure them.
-Besides these, MakeProfiles also supports all the common Gnuastro program
options that are discussed in @ref{Common options}, so please flip through them
is well for a more comfortable usage.
+@cindex Simulating noise
+@cindex Noise simulation
+In each element of the dataset (pixel in an image), the flux is the sum of
contributions from various sources (after convolution by the PSF, see
@ref{PSF}).
+Let's name the convolved sum of possibly overlapping objects, @mymath{I_{nn}}.
+@mymath{nn} representing `no noise'.
+For now, let's assume the background (@mymath{B}) is constant and sufficiently
high for the Poisson distribution to be approximated by a Gaussian.
+Then the flux after adding noise is a random value taken from a Gaussian
distribution with the following mean (@mymath{\mu}) and standard deviation
(@mymath{\sigma}):
-When building 3D profiles, there are more degrees of freedom.
-Hence, more columns are necessary and all the values related to dimensions
(for example size of dataset in each dimension and the WCS properties) must
also have 3 values.
-To allow having an independent set of default values for creating 3D profiles,
MakeProfiles also installs a @file{astmkprof-3d.conf} configuration file (see
@ref{Configuration files}).
-You can use this for default 3D profile values.
-For example, if you installed Gnuastro with the prefix @file{/usr/local} (the
default location, see @ref{Installation directory}), you can benefit from this
configuration file by running MakeProfiles like the example below.
-As with all configuration files, if you want to customize a given option, call
it before the configuration file.
+@dispmath{\mu=B+I_{nn}, \quad \sigma=\sqrt{B+I_{nn}}}
-@example
-$ astmkprof --config=/usr/local/etc/astmkprof-3d.conf catalog.txt
-@end example
+Since this type of noise is inherent in the objects we study, it is usually
measured on the same scale as the astronomical objects, namely the magnitude
system, see @ref{Brightness flux magnitude}.
+It is then internally converted to the flux scale for further processing.
-@cindex Shell alias
-@cindex Alias, shell
-@cindex Shell startup
-@cindex Startup, shell
-To further simplify the process, you can define a shell alias in any startup
file (for example @file{~/.bashrc}, see @ref{Installation directory}).
-Assuming that you installed Gnuastro in @file{/usr/local}, you can add this
line to the startup file (you may put it all in one line, it is broken into two
lines here for fitting within page limits).
+@node Instrumental noise, Final noised pixel value, Photon counting noise,
Noise basics
+@subsubsection Instrumental noise
-@example
-alias astmkprof-3d="astmkprof --config=/usr/local/etc/astmkprof-3d.conf"
-@end example
+@cindex Readout noise
+@cindex Instrumental noise
+@cindex Noise, instrumental
+While taking images with a camera, a dark current is fed to the pixels, the
variation of the value of this dark current over the pixels, also adds to the
final image noise.
+Another source of noise is the readout noise that is produced by the
electronics in the detector.
+Specifically, the parts that attempt to digitize the voltage produced by the
photo-electrons in the analog to digital converter.
+With the current generation of instruments, this source of noise is not as
significant as the noise due to the background Sky discussed in @ref{Photon
counting noise}.
-@noindent
-Using this alias, you can call MakeProfiles with the name
@command{astmkprof-3d} (instead of @command{astmkprof}).
-It will automatically load the 3D specific configuration file first, and then
parse any other arguments, options or configuration files.
-You can change the default values in this 3D configuration file by calling
them on the command-line as you do with @command{astmkprof}@footnote{Recall
that for single-invocation options, the last command-line invocation takes
precedence over all previous invocations (including those in the 3D
configuration file).
-See the description of @option{--config} in @ref{Operating mode options}.}.
+Let @mymath{C} represent the combined standard deviation of all these
instrumental sources of noise.
+When only this source of noise is present, the noised pixel value would be a
random value chosen from a Gaussian distribution with
-Please see @ref{Sufi simulates a detection} for a very complete tutorial
explaining how one could use MakeProfiles in conjunction with other Gnuastro's
programs to make a complete simulated image of a mock galaxy.
+@dispmath{\mu=I_{nn}, \quad \sigma=\sqrt{C^2+I_{nn}}}
-@menu
-* MakeProfiles catalog:: Required catalog properties.
-* MakeProfiles profile settings:: Configuration parameters for all profiles.
-* MakeProfiles output dataset:: The canvas/dataset to build profiles over.
-* MakeProfiles log file:: A description of the optional log file.
-@end menu
+@cindex ADU
+@cindex Gain
+@cindex Counts
+This type of noise is independent of the signal in the dataset, it is only
determined by the instrument.
+So the flux scale (and not magnitude scale) is most commonly used for this
type of noise.
+In practice, this value is usually reported in analog-to-digital units or
ADUs, not flux or electron counts.
+The gain value of the device can be used to convert between these two, see
@ref{Brightness flux magnitude}.
-@node MakeProfiles catalog, MakeProfiles profile settings, Invoking astmkprof,
Invoking astmkprof
-@subsubsection MakeProfiles catalog
-The catalog containing information about each profile can be in the FITS
ASCII, FITS binary, or plain text formats (see @ref{Tables}).
-The latter can also be provided using standard input (see @ref{Standard
input}).
-Its columns can be ordered in any desired manner.
-You can specify which columns belong to which parameters using the set of
options discussed below.
-For example through the @option{--rcol} and @option{--tcol} options, you can
specify the column that contains the radial parameter for each profile and its
truncation respectively.
-See @ref{Selecting table columns} for a thorough discussion on the values to
these options.
+@node Final noised pixel value, Generating random numbers, Instrumental noise,
Noise basics
+@subsubsection Final noised pixel value
+Based on the discussions in @ref{Photon counting noise} and @ref{Instrumental
noise}, depending on the values you specify for @mymath{B} and @mymath{C} from
the above, the final noised value for each pixel is a random value chosen from
a Gaussian distribution with
-The value for the profile center in the catalog (the @option{--ccol} option)
can be a floating point number so the profile center can be on any sub-pixel
position.
-Note that pixel positions in the FITS standard start from 1 and an integer is
the pixel center.
-So a 2D image actually starts from the position (0.5, 0.5), which is the
bottom-left corner of the first pixel.
-When a @option{--background} image with WCS information is provided or you
specify the WCS parameters with the respective options, you may also use RA and
Dec to identify the center of each profile (see the @option{--mode} option
below).
+@dispmath{\mu=B+I_{nn}, \quad \sigma=\sqrt{C^2+B+I_{nn}}}
-In MakeProfiles, profile centers do not have to be in (overlap with) the final
image.
-Even if only one pixel of the profile within the truncation radius overlaps
with the final image size, the profile is built and included in the final image
image.
-Profiles that are completely out of the image will not be created (unless you
explicitly ask for it with the @option{--individual} option).
-You can use the output log file (created with @option{--log} to see which
profiles were within the image, see @ref{Common options}.
-If PSF profiles (Moffat or Gaussian, see @ref{PSF}) are in the catalog and the
profiles are to be built in one image (when @option{--individual} is not used),
it is assumed they are the PSF(s) you want to convolve your created image with.
-So by default, they will not be built in the output image but as separate
files.
-The sum of pixels of these separate files will also be set to unity (1) so you
are ready to convolve, see @ref{Convolution process}.
-As a summary, the position and magnitude of PSF profile will be ignored.
-This behavior can be disabled with the @option{--psfinimg} option.
-If you want to create all the profiles separately (with @option{--individual})
and you want the sum of the PSF profile pixels to be unity, you have to set
their magnitudes in the catalog to the zero point magnitude and be sure that
the central positions of the profiles don't have any fractional part (the PSF
center has to be in the center of the pixel).
-The list of options directly related to the input catalog columns is shown
below.
+@node Generating random numbers, , Final noised pixel value, Noise basics
+@subsubsection Generating random numbers
-@table @option
+@cindex Random numbers
+@cindex Numbers, random
+As discussed above, to generate noise we need to make random samples of a
particular distribution.
+So it is important to understand some general concepts regarding the
generation of random numbers.
+For a very complete and nice introduction we strongly advise reading Donald
Knuth's ``The art of computer programming'', volume 2, chapter
3@footnote{Knuth, Donald. 1998.
+The art of computer programming. Addison--Wesley. ISBN 0-201-89684-2 }.
+Quoting from the GNU Scientific Library manual, ``If you don't own it, you
should stop reading right now, run to the nearest bookstore, and buy
it''@footnote{For students, running to the library might be more affordable!}!
-@item --ccol=STR/INT
-Center coordinate column for each dimension.
-This option must be called two times to define the center coordinates in an
image.
-For example @option{--ccol=RA} and @option{--ccol=DEC} (along with
@option{--mode=wcs}) will inform MakeProfiles to look into the catalog columns
named @option{RA} and @option{DEC} for the Right Ascension and Declination of
the profile centers.
+@cindex Psuedo-random numbers
+@cindex Numbers, psuedo-random
+Using only software, we can only produce what is called a psuedo-random
sequence of numbers.
+A true random number generator is a hardware (let's assume we have made sure
it has no systematic biases), for example throwing dice or flipping coins
(which have remained from the ancient times).
+More modern hardware methods use atmospheric noise, thermal noise or other
types of external electromagnetic or quantum phenomena.
+All pseudo-random number generators (software) require a seed to be the basis
of the generation.
+The advantage of having a seed is that if you specify the same seed for
multiple runs, you will get an identical sequence of random numbers which
allows you to reproduce the same final noised image.
-@item --fcol=INT/STR
-The functional form of the profile with one of the values below depending on
the desired profile.
-The column can contain either the numeric codes (for example `@code{1}') or
string characters (for example `@code{sersic}').
-The numeric codes are easier to use in scripts which generate catalogs with
hundreds or thousands of profiles.
+@cindex Environment variables
+@cindex GNU Scientific Library
+The programs in GNU Astronomy Utilities (for example MakeNoise or
MakeProfiles) use the GNU Scientific Library (GSL) to generate random numbers.
+GSL allows the user to set the random number generator through environment
variables, see @ref{Installation directory} for an introduction to environment
variables.
+In the chapter titled ``Random Number Generation'' they have fully explained
the various random number generators that are available (there are a lot of
them!).
+Through the two environment variables @code{GSL_RNG_TYPE} and
@code{GSL_RNG_SEED} you can specify the generator and its seed respectively.
-The string format can be easier when the catalog is to be written/checked by
hand/eye before running MakeProfiles.
-It is much more readable and provides a level of documentation.
-All Gnuastro's recognized table formats (see @ref{Recognized table formats})
accept string type columns.
-To have string columns in a plain text table/catalog, see @ref{Gnuastro text
table format}.
+@cindex Seed, Random number generator
+@cindex Random number generator, Seed
+If you don't specify a value for @code{GSL_RNG_TYPE}, GSL will use its default
random number generator type.
+The default type is sufficient for most general applications.
+If no value is given for the @code{GSL_RNG_SEED} environment variable and you
have asked Gnuastro to read the seed from the environment (through the
@option{--envseed} option), then GSL will use the default value of each
generator to give identical outputs.
+If you don't explicitly tell Gnuastro programs to read the seed value from the
environment variable, then they will use the system time (accurate to within a
microsecond) to generate (apparently random) seeds.
+In this manner, every time you run the program, you will get a different
random number distribution.
-@itemize
-@item
-S@'ersic profile with `@code{sersic}' or `@code{1}'.
+There are two ways you can specify values for these environment variables.
+You can call them on the same command-line for example:
-@item
-Moffat profile with `@code{moffat}' or `@code{2}'.
+@example
+$ GSL_RNG_TYPE="taus" GSL_RNG_SEED=345 astmknoise input.fits
+@end example
-@item
-Gaussian profile with `@code{gaussian}' or `@code{3}'.
+@noindent
+In this manner the values will only be used for this particular execution of
MakeNoise.
+Alternatively, you can define them for the full period of your terminal
session or script length, using the shell's @command{export} command with the
two separate commands below (for a script remove the @code{$} signs):
-@item
-Point source with `@code{point}' or `@code{4}'.
+@example
+$ export GSL_RNG_TYPE="taus"
+$ export GSL_RNG_SEED=345
+@end example
-@item
-Flat profile with `@code{flat}' or `@code{5}'.
+@cindex Startup scripts
+@cindex @file{.bashrc}
+@noindent
+The subsequent programs which use GSL's random number generators will hence
forth use these values in this session of the terminal you are running or while
executing this script.
+In case you want to set fixed values for these parameters every time you use
the GSL random number generator, you can add these two lines to your
@file{.bashrc} startup script@footnote{Don't forget that if you are going to
give your scripts (that use the GSL random number generator) to others you have
to make sure you also tell them to set these environment variable separately.
+So for scripts, it is best to keep all such variable definitions within the
script, even if they are within your @file{.bashrc}.}, see @ref{Installation
directory}.
-@item
-Circumference profile with `@code{circum}' or `@code{6}'.
-A fixed value will be used for all pixels less than or equal to the truncation
radius (@mymath{r_t}) and greater than @mymath{r_t-w} (@mymath{w} is the value
to the @option{--circumwidth}).
+@cartouche
+@noindent
+@strong{NOTE:} If the two environment variables @code{GSL_RNG_TYPE} and
@code{GSL_RNG_SEED} are defined, GSL will report them by default, even if you
don't use the @option{--envseed} option.
+For example you can see the top few lines of the output of MakeProfiles:
-@item
-Radial distance profile with `@code{distance}' or `@code{7}'.
-At the lowest level, each pixel only has an elliptical radial distance given
the profile's shape and orientation (see @ref{Defining an ellipse and
ellipsoid}).
-When this profile is chosen, the pixel's elliptical radial distance from the
profile center is written as its value.
-For this profile, the value in the magnitude column (@option{--mcol}) will be
ignored.
+@example
+$ export GSL_RNG_TYPE="taus"
+$ export GSL_RNG_SEED=345
+$ astmkprof -s1 --kernel=gaussian,2,5 --envseed
+GSL_RNG_TYPE=taus
+GSL_RNG_SEED=345
+MakeProfiles A.B started on DDD MMM DD HH:MM:SS YYYY
+ - Building one gaussian kernel
+ - Random number generator (RNG) type: ranlxs1
+ - RNG seed for all profiles: 345
+ ---- ./kernel.fits created.
+MakeProfiles finished in 0.111271 seconds
+@end example
-You can use this for checks or as a first approximation to define your own
higher-level radial function.
-In the latter case, just note that the central values are going to be
incorrect (see @ref{Sampling from a function}).
+@noindent
+@cindex Seed, Random number generator
+@cindex Random number generator, Seed
+The first two output lines (showing the names of the environment variables)
are printed by GSL before MakeProfiles actually starts generating random
numbers.
+The Gnuastro programs will report the values they use independently, you
should check them for the final values used.
+For example if @option{--envseed} is not given, @code{GSL_RNG_SEED} will not
be used and the last line shown above will not be printed.
+In the case of MakeProfiles, each profile will get its own seed value.
+@end cartouche
-@item
-Custom profile with `@code{custom}' or `@code{8}'.
-The values to use for each radial interval should be in the table given to
@option{--customtable}. For more, see @ref{MakeProfiles profile settings}.
-@end itemize
-@item --rcol=STR/INT
-The radius parameter of the profiles.
-Effective radius (@mymath{r_e}) if S@'ersic, FWHM if Moffat or Gaussian.
+@node Invoking astmknoise, , Noise basics, MakeNoise
+@subsection Invoking MakeNoise
-@item --ncol=STR/INT
-The S@'ersic index (@mymath{n}) or Moffat @mymath{\beta}.
+MakeNoise will add noise to an existing image.
+The executable name is @file{astmknoise} with the following general template
-@item --pcol=STR/INT
-The position angle (in degrees) of the profiles relative to the first FITS
axis (horizontal when viewed in SAO ds9).
-When building a 3D profile, this is the first Euler angle: first rotation of
the ellipsoid major axis from the first FITS axis (rotating about the third
axis).
-See @ref{Defining an ellipse and ellipsoid}.
+@example
+$ astmknoise [OPTION ...] InputImage.fits
+@end example
-@item --p2col=STR/INT
-Second Euler angle (in degrees) when building a 3D ellipsoid.
-This is the second rotation of the ellipsoid major axis (following
@option{--pcol}) about the (rotated) X axis.
-See @ref{Defining an ellipse and ellipsoid}.
-This column is ignored when building a 2D profile.
+@noindent
+One line examples:
-@item --p3col=STR/INT
-Third Euler angle (in degrees) when building a 3D ellipsoid.
-This is the third rotation of the ellipsoid major axis (following
@option{--pcol} and @option{--p2col}) about the (rotated) Z axis.
-See @ref{Defining an ellipse and ellipsoid}.
-This column is ignored when building a 2D profile.
+@example
+## Add noise with a standard deviation of 100 to image.
+## (this is independent of the pixel value: not Poission noise)
+$ astmknoise --sigma=100 image.fits
-@item --qcol=STR/INT
-The axis ratio of the profiles (minor axis divided by the major axis in a 2D
ellipse).
-When building a 3D ellipse, this is the ratio of the major axis to the
semi-axis length of the second dimension (in a right-handed coordinate system).
-See @mymath{q1} in @ref{Defining an ellipse and ellipsoid}.
+## Add noise to input image assuming a background magnitude (with
+## zero point magnitude of 0) and a certain instrumental noise:
+$ astmknoise --background=-10 -z0 --instrumental=20 mockimage.fits
+@end example
-@item --q2col=STR/INT
-The ratio of the ellipsoid major axis to the third semi-axis length (in a
right-handed coordinate system) of a 3D ellipsoid.
-See @mymath{q1} in @ref{Defining an ellipse and ellipsoid}.
-This column is ignored when building a 2D profile.
+@noindent
+If actual processing is to be done, the input image is a mandatory argument.
+The full list of options common to all the programs in Gnuastro can be seen in
@ref{Common options}.
+The type (see @ref{Numeric data types}) of the output can be specified with
the @option{--type} option, see @ref{Input output options}.
+The header of the output FITS file keeps all the parameters that were
influential in making it.
+This is done for future reproducibility.
-@item --mcol=STR/INT
-The total pixelated magnitude of the profile within the truncation radius, see
@ref{Profile magnitude}.
+@table @option
-@item --tcol=STR/INT
-The truncation radius of this profile.
-By default it is in units of the radial parameter of the profile (the value in
the @option{--rcol} of the catalog).
-If @option{--tunitinp} is given, this value is interpreted in units of pixels
(prior to oversampling) irrespective of the profile.
+@item -b FLT
+@itemx --background=FLT
+The background value (per pixel) that will be added to each pixel value
(internally) to estimate Poisson noise, see @ref{Photon counting noise}.
+By default the units of this value are assumed to be in magnitudes, hence a
@option{--zeropoint} is also necessary.
+But if the background is in units of brightness, you need add
@option{--bgisbrightness}, see @ref{Brightness flux magnitude}
-@end table
+Internally, the value given to this option will be converted to brightness
(@mymath{b}, when @option{--bgisbrightness} is called, the value will be used
directly).
+Assuming the pixel value is @mymath{p}, the random value for that pixel will
be taken from a Gaussian distribution with mean of @mymath{p+b} and standard
deviation of @mymath{\sqrt{p+b}}.
+With this option, the noise will therefore be dependent on the pixel values:
according to the Poission noise model, as the pixel value becomes larger, its
noise will also become larger.
+This is thus a realistic way to model noise, see @ref{Photon counting noise}.
-@node MakeProfiles profile settings, MakeProfiles output dataset, MakeProfiles
catalog, Invoking astmkprof
-@subsubsection MakeProfiles profile settings
+@item -B
+@itemx --bgisbrightness
+The value given to @option{--background} should be interpretted as brightness,
not as a magnitude.
-The profile parameters that differ between each created profile are specified
through the columns in the input catalog and described in @ref{MakeProfiles
catalog}.
-Besides those there are general settings for some profiles that don't differ
between one profile and another, they are a property of the general process.
-For example how many random points to use in the monte-carlo integration, this
value is fixed for all the profiles.
-The options described in this section are for configuring such properties.
+@item -z FLT
+@itemx --zeropoint=FLT
+The zero point magnitude used to convert the value of @option{--background}
(in units of magnitude) to flux, see @ref{Brightness flux magnitude}.
-@table @option
+@item -i FLT
+@itemx --instrumental=FLT
+The instrumental noise which is in units of flux, see @ref{Instrumental noise}.
-@item --mode=STR
-Interpret the center position columns (@option{--ccol} in @ref{MakeProfiles
catalog}) in image or WCS coordinates.
-This option thus accepts only two values: @option{img} and @option{wcs}.
-It is mandatory when a catalog is being used as input.
+@item -s FLT
+@item --sigma=FLT
+The total noise sigma in the same units as the pixel values.
+With this option, the @option{--background}, @option{--zeropoint} and
@option{--instrumental} will be ignored.
+With this option, the noise will be independent of the pixel values (which is
not realistic, see @ref{Photon counting noise}).
+Hence it is only useful if you are working on low surface brightness regions
where the change in pixel value (and thus real noise) is insignificant.
-@item -r
-@itemx --numrandom
-The number of random points used in the central regions of the profile, see
@ref{Sampling from a function}.
+Generally, @strong{usage of this option is discouraged} unless you understand
the risks of not simulating real noise.
+This is because with this option, you will not get Poisson noise (the common
noise model for astronomical imaging), where the noise varies based on pixel
value.
+Use @option{--background} for adding Poission noise.
@item -e
@itemx --envseed
@cindex Seed, Random number generator
@cindex Random number generator, Seed
-Use the value to the @code{GSL_RNG_SEED} environment variable to generate the
random Monte Carlo sampling distribution, see @ref{Sampling from a function}
and @ref{Generating random numbers}.
-
-@item -t FLT
-@itemx --tolerance=FLT
-The tolerance to switch from Monte Carlo integration to the central pixel
value, see @ref{Sampling from a function}.
-
-@item -p
-@itemx --tunitinp
-The truncation column of the catalog is in units of pixels.
-By default, the truncation column is considered to be in units of the radial
parameters of the profile (@option{--rcol}).
-Read it as `t-unit-in-p' for `truncation unit in pixels'.
-
-@item -f
-@itemx --mforflatpix
-When making fixed value profiles (flat and circumference, see
`@option{--fcol}'), don't use the value in the column specified by
`@option{--mcol}' as the magnitude.
-Instead use it as the exact value that all the pixels of these profiles should
have.
-This option is irrelevant for other types of profiles.
-This option is very useful for creating masks, or labeled regions in an image.
-Any integer, or floating point value can used in this column with this option,
including @code{NaN} (or `@code{nan}', or `@code{NAN}', case is irrelevant),
and infinities (@code{inf}, @code{-inf}, or @code{+inf}).
+Use the @code{GSL_RNG_SEED} environment variable for the seed used in the
random number generator, see @ref{Generating random numbers}.
+With this option, the output image noise is always going to be identical (or
reproducible).
-For example, with this option if you set the value in the magnitude column
(@option{--mcol}) to @code{NaN}, you can create an elliptical or circular mask
over an image (which can be given as the argument), see @ref{Blank pixels}.
-Another useful application of this option is to create labeled elliptical or
circular apertures in an image.
-To do this, set the value in the magnitude column to the label you want for
this profile.
-This labeled image can then be used in combination with NoiseChisel's output
(see @ref{NoiseChisel output}) to do aperture photometry with MakeCatalog (see
@ref{MakeCatalog}).
+@item -d
+@itemx --doubletype
+Save the output in the double precision floating point format that was used
internally.
+This option will be most useful if the input images were of integer types.
-Alternatively, if you want to mark regions of the image (for example with an
elliptical circumference) and you don't want to use NaN values (as explained
above) for some technical reason, you can get the minimum or maximum value in
the image @footnote{
-The minimum will give a better result, because the maximum can be too high
compared to most pixels in the image, making it harder to display.}
-using Arithmetic (see @ref{Arithmetic}), then use that value in the magnitude
column along with this option for all the profiles.
+@end table
-Please note that when using MakeProfiles on an already existing image, you
have to set `@option{--oversample=1}'.
-Otherwise all the profiles will be scaled up based on the oversampling scale
in your configuration files (see @ref{Configuration files}) unless you have
accounted for oversampling in your catalog.
-@item --mcolisbrightness
-The value given in the ``magnitude column'' (specified by @option{--mcol}, see
@ref{MakeProfiles catalog}) must be interpreted as brightness, not magnitude.
-The zero point magnitude (value to the @option{--zeropoint} option) is ignored
and the given value must have the same units as the input dataset's pixels.
-Recall that the total profile magnitude or brightness that is specified with
in the @option{--mcol} column of the input catalog is not an integration to
infinity, but the actual sum of pixels in the profile (until the desired
truncation radius).
-See @ref{Profile magnitude} for more on this point.
-@item --magatpeak
-The magnitude column in the catalog (see @ref{MakeProfiles catalog}) will be
used to find the brightness only for the peak profile pixel, not the full
profile.
-Note that this is the flux of the profile's peak pixel in the final output of
MakeProfiles.
-So beware of the oversampling, see @ref{Oversampling}.
-This option can be useful if you want to check a mock profile's total
magnitude at various truncation radii.
-Without this option, no matter what the truncation radius is, the total
magnitude will be the same as that given in the catalog.
-But with this option, the total magnitude will become brighter as you increase
the truncation radius.
-In sharper profiles, sometimes the accuracy of measuring the peak profile flux
is more than the overall object brightness.
-In such cases, with this option, the final profile will be built such that its
peak has the given magnitude, not the total profile.
-@cartouche
-@strong{CAUTION:} If you want to use this option for comparing with
observations, please note that MakeProfiles does not do convolution.
-Unless you have de-convolved your data, your images are convolved with the
instrument and atmospheric PSF, see @ref{PSF}.
-Particularly in sharper profiles, the flux in the peak pixel is strongly
decreased after convolution.
-Also note that in such cases, besides de-convolution, you will have to set
@option{--oversample=1} otherwise after resampling your profile with Warp (see
@ref{Warp}), the peak flux will be different.
-@end cartouche
-@item --customtable FITS/TXT
-The filename of the table to use in the custom profiles (see description of
@option{--fcol} in @ref{MakeProfiles catalog}.
-This can be a plain-text table, or FITS table, see @ref{Tables}, if its a FITS
table, you can use @option{--customtablehdu} to specify which HDU should be
used (described below).
-A custom profile can have any value you want for a given radial profile.
-Each interval is defined by its minimum (inclusive) and maximum (exclusive)
radius, when a pixel falls within this radius the value specified for that
interval will be used.
-If a pixel is not in the given intervals, a value of 0 will be used for it.
-The table should have 3 columns as shown below.
-If the intervals are contiguous (the maximum value of the previous interval is
equal to the minimum value of an interval) and the intervals all have the same
size (difference between minimum and maximum values) the creation of these
profiles will be fast.
-However, if the intervals are not sorted and contiguous, Makeprofiles will
parse the intervals from the top of the table and use the first interval that
contains the pixel center.
-@table @asis
-@item Column 1:
-The interval's minimum radius.
-@item Column 2:
-The interval's maximum radius.
-@item Column 3:
-The value to be used for pixels within the given interval.
-@end table
-For example let's assume you have the radial profile below in a file called
@file{radial.txt}.
-The first column is the larger interval radius and the second column is the
value in that interval:
-@example
-1 100
-2 90
-3 50
-4 10
-5 2
-6 0.1
-7 0.05
-@end example
-@noindent
-You can construct the table to give to @option{--customtable} with either of
the commands below: the first one with Gnuastro's @ref{Column arithmetic} which
can also work on FITS tables, and the second one with an AWK command that only
works on plain-text tables..
-@example
-asttable radial.fits -c'arith $1 1 -' -c1,2 -ocustom.fits
-awk '@{print $1-1, $1, $2@}' radial.txt > custom.txt
-@end example
-@noindent
-In case the intervals are different from 1 (for example 0.5), change them
respectively: for Gnuastro's table change @code{$1 1 -} to @code{$1 0.5 -} and
for AWK change @code{$1-1} to @code{$1-0.5}.
-@item --customtablehdu INT/STR
-The HDU/extension in the FITS file given to @option{--customtable}.
+@node High-level calculations, Installed scripts, Modeling and fittings, Top
+@chapter High-level calculations
-@item -X INT,INT
-@itemx --shift=INT,INT
-Shift all the profiles and enlarge the image along each dimension.
-To better understand this option, please see @mymath{n} in @ref{If convolving
afterwards}.
-This is useful when you want to convolve the image afterwards.
-If you are using an external PSF, be sure to oversample it to the same scale
used for creating the mock images.
-If a background image is specified, any possible value to this option is
ignored.
+After the reduction of raw data (for example with the programs in @ref{Data
manipulation}) you will have reduced images/data ready for processing/analyzing
(for example with the programs in @ref{Data analysis}).
+But the processed/analyzed data (or catalogs) are still not enough to derive
any scientific result.
+Even higher-level analysis is still needed to convert the observed magnitudes,
sizes or volumes into physical quantities that we associate with each catalog
entry or detected object which is the purpose of the tools in this section.
-@item -c
-@itemx --prepforconv
-Shift all the profiles and enlarge the image based on half the width of the
first Moffat or Gaussian profile in the catalog, considering any possible
oversampling see @ref{If convolving afterwards}.
-@option{--prepforconv} is only checked and possibly activated if
@option{--xshift} and @option{--yshift} are both zero (after reading the
command-line and configuration files).
-If a background image is specified, any possible value to this option is
ignored.
-@item -z FLT
-@itemx --zeropoint=FLT
-The zero point magnitude of the input.
-For more on the zero point magnitude, see @ref{Brightness flux magnitude}.
-@item -w FLT
-@itemx --circumwidth=FLT
-The width of the circumference if the profile is to be an elliptical
circumference or annulus.
-See the explanations for this type of profile in @option{--fcol}.
-@item -R
-@itemx --replace
-Do not add the pixels of each profile over the background, or other profiles.
-But replace the values.
-By default, when two profiles overlap, the final pixel value is the sum of all
the profiles that overlap on that pixel.
-This is the expected situation when dealing with physical object profiles like
galaxies or stars/PSF.
-However, when MakeProfiles is used to build integer labeled images (for
example in @ref{Aperture photometry}), this is not the expected situation: the
sum of two labels will be a new label.
-With this option, the pixels are not added but the largest (maximum) value
over that pixel is used.
-Because the maximum operator is independent of the order of values, the output
is also thread-safe.
+@menu
+* CosmicCalculator:: Calculate cosmological variables
+@end menu
-@end table
+@node CosmicCalculator, , High-level calculations, High-level calculations
+@section CosmicCalculator
-@node MakeProfiles output dataset, MakeProfiles log file, MakeProfiles profile
settings, Invoking astmkprof
-@subsubsection MakeProfiles output dataset
-MakeProfiles takes an input catalog uses basic properties that are defined
there to build a dataset, for example a 2D image containing the profiles in the
catalog.
-In @ref{MakeProfiles catalog} and @ref{MakeProfiles profile settings}, the
catalog and profile settings were discussed.
-The options of this section, allow you to configure the output dataset (or the
canvas that will host the built profiles).
+To derive higher-level information regarding our sources in extra-galactic
astronomy, cosmological calculations are necessary.
+In Gnuastro, CosmicCalculator is in charge of such calculations.
+Before discussing how CosmicCalculator is called and operates (in
@ref{Invoking astcosmiccal}), it is important to provide a rough but mostly
self sufficient review of the basics and the equations used in the analysis.
+In @ref{Distance on a 2D curved space} the basic idea of understanding
distances in a curved and expanding 2D universe (which we can visualize) are
reviewed.
+Having solidified the concepts there, in @ref{Extending distance concepts to
3D}, the formalism is extended to the 3D universe we are trying to study in our
research.
-@table @option
+The focus here is obtaining a physical insight into these equations (mainly
for the use in real observational studies).
+There are many books thoroughly deriving and proving all the equations with
all possible initial conditions and assumptions for any abstract universe,
interested readers can study those books.
-@item -k FITS
-@itemx --background=FITS
-A background image FITS file to build the profiles on.
-The extension that contains the image should be specified with the
@option{--backhdu} option, see below.
-When a background image is specified, it will be used to derive all the
information about the output image.
-Hence, the following options will be ignored: @option{--mergedsize},
@option{--oversample}, @option{--crpix}, @option{--crval} (generally, all other
WCS related parameters) and the output's data type (see @option{--type} in
@ref{Input output options}).
+@menu
+* Distance on a 2D curved space:: Distances in 2D for simplicity
+* Extending distance concepts to 3D:: Going to 3D (our real universe).
+* Invoking astcosmiccal:: How to run CosmicCalculator
+@end menu
-The image will act like a canvas to build the profiles on: profile pixel
values will be summed with the background image pixel values.
-With the @option{--replace} option you can disable this behavior and replace
the profile pixels with the background pixels.
-If you want to use all the image information above, except for the pixel
values (you want to have a blank canvas to build the profiles on, based on an
input image), you can call @option{--clearcanvas}, to set all the input image's
pixels to zero before starting to build the profiles over it (this is done in
memory after reading the input, so nothing will happen to your input file).
+@node Distance on a 2D curved space, Extending distance concepts to 3D,
CosmicCalculator, CosmicCalculator
+@subsection Distance on a 2D curved space
-@item -B STR/INT
-@itemx --backhdu=STR/INT
-The header data unit (HDU) of the file given to @option{--background}.
+The observations to date (for example the Planck 2015 results), have not
measured@footnote{The observations are interpreted under the assumption of
uniform curvature.
+For a relativistic alternative to dark energy (and maybe also some part of
dark matter), non-uniform curvature may be even be more critical, but that is
beyond the scope of this brief explanation.} the presence of significant
curvature in the universe.
+However to be generic (and allow its measurement if it does in fact exist), it
is very important to create a framework that allows non-zero uniform curvature.
+However, this section is not intended to be a fully thorough and
mathematically complete derivation of these concepts.
+There are many references available for such reviews that go deep into the
abstract mathematical proofs.
+The emphasis here is on visualization of the concepts for a beginner.
-@item -C
-@itemx --clearcanvas
-When an input image is specified (with the @option{--background} option, set
all its pixels to 0.0 immediately after reading it into memory.
-Effectively, this will allow you to use all its properties (described under
the @option{--background} option), without having to worry about the pixel
values.
+As 3D beings, it is difficult for us to mentally create (visualize) a picture
of the curvature of a 3D volume.
+Hence, here we will assume a 2D surface/space and discuss distances on that 2D
surface when it is flat and when it is curved.
+Once the concepts have been created/visualized here, we will extend them, in
@ref{Extending distance concepts to 3D}, to a real 3D spatial @emph{slice} of
the Universe we live in and hope to study.
-@option{--clearcanvas} can come in handy in many situations, for example if
you want to create a labeled image (segmentation map) for creating a catalog
(see @ref{MakeCatalog}).
-In other cases, you might have modeled the objects in an image and want to
create them on the same frame, but without the original pixel values.
+To be more understandable (actively discuss from an observer's point of view)
let's assume there's an imaginary 2D creature living on the 2D space (which
@emph{might} be curved in 3D).
+Here, we will be working with this creature in its efforts to analyze
distances in its 2D universe.
+The start of the analysis might seem too mundane, but since it is difficult to
imagine a 3D curved space, it is important to review all the very basic
concepts thoroughly for an easy transition to a universe that is more difficult
to visualize (a curved 3D space embedded in 4D).
-@item -E STR/INT,FLT[,FLT,[...]]
-@itemx --kernel=STR/INT,FLT[,FLT,[...]]
-Only build one kernel profile with the parameters given as the values to this
option.
-The different values must be separated by a comma (@key{,}).
-The first value identifies the radial function of the profile, either through
a string or through a number (see description of @option{--fcol} in
@ref{MakeProfiles catalog}).
-Each radial profile needs a different total number of parameters: S@'ersic and
Moffat functions need 3 parameters: radial, S@'ersic index or Moffat
@mymath{\beta}, and truncation radius.
-The Gaussian function needs two parameters: radial and truncation radius.
-The point function doesn't need any parameters and flat and circumference
profiles just need one parameter (truncation radius).
+To start, let's assume a static (not expanding or shrinking), flat 2D surface
similar to @ref{flatplane} and that the 2D creature is observing its universe
from point @mymath{A}.
+One of the most basic ways to parameterize this space is through the Cartesian
coordinates (@mymath{x}, @mymath{y}).
+In @ref{flatplane}, the basic axes of these two coordinates are plotted.
+An infinitesimal change in the direction of each axis is written as
@mymath{dx} and @mymath{dy}.
+For each point, the infinitesimal changes are parallel with the respective
axes and are not shown for clarity.
+Another very useful way of parameterizing this space is through polar
coordinates.
+For each point, we define a radius (@mymath{r}) and angle (@mymath{\phi}) from
a fixed (but arbitrary) reference axis.
+In @ref{flatplane} the infinitesimal changes for each polar coordinate are
plotted for a random point and a dashed circle is shown for all points with the
same radius.
-The PSF or kernel is a unique (and highly constrained) type of profile: the
sum of its pixels must be one, its center must be the center of the central
pixel (in an image with an odd number of pixels on each side), and commonly it
is circular, so its axis ratio and position angle are one and zero respectively.
-Kernels are commonly necessary for various data analysis and data manipulation
steps (for example see @ref{Convolve}, and @ref{NoiseChisel}.
-Because of this it is inconvenient to define a catalog with one row and many
zero valued columns (for all the non-necessary parameters).
-Hence, with this option, it is possible to create a kernel with MakeProfiles
without the need to create a catalog.
-Here are some examples:
+@float Figure,flatplane
+@center@image{gnuastro-figures/flatplane, 10cm, , }
-@table @option
-@item --kernel=moffat,3,2.8,5
-A Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is truncated
at 5 times the FWHM.
+@caption{Two dimensional Cartesian and polar coordinates on a flat
+plane.}
+@end float
-@item --kernel=gaussian,2,3
-A circular Gaussian kernel with FWHM of 2 pixels and truncated at 3 times
-the FWHM.
-@end table
+Assuming an object is placed at a certain position, which can be parameterized
as @mymath{(x,y)}, or @mymath{(r,\phi)}, a general infinitesimal change in its
position will place it in the coordinates @mymath{(x+dx,y+dy)} and
@mymath{(r+dr,\phi+d\phi)}.
+The distance (on the flat 2D surface) that is covered by this infinitesimal
change in the static universe (@mymath{ds_s}, the subscript signifies the
static nature of this universe) can be written as:
-This option may also be used to create a 3D kernel.
-To do that, two small modifications are necessary: add a @code{-3d} (or
@code{-3D}) to the profile name (for example @code{moffat-3d}) and add a number
(axis-ratio along the third dimension) to the end of the parameters for all
profiles except @code{point}.
-The main reason behind providing an axis ratio in the third dimension is that
in 3D astronomical datasets, commonly the third dimension doesn't have the same
nature (units/sampling) as the first and second.
+@dispmath{ds_s=dx^2+dy^2=dr^2+r^2d\phi^2}
-For example in IFU datacubes, the first and second dimensions are
angularpositions (like RA and Dec) but the third is in units of Angstroms for
wavelength.
-Because of this different nature (which also affects theprocessing), it may be
necessary for the kernel to have a different extent in that direction.
+The main question is this: how can the 2D creature incorporate the (possible)
curvature in its universe when it's calculating distances? The universe that it
lives in might equally be a curved surface like @ref{sphereandplane}.
+The answer to this question but for a 3D being (us) is the whole purpose to
this discussion.
+Here, we want to give the 2D creature (and later, ourselves) the tools to
measure distances if the space (that hosts the objects) is curved.
-If the 3rd dimension axis ratio is equal to @mymath{1.0}, then the kernel will
be a spheroid.
-If its smaller than @mymath{1.0}, the kernel will be button-shaped: extended
less in the third dimension.
-However, when it islarger than @mymath{1.0}, the kernel will be bullet-shaped:
extended more in the third dimension.
-In the latter case, the radial parameter will correspond to the length along
the 3rd dimension.
-For example, let's have a look at the two examples above but in 3D:
+@ref{sphereandplane} assumes a spherical shell with radius @mymath{R} as the
curved 2D plane for simplicity.
+The 2D plane is tangent to the spherical shell and only touches it at
@mymath{A}.
+This idea will be generalized later.
+The first step in measuring the distance in a curved space is to imagine a
third dimension along the @mymath{z} axis as shown in @ref{sphereandplane}.
+For simplicity, the @mymath{z} axis is assumed to pass through the center of
the spherical shell.
+Our imaginary 2D creature cannot visualize the third dimension or a curved 2D
surface within it, so the remainder of this discussion is purely abstract for
it (similar to us having difficulty in visualizing a 3D curved space in 4D).
+But since we are 3D creatures, we have the advantage of visualizing the
following steps.
+Fortunately the 2D creature is already familiar with our mathematical
constructs, so it can follow our reasoning.
-@table @option
-@item --kernel=moffat-3d,3,2.8,5,0.5
-An ellipsoid Moffat kernel with FWHM of 3 pixels, @mymath{\beta=2.8} which is
truncated at 5 times the FWHM.
-The ellipsoid is circular in the first two dimensions, but in the third
dimension its extent is half the first two.
+With the third axis added, a generic infinitesimal change over @emph{the full}
3D space corresponds to the distance:
-@item --kernel=gaussian-3d,2,3,1
-A spherical Gaussian kernel with FWHM of 2 pixels and truncated at 3 times
-the FWHM.
-@end table
+@dispmath{ds_s^2=dx^2+dy^2+dz^2=dr^2+r^2d\phi^2+dz^2.}
-Ofcourse, if a specific kernel is needed that doesn't fit the constraints
imposed by this option, you can always use a catalog to define any arbitrary
kernel.
-Just call the @option{--individual} and @option{--nomerged} options to make
sure that it is built as a separate file (individually) and no ``merged'' image
of the input profiles is created.
+@float Figure,sphereandplane
+@center@image{gnuastro-figures/sphereandplane, 10cm, , }
-@item -x INT,INT
-@itemx --mergedsize=INT,INT
-The number of pixels along each axis of the output, in FITS order.
-This is before over-sampling.
-For example if you call MakeProfiles with @option{--mergedsize=100,150
--oversample=5} (assuming no shift due for later convolution), then the final
image size along the first axis will be 500 by 750 pixels.
-Fractions are acceptable as values for each dimension, however, they must
reduce to an integer, so @option{--mergedsize=150/3,300/3} is acceptable but
@option{--mergedsize=150/4,300/4} is not.
+@caption{2D spherical shell (centered on @mymath{O}) and flat plane (light
gray) tangent to it at point @mymath{A}.}
+@end float
-When viewing a FITS image in DS9, the first FITS dimension is in the
horizontal direction and the second is vertical.
-As an example, the image created with the example above will have 500 pixels
horizontally and 750 pixels vertically.
+It is very important to recognize that this change of distance is for
@emph{any} point in the 3D space, not just those changes that occur on the 2D
spherical shell of @ref{sphereandplane}.
+Recall that our 2D friend can only do measurements on the 2D surfaces, not the
full 3D space.
+So we have to constrain this general change to any change on the 2D spherical
shell.
+To do that, let's look at the arbitrary point @mymath{P} on the 2D spherical
shell.
+Its image (@mymath{P'}) on the flat plain is also displayed. From the dark
gray triangle, we see that
-If a background image is specified, this option is ignored.
+@dispmath{\sin\theta={r\over R},\quad\cos\theta={R-z\over R}.}These relations
allow the 2D creature to find the value of @mymath{z} (an abstract dimension
for it) as a function of r (distance on a flat 2D plane, which it can
visualize) and thus eliminate @mymath{z}.
+From @mymath{\sin^2\theta+\cos^2\theta=1}, we get @mymath{z^2-2Rz+r^2=0} and
solving for @mymath{z}, we find:
-@item -s INT
-@itemx --oversample=INT
-The scale to over-sample the profiles and final image.
-If not an odd number, will be added by one, see @ref{Oversampling}.
-Note that this @option{--oversample} will remain active even if an input image
is specified.
-If your input catalog is based on the background image, be sure to set
@option{--oversample=1}.
+@dispmath{z=R\left(1\pm\sqrt{1-{r^2\over R^2}}\right).}
-@item --psfinimg
-Build the possibly existing PSF profiles (Moffat or Gaussian) in the catalog
into the final image.
-By default they are built separately so you can convolve your images with
them, thus their magnitude and positions are ignored.
-With this option, they will be built in the final image like every other
galaxy profile.
-To have a final PSF in your image, make a point profile where you want the PSF
and after convolution it will be the PSF.
+The @mymath{\pm} can be understood from @ref{sphereandplane}: For each
@mymath{r}, there are two points on the sphere, one in the upper hemisphere and
one in the lower hemisphere.
+An infinitesimal change in @mymath{r}, will create the following infinitesimal
change in @mymath{z}:
-@item -i
-@itemx --individual
-@cindex Individual profiles
-@cindex Build individual profiles
-If this option is called, each profile is created in a separate FITS file
within the same directory as the output and the row number of the profile
(starting from zero) in the name.
-The file for each row's profile will be in the same directory as the final
combined image of all the profiles and will have the final image's name as a
suffix.
-So for example if the final combined image is named
@file{./out/fromcatalog.fits}, then the first profile that will be created with
this option will be named @file{./out/0_fromcatalog.fits}.
+@dispmath{dz={\mp r\over R}\left(1\over
+\sqrt{1-{r^2/R^2}}\right)dr.}Using the positive signed equation instead of
@mymath{dz} in the @mymath{ds_s^2} equation above, we get:
+
+@dispmath{ds_s^2={dr^2\over 1-r^2/R^2}+r^2d\phi^2.}
+
+The derivation above was done for a spherical shell of radius @mymath{R} as a
curved 2D surface.
+To generalize it to any surface, we can define @mymath{K=1/R^2} as the
curvature parameter.
+Then the general infinitesimal change in a static universe can be written as:
+
+@dispmath{ds_s^2={dr^2\over 1-Kr^2}+r^2d\phi^2.}
+
+Therefore, when @mymath{K>0} (and curvature is the same everywhere), we have a
finite universe, where @mymath{r} cannot become larger than @mymath{R} as in
@ref{sphereandplane}.
+When @mymath{K=0}, we have a flat plane (@ref{flatplane}) and a negative
@mymath{K} will correspond to an imaginary @mymath{R}.
+The latter two cases may be infinite in area (which is not a simple concept,
but mathematically can be modeled with @mymath{r} extending infinitely), or
finite-area (like a cylinder is flat everywhere with @mymath{ds_s^2={dx^2 +
dy^2}}, but finite in one direction in size).
+
+@cindex Proper distance
+A very important issue that can be discussed now (while we are still in 2D and
can actually visualize things) is that @mymath{\overrightarrow{r}} is tangent
to the curved space at the observer's position.
+In other words, it is on the gray flat surface of @ref{sphereandplane}, even
when the universe if curved: @mymath{\overrightarrow{r}=P'-A}.
+Therefore for the point @mymath{P} on a curved space, the raw coordinate
@mymath{r} is the distance to @mymath{P'}, not @mymath{P}.
+The distance to the point @mymath{P} (at a specific coordinate @mymath{r} on
the flat plane) over the curved surface (thick line in @ref{sphereandplane}) is
called the @emph{proper distance} and is displayed with @mymath{l}.
+For the specific example of @ref{sphereandplane}, the proper distance can be
calculated with: @mymath{l=R\theta} (@mymath{\theta} is in radians).
+Using the @mymath{\sin\theta} relation found above, we can find @mymath{l} as
a function of @mymath{r}:
-Since each image only has one full profile out to the truncation radius the
profile is centered and so, only the sub-pixel position of the profile center
is important for the outputs of this option.
-The output will have an odd number of pixels.
-If there is no oversampling, the central pixel will contain the profile center.
-If the value to @option{--oversample} is larger than unity, then the profile
center is on any of the central @option{--oversample}'d pixels depending on the
fractional value of the profile center.
+@dispmath{\theta=\sin^{-1}\left({r\over R}\right)\quad\rightarrow\quad
+l(r)=R\sin^{-1}\left({r\over R}\right)}
-If the fractional value is larger than half, it is on the bottom half of the
central region.
-This is due to the FITS definition of a real number position: The center of a
pixel has fractional value @mymath{0.00} so each pixel contains these
fractions: .5 -- .75 -- .00 (pixel center) -- .25 -- .5.
-@item -m
-@itemx --nomerged
-Don't make a merged image.
-By default after making the profiles, they are added to a final image with
side lengths specified by @option{--mergedsize} if they overlap with it.
+@mymath{R} is just an arbitrary constant and can be directly found from
@mymath{K}, so for cleaner equations, it is common practice to set
@mymath{R=1}, which gives: @mymath{l(r)=\sin^{-1}r}.
+Also note that when @mymath{R=1}, then @mymath{l=\theta}.
+Generally, depending on the curvature, in a @emph{static} universe the proper
distance can be written as a function of the coordinate @mymath{r} as (from now
on we are assuming @mymath{R=1}):
-@end table
+@dispmath{l(r)=\sin^{-1}(r)\quad(K>0),\quad\quad
+l(r)=r\quad(K=0),\quad\quad l(r)=\sinh^{-1}(r)\quad(K<0).}With
+@mymath{l}, the infinitesimal change of distance can be written in a
+more simpler and abstract form of
+@dispmath{ds_s^2=dl^2+r^2d\phi^2.}
-@noindent
-The options below can be used to define the world coordinate system (WCS)
properties of the MakeProfiles outputs.
-The option names are deliberately chosen to be the same as the FITS standard
WCS keywords.
-See Section 8 of @url{https://doi.org/10.1051/0004-6361/201015362, Pence et al
[2010]} for a short introduction to WCS in the FITS standard@footnote{The world
coordinate standard in FITS is a very beautiful and powerful concept to
link/associate datasets with the outside world (other datasets).
-The description in the FITS standard (link above) only touches the tip of the
ice-burg.
-To learn more please see @url{https://doi.org/10.1051/0004-6361:20021326,
Greisen and Calabretta [2002]},
@url{https://doi.org/10.1051/0004-6361:20021327, Calabretta and Greisen
[2002]}, @url{https://doi.org/10.1051/0004-6361:20053818, Greisen et al.
[2006]}, and
@url{http://www.atnf.csiro.au/people/mcalabre/WCS/dcs_20040422.pdf, Calabretta
et al.}}.
+@cindex Comoving distance
+Until now, we had assumed a static universe (not changing with time).
+But our observations so far appear to indicate that the universe is expanding
(it isn't static).
+Since there is no reason to expect the observed expansion is unique to our
particular position of the universe, we expect the universe to be expanding at
all points with the same rate at the same time.
+Therefore, to add a time dependence to our distance measurements, we can
include a multiplicative scaling factor, which is a function of time:
@mymath{a(t)}.
+The functional form of @mymath{a(t)} comes from the cosmology, the physics we
assume for it: general relativity, and the choice of whether the universe is
uniform (`homogeneous') in density and curvature or inhomogeneous.
+In this section, the functional form of @mymath{a(t)} is irrelevant, so we can
avoid these issues.
-If you look into the headers of a FITS image with WCS for example you will see
all these names but in uppercase and with numbers to represent the dimensions,
for example @code{CRPIX1} and @code{PC2_1}.
-You can see the FITS headers with Gnuastro's @ref{Fits} program using a
command like this: @command{$ astfits -p image.fits}.
+With this scaling factor, the proper distance will also depend on time.
+As the universe expands, the distance between two given points will shift to
larger values.
+We thus define a distance measure, or coordinate, that is independent of time
and thus doesn't `move'.
+We call it the @emph{comoving distance} and display with @mymath{\chi} such
that: @mymath{l(r,t)=\chi(r)a(t)}.
+We have therefore, shifted the @mymath{r} dependence of the proper distance we
derived above for a static universe to the comoving distance:
-If the values given to any of these options does not correspond to the number
of dimensions in the output dataset, then no WCS information will be added.
+@dispmath{\chi(r)=\sin^{-1}(r)\quad(K>0),\quad\quad
+\chi(r)=r\quad(K=0),\quad\quad \chi(r)=\sinh^{-1}(r)\quad(K<0).}
-@table @option
+Therefore, @mymath{\chi(r)} is the proper distance to an object at a specific
reference time: @mymath{t=t_r} (the @mymath{r} subscript signifies
``reference'') when @mymath{a(t_r)=1}.
+At any arbitrary moment (@mymath{t\neq{t_r}}) before or after @mymath{t_r},
the proper distance to the object can be scaled with @mymath{a(t)}.
-@item --crpix=FLT,FLT
-The pixel coordinates of the WCS reference point.
-Fractions are acceptable for the values of this option.
+Measuring the change of distance in a time-dependent (expanding) universe only
makes sense if we can add up space and time@footnote{In other words, making our
space-time consistent with Minkowski space-time geometry.
+In this geometry, different observers at a given point (event) in space-time
split up space-time into `space' and `time' in different ways, just like people
at the same spatial position can make different choices of splitting up a map
into `left--right' and `up--down'.
+This model is well supported by twentieth and twenty-first century
observations.}.
+But we can only add bits of space and time together if we measure them in the
same units: with a conversion constant (similar to how 1000 is used to convert
a kilometer into meters).
+Experimentally, we find strong support for the hypothesis that this conversion
constant is the speed of light (or gravitational waves@footnote{The speed of
gravitational waves was recently found to be very similar to that of light in
vacuum, see @url{https://arxiv.org/abs/1710.05834, arXiv:1710.05834}.}) in a
vacuum.
+This speed is postulated to be constant@footnote{In @emph{natural units},
speed is measured in units of the speed of light in vacuum.} and is almost
always written as @mymath{c}.
+We can thus parameterize the change in distance on an expanding 2D surface as
-@item --crval=FLT,FLT
-The WCS coordinates of the Reference point.
-Fractions are acceptable for the values of this option.
+@dispmath{ds^2=c^2dt^2-a^2(t)ds_s^2 = c^2dt^2-a^2(t)(d\chi^2+r^2d\phi^2).}
-@item --cdelt=FLT,FLT
-The resolution (size of one data-unit or pixel in WCS units) of the
non-oversampled dataset.
-Fractions are acceptable for the values of this option.
-@item --pc=FLT,FLT,FLT,FLT
-The PC matrix of the WCS rotation, see the FITS standard (link above) to
better understand the PC matrix.
+@node Extending distance concepts to 3D, Invoking astcosmiccal, Distance on a
2D curved space, CosmicCalculator
+@subsection Extending distance concepts to 3D
-@item --cunit=STR,STR
-The units of each WCS axis, for example @code{deg}.
-Note that these values are part of the FITS standard (link above).
-MakeProfiles won't complain if you use non-standard values, but later usage of
them might cause trouble.
+The concepts of @ref{Distance on a 2D curved space} are here extended to a 3D
space that @emph{might} be curved.
+We can start with the generic infinitesimal distance in a static 3D universe,
but this time in spherical coordinates instead of polar coordinates.
+@mymath{\theta} is shown in @ref{sphereandplane}, but here we are 3D beings,
positioned on @mymath{O} (the center of the sphere) and the point @mymath{O} is
tangent to a 4D-sphere.
+In our 3D space, a generic infinitesimal displacement will correspond to the
following distance in spherical coordinates:
-@item --ctype=STR,STR
-The type of each WCS axis, for example @code{RA---TAN} and @code{DEC--TAN}.
-Note that these values are part of the FITS standard (link above).
-MakeProfiles won't complain if you use non-standard values, but later usage of
them might cause trouble.
+@dispmath{ds_s^2=dx^2+dy^2+dz^2=dr^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2).}
-@end table
+Like the 2D creature before, we now have to assume an abstract dimension which
we cannot visualize easily.
+Let's call the fourth dimension @mymath{w}, then the general change in
coordinates in the @emph{full} four dimensional space will be:
-@node MakeProfiles log file, , MakeProfiles output dataset, Invoking astmkprof
-@subsubsection MakeProfiles log file
+@dispmath{ds_s^2=dr^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2)+dw^2.}
-Besides the final merged dataset of all the profiles, or the individual
datasets (see @ref{MakeProfiles output dataset}), if the @option{--log} option
is called MakeProfiles will also create a log file in the current directory
(where you run MockProfiles).
-See @ref{Common options} for a full description of @option{--log} and other
options that are shared between all Gnuastro programs.
-The values for each column are explained in the first few commented lines of
the log file (starting with @command{#} character).
-Here is a more complete description.
+@noindent
+But we can only work on a 3D curved space, so following exactly the same steps
and conventions as our 2D friend, we arrive at:
-@itemize
-@item
-An ID (row number of profile in input catalog).
+@dispmath{ds_s^2={dr^2\over 1-Kr^2}+r^2(d\theta^2+\sin^2{\theta}d\phi^2).}
-@item
-The total magnitude of the profile in the output dataset.
-When the profile does not completely overlap with the output dataset, this
will be different from your input magnitude.
+@noindent
+In a non-static universe (with a scale factor a(t)), the distance can be
written as:
-@item
-The number of pixels (in the oversampled image) which used Monte Carlo
integration and not the central pixel value, see @ref{Sampling from a function}.
+@dispmath{ds^2=c^2dt^2-a^2(t)[d\chi^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2)].}
-@item
-The fraction of flux in the Monte Carlo integrated pixels.
-@item
-If an individual image was created, this column will have a value of @code{1},
otherwise it will have a value of @code{0}.
-@end itemize
+@c@dispmath{H(z){\equiv}\left(\dot{a}\over a\right)(z)=H_0E(z) }
+@c@dispmath{E(z)=[ \Omega_{\Lambda,0} + \Omega_{C,0}(1+z)^2 +
+@c\Omega_{m,0}(1+z)^3 + \Omega_{r,0}(1+z)^4 ]^{1/2}}
+@c Let's take @mymath{r} to be the radial coordinate of the emitting
+@c source, which emitted its light at redshift $z$. Then the comoving
+@c distance of this object would be:
+@c@dispmath{ \chi(r)={c\over H_0a_0}\int_0^z{dz'\over E(z')} }
+@c@noindent
+@c So the proper distance at the current time to that object is:
+@c @mymath{a_0\chi(r)}, therefore the angular diameter distance
+@c (@mymath{d_A}) and luminosity distance (@mymath{d_L}) can be written
+@c as:
+@c@dispmath{ d_A={a_0\chi(r)\over 1+z}, \quad d_L=a_0\chi(r)(1+z) }
+@node Invoking astcosmiccal, , Extending distance concepts to 3D,
CosmicCalculator
+@subsection Invoking CosmicCalculator
+CosmicCalculator will calculate cosmological variables based on the input
parameters.
+The executable name is @file{astcosmiccal} with the following general template
-@node MakeNoise, , MakeProfiles, Modeling and fittings
-@section MakeNoise
+@example
+$ astcosmiccal [OPTION...] ...
+@end example
-@cindex Noise
-Real data are always buried in noise, therefore to finalize a simulation of
real data (for example to test our observational algorithms) it is essential to
add noise to the mock profiles created with MakeProfiles, see
@ref{MakeProfiles}.
-Below, the general principles and concepts to help understand how noise is
quantified is discussed.
-MakeNoise options and argument are then discussed in @ref{Invoking astmknoise}.
-@menu
-* Noise basics:: Noise concepts and definitions.
-* Invoking astmknoise:: Options and arguments to MakeNoise.
-@end menu
+@noindent
+One line examples:
+@example
+## Print basic cosmological properties at redshift 2.5:
+$ astcosmiccal -z2.5
+## Only print Comoving volume over 4pi stradian to z (Mpc^3):
+$ astcosmiccal --redshift=0.8 --volume
-@node Noise basics, Invoking astmknoise, MakeNoise, MakeNoise
-@subsection Noise basics
+## Print redshift and age of universe when Lyman-alpha line is
+## at 6000 angstrom (another way to specify redshift).
+$ astcosmiccal --obsline=lyalpha,6000 --age
-@cindex Noise
-@cindex Image noise
-Deep astronomical images, like those used in extragalactic studies, seriously
suffer from noise in the data.
-Generally speaking, the sources of noise in an astronomical image are photon
counting noise and Instrumental noise which are discussed in @ref{Photon
counting noise} and @ref{Instrumental noise}.
-This review finishes with @ref{Generating random numbers} which is a short
introduction on how random numbers are generated.
-We will see that while software random number generators are not perfect, they
allow us to obtain a reproducible series of random numbers through setting the
random number generator function and seed value.
-Therefore in this section, we'll also discuss how you can set these two
parameters in Gnuastro's programs (including MakeNoise).
+## Print luminosity distance, angular diameter distance and age
+## of universe in one row at redshift 0.4
+$ astcosmiccal -z0.4 -LAg
-@menu
-* Photon counting noise:: Poisson noise
-* Instrumental noise:: Readout, dark current and other sources.
-* Final noised pixel value:: How the final noised value is calculated.
-* Generating random numbers:: How random numbers are generated.
-@end menu
+## Assume Lambda and matter density of 0.7 and 0.3 and print
+## basic cosmological parameters for redshift 2.1:
+$ astcosmiccal -l0.7 -m0.3 -z2.1
-@node Photon counting noise, Instrumental noise, Noise basics, Noise basics
-@subsubsection Photon counting noise
+## Print wavelength of all pre-defined spectral lines when
+## Lyman-alpha is observed at 4000 Angstroms.
+$ astcosmiccal --obsline=lyalpha,4000 --listlinesatz
+@end example
-@cindex Counting error
-@cindex de Moivre, Abraham
-@cindex Poisson distribution
-@cindex Photon counting noise
-@cindex Poisson, Sim@'eon Denis
-With the very accurate electronics used in today's detectors, photon counting
noise@footnote{In practice, we are actually counting the electrons that are
produced by each photon, not the actual photons.} is the most significant
source of uncertainty in most datasets.
-To understand this noise (error in counting), we need to take a closer look at
how a distribution produced by counting can be modeled as a parametric function.
+The input parameters (for example current matter density, etc) can be given as
command-line options or in the configuration files, see @ref{Configuration
files}.
+For a definition of the different parameters, please see the sections prior to
this.
+If no redshift is given, CosmicCalculator will just print its input parameters
and abort.
+For a full list of the input options, please see @ref{CosmicCalculator input
options}.
-Counting is an inherently discrete operation, which can only produce positive
(including zero) integer outputs.
-For example we can't count @mymath{3.2} or @mymath{-2} of anything.
-We only count @mymath{0}, @mymath{1}, @mymath{2}, @mymath{3} and so on.
-The distribution of values, as a result of counting efforts is formally known
as the @url{https://en.wikipedia.org/wiki/Poisson_distribution, Poisson
distribution}.
-It is associated to Sim@'eon Denis Poisson, because he discussed it while
working on the number of wrongful convictions in court cases in his 1837
book@footnote{[From Wikipedia] Poisson's result was also derived in a previous
study by Abraham de Moivre in 1711.
-Therefore some people suggest it should rightly be called the de Moivre
distribution.}.
+Without any particular output requested (and only a given redshift),
CosmicCalculator will print all basic cosmological calculations (one per line)
with some explanations before each.
+This can be good when you want a general feeling of the conditions at a
specific redshift.
+Alternatively, if any specific calculation(s) are requested (its possible to
call more than one), only the requested value(s) will be calculated and printed
with one character space between them.
+In this case, no description or units will be printed.
+See @ref{CosmicCalculator basic cosmology calculations} for the full list of
these options along with some explanations how when/how they can be useful.
-@cindex Probability density function
-Let's take @mymath{\lambda} to represent the expected mean count of something.
-Furthermore, let's take @mymath{k} to represent the result of one particular
counting attempt.
-The probability density function of getting @mymath{k} counts (in each
attempt, given the expected/mean count of @mymath{\lambda}) can be written as:
+Another common operation in observational cosmology is dealing with spectral
lines at different redshifts.
+CosmicCalculator also has features to help in such situations, please see
@ref{CosmicCalculator spectral line calculations}.
-@cindex Poisson distribution
-@dispmath{f(k)={\lambda^k \over k!} e^{-\lambda},\quad k\in @{0, 1, 2, 3,
\dots @}}
+@menu
+* CosmicCalculator input options:: Options to specify input conditions.
+* CosmicCalculator basic cosmology calculations:: Like distance modulus,
distances and etc.
+* CosmicCalculator spectral line calculations:: How they get affected by
redshift.
+@end menu
-@cindex Skewed Poisson distribution
-Because the Poisson distribution is only applicable to positive values (note
the factorial operator, which only applies to non-negative integers), naturally
it is very skewed when @mymath{\lambda} is near zero.
-One qualitative way to understand this behavior is that there simply aren't
enough integers smaller than @mymath{\lambda}, than integers that are larger
than it.
-Therefore to accommodate all possibilities/counts, it has to be strongly
skewed when @mymath{\lambda} is small.
+@node CosmicCalculator input options, CosmicCalculator basic cosmology
calculations, Invoking astcosmiccal, Invoking astcosmiccal
+@subsubsection CosmicCalculator input options
-@cindex Compare Poisson and Gaussian
-As @mymath{\lambda} becomes larger, the distribution becomes more and more
symmetric.
-A very useful property of the Poisson distribution is that the mean value is
also its variance.
-When @mymath{\lambda} is very large, say @mymath{\lambda>1000}, then the
@url{https://en.wikipedia.org/wiki/Normal_distribution, Normal (Gaussian)
distribution}, is an excellent approximation of the Poisson distribution with
mean @mymath{\mu=\lambda} and standard deviation @mymath{\sigma=\sqrt{\lambda}}.
-In other words, a Poisson distribution (with a sufficiently large
@mymath{\lambda}) is simply a Gaussian that only has one free parameter
(@mymath{\mu=\lambda} and @mymath{\sigma=\sqrt{\lambda}}), instead of the two
parameters (independent @mymath{\mu} and @mymath{\sigma}) that it originally
has.
+The inputs to CosmicCalculator can be specified with the following options:
+@table @option
-@cindex Sky value
-@cindex Background flux
-@cindex Undetected objects
-In real situations, the photons/flux from our targets are added to a certain
background flux (observationally, the @emph{Sky} value).
-The Sky value is defined to be the average flux of a region in the dataset
with no targets.
-Its physical origin can be the brightness of the atmosphere (for ground-based
instruments), possible stray light within the imaging instrument, the average
flux of undetected targets, etc.
-The Sky value is thus an ideal definition, because in real datasets, what lies
deep in the noise (far lower than the detection limit) is never
known@footnote{In a real image, a relatively large number of very faint objects
can been fully buried in the noise and never detected.
-These undetected objects will bias the background measurement to slightly
larger values.
-Our best approximation is thus to simply assume they are uniform, and consider
their average effect.
-See Figure 1 (a.1 and a.2) and Section 2.2 in
@url{https://arxiv.org/abs/1505.01664, Akhlaghi and Ichikawa [2015]}.}.
-To account for all of these, the sky value is defined to be the average
count/value of the undetected regions in the image.
-In a mock image/dataset, we have the luxury of setting the background (Sky)
value.
+@item -z FLT
+@itemx --redshift=FLT
+The redshift of interest.
+There are two other ways that you can specify the target redshift:
+1) Spectral lines and their observed wavelengths, see @option{--obsline}.
+2) Velocity, see @option{--velocity}.
+Hence this option cannot be called with @option{--obsline} or
@option{--velocity}.
-@cindex Simulating noise
-@cindex Noise simulation
-In each element of the dataset (pixel in an image), the flux is the sum of
contributions from various sources (after convolution by the PSF, see
@ref{PSF}).
-Let's name the convolved sum of possibly overlapping objects, @mymath{I_{nn}}.
-@mymath{nn} representing `no noise'.
-For now, let's assume the background (@mymath{B}) is constant and sufficiently
high for the Poisson distribution to be approximated by a Gaussian.
-Then the flux after adding noise is a random value taken from a Gaussian
distribution with the following mean (@mymath{\mu}) and standard deviation
(@mymath{\sigma}):
+@item -y FLT
+@itemx --velocity=FLT
+Input velocity in km/s.
+The given value will be converted to redshift internally, and used in any
subsequent calculation.
+This option is thus an alternative to @code{--redshift} or @code{--obsline},
it cannot be used with them.
+The conversion will be done with the more general and accurate relativistic
equation of @mymath{1+z=\sqrt{(c+v)/(c-v)}}, not the simplified
@mymath{z\approx v/c}.
-@dispmath{\mu=B+I_{nn}, \quad \sigma=\sqrt{B+I_{nn}}}
+@item -H FLT
+@itemx --H0=FLT
+Current expansion rate (in km sec@mymath{^{-1}} Mpc@mymath{^{-1}}).
-Since this type of noise is inherent in the objects we study, it is usually
measured on the same scale as the astronomical objects, namely the magnitude
system, see @ref{Brightness flux magnitude}.
-It is then internally converted to the flux scale for further processing.
+@item -l FLT
+@itemx --olambda=FLT
+Cosmological constant density divided by the critical density in the current
Universe (@mymath{\Omega_{\Lambda,0}}).
-@node Instrumental noise, Final noised pixel value, Photon counting noise,
Noise basics
-@subsubsection Instrumental noise
+@item -m FLT
+@itemx --omatter=FLT
+Matter (including massive neutrinos) density divided by the critical density
in the current Universe (@mymath{\Omega_{m,0}}).
-@cindex Readout noise
-@cindex Instrumental noise
-@cindex Noise, instrumental
-While taking images with a camera, a dark current is fed to the pixels, the
variation of the value of this dark current over the pixels, also adds to the
final image noise.
-Another source of noise is the readout noise that is produced by the
electronics in the detector.
-Specifically, the parts that attempt to digitize the voltage produced by the
photo-electrons in the analog to digital converter.
-With the current generation of instruments, this source of noise is not as
significant as the noise due to the background Sky discussed in @ref{Photon
counting noise}.
+@item -r FLT
+@itemx --oradiation=FLT
+Radiation density divided by the critical density in the current Universe
(@mymath{\Omega_{r,0}}).
-Let @mymath{C} represent the combined standard deviation of all these
instrumental sources of noise.
-When only this source of noise is present, the noised pixel value would be a
random value chosen from a Gaussian distribution with
+@item -O STR/FLT,FLT
+@itemx --obsline=STR/FLT,FLT
+@cindex Rest-frame wavelength
+@cindex Wavelength, rest-frame
+Find the redshift to use in next steps based on the rest-frame and observed
wavelengths of a line.
+This option is thus an alternative to @code{--redshift} or @code{--velocity},
it cannot be used with them.
+Wavelengths are assumed to be in Angstroms.
+The first argument identifies the line.
+It can be one of the standard names below, or any rest-frame wavelength in
Angstroms.
+The second argument is the observed wavelength of that line.
+For example @option{--obsline=lyalpha,6000} is the same as
@option{--obsline=1215.64,6000}.
-@dispmath{\mu=I_{nn}, \quad \sigma=\sqrt{C^2+I_{nn}}}
+The pre-defined names are listed below, sorted from red (longer wavelength) to
blue (shorter wavelength).
+You can get this list on the command-line with the @option{--listlines}.
-@cindex ADU
-@cindex Gain
-@cindex Counts
-This type of noise is independent of the signal in the dataset, it is only
determined by the instrument.
-So the flux scale (and not magnitude scale) is most commonly used for this
type of noise.
-In practice, this value is usually reported in analog-to-digital units or
ADUs, not flux or electron counts.
-The gain value of the device can be used to convert between these two, see
@ref{Brightness flux magnitude}.
+@table @code
+@item siired
+[6731@AA{}] SII doublet's redder line.
-@node Final noised pixel value, Generating random numbers, Instrumental noise,
Noise basics
-@subsubsection Final noised pixel value
-Based on the discussions in @ref{Photon counting noise} and @ref{Instrumental
noise}, depending on the values you specify for @mymath{B} and @mymath{C} from
the above, the final noised value for each pixel is a random value chosen from
a Gaussian distribution with
+@item sii
+@cindex Doublet: SII
+@cindex SII doublet
+[6724@AA{}] SII doublet's mean center at .
-@dispmath{\mu=B+I_{nn}, \quad \sigma=\sqrt{C^2+B+I_{nn}}}
+@item siiblue
+[6717@AA{}] SII doublet's bluer line.
+@item niired
+[6584@AA{}] NII doublet's redder line.
+@item nii
+@cindex Doublet: NII
+@cindex NII doublet
+[6566@AA{}] NII doublet's mean center.
-@node Generating random numbers, , Final noised pixel value, Noise basics
-@subsubsection Generating random numbers
+@item halpha
+@cindex H-alpha
+[6562.8@AA{}] H-@mymath{\alpha} line.
-@cindex Random numbers
-@cindex Numbers, random
-As discussed above, to generate noise we need to make random samples of a
particular distribution.
-So it is important to understand some general concepts regarding the
generation of random numbers.
-For a very complete and nice introduction we strongly advise reading Donald
Knuth's ``The art of computer programming'', volume 2, chapter
3@footnote{Knuth, Donald. 1998.
-The art of computer programming. Addison--Wesley. ISBN 0-201-89684-2 }.
-Quoting from the GNU Scientific Library manual, ``If you don't own it, you
should stop reading right now, run to the nearest bookstore, and buy
it''@footnote{For students, running to the library might be more affordable!}!
+@item niiblue
+[6548@AA{}] NII doublet's bluer line.
-@cindex Psuedo-random numbers
-@cindex Numbers, psuedo-random
-Using only software, we can only produce what is called a psuedo-random
sequence of numbers.
-A true random number generator is a hardware (let's assume we have made sure
it has no systematic biases), for example throwing dice or flipping coins
(which have remained from the ancient times).
-More modern hardware methods use atmospheric noise, thermal noise or other
types of external electromagnetic or quantum phenomena.
-All pseudo-random number generators (software) require a seed to be the basis
of the generation.
-The advantage of having a seed is that if you specify the same seed for
multiple runs, you will get an identical sequence of random numbers which
allows you to reproduce the same final noised image.
+@item oiiired-vis
+[5007@AA{}] OIII doublet's redder line in the visible.
-@cindex Environment variables
-@cindex GNU Scientific Library
-The programs in GNU Astronomy Utilities (for example MakeNoise or
MakeProfiles) use the GNU Scientific Library (GSL) to generate random numbers.
-GSL allows the user to set the random number generator through environment
variables, see @ref{Installation directory} for an introduction to environment
variables.
-In the chapter titled ``Random Number Generation'' they have fully explained
the various random number generators that are available (there are a lot of
them!).
-Through the two environment variables @code{GSL_RNG_TYPE} and
@code{GSL_RNG_SEED} you can specify the generator and its seed respectively.
+@item oiii-vis
+@cindex Doublet: OIII (visible)
+@cindex OIII doublet in visible
+[4983@AA{}] OIII doublet's mean center in the visible.
-@cindex Seed, Random number generator
-@cindex Random number generator, Seed
-If you don't specify a value for @code{GSL_RNG_TYPE}, GSL will use its default
random number generator type.
-The default type is sufficient for most general applications.
-If no value is given for the @code{GSL_RNG_SEED} environment variable and you
have asked Gnuastro to read the seed from the environment (through the
@option{--envseed} option), then GSL will use the default value of each
generator to give identical outputs.
-If you don't explicitly tell Gnuastro programs to read the seed value from the
environment variable, then they will use the system time (accurate to within a
microsecond) to generate (apparently random) seeds.
-In this manner, every time you run the program, you will get a different
random number distribution.
+@item oiiiblue-vis
+[4959@AA{}] OIII doublet's bluer line in the visible.
-There are two ways you can specify values for these environment variables.
-You can call them on the same command-line for example:
+@item hbeta
+@cindex H-beta
+[4861.36@AA{}] H-@mymath{\beta} line.
-@example
-$ GSL_RNG_TYPE="taus" GSL_RNG_SEED=345 astmknoise input.fits
-@end example
+@item heii-vis
+[4686@AA{}] HeII doublet's redder line in the visible.
-@noindent
-In this manner the values will only be used for this particular execution of
MakeNoise.
-Alternatively, you can define them for the full period of your terminal
session or script length, using the shell's @command{export} command with the
two separate commands below (for a script remove the @code{$} signs):
+@item hgamma
+@cindex H-gamma
+[4340.46@AA{}] H-@mymath{\gamma} line.
-@example
-$ export GSL_RNG_TYPE="taus"
-$ export GSL_RNG_SEED=345
-@end example
+@item hdelta
+@cindex H-delta
+[4101.74@AA{}] H-@mymath{\delta} line.
-@cindex Startup scripts
-@cindex @file{.bashrc}
-@noindent
-The subsequent programs which use GSL's random number generators will hence
forth use these values in this session of the terminal you are running or while
executing this script.
-In case you want to set fixed values for these parameters every time you use
the GSL random number generator, you can add these two lines to your
@file{.bashrc} startup script@footnote{Don't forget that if you are going to
give your scripts (that use the GSL random number generator) to others you have
to make sure you also tell them to set these environment variable separately.
-So for scripts, it is best to keep all such variable definitions within the
script, even if they are within your @file{.bashrc}.}, see @ref{Installation
directory}.
+@item hepsilon
+@cindex H-epsilon
+[3970.07@AA{}] H-@mymath{\epsilon} line.
-@cartouche
-@noindent
-@strong{NOTE:} If the two environment variables @code{GSL_RNG_TYPE} and
@code{GSL_RNG_SEED} are defined, GSL will report them by default, even if you
don't use the @option{--envseed} option.
-For example you can see the top few lines of the output of MakeProfiles:
+@item neiii
+[3869@AA{}] NEIII line.
-@example
-$ export GSL_RNG_TYPE="taus"
-$ export GSL_RNG_SEED=345
-$ astmkprof -s1 --kernel=gaussian,2,5 --envseed
-GSL_RNG_TYPE=taus
-GSL_RNG_SEED=345
-MakeProfiles A.B started on DDD MMM DD HH:MM:SS YYYY
- - Building one gaussian kernel
- - Random number generator (RNG) type: ranlxs1
- - RNG seed for all profiles: 345
- ---- ./kernel.fits created.
-MakeProfiles finished in 0.111271 seconds
-@end example
+@item oiired
+[3729@AA{}] OII doublet's redder line.
-@noindent
-@cindex Seed, Random number generator
-@cindex Random number generator, Seed
-The first two output lines (showing the names of the environment variables)
are printed by GSL before MakeProfiles actually starts generating random
numbers.
-The Gnuastro programs will report the values they use independently, you
should check them for the final values used.
-For example if @option{--envseed} is not given, @code{GSL_RNG_SEED} will not
be used and the last line shown above will not be printed.
-In the case of MakeProfiles, each profile will get its own seed value.
-@end cartouche
+@item oii
+@cindex Doublet: OII
+@cindex OII doublet
+[3727.5@AA{}] OII doublet's mean center.
+@item oiiblue
+[3726@AA{}] OII doublet's bluer line.
-@node Invoking astmknoise, , Noise basics, MakeNoise
-@subsection Invoking MakeNoise
+@item blimit
+@cindex Balmer limit
+[3646@AA{}] Balmer limit.
-MakeNoise will add noise to an existing image.
-The executable name is @file{astmknoise} with the following general template
+@item mgiired
+[2803@AA{}] MgII doublet's redder line.
-@example
-$ astmknoise [OPTION ...] InputImage.fits
-@end example
+@item mgii
+@cindex Doublet: MgII
+@cindex MgII doublet
+[2799.5@AA{}] MgII doublet's mean center.
-@noindent
-One line examples:
+@item mgiiblue
+[2796@AA{}] MgII doublet's bluer line.
-@example
-## Add noise with a standard deviation of 100 to image.
-## (this is independent of the pixel value: not Poission noise)
-$ astmknoise --sigma=100 image.fits
+@item ciiired
+[1909@AA{}] CIII doublet's redder line.
-## Add noise to input image assuming a background magnitude (with
-## zero point magnitude of 0) and a certain instrumental noise:
-$ astmknoise --background=-10 -z0 --instrumental=20 mockimage.fits
-@end example
+@item ciii
+@cindex Doublet: CIII
+@cindex CIII doublet
+[1908@AA{}] CIII doublet's mean center.
-@noindent
-If actual processing is to be done, the input image is a mandatory argument.
-The full list of options common to all the programs in Gnuastro can be seen in
@ref{Common options}.
-The type (see @ref{Numeric data types}) of the output can be specified with
the @option{--type} option, see @ref{Input output options}.
-The header of the output FITS file keeps all the parameters that were
influential in making it.
-This is done for future reproducibility.
+@item ciiiblue
+[1907@AA{}] CIII doublet's bluer line.
-@table @option
+@item si_iiired
+[1892@AA{}] SiIII doublet's redder line.
-@item -b FLT
-@itemx --background=FLT
-The background value (per pixel) that will be added to each pixel value
(internally) to estimate Poisson noise, see @ref{Photon counting noise}.
-By default the units of this value are assumed to be in magnitudes, hence a
@option{--zeropoint} is also necessary.
-But if the background is in units of brightness, you need add
@option{--bgisbrightness}, see @ref{Brightness flux magnitude}
+@item si_iii
+@cindex Doublet: SiIII
+@cindex SiIII doublet
+[1887.5@AA{}] SiIII doublet's mean center.
-Internally, the value given to this option will be converted to brightness
(@mymath{b}, when @option{--bgisbrightness} is called, the value will be used
directly).
-Assuming the pixel value is @mymath{p}, the random value for that pixel will
be taken from a Gaussian distribution with mean of @mymath{p+b} and standard
deviation of @mymath{\sqrt{p+b}}.
-With this option, the noise will therefore be dependent on the pixel values:
according to the Poission noise model, as the pixel value becomes larger, its
noise will also become larger.
-This is thus a realistic way to model noise, see @ref{Photon counting noise}.
+@item si_iiiblue
+[1883@AA{}] SiIII doublet's bluer line.
-@item -B
-@itemx --bgisbrightness
-The value given to @option{--background} should be interpretted as brightness,
not as a magnitude.
+@item oiiired-uv
+[1666@AA{}] OIII doublet's redder line in the ultra-violet.
-@item -z FLT
-@itemx --zeropoint=FLT
-The zero point magnitude used to convert the value of @option{--background}
(in units of magnitude) to flux, see @ref{Brightness flux magnitude}.
+@item oiii-uv
+@cindex Doublet: OIII (in UV)
+@cindex OIII doublet in UV
+[1663.5@AA{}] OIII doublet's mean center in the ultra-violet.
-@item -i FLT
-@itemx --instrumental=FLT
-The instrumental noise which is in units of flux, see @ref{Instrumental noise}.
+@item oiiiblue-uv
+[1661@AA{}] OIII doublet's bluer line in the ultra-violet.
-@item -s FLT
-@item --sigma=FLT
-The total noise sigma in the same units as the pixel values.
-With this option, the @option{--background}, @option{--zeropoint} and
@option{--instrumental} will be ignored.
-With this option, the noise will be independent of the pixel values (which is
not realistic, see @ref{Photon counting noise}).
-Hence it is only useful if you are working on low surface brightness regions
where the change in pixel value (and thus real noise) is insignificant.
+@item heii-uv
+[1640@AA{}] HeII doublet's bluer line in the ultra-violet.
-Generally, @strong{usage of this option is discouraged} unless you understand
the risks of not simulating real noise.
-This is because with this option, you will not get Poisson noise (the common
noise model for astronomical imaging), where the noise varies based on pixel
value.
-Use @option{--background} for adding Poission noise.
+@item civred
+[1551@AA{}] CIV doublet's redder line.
-@item -e
-@itemx --envseed
-@cindex Seed, Random number generator
-@cindex Random number generator, Seed
-Use the @code{GSL_RNG_SEED} environment variable for the seed used in the
random number generator, see @ref{Generating random numbers}.
-With this option, the output image noise is always going to be identical (or
reproducible).
+@item civ
+@cindex Doublet: CIV
+@cindex CIV doublet
+[1549@AA{}] CIV doublet's mean center.
-@item -d
-@itemx --doubletype
-Save the output in the double precision floating point format that was used
internally.
-This option will be most useful if the input images were of integer types.
+@item civblue
+[1548@AA{}] CIV doublet's bluer line.
-@end table
+@item nv
+[1240@AA{}] NV (four times ionized Sodium).
+@item lyalpha
+@cindex Lyman-alpha
+[1215.67@AA{}] Lyman-@mymath{\alpha} line.
+@item lybeta
+@cindex Lyman-beta
+[1025.7@AA{}] Lyman-@mymath{\beta} line.
+@item lygamma
+@cindex Lyman-gamma
+[972.54@AA{}] Lyman-@mymath{\gamma} line.
+@item lydelta
+@cindex Lyman-delta
+[949.74@AA{}] Lyman-@mymath{\delta} line.
+@item lyepsilon
+@cindex Lyman-epsilon
+[937.80@AA{}] Lyman-@mymath{\epsilon} line.
+@item lylimit
+@cindex Lyman limit
+[912@AA{}] Lyman limit.
+@end table
+@end table
+@node CosmicCalculator basic cosmology calculations, CosmicCalculator spectral
line calculations, CosmicCalculator input options, Invoking astcosmiccal
+@subsubsection CosmicCalculator basic cosmology calculations
+By default, when no specific calculations are requested, CosmicCalculator will
print a complete set of all its calculators (one line for each calculation, see
@ref{Invoking astcosmiccal}).
+The full list of calculations can be useful when you don't want any specific
value, but just a general view.
+In other contexts (for example in a batch script or during a discussion), you
know exactly what you want and don't want to be distracted by all the extra
information.
+You can use any number of the options described below in any order.
+When any of these options are requested, CosmicCalculator's output will just
be a single line with a single space between the (possibly) multiple values.
+In the example below, only the tangential distance along one arc-second (in
kpc), absolute magnitude conversion, and age of the universe at redshift 2 are
printed (recall that you can merge short options together, see @ref{Options}).
+@example
+$ astcosmiccal -z2 -sag
+8.585046 44.819248 3.289979
+@end example
+Here is one example of using this feature in scripts: by adding the following
two lines in a script to keep/use the comoving volume with varying redshifts:
+@example
+z=3.12
+vol=$(astcosmiccal --redshift=$z --volume)
+@end example
+@cindex GNU Grep
+@noindent
+In a script, this operation might be necessary for a large number of objects
(several of galaxies in a catalog for example).
+So the fact that all the other default calculations are ignored will also help
you get to your result faster.
+If you are indeed dealing with many (for example thousands) of redshifts,
using CosmicCalculator is not the best/fastest solution.
+Because it has to go through all the configuration files and preparations for
each invocation.
+To get the best efficiency (least overhead), we recommend using Gnuastro's
cosmology library (see @ref{Cosmology library}).
+CosmicCalculator also calls the library functions defined there for its
calculations, so you get the same result with no overhead.
+Gnuastro also has libraries for easily reading tables into a C program, see
@ref{Table input output}.
+Afterwards, you can easily build and run your C program for the particular
processing with @ref{BuildProgram}.
-@node High-level calculations, Library, Modeling and fittings, Top
-@chapter High-level calculations
+If you just want to inspect the value of a variable visually, the description
(which comes with units) might be more useful.
+In such cases, the following command might be better.
+The other calculations will also be done, but they are so fast that you will
not notice on modern computers (the time it takes your eye to focus on the
result is usually longer than the processing: a fraction of a second).
-After the reduction of raw data (for example with the programs in @ref{Data
manipulation}) you will have reduced images/data ready for processing/analyzing
(for example with the programs in @ref{Data analysis}).
-But the processed/analyzed data (or catalogs) are still not enough to derive
any scientific result.
-Even higher-level analysis is still needed to convert the observed magnitudes,
sizes or volumes into physical quantities that we associate with each catalog
entry or detected object which is the purpose of the tools in this section.
+@example
+$ astcosmiccal --redshift=0.832 | grep volume
+@end example
+The full list of CosmicCalculator's specific calculations is present below in
two groups: basic cosmology calculations and those related to spectral lines.
+In case you have forgot the units, you can use the @option{--help} option
which has the units along with a short description.
+@table @option
+@item -e
+@itemx --usedredshift
+The redshift that was used in this run.
+In many cases this is the main input parameter to CosmicCalculator, but it is
useful in others.
+For example in combination with @option{--obsline} (where you give an observed
and rest-frame wavelength and would like to know the redshift) or with
@option{--velocity} (where you specify the velocity instead of redshift).
+Another example is when you run CosmicCalculator in a loop, while changing the
redshift and you want to keep the redshift value with the resulting calculation.
+@item -Y
+@itemx --usedvelocity
+The velocity (in km/s) that was used in this run.
+The conversion from redshift will be done with the more general and accurate
relativistic equation of @mymath{1+z=\sqrt{(c+v)/(c-v)}}, not the simplified
@mymath{z\approx v/c}.
-@menu
-* CosmicCalculator:: Calculate cosmological variables
-@end menu
+@item -G
+@itemx --agenow
+The current age of the universe (given the input parameters) in Ga (Giga
annum, or billion years).
-@node CosmicCalculator, , High-level calculations, High-level calculations
-@section CosmicCalculator
+@item -C
+@itemx --criticaldensitynow
+The current critical density (given the input parameters) in grams per
centimeter-cube (@mymath{g/cm^3}).
-To derive higher-level information regarding our sources in extra-galactic
astronomy, cosmological calculations are necessary.
-In Gnuastro, CosmicCalculator is in charge of such calculations.
-Before discussing how CosmicCalculator is called and operates (in
@ref{Invoking astcosmiccal}), it is important to provide a rough but mostly
self sufficient review of the basics and the equations used in the analysis.
-In @ref{Distance on a 2D curved space} the basic idea of understanding
distances in a curved and expanding 2D universe (which we can visualize) are
reviewed.
-Having solidified the concepts there, in @ref{Extending distance concepts to
3D}, the formalism is extended to the 3D universe we are trying to study in our
research.
+@item -d
+@itemx --properdistance
+The proper distance (at current time) to object at the given redshift in
Megaparsecs (Mpc).
+See @ref{Distance on a 2D curved space} for a description of the proper
distance.
-The focus here is obtaining a physical insight into these equations (mainly
for the use in real observational studies).
-There are many books thoroughly deriving and proving all the equations with
all possible initial conditions and assumptions for any abstract universe,
interested readers can study those books.
+@item -A
+@itemx --angulardimdist
+The angular diameter distance to object at given redshift in Megaparsecs (Mpc).
-@menu
-* Distance on a 2D curved space:: Distances in 2D for simplicity
-* Extending distance concepts to 3D:: Going to 3D (our real universe).
-* Invoking astcosmiccal:: How to run CosmicCalculator
-@end menu
+@item -s
+@itemx --arcsectandist
+The tangential distance covered by 1 arc-seconds at the given redshift in
kiloparsecs (Kpc).
+This can be useful when trying to estimate the resolution or pixel scale of an
instrument (usually in units of arc-seconds) at a given redshift.
-@node Distance on a 2D curved space, Extending distance concepts to 3D,
CosmicCalculator, CosmicCalculator
-@subsection Distance on a 2D curved space
+@item -L
+@itemx --luminositydist
+The luminosity distance to object at given redshift in Megaparsecs (Mpc).
-The observations to date (for example the Planck 2015 results), have not
measured@footnote{The observations are interpreted under the assumption of
uniform curvature.
-For a relativistic alternative to dark energy (and maybe also some part of
dark matter), non-uniform curvature may be even be more critical, but that is
beyond the scope of this brief explanation.} the presence of significant
curvature in the universe.
-However to be generic (and allow its measurement if it does in fact exist), it
is very important to create a framework that allows non-zero uniform curvature.
-However, this section is not intended to be a fully thorough and
mathematically complete derivation of these concepts.
-There are many references available for such reviews that go deep into the
abstract mathematical proofs.
-The emphasis here is on visualization of the concepts for a beginner.
+@item -u
+@itemx --distancemodulus
+The distance modulus at given redshift.
-As 3D beings, it is difficult for us to mentally create (visualize) a picture
of the curvature of a 3D volume.
-Hence, here we will assume a 2D surface/space and discuss distances on that 2D
surface when it is flat and when it is curved.
-Once the concepts have been created/visualized here, we will extend them, in
@ref{Extending distance concepts to 3D}, to a real 3D spatial @emph{slice} of
the Universe we live in and hope to study.
+@item -a
+@itemx --absmagconv
+The conversion factor (addition) to absolute magnitude.
+Note that this is practically the distance modulus added with
@mymath{-2.5\log{(1+z)}} for the desired redshift based on the input parameters.
+Once the apparent magnitude and redshift of an object is known, this value may
be added with the apparent magnitude to give the object's absolute magnitude.
-To be more understandable (actively discuss from an observer's point of view)
let's assume there's an imaginary 2D creature living on the 2D space (which
@emph{might} be curved in 3D).
-Here, we will be working with this creature in its efforts to analyze
distances in its 2D universe.
-The start of the analysis might seem too mundane, but since it is difficult to
imagine a 3D curved space, it is important to review all the very basic
concepts thoroughly for an easy transition to a universe that is more difficult
to visualize (a curved 3D space embedded in 4D).
+@item -g
+@itemx --age
+Age of the universe at given redshift in Ga (Giga annum, or billion years).
-To start, let's assume a static (not expanding or shrinking), flat 2D surface
similar to @ref{flatplane} and that the 2D creature is observing its universe
from point @mymath{A}.
-One of the most basic ways to parameterize this space is through the Cartesian
coordinates (@mymath{x}, @mymath{y}).
-In @ref{flatplane}, the basic axes of these two coordinates are plotted.
-An infinitesimal change in the direction of each axis is written as
@mymath{dx} and @mymath{dy}.
-For each point, the infinitesimal changes are parallel with the respective
axes and are not shown for clarity.
-Another very useful way of parameterizing this space is through polar
coordinates.
-For each point, we define a radius (@mymath{r}) and angle (@mymath{\phi}) from
a fixed (but arbitrary) reference axis.
-In @ref{flatplane} the infinitesimal changes for each polar coordinate are
plotted for a random point and a dashed circle is shown for all points with the
same radius.
+@item -b
+@itemx --lookbacktime
+The look-back time to given redshift in Ga (Giga annum, or billion years).
+The look-back time at a given redshift is defined as the current age of the
universe (@option{--agenow}) subtracted by the age of the universe at the given
redshift.
-@float Figure,flatplane
-@center@image{gnuastro-figures/flatplane, 10cm, , }
+@item -c
+@itemx --criticaldensity
+The critical density at given redshift in grams per centimeter-cube
(@mymath{g/cm^3}).
-@caption{Two dimensional Cartesian and polar coordinates on a flat
-plane.}
-@end float
+@item -v
+@itemx --onlyvolume
+The comoving volume in Megaparsecs cube (Mpc@mymath{^3}) until the desired
redshift based on the input parameters.
-Assuming an object is placed at a certain position, which can be parameterized
as @mymath{(x,y)}, or @mymath{(r,\phi)}, a general infinitesimal change in its
position will place it in the coordinates @mymath{(x+dx,y+dy)} and
@mymath{(r+dr,\phi+d\phi)}.
-The distance (on the flat 2D surface) that is covered by this infinitesimal
change in the static universe (@mymath{ds_s}, the subscript signifies the
static nature of this universe) can be written as:
+@end table
-@dispmath{ds_s=dx^2+dy^2=dr^2+r^2d\phi^2}
-The main question is this: how can the 2D creature incorporate the (possible)
curvature in its universe when it's calculating distances? The universe that it
lives in might equally be a curved surface like @ref{sphereandplane}.
-The answer to this question but for a 3D being (us) is the whole purpose to
this discussion.
-Here, we want to give the 2D creature (and later, ourselves) the tools to
measure distances if the space (that hosts the objects) is curved.
-@ref{sphereandplane} assumes a spherical shell with radius @mymath{R} as the
curved 2D plane for simplicity.
-The 2D plane is tangent to the spherical shell and only touches it at
@mymath{A}.
-This idea will be generalized later.
-The first step in measuring the distance in a curved space is to imagine a
third dimension along the @mymath{z} axis as shown in @ref{sphereandplane}.
-For simplicity, the @mymath{z} axis is assumed to pass through the center of
the spherical shell.
-Our imaginary 2D creature cannot visualize the third dimension or a curved 2D
surface within it, so the remainder of this discussion is purely abstract for
it (similar to us having difficulty in visualizing a 3D curved space in 4D).
-But since we are 3D creatures, we have the advantage of visualizing the
following steps.
-Fortunately the 2D creature is already familiar with our mathematical
constructs, so it can follow our reasoning.
-With the third axis added, a generic infinitesimal change over @emph{the full}
3D space corresponds to the distance:
+@node CosmicCalculator spectral line calculations, , CosmicCalculator basic
cosmology calculations, Invoking astcosmiccal
+@subsubsection CosmicCalculator spectral line calculations
-@dispmath{ds_s^2=dx^2+dy^2+dz^2=dr^2+r^2d\phi^2+dz^2.}
+@cindex Rest frame wavelength
+At different redshifts, observed spectral lines are shifted compared to their
rest frame wavelengths with this simple relation:
@mymath{\lambda_{obs}=\lambda_{rest}(1+z)}.
+Although this relation is very simple and can be done for one line in the head
(or a simple calculator!), it slowly becomes tiring when dealing with a lot of
lines or redshifts, or some precision is necessary.
+The options in this section are thus provided to greatly simplify usage of
this simple equation, and also helping by storing a list of pre-defined
spectral line wavelengths.
-@float Figure,sphereandplane
-@center@image{gnuastro-figures/sphereandplane, 10cm, , }
+For example if you want to know the wavelength of the @mymath{H\alpha} line
(at 6562.8 Angstroms in rest frame), when @mymath{Ly\alpha} is at 8000
Angstroms, you can call CosmicCalculator like the first example below.
+And if you want the wavelength of all pre-defined spectral lines at this
redshift, you can use the second command.
-@caption{2D spherical shell (centered on @mymath{O}) and flat plane (light
gray) tangent to it at point @mymath{A}.}
-@end float
+@example
+$ astcosmiccal --obsline=lyalpha,8000 --lineatz=halpha
+$ astcosmiccal --obsline=lyalpha,8000 --listlinesatz
+@end example
-It is very important to recognize that this change of distance is for
@emph{any} point in the 3D space, not just those changes that occur on the 2D
spherical shell of @ref{sphereandplane}.
-Recall that our 2D friend can only do measurements on the 2D surfaces, not the
full 3D space.
-So we have to constrain this general change to any change on the 2D spherical
shell.
-To do that, let's look at the arbitrary point @mymath{P} on the 2D spherical
shell.
-Its image (@mymath{P'}) on the flat plain is also displayed. From the dark
gray triangle, we see that
+Bellow you can see the printed/output calculations of CosmicCalculator that
are related to spectral lines.
+Note that @option{--obsline} is an input parameter, so its discussed (with the
full list of known lines) in @ref{CosmicCalculator input options}.
-@dispmath{\sin\theta={r\over R},\quad\cos\theta={R-z\over R}.}These relations
allow the 2D creature to find the value of @mymath{z} (an abstract dimension
for it) as a function of r (distance on a flat 2D plane, which it can
visualize) and thus eliminate @mymath{z}.
-From @mymath{\sin^2\theta+\cos^2\theta=1}, we get @mymath{z^2-2Rz+r^2=0} and
solving for @mymath{z}, we find:
+@table @option
-@dispmath{z=R\left(1\pm\sqrt{1-{r^2\over R^2}}\right).}
+@item --listlines
+List the pre-defined rest frame spectral line wavelengths and their names on
standard output, then abort CosmicCalculator.
+When this option is given, other operations on the command-line will be
ignored.
+This is convenient when you forget the specific name of the spectral line used
within Gnuastro, or when you forget the exact wavelength of a certain line.
-The @mymath{\pm} can be understood from @ref{sphereandplane}: For each
@mymath{r}, there are two points on the sphere, one in the upper hemisphere and
one in the lower hemisphere.
-An infinitesimal change in @mymath{r}, will create the following infinitesimal
change in @mymath{z}:
+These names can be used with the options that deal with spectral lines, for
example @option{--obsline} and @option{--lineatz} (@ref{CosmicCalculator basic
cosmology calculations}).
-@dispmath{dz={\mp r\over R}\left(1\over
-\sqrt{1-{r^2/R^2}}\right)dr.}Using the positive signed equation instead of
@mymath{dz} in the @mymath{ds_s^2} equation above, we get:
+The format of the output list is a two-column table, with Gnuastro's text
table format (see @ref{Gnuastro text table format}).
+Therefore, if you are only looking for lines in a specific range, you can pipe
the output into Gnuastro's table program and use its @option{--range} option on
the @code{wavelength} (first) column.
+For example, if you only want to see the lines between 4000 and 6000
Angstroms, you can run this command:
-@dispmath{ds_s^2={dr^2\over 1-r^2/R^2}+r^2d\phi^2.}
+@example
+$ astcosmiccal --listlines \
+ | asttable --range=wavelength,4000,6000
+@end example
-The derivation above was done for a spherical shell of radius @mymath{R} as a
curved 2D surface.
-To generalize it to any surface, we can define @mymath{K=1/R^2} as the
curvature parameter.
-Then the general infinitesimal change in a static universe can be written as:
+@noindent
+And if you want to use the list later and have it as a table in a file, you
can easily add the @option{--output} (or @option{-o}) option to the
@command{asttable} command, and specify the filename, for example
@option{--output=lines.fits} or @option{--output=lines.txt}.
+
+@item --listlinesatz
+Similar to @option{--listlines} (above), but the printed wavelength is not in
the rest frame, but redshifted to the given redshift.
+Recall that the redshift can be specified by @option{--redshift} directly or
by @option{--obsline}, see @ref{CosmicCalculator input options}.
-@dispmath{ds_s^2={dr^2\over 1-Kr^2}+r^2d\phi^2.}
+@item -i STR/FLT
+@itemx --lineatz=STR/FLT
+The wavelength of the specified line at the redshift given to CosmicCalculator.
+The line can be specified either by its name or directly as a number (its
wavelength).
+To get the list of pre-defined names for the lines and their wavelength, you
can use the @option{--listlines} option, see @ref{CosmicCalculator input
options}.
+In the former case (when a name is given), the returned number is in units of
Angstroms.
+In the latter (when a number is given), the returned value is the same units
of the input number (assuming its a wavelength).
-Therefore, when @mymath{K>0} (and curvature is the same everywhere), we have a
finite universe, where @mymath{r} cannot become larger than @mymath{R} as in
@ref{sphereandplane}.
-When @mymath{K=0}, we have a flat plane (@ref{flatplane}) and a negative
@mymath{K} will correspond to an imaginary @mymath{R}.
-The latter two cases may be infinite in area (which is not a simple concept,
but mathematically can be modeled with @mymath{r} extending infinitely), or
finite-area (like a cylinder is flat everywhere with @mymath{ds_s^2={dx^2 +
dy^2}}, but finite in one direction in size).
+@end table
-@cindex Proper distance
-A very important issue that can be discussed now (while we are still in 2D and
can actually visualize things) is that @mymath{\overrightarrow{r}} is tangent
to the curved space at the observer's position.
-In other words, it is on the gray flat surface of @ref{sphereandplane}, even
when the universe if curved: @mymath{\overrightarrow{r}=P'-A}.
-Therefore for the point @mymath{P} on a curved space, the raw coordinate
@mymath{r} is the distance to @mymath{P'}, not @mymath{P}.
-The distance to the point @mymath{P} (at a specific coordinate @mymath{r} on
the flat plane) over the curved surface (thick line in @ref{sphereandplane}) is
called the @emph{proper distance} and is displayed with @mymath{l}.
-For the specific example of @ref{sphereandplane}, the proper distance can be
calculated with: @mymath{l=R\theta} (@mymath{\theta} is in radians).
-Using the @mymath{\sin\theta} relation found above, we can find @mymath{l} as
a function of @mymath{r}:
-@dispmath{\theta=\sin^{-1}\left({r\over R}\right)\quad\rightarrow\quad
-l(r)=R\sin^{-1}\left({r\over R}\right)}
-@mymath{R} is just an arbitrary constant and can be directly found from
@mymath{K}, so for cleaner equations, it is common practice to set
@mymath{R=1}, which gives: @mymath{l(r)=\sin^{-1}r}.
-Also note that when @mymath{R=1}, then @mymath{l=\theta}.
-Generally, depending on the curvature, in a @emph{static} universe the proper
distance can be written as a function of the coordinate @mymath{r} as (from now
on we are assuming @mymath{R=1}):
-@dispmath{l(r)=\sin^{-1}(r)\quad(K>0),\quad\quad
-l(r)=r\quad(K=0),\quad\quad l(r)=\sinh^{-1}(r)\quad(K<0).}With
-@mymath{l}, the infinitesimal change of distance can be written in a
-more simpler and abstract form of
-@dispmath{ds_s^2=dl^2+r^2d\phi^2.}
-@cindex Comoving distance
-Until now, we had assumed a static universe (not changing with time).
-But our observations so far appear to indicate that the universe is expanding
(it isn't static).
-Since there is no reason to expect the observed expansion is unique to our
particular position of the universe, we expect the universe to be expanding at
all points with the same rate at the same time.
-Therefore, to add a time dependence to our distance measurements, we can
include a multiplicative scaling factor, which is a function of time:
@mymath{a(t)}.
-The functional form of @mymath{a(t)} comes from the cosmology, the physics we
assume for it: general relativity, and the choice of whether the universe is
uniform (`homogeneous') in density and curvature or inhomogeneous.
-In this section, the functional form of @mymath{a(t)} is irrelevant, so we can
avoid these issues.
-With this scaling factor, the proper distance will also depend on time.
-As the universe expands, the distance between two given points will shift to
larger values.
-We thus define a distance measure, or coordinate, that is independent of time
and thus doesn't `move'.
-We call it the @emph{comoving distance} and display with @mymath{\chi} such
that: @mymath{l(r,t)=\chi(r)a(t)}.
-We have therefore, shifted the @mymath{r} dependence of the proper distance we
derived above for a static universe to the comoving distance:
+@node Installed scripts, Library, High-level calculations, Top
+@chapter Installed scripts
-@dispmath{\chi(r)=\sin^{-1}(r)\quad(K>0),\quad\quad
-\chi(r)=r\quad(K=0),\quad\quad \chi(r)=\sinh^{-1}(r)\quad(K<0).}
+Gnuastro's programs (introduced in previous chapters) are designed to be
highly modular and thus contain lower-level operations on the data.
+However, in many contexts, certain higher-level are also shared between many
contexts.
+For example a sequence of calls to multiple Gnuastro programs, or a special
way of running a program and treating the output.
+To facilitate such higher-level data analysis, Gnuastro also installs some
scripts on your system with the (@code{astscript-}) prefix (in contrast to the
other programs that only have the @code{ast} prefix).
-Therefore, @mymath{\chi(r)} is the proper distance to an object at a specific
reference time: @mymath{t=t_r} (the @mymath{r} subscript signifies
``reference'') when @mymath{a(t_r)=1}.
-At any arbitrary moment (@mymath{t\neq{t_r}}) before or after @mymath{t_r},
the proper distance to the object can be scaled with @mymath{a(t)}.
+@cindex GNU Bash
+@cindex Portable shell
+@cindex Shell, portable
+Like all of Gnuastro's source code, these scripts are also heavily commented.
+They are written in portable shell scripts (command-line environments), which
doesn't need compilation.
+Therefore, if you open the installed scripts in a text editor, you can
actually read them@footnote{Gnuastro's installed programs (those only starting
with @code{ast}) aren't human-readable.
+They are written in C and need to be compiled before execution.
+Compilation optimizes the steps into the low-level hardware CPU
instructions/language to improve efficiency.
+Because compiled programs don't need an interpreter like Bash on every run,
they are much faster and more independent than scripts.
+To read the source code of the programs, look into the @file{bin/progname}
directory of Gnuastro's source (@ref{Downloading the source}).
+If you would like to read more about why C was chosen for the programs, please
see @ref{Why C}.}.
+For example with this command (just replace @code{nano} with your favorite
text editor, like @command{emacs} or @command{vim}):
-Measuring the change of distance in a time-dependent (expanding) universe only
makes sense if we can add up space and time@footnote{In other words, making our
space-time consistent with Minkowski space-time geometry.
-In this geometry, different observers at a given point (event) in space-time
split up space-time into `space' and `time' in different ways, just like people
at the same spatial position can make different choices of splitting up a map
into `left--right' and `up--down'.
-This model is well supported by twentieth and twenty-first century
observations.}.
-But we can only add bits of space and time together if we measure them in the
same units: with a conversion constant (similar to how 1000 is used to convert
a kilometer into meters).
-Experimentally, we find strong support for the hypothesis that this conversion
constant is the speed of light (or gravitational waves@footnote{The speed of
gravitational waves was recently found to be very similar to that of light in
vacuum, see @url{https://arxiv.org/abs/1710.05834, arXiv:1710.05834}.}) in a
vacuum.
-This speed is postulated to be constant@footnote{In @emph{natural units},
speed is measured in units of the speed of light in vacuum.} and is almost
always written as @mymath{c}.
-We can thus parameterize the change in distance on an expanding 2D surface as
+@example
+$ nano $(which astscript-NAME)
+@end example
-@dispmath{ds^2=c^2dt^2-a^2(t)ds_s^2 = c^2dt^2-a^2(t)(d\chi^2+r^2d\phi^2).}
+Shell scripting is the same language that you use when typing on the
command-line.
+Therefore shell scripting is much more widely known and used compared to C
(the language of other Gnuastro programs).
+Because Gnuastro's installed scripts do higher-level operations, customizing
these scripts for a special project will be more common than the programs.
+These scripts also accept options and are in many ways similar to the programs
(see @ref{Common options}) with some minor differences:
-@node Extending distance concepts to 3D, Invoking astcosmiccal, Distance on a
2D curved space, CosmicCalculator
-@subsection Extending distance concepts to 3D
+@itemize
+@item
+Currently they don't accept configuration files themselves.
+However, the configuration files of the Gnuastro programs they call are indeed
parsed and used by those programs.
-The concepts of @ref{Distance on a 2D curved space} are here extended to a 3D
space that @emph{might} be curved.
-We can start with the generic infinitesimal distance in a static 3D universe,
but this time in spherical coordinates instead of polar coordinates.
-@mymath{\theta} is shown in @ref{sphereandplane}, but here we are 3D beings,
positioned on @mymath{O} (the center of the sphere) and the point @mymath{O} is
tangent to a 4D-sphere.
-In our 3D space, a generic infinitesimal displacement will correspond to the
following distance in spherical coordinates:
+As a result, they don't have the following options: @option{--checkconfig},
@option{--config}, @option{--lastconfig}, @option{--onlyversion},
@option{--printparams}, @option{--setdirconf} and @option{--setusrconf}.
-@dispmath{ds_s^2=dx^2+dy^2+dz^2=dr^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2).}
+@item
+They don't directly allocate any memory, so there is no @option{--minmapsize}.
-Like the 2D creature before, we now have to assume an abstract dimension which
we cannot visualize easily.
-Let's call the fourth dimension @mymath{w}, then the general change in
coordinates in the @emph{full} four dimensional space will be:
+@item
+They don't have an independent @option{--usage} option: when called with
@option{--usage}, they just recommend running @option{--help}.
-@dispmath{ds_s^2=dr^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2)+dw^2.}
+@item
+The output of @option{--help} is not configurable like the programs (see
@ref{--help}).
-@noindent
-But we can only work on a 3D curved space, so following exactly the same steps
and conventions as our 2D friend, we arrive at:
+@item
+@cindex GNU AWK
+@cindex GNU SED
+The scripts will commonly use your installed shell and other basic
command-line tools (for example AWK or SED).
+Different systems have different versions and implementations of these basic
tools (for example GNU/Linux systems use GNU Bash, GNU AWK and GNU SED which
are far more advanced and up to date then the minimalist AWK and SED of most
other systems).
+Therefore, unexpected errors in these tools might come up when you run these
scripts on non-GNU/Linux operating systems.
+If you do confront such strange errors, please submit a bug report so we fix
it as soon as possible (see @ref{Report a bug}).
-@dispmath{ds_s^2={dr^2\over 1-Kr^2}+r^2(d\theta^2+\sin^2{\theta}d\phi^2).}
+@end itemize
-@noindent
-In a non-static universe (with a scale factor a(t)), the distance can be
written as:
+@menu
+* Sort FITS files by night:: Sort many files by date.
+* Generate radial profile:: Radial profile of an object in an image.
+* SAO DS9 region files from table:: Create ds9 region file from a table.
+@end menu
-@dispmath{ds^2=c^2dt^2-a^2(t)[d\chi^2+r^2(d\theta^2+\sin^2{\theta}d\phi^2)].}
+@node Sort FITS files by night, SAO DS9 region files from table, Installed
scripts, Installed scripts
+@section Sort FITS files by night
+@cindex Calendar
+FITS images usually contain (several) keywords for preserving important dates.
+In particular, for lower-level data, this is usually the observation date and
time (for example, stored in the @code{DATE-OBS} keyword value).
+When analyzing observed datasets, many calibration steps (like the dark, bias
or flat-field), are commonly calculated on a per-observing-night basis.
+However, the FITS standard's date format (@code{YYYY-MM-DDThh:mm:ss.ddd}) is
based on the western (Gregorian) calendar.
+Dates that are stored in this format are complicated for automatic processing:
a night starts in the final hours of one calendar day, and extends to the early
hours of the next calendar day.
+As a result, to identify datasets from one night, we commonly need to search
for two dates.
+However calendar peculiarities can make this identification very difficult.
+For example when an observation is done on the night separating two months
(like the night starting on March 31st and going into April 1st), or two years
(like the night starting on December 31st 2018 and going into January 1st,
2019).
+To account for such situations, it is necessary to keep track of how many days
are in a month, and leap years, etc.
-@c@dispmath{H(z){\equiv}\left(\dot{a}\over a\right)(z)=H_0E(z) }
+@cindex Unix epoch time
+@cindex Time, Unix epoch
+@cindex Epoch, Unix time
+Gnuastro's @file{astscript-sort-by-night} script is created to help in such
important scenarios.
+It uses @ref{Fits} to convert the FITS date format into the Unix epoch time
(number of seconds since 00:00:00 of January 1st, 1970), using the
@option{--datetosec} option.
+The Unix epoch time is a single number (integer, if not given in sub-second
precision), enabling easy comparison and sorting of dates after January 1st,
1970.
-@c@dispmath{E(z)=[ \Omega_{\Lambda,0} + \Omega_{C,0}(1+z)^2 +
-@c\Omega_{m,0}(1+z)^3 + \Omega_{r,0}(1+z)^4 ]^{1/2}}
+You can use this script as a basis for making a much more highly customized
sorting script.
+Here are some examples
-@c Let's take @mymath{r} to be the radial coordinate of the emitting
-@c source, which emitted its light at redshift $z$. Then the comoving
-@c distance of this object would be:
+@itemize
+@item
+If you need to copy the files, but only need a single extension (not the whole
file), you can add a step just before the making of the symbolic links, or
copies, and change it to only copy a certain extension of the FITS file using
the Fits program's @option{--copy} option, see @ref{HDU information and
manipulation}.
-@c@dispmath{ \chi(r)={c\over H_0a_0}\int_0^z{dz'\over E(z')} }
+@item
+If you need to classify the files with finer detail (for example the purpose
of the dataset), you can add a step just before the making of the symbolic
links, or copies, to specify a file-name prefix based on other certain keyword
values in the files.
+For example when the FITS files have a keyword to specify if the dataset is a
science, bias, or flat-field image.
+You can read it and to add a @code{sci-}, @code{bias-}, or @code{flat-} to the
created file (after the @option{--prefix}) automatically.
-@c@noindent
-@c So the proper distance at the current time to that object is:
-@c @mymath{a_0\chi(r)}, therefore the angular diameter distance
-@c (@mymath{d_A}) and luminosity distance (@mymath{d_L}) can be written
-@c as:
+For example, let's assume the observing mode is stored in the hypothetical
@code{MODE} keyword, which can have three values of @code{BIAS-IMAGE},
@code{SCIENCE-IMAGE} and @code{FLAT-EXP}.
+With the step below, you can generate a mode-prefix, and add it to the
generated link/copy names (just correct the filename and extension of the first
line to the script's variables):
-@c@dispmath{ d_A={a_0\chi(r)\over 1+z}, \quad d_L=a_0\chi(r)(1+z) }
+@example
+modepref=$(astfits infile.fits -h1 \
+ | sed -e"s/'/ /g" \
+ | awk '$1=="MODE"@{ \
+ if($3=="BIAS-IMAGE") print "bias-"; \
+ else if($3=="SCIENCE-IMAGE") print "sci-"; \
+ else if($3==FLAT-EXP) print "flat-"; \
+ else print $3, "NOT recognized"; exit 1@}')
+@end example
+@cindex GNU AWK
+@cindex GNU Sed
+Here is a description of it.
+We first use @command{astfits} to print all the keywords in extension @code{1}
of @file{infile.fits}.
+In the FITS standard, string values (that we are assuming here) are placed in
single quotes (@key{'}) which are annoying in this context/use-case.
+Therefore, we pipe the output of @command{astfits} into @command{sed} to
remove all such quotes (substituting them with a blank space).
+The result is then piped to AWK for giving us the final mode-prefix: with
@code{$1=="MODE"}, we ask AWK to only consider the line where the first column
is @code{MODE}.
+There is an equal sign between the key name and value, so the value is the
third column (@code{$3} in AWK).
+We thus use a simple @code{if-else} structure to look into this value and
print our custom prefix based on it.
+The output of AWK is then stored in the @code{modepref} shell variable which
you can add to the link/copy name.
+With the solution above, the increment of the file counter for each night will
be independent of the mode.
+If you want the counter to be mode-dependent, you can add a different counter
for each mode and use that counter instead of the generic counter for each
night (based on the value of @code{modepref}).
+But we'll leave the implementation of this step to you as an exercise.
+@end itemize
-@node Invoking astcosmiccal, , Extending distance concepts to 3D,
CosmicCalculator
-@subsection Invoking CosmicCalculator
+@menu
+* Invoking astscript-sort-by-night:: Inputs and outputs to this script.
+@end menu
-CosmicCalculator will calculate cosmological variables based on the input
parameters.
-The executable name is @file{astcosmiccal} with the following general template
+@node Invoking astscript-sort-by-night, , Sort FITS files by night, Sort FITS
files by night
+@subsection Invoking astscript-sort-by-night
+
+This installed script will read a FITS date formatted value from the given
keyword, and classify the input FITS files into individual nights.
+For more on installed scripts please see (see @ref{Installed scripts}).
+This script can be used with the following general template:
@example
-$ astcosmiccal [OPTION...] ...
+$ astscript-sort-by-night [OPTION...] FITS-files
@end example
-
@noindent
One line examples:
@example
-## Print basic cosmological properties at redshift 2.5:
-$ astcosmiccal -z2.5
+## Use the DATE-OBS keyword
+$ astscript-sort-by-night --key=DATE-OBS /path/to/data/*.fits
-## Only print Comoving volume over 4pi stradian to z (Mpc^3):
-$ astcosmiccal --redshift=0.8 --volume
+## Make links to the input files with the `img-' prefix
+$ astscript-sort-by-night --link --prefix=img- /path/to/data/*.fits
+@end example
-## Print redshift and age of universe when Lyman-alpha line is
-## at 6000 angstrom (another way to specify redshift).
-$ astcosmiccal --obsline=lyalpha,6000 --age
+This script will look into a HDU/extension (@option{--hdu}) for a keyword
(@option{--key}) in the given FITS files and interpret the value as a date.
+The inputs will be separated by "night"s (11:00a.m to next day's 10:59:59a.m,
spanning two calendar days, exact hour can be set with @option{--hour}).
-## Print luminosity distance, angular diameter distance and age
-## of universe in one row at redshift 0.4
-$ astcosmiccal -z0.4 -LAg
+The default output is a list of all the input files along with the following
two columns: night number and file number in that night (sorted by time).
+With @option{--link} a symbolic link will be made (one for each input) that
contains the night number, and number of file in that night (sorted by time),
see the description of @option{--link} for more.
+When @option{--copy} is used instead of a link, a copy of the inputs will be
made instead of symbolic link.
-## Assume Lambda and matter density of 0.7 and 0.3 and print
-## basic cosmological parameters for redshift 2.1:
-$ astcosmiccal -l0.7 -m0.3 -z2.1
+Below you can see one example where all the @file{target-*.fits} files in the
@file{data} directory should be separated by observing night according to the
@code{DATE-OBS} keyword value in their second extension (number @code{1},
recall that HDU counting starts from 0).
+You can see the output after the @code{ls} command.
-## Print wavelength of all pre-defined spectral lines when
-## Lyman-alpha is observed at 4000 Angstroms.
-$ astcosmiccal --obsline=lyalpha,4000 --listlinesatz
+@example
+$ astscript-sort-by-night -pimg- -h1 -kDATE-OBS data/target-*.fits
+$ ls
+img-n1-1.fits img-n1-2.fits img-n2-1.fits ...
@end example
-The input parameters (for example current matter density, etc) can be given as
command-line options or in the configuration files, see @ref{Configuration
files}.
-For a definition of the different parameters, please see the sections prior to
this.
-If no redshift is given, CosmicCalculator will just print its input parameters
and abort.
-For a full list of the input options, please see @ref{CosmicCalculator input
options}.
-
-Without any particular output requested (and only a given redshift),
CosmicCalculator will print all basic cosmological calculations (one per line)
with some explanations before each.
-This can be good when you want a general feeling of the conditions at a
specific redshift.
-Alternatively, if any specific calculation(s) are requested (its possible to
call more than one), only the requested value(s) will be calculated and printed
with one character space between them.
-In this case, no description or units will be printed.
-See @ref{CosmicCalculator basic cosmology calculations} for the full list of
these options along with some explanations how when/how they can be useful.
-
-Another common operation in observational cosmology is dealing with spectral
lines at different redshifts.
-CosmicCalculator also has features to help in such situations, please see
@ref{CosmicCalculator spectral line calculations}.
-
-@menu
-* CosmicCalculator input options:: Options to specify input conditions.
-* CosmicCalculator basic cosmology calculations:: Like distance modulus,
distances and etc.
-* CosmicCalculator spectral line calculations:: How they get affected by
redshift.
-@end menu
+The outputs can be placed in a different (already existing) directory by
including that directory's name in the @option{--prefix} value, for example
@option{--prefix=sorted/img-} will put them all under the @file{sorted}
directory.
-@node CosmicCalculator input options, CosmicCalculator basic cosmology
calculations, Invoking astcosmiccal, Invoking astcosmiccal
-@subsubsection CosmicCalculator input options
+This script can be configured like all Gnuastro's programs (through
command-line options, see @ref{Common options}), with some minor differences
that are described in @ref{Installed scripts}.
+The particular options to this script are listed below:
-The inputs to CosmicCalculator can be specified with the following options:
@table @option
+@item -h STR
+@itemx --hdu=STR
+The HDU/extension to use in all the given FITS files.
+All of the given FITS files must have this extension.
-@item -z FLT
-@itemx --redshift=FLT
-The redshift of interest.
-There are two other ways that you can specify the target redshift:
-1) Spectral lines and their observed wavelengths, see @option{--obsline}.
-2) Velocity, see @option{--velocity}.
-Hence this option cannot be called with @option{--obsline} or
@option{--velocity}.
-
-@item -y FLT
-@itemx --velocity=FLT
-Input velocity in km/s.
-The given value will be converted to redshift internally, and used in any
subsequent calculation.
-This option is thus an alternative to @code{--redshift} or @code{--obsline},
it cannot be used with them.
-The conversion will be done with the more general and accurate relativistic
equation of @mymath{1+z=\sqrt{(c+v)/(c-v)}}, not the simplified
@mymath{z\approx v/c}.
-
-@item -H FLT
-@itemx --H0=FLT
-Current expansion rate (in km sec@mymath{^{-1}} Mpc@mymath{^{-1}}).
+@item -k STR
+@itemx --key=STR
+The keyword name that contains the FITS date format to classify/sort by.
-@item -l FLT
-@itemx --olambda=FLT
-Cosmological constant density divided by the critical density in the current
Universe (@mymath{\Omega_{\Lambda,0}}).
+@item -H FLT
+@itemx --hour=FLT
+The hour that defines the next ``night''.
+By default, all times before 11:00a.m are considered to belong to the previous
calendar night.
+If a sub-hour value is necessary, it should be given in units of hours, for
example @option{--hour=9.5} corresponds to 9:30a.m.
-@item -m FLT
-@itemx --omatter=FLT
-Matter (including massive neutrinos) density divided by the critical density
in the current Universe (@mymath{\Omega_{m,0}}).
+@cartouche
+@noindent
+@cindex Time zone
+@cindex UTC (Universal time coordinate)
+@cindex Universal time coordinate (UTC)
+@strong{Dealing with time zones:}
+The time that is recorded in @option{--key} may be in UTC (Universal Time
Coordinate).
+However, the organization of the images taken during the night depends on the
local time.
+It is possible to take this into account by setting the @option{--hour} option
to the local time in UTC.
-@item -r FLT
-@itemx --oradiation=FLT
-Radiation density divided by the critical density in the current Universe
(@mymath{\Omega_{r,0}}).
+For example, consider a set of images taken in Auckland (New Zealand, UTC+12)
during different nights.
+If you want to classify these images by night, you have to know at which time
(in UTC time) the Sun rises (or any other separator/definition of a different
night).
+For example if your observing night finishes before 9:00a.m in Auckland, you
can use @option{--hour=21}.
+Because in Auckland the local time of 9:00 corresponds to 21:00 UTC.
+@end cartouche
-@item -O STR/FLT,FLT
-@itemx --obsline=STR/FLT,FLT
-@cindex Rest-frame wavelength
-@cindex Wavelength, rest-frame
-Find the redshift to use in next steps based on the rest-frame and observed
wavelengths of a line.
-This option is thus an alternative to @code{--redshift} or @code{--velocity},
it cannot be used with them.
-Wavelengths are assumed to be in Angstroms.
-The first argument identifies the line.
-It can be one of the standard names below, or any rest-frame wavelength in
Angstroms.
-The second argument is the observed wavelength of that line.
-For example @option{--obsline=lyalpha,6000} is the same as
@option{--obsline=1215.64,6000}.
+@item -l
+@itemx --link
+Create a symbolic link for each input FITS file.
+This option cannot be used with @option{--copy}.
+The link will have a standard name in the following format (variable parts are
written in @code{CAPITAL} letters and described after it):
-The pre-defined names are listed below, sorted from red (longer wavelength) to
blue (shorter wavelength).
-You can get this list on the command-line with the @option{--listlines}.
+@example
+PnN-I.fits
+@end example
@table @code
-@item siired
-[6731@AA{}] SII doublet's redder line.
+@item P
+This is the value given to @option{--prefix}.
+By default, its value is @code{./} (to store the links in the directory this
script was run in).
+See the description of @code{--prefix} for more.
+@item N
+This is the night-counter: starting from 1.
+@code{N} is just incremented by 1 for the next night, no matter how many
nights (without any dataset) there are between two subsequent observing nights
(its just an identifier for each night which you can easily map to different
calendar nights).
+@item I
+File counter in that night, sorted by time.
+@end table
-@item sii
-@cindex Doublet: SII
-@cindex SII doublet
-[6724@AA{}] SII doublet's mean center at .
+@item -c
+@itemx --copy
+Make a copy of each input FITS file with the standard naming convention
described in @option{--link}.
+With this option, instead of making a link, a copy is made.
+This option cannot be used with @option{--link}.
-@item siiblue
-[6717@AA{}] SII doublet's bluer line.
+@item -p STR
+@itemx --prefix=STR
+Prefix to append before the night-identifier of each newly created link or
copy.
+This option is thus only relevant with the @option{--copy} or @option{--link}
options.
+See the description of @option{--link} for how its used.
+For example, with @option{--prefix=img-}, all the created file names in the
current directory will start with @code{img-}, making outputs like
@file{img-n1-1.fits} or @file{img-n3-42.fits}.
-@item niired
-[6584@AA{}] NII doublet's redder line.
+@option{--prefix} can also be used to store the links/copies in another
directory relative to the directory this script is being run (it must already
exist).
+For example @code{--prefix=/path/to/processing/img-} will put all the
links/copies in the @file{/path/to/processing} directory, and the files (in
that directory) will all start with @file{img-}.
+@end table
-@item nii
-@cindex Doublet: NII
-@cindex NII doublet
-[6566@AA{}] NII doublet's mean center.
-@item halpha
-@cindex H-alpha
-[6562.8@AA{}] H-@mymath{\alpha} line.
-@item niiblue
-[6548@AA{}] NII doublet's bluer line.
-@item oiiired-vis
-[5007@AA{}] OIII doublet's redder line in the visible.
-@item oiii-vis
-@cindex Doublet: OIII (visible)
-@cindex OIII doublet in visible
-[4983@AA{}] OIII doublet's mean center in the visible.
-@item oiiiblue-vis
-[4959@AA{}] OIII doublet's bluer line in the visible.
-@item hbeta
-@cindex H-beta
-[4861.36@AA{}] H-@mymath{\beta} line.
-@item heii-vis
-[4686@AA{}] HeII doublet's redder line in the visible.
-@item hgamma
-@cindex H-gamma
-[4340.46@AA{}] H-@mymath{\gamma} line.
-@item hdelta
-@cindex H-delta
-[4101.74@AA{}] H-@mymath{\delta} line.
-@item hepsilon
-@cindex H-epsilon
-[3970.07@AA{}] H-@mymath{\epsilon} line.
-@item neiii
-[3869@AA{}] NEIII line.
-@item oiired
-[3729@AA{}] OII doublet's redder line.
-@item oii
-@cindex Doublet: OII
-@cindex OII doublet
-[3727.5@AA{}] OII doublet's mean center.
-@item oiiblue
-[3726@AA{}] OII doublet's bluer line.
-@item blimit
-@cindex Balmer limit
-[3646@AA{}] Balmer limit.
-@item mgiired
-[2803@AA{}] MgII doublet's redder line.
-@item mgii
-@cindex Doublet: MgII
-@cindex MgII doublet
-[2799.5@AA{}] MgII doublet's mean center.
-@item mgiiblue
-[2796@AA{}] MgII doublet's bluer line.
-@item ciiired
-[1909@AA{}] CIII doublet's redder line.
+@node Generate radial profile, , SAO DS9 region files from table, Installed
scripts
+@section Generate radial profile
-@item ciii
-@cindex Doublet: CIII
-@cindex CIII doublet
-[1908@AA{}] CIII doublet's mean center.
+@cindex Radial profile
+@cindex Profile, profile
+The 1 dimensional radial profile of an object is an important parameter in
many aspects of astronomical image processing.
+For example, you want to study how the light of a galaxy is distributed as a
function of the radial distance from the center.
+In other cases, the radial profile of a star can show the PSF (see @ref{PSF}).
+Gnuastro's @file{astscript-radial-profile} script is created to obtain such
radial profiles for one object within an image.
+This script uses @ref{MakeProfiles} to generate elliptical apertures with the
values equal to the distance from the center of the object and
@ref{MakeCatalog} for measuring the values over the apertures.
-@item ciiiblue
-[1907@AA{}] CIII doublet's bluer line.
+@menu
+* Invoking astscript-radial-profile:: How to call astscript-radial-profile
+@end menu
-@item si_iiired
-[1892@AA{}] SiIII doublet's redder line.
+@node Invoking astscript-radial-profile, , Generate radial profile, Generate
radial profile
+@subsection Invoking astscript-radial-profile
-@item si_iii
-@cindex Doublet: SiIII
-@cindex SiIII doublet
-[1887.5@AA{}] SiIII doublet's mean center.
+This installed script will measure the radial profile of an object within an
image.
+For more on installed scripts please see (see @ref{Installed scripts}).
+This script can be used with the following general template:
-@item si_iiiblue
-[1883@AA{}] SiIII doublet's bluer line.
+@example
+$ astscript-radial-profile [OPTION...] FITS-file
+@end example
-@item oiiired-uv
-[1666@AA{}] OIII doublet's redder line in the ultra-violet.
+@noindent
+Examples:
-@item oiii-uv
-@cindex Doublet: OIII (in UV)
-@cindex OIII doublet in UV
-[1663.5@AA{}] OIII doublet's mean center in the ultra-violet.
+@example
+## Generate the radial profile with default options (assuming the
+## object is in the center of the image, and using the mean).
+$ astscript-radial-profile image.fits
-@item oiiiblue-uv
-[1661@AA{}] OIII doublet's bluer line in the ultra-violet.
+## Generate the radial profile centered at x=44 and y=37 (in pixels),
+## up to a radial distance of 19 pixels, use the mean value.
+$ astscript-radial-profile image.fits \
+ --xcenter=44 \
+ --ycenter=37 \
+ --rmax=19
-@item heii-uv
-[1640@AA{}] HeII doublet's bluer line in the ultra-violet.
+## Generate the radial profile centered at x=44 and y=37 (in pixels),
+## up to a radial distance of 100 pixels, compute sigma clipped
+## mean and standard deviation (sigclip-mean and sigclip-std) using
+## 3 sigma and 10 iterations.
+$ astscript-radial-profile image.fits \
+ --xcenter=44 \
+ --ycenter=37 \
+ --rmax=100 \
+ --sigmaclip=3,10 \
+ --measure=sigclip-mean,sigclip-std
-@item civred
-[1551@AA{}] CIV doublet's redder line.
+## Generate the radial profile centered at RA=20.53751695,
+## DEC=0.9454292263, up to a radial distance of 88 pixels,
+## axis ratio equal to 0.32, and position angle of 148 deg.
+## Name the output table as `radial-profile.fits'
+$ astscript-radial-profile image.fits --mode=wcs \
+ --xcenter=20.53751695 \
+ --ycenter=0.9454292263 \
+ --rmax=88 \
+ --axisratio=0.32 \
+ --positionangle=148 -oradial-profile.fits
-@item civ
-@cindex Doublet: CIV
-@cindex CIV doublet
-[1549@AA{}] CIV doublet's mean center.
+@end example
-@item civblue
-[1548@AA{}] CIV doublet's bluer line.
+This installed script will read a FITS image and will use it as the basis for
constructing the radial profile.
+The output radial profile is a table (FITS or plain-text) containing the
radial distance from the center in the first row and the specified measurements
in the other columns (mean, median, sigclip-mean, sigclip-median, etc.).
-@item nv
-[1240@AA{}] NV (four times ionized Sodium).
+To measure the radial profile, this script needs to generate temporary files.
+All these temporary files will be created within the directory given to the
@option{--tmpdir} option.
+When @option{--tmpdir} is not called, a temporary directory (with a name based
on the inputs) will be created in the running directory.
+After the output is created, this script will delete the directory by default,
unless you call the @option{--keeptmp} option.
-@item lyalpha
-@cindex Lyman-alpha
-[1215.67@AA{}] Lyman-@mymath{\alpha} line.
+With the default options, the script will generate a circular radial profile
using the mean value and centered at the center of the image.
+In order to have more flexibility, several options are available to configure
for the desired radial profile.
+In this sense, you can change the center position, the maximum radius, the
axis ratio and the position angle (elliptical apertures are considered), the
operator for obtaining the profiles, and others (described below).
-@item lybeta
-@cindex Lyman-beta
-[1025.7@AA{}] Lyman-@mymath{\beta} line.
+@cartouche
+@noindent
+@strong{Debug your profile:} to debug your results, especially close to the
center of your object, you can see the radial distance associated to every
pixel in your input.
+To do this, use @option{--keeptmp} to keep the temporary files, and compare
@file{crop.fits} (crop of your input image centered on your desired coordinate)
with @file{apertures.fits} (radial distance of each pixel).
+@end cartouche
-@item lygamma
-@cindex Lyman-gamma
-[972.54@AA{}] Lyman-@mymath{\gamma} line.
+@cartouche
+@noindent
+@strong{Finding properties of your elliptical target: } you want to measure
the radial profile of a galaxy, but don't know its exact location, position
angle or axis ratio.
+To obtain these values, you can use @ref{NoiseChisel} to detect signal in the
image, feed it to @ref{Segment} to do basic segmentation, then use
@ref{MakeCatalog} to measure the center (@option{--x} and @option{--y} in
MakeCatalog), axis ratio (@option{--axisratio}) and position angle
(@option{--positionangle}).
+@end cartouche
-@item lydelta
-@cindex Lyman-delta
-[949.74@AA{}] Lyman-@mymath{\delta} line.
+@cartouche
+@noindent
+@strong{Masking other sources:} The image of an astronomical object will
usually have many other sources with your main target.
+A crude solution is to use sigma-clipped measurements for the profile.
+However, sigma-clipped measurements can easily be baised when the number of
sources at each radial distance increases at larger distances.
+Therefore a robust solution is to mask all other detections within the image.
+You can use @ref{NoiseChisel} and @ref{Segment} to detect and segment the
sources, then set all pixels that don't belong to your target to blank using
@ref{Arithmetic} (in particular, its @code{where} operator).
+@end cartouche
-@item lyepsilon
-@cindex Lyman-epsilon
-[937.80@AA{}] Lyman-@mymath{\epsilon} line.
+@table @option
+@item -h STR
+@itemx --hdu=STR
+The HDU/extension of the input image to use.
-@item lylimit
-@cindex Lyman limit
-[912@AA{}] Lyman limit.
+@item -o STR
+@itemx --output=STR
+Filename of measured radial profile.
+It can be either a FITS table, or plain-text table (determied from your given
file name suffix).
+
+@item -O STR
+@itemx --mode=STR
+Interpret the center position of the object (values given to
@option{--xcenter} and @option{--ycenter}) in image or WCS coordinates.
+This option thus accepts only two values: @option{img} or @option{wcs}.
+By default, it is @option{--mode=img}.
+
+@item -x FLT
+@itemx --xcenter=FLT
+Center coordinate along the first dimension (horizontal axis in FITS).
+This option will be used for placing the center of the profiles.
+If @option{--mode=img} is considered, then @option{--xcenter} has to be in
image units (pixels).
+If @option{--mode=wcs} is considered, then @option{--xcenter} has to be in WCS
units.
+When this option isn't called, this script will assume the the radial
profile's core in the center of the image along the first/horizontal axis.
-@end table
+@item -y FLT
+@itemx --ycenter=FLT
+Center coordinate along the second dimension (vertical axis in FITS).
+This operator behaves very similar to @option{--xcenter} argument, but for the
second dimension (see above for details).
-@end table
+@item -R FLT
+@itemx --rmax=FLT
+Maximum radius for the radial profile (in pixels).
+By default, the radial profile will be computed up to a radial distance equal
to the maximum radius that fits into the image (assuming circular shape).
+@item -Q FLT
+@itemx --axisratio=FLT
+The axis ratio of the apertures (minor axis divided by the major axis in a 2D
ellipse).
+By default (when this option isn't given), the radial profile will be circular
(axis ratio of 1).
+This parameter is used as the option @option{--qcol} in the generation of the
apertures with @command{astmkprof}.
+@item -p FLT
+@itemx --positionangle=FLT
+The position angle (in degrees) of the profiles relative to the first FITS
axis (horizontal when viewed in SAO ds9).
+By default, it is @option{--pangle=0}, which means that the semi-major axis of
the profiles will be parallel to the first FITS axis.
-@node CosmicCalculator basic cosmology calculations, CosmicCalculator spectral
line calculations, CosmicCalculator input options, Invoking astcosmiccal
-@subsubsection CosmicCalculator basic cosmology calculations
-By default, when no specific calculations are requested, CosmicCalculator will
print a complete set of all its calculators (one line for each calculation, see
@ref{Invoking astcosmiccal}).
-The full list of calculations can be useful when you don't want any specific
value, but just a general view.
-In other contexts (for example in a batch script or during a discussion), you
know exactly what you want and don't want to be distracted by all the extra
information.
+@item -m STR
+@itemx --measure=STR
+The operator for measuring the values over each radial distance.
+The values given to this option will be directly passed to @ref{MakeCatalog}.
+As a consequence, all MakeCatalog measurements like the median, mean, std,
sigclip-mean, sigclip-number, etc. can be used here.
+For a full list of MakeCatalog's measurements, please run
@command{astmkcatalog --help}.
+Multiple values can be given to this option, each separated by a comma.
+This option can also be called multiple times.
+
+For example, by setting @option{--measure=mean,sigclip-mean --measure=median},
the mean, sigma-clipped mean and median values will be computed.
+The output radial profile will have 4 columns in this order: radial distance,
mean, sigma-clipped and median.
+By default (when this option isn't given), the mean of all pixels at each
radial position will be computed.
-You can use any number of the options described below in any order.
-When any of these options are requested, CosmicCalculator's output will just
be a single line with a single space between the (possibly) multiple values.
-In the example below, only the tangential distance along one arc-second (in
kpc), absolute magnitude conversion, and age of the universe at redshift 2 are
printed (recall that you can merge short options together, see @ref{Options}).
+@item -s FLT,FLT
+@itemx --sigmaclip=FLT,FLT
+Sigma clipping parameters: only relevant if sigma-clipping operators are
requested by @option{--measure}.
+For more on sigma-clipping, see @ref{Sigma clipping}.
+If given, the value to this option is directly passed to the
@option{--sigmaclip} option of @ref{MakeCatalog}, see @ref{MakeCatalog inputs
and basic settings}.
+By default (when this option isn't given), the default values within
MakeCatalog will be used.
+To see the default value of this option in MakeCatalog, you can run this
command:
@example
-$ astcosmiccal -z2 -sag
-8.585046 44.819248 3.289979
+$ astmkcatalog -P | grep " sigmaclip "
@end example
-Here is one example of using this feature in scripts: by adding the following
two lines in a script to keep/use the comoving volume with varying redshifts:
+@item -t STR
+@itemx --tmpdir=STR
+Several intermediate files are necessary to obtain the radial profile.
+All of these temporal files are saved into a temporal directory.
+With this option, you can directly specify this directory.
+By default (when this option isn't called), it will be built in the running
directory and given an input-based name.
+Once the radial profile has been obtained, this directory is removed.
+You can disable the deletion of the temporary directory with the
@option{--keeptmp} option.
-@example
-z=3.12
-vol=$(astcosmiccal --redshift=$z --volume)
-@end example
+@item -k
+@itemx --keeptmp
+Don't delete the temporary directory (see description of @option{--tmpdir}
above).
+This option is useful for debugging.
+For example, to check that the profiles generated for obtaining the radial
profile have the desired center, shape and orientation.
+@end table
-@cindex GNU Grep
-@noindent
-In a script, this operation might be necessary for a large number of objects
(several of galaxies in a catalog for example).
-So the fact that all the other default calculations are ignored will also help
you get to your result faster.
-If you are indeed dealing with many (for example thousands) of redshifts,
using CosmicCalculator is not the best/fastest solution.
-Because it has to go through all the configuration files and preparations for
each invocation.
-To get the best efficiency (least overhead), we recommend using Gnuastro's
cosmology library (see @ref{Cosmology library}).
-CosmicCalculator also calls the library functions defined there for its
calculations, so you get the same result with no overhead.
-Gnuastro also has libraries for easily reading tables into a C program, see
@ref{Table input output}.
-Afterwards, you can easily build and run your C program for the particular
processing with @ref{BuildProgram}.
-If you just want to inspect the value of a variable visually, the description
(which comes with units) might be more useful.
-In such cases, the following command might be better.
-The other calculations will also be done, but they are so fast that you will
not notice on modern computers (the time it takes your eye to focus on the
result is usually longer than the processing: a fraction of a second).
-@example
-$ astcosmiccal --redshift=0.832 | grep volume
-@end example
-The full list of CosmicCalculator's specific calculations is present below in
two groups: basic cosmology calculations and those related to spectral lines.
-In case you have forgot the units, you can use the @option{--help} option
which has the units along with a short description.
-@table @option
-@item -e
-@itemx --usedredshift
-The redshift that was used in this run.
-In many cases this is the main input parameter to CosmicCalculator, but it is
useful in others.
-For example in combination with @option{--obsline} (where you give an observed
and rest-frame wavelength and would like to know the redshift) or with
@option{--velocity} (where you specify the velocity instead of redshift).
-Another example is when you run CosmicCalculator in a loop, while changing the
redshift and you want to keep the redshift value with the resulting calculation.
-@item -Y
-@itemx --usedvelocity
-The velocity (in km/s) that was used in this run.
-The conversion from redshift will be done with the more general and accurate
relativistic equation of @mymath{1+z=\sqrt{(c+v)/(c-v)}}, not the simplified
@mymath{z\approx v/c}.
-@item -G
-@itemx --agenow
-The current age of the universe (given the input parameters) in Ga (Giga
annum, or billion years).
-@item -C
-@itemx --criticaldensitynow
-The current critical density (given the input parameters) in grams per
centimeter-cube (@mymath{g/cm^3}).
-@item -d
-@itemx --properdistance
-The proper distance (at current time) to object at the given redshift in
Megaparsecs (Mpc).
-See @ref{Distance on a 2D curved space} for a description of the proper
distance.
-@item -A
-@itemx --angulardimdist
-The angular diameter distance to object at given redshift in Megaparsecs (Mpc).
-@item -s
-@itemx --arcsectandist
-The tangential distance covered by 1 arc-seconds at the given redshift in
kiloparsecs (Kpc).
-This can be useful when trying to estimate the resolution or pixel scale of an
instrument (usually in units of arc-seconds) at a given redshift.
-@item -L
-@itemx --luminositydist
-The luminosity distance to object at given redshift in Megaparsecs (Mpc).
-@item -u
-@itemx --distancemodulus
-The distance modulus at given redshift.
-@item -a
-@itemx --absmagconv
-The conversion factor (addition) to absolute magnitude.
-Note that this is practically the distance modulus added with
@mymath{-2.5\log{(1+z)}} for the desired redshift based on the input parameters.
-Once the apparent magnitude and redshift of an object is known, this value may
be added with the apparent magnitude to give the object's absolute magnitude.
-@item -g
-@itemx --age
-Age of the universe at given redshift in Ga (Giga annum, or billion years).
-@item -b
-@itemx --lookbacktime
-The look-back time to given redshift in Ga (Giga annum, or billion years).
-The look-back time at a given redshift is defined as the current age of the
universe (@option{--agenow}) subtracted by the age of the universe at the given
redshift.
-@item -c
-@itemx --criticaldensity
-The critical density at given redshift in grams per centimeter-cube
(@mymath{g/cm^3}).
-@item -v
-@itemx --onlyvolume
-The comoving volume in Megaparsecs cube (Mpc@mymath{^3}) until the desired
redshift based on the input parameters.
+@node SAO DS9 region files from table, Generate radial profile, Sort FITS
files by night, Installed scripts
+@section SAO DS9 region files from table
-@end table
+Once your desired catalog (containing the positions of some objects) is
created (for example with @ref{MakeCatalog}, @ref{Match}, or @ref{Table}) it
often happens that you want to see your selected objects on an image for a
feeling of the spatial properties of your objects.
+For example you want to see their positions relative to each other.
+In this section we describe a simple installed script that is provided within
Gnuastro for converting your given columns to an SAO DS9 region file to help in
this process.
+SAO DS9@footnote{@url{https://sites.google.com/cfa.harvard.edu/saoimageds9}}
is one of the most common FITS image vizualization tools in astronomy and is
free software.
+@menu
+* Invoking astscript-make-ds9-reg:: How to call astscript-make-ds9-reg
+@end menu
+@node Invoking astscript-make-ds9-reg, , SAO DS9 region files from table, SAO
DS9 region files from table
+@subsection Invoking astscript-make-ds9-reg
-@node CosmicCalculator spectral line calculations, , CosmicCalculator basic
cosmology calculations, Invoking astcosmiccal
-@subsubsection CosmicCalculator spectral line calculations
+This installed script will read two positional columns within an input table
and generate an SAO DS9 region file to visualize the position of the given
objects over an image.
+For more on installed scripts please see (see @ref{Installed scripts}).
+This script can be used with the following general template:
-@cindex Rest frame wavelength
-At different redshifts, observed spectral lines are shifted compared to their
rest frame wavelengths with this simple relation:
@mymath{\lambda_{obs}=\lambda_{rest}(1+z)}.
-Although this relation is very simple and can be done for one line in the head
(or a simple calculator!), it slowly becomes tiring when dealing with a lot of
lines or redshifts, or some precision is necessary.
-The options in this section are thus provided to greatly simplify usage of
this simple equation, and also helping by storing a list of pre-defined
spectral line wavelengths.
+@example
+## Use the RA and DEC columns of 'table.fits' for the region file.
+$ astscript-make-ds9-reg table.fits --column=RA,DEC \
+ --output=ds9.reg
-For example if you want to know the wavelength of the @mymath{H\alpha} line
(at 6562.8 Angstroms in rest frame), when @mymath{Ly\alpha} is at 8000
Angstroms, you can call CosmicCalculator like the first example below.
-And if you want the wavelength of all pre-defined spectral lines at this
redshift, you can use the second command.
+## Select objects with a magnitude between 18 to 20, and generate the
+## region file directly (through a pipe), each region with radius of
+## 0.5 arcseconds.
+$ asttable table.fits --range=MAG,18:20 --column=RA,DEC \
+ | astscript-make-ds9-reg --column=1,2 --radius=0.5
-@example
-$ astcosmiccal --obsline=lyalpha,8000 --lineatz=halpha
-$ astcosmiccal --obsline=lyalpha,8000 --listlinesatz
+## With the first command, select objects with a magnitude of 25 to 26
+## as red regions in 'bright.reg'. With the second command, select
+## objects with a magnitude between 28 to 29 as a green region and
+## show both.
+$ asttable cat.fits --range=MAG_F160W,25:26 -cRA,DEC \
+ | ./astscript-make-ds9-reg -c1,2 --color=red -obright.reg
+$ asttable cat.fits --range=MAG_F160W,28:29 -cRA,DEC \
+ | ./astscript-make-ds9-reg -c1,2 --color=green \
+ --command="ds9 image.fits -regions bright.reg"
@end example
-Bellow you can see the printed/output calculations of CosmicCalculator that
are related to spectral lines.
-Note that @option{--obsline} is an input parameter, so its discussed (with the
full list of known lines) in @ref{CosmicCalculator input options}.
+The input can either be passed as a named file, or from standard input (a
pipe).
+Only the @option{--column} option is mandatory (to specify the input table
columns): two colums from the input table must be specified, either by name
(recommended) or number.
+You can optionally also specify the region's radius, width and color of the
regions with the @option{--radius}, @option{--width} and @option{--color}
options, otherwise default values will be used for these (described under each
option).
+
+The created region file will be written into the file name given to
@option{--output}.
+When @option{--output} isn't called, the default name of @file{ds9.reg} will
be used (in the running directory).
+If the file exists before calling this script, it will be overwritten, unless
you pass the @option{--dontdelete} option.
+Optionally you can also use the @option{--command} option to give the full
command that should be run to execute SAO DS9 (see example above and
description below).
+In this mode, the created region file will be deleted once DS9 is closed
(unless you pass the @option{--dontdelete} option).
+A full description of each option is given below.
@table @option
-@item --listlines
-List the pre-defined rest frame spectral line wavelengths and their names on
standard output, then abort CosmicCalculator.
-When this option is given, other operations on the command-line will be
ignored.
-This is convenient when you forget the specific name of the spectral line used
within Gnuastro, or when you forget the exact wavelength of a certain line.
+@item -h INT/STR
+@item --hdu INT/STR
+The HDU of the input table when a named FITS file is given as input.
+The HDU (or extension) can be either a name or number (counting from zero).
+For more on this option, see @ref{Input output options}.
-These names can be used with the options that deal with spectral lines, for
example @option{--obsline} and @option{--lineatz} (@ref{CosmicCalculator basic
cosmology calculations}).
+@item -c STR,STR
+@itemx --column=STR,STR
+Identifiers of the two positional columns to use in the DS9 region file from
the table.
+They can either be in WCS (RA and Dec) or image (pixel) coordiantes.
+The mode can be specified with the @option{--mode} option, described below.
-The format of the output list is a two-column table, with Gnuastro's text
table format (see @ref{Gnuastro text table format}).
-Therefore, if you are only looking for lines in a specific range, you can pipe
the output into Gnuastro's table program and use its @option{--range} option on
the @code{wavelength} (first) column.
-For example, if you only want to see the lines between 4000 and 6000
Angstroms, you can run this command:
+@item -n STR
+@itemx --namecol=STR
+The column containing the name (or label) of each region.
+The type of the column (numeric or a character-based string) is irrelevant:
you can use both types of columns as a name or label for the region.
+This feature is useful when you need to recognize each region with a certain
ID or property (for example magnitude or redshift).
-@example
-$ astcosmiccal --listlines \
- | asttable --range=wavelength,4000,6000
-@end example
+@item -m wcs|img
+@itemx --mode=wcs|org
+The coordinate system of the positional columns (can be either
@option{--mode=wcs} and @option{--mode=img}).
+In the WCS mode, the values within the columns are interpreted to be RA and
Dec.
+In the image mode, they are interpreted to be pixel X and Y positions.
+This option also affects the interpretation of the value given to
@option{--radius}.
+When this option isn't explicitly given, the columns are assumed to be in WCS
mode.
-@noindent
-And if you want to use the list later and have it as a table in a file, you
can easily add the @option{--output} (or @option{-o}) option to the
@command{asttable} command, and specify the filename, for example
@option{--output=lines.fits} or @option{--output=lines.txt}.
+@item -C STR
+@itemx --color=STR
+The color to use for created regions.
+These will be directly interpreted by SAO DS9 when it wants to open the region
file so it must be recognizable by SAO DS9.
+As of SAO DS9 8.2, the recognized color names are @code{black}, @code{white},
@code{red}, @code{green}, @code{blue}, @code{cyan}, @code{magenta} and
@code{yellow}.
+The default color (when this option is not called) is @code{green}
-@item --listlinesatz
-Similar to @option{--listlines} (above), but the printed wavelength is not in
the rest frame, but redshifted to the given redshift.
-Recall that the redshift can be specified by @option{--redshift} directly or
by @option{--obsline}, see @ref{CosmicCalculator input options}.
+@item -w INT
+@itemx --width=INT
+The line width of the regions.
+These will be directly interpreted by SAO DS9 when it wants to open the region
file so it must be recognizable by SAO DS9.
+The default value is @code{1}.
-@item -i STR/FLT
-@itemx --lineatz=STR/FLT
-The wavelength of the specified line at the redshift given to CosmicCalculator.
-The line can be specified either by its name or directly as a number (its
wavelength).
-To get the list of pre-defined names for the lines and their wavelength, you
can use the @option{--listlines} option, see @ref{CosmicCalculator input
options}.
-In the former case (when a name is given), the returned number is in units of
Angstroms.
-In the latter (when a number is given), the returned value is the same units
of the input number (assuming its a wavelength).
+@item -r FLT
+@itemx --radius=FLT
+The radius of all the regions.
+In WCS mode, the radius is assumed to be in arc-seconds, in image mode, it is
in pixel units.
+If this option is not explicitly given, in WCS mode the default radius is 1
arc-seconds and in image mode it is 3 pixels.
+
+@item --dontdelete
+If the output file name exists, abort the program and don't over-write the
contents of the file.
+This option is thus good if you want to avoid accidentally writing over an
important file.
+Also, don't delete the created region file when @option{--command} is given
(by default, when @option{--command} is given, the created region file will be
deleted after SAO DS9 closes).
+
+@item -o STR
+@itemx --output=STR
+Write the created SAO DS9 region file into the name given to this option.
+If not explicity given on the command-line, a default name of @file{ds9.reg}
will be used.
+If the file already exists, it will be over-written, you can avoid the
deletion (or over-writing) of an existing file with the @option{--dontdelete}.
+
+@item --command="STR"
+After creating the region file, run the string given to this option as a
command-line command.
+The SAO DS9 region command will be appended to the end of the given command.
+Because the command will mostly likely contain white-space characters it is
recommended to put the given string in double quotations.
+
+For example, let's assume @option{--command="ds9 image.fits -zscale"}.
+After making the region file (assuming it is called @file{ds9.reg}), the
following command will be executed:
+
+@example
+ds9 image.fits -zscale -regions ds9.reg
+@end example
+You can customize all aspects of SAO DS9 with its command-line options,
therefore the value of this option can be as long and complicated as you like.
+For example if you also want the image to fit into the window, this option
will be: @command{--command="ds9 image.fits -zscale -zoom to fit"}.
+You can see the SAO DS9 command-line descriptions by clicking on the ``Help''
menu and selecting ``Reference Manual''.
+In the opened window, click on ``Command Line Options''.
@end table
@@ -20675,7 +20701,7 @@ In the latter (when a number is given), the returned
value is the same units of
-@node Library, Developing, High-level calculations, Top
+@node Library, Developing, Installed scripts, Top
@chapter Library
Each program in Gnuastro that was discussed in the prior chapters (or any
program in general) is a collection of functions that is compiled into one
executable file which can communicate directly with the outside world.
@@ -30690,10 +30716,15 @@ in a special way), are done with installed Bash
scripts (all prefixed with
similarly (with minor differences, see @ref{Installed scripts}).
@table @code
+@item astscript-make-ds9-reg
+(See @ref{SAO DS9 region files from table}) Given a table (either as a file or
from standard input), create an SAO DS9 region file from the requested
positional columns (WCS or image coordinates).
+
+@item astscript-radial-profile
+(See @ref{Generate radial profile}) Calculate the radial profile of an object
within an image.
+The object can be at any location in the image, using various measures
(median, sigma-clipped mean and etc), and the radial distance can also be
measured on any general ellipse.
+
@item astscript-sort-by-night
-(See @ref{Sort FITS files by night}) Given a list of FITS files, and a HDU
-and keyword name (for a date), this script separates the files in the same
-night (possibly over two calendar days).
+(See @ref{Sort FITS files by night}) Given a list of FITS files, and a HDU and
keyword name (for a date), this script separates the files in the same night
(possibly over two calendar days).
@end table
- [gnuastro-commits] master 3fcd49a 10/32: astscript-radial-profile: setting name and version from the compilation, (continued)
- [gnuastro-commits] master 3fcd49a 10/32: astscript-radial-profile: setting name and version from the compilation, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master ebab496 15/32: Book: changed the place of radial profile script documentation, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 6400ca4 16/32: Some minor correction in description, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 4f3d70d 20/32: Binning data in some case, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master b36c21f 17/32: astscript-radial-profile: modification to use $ instead of c in Table, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master e24caa6 07/32: astscript-radial-profile: user can now specify output column names, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master e1ded16 11/32: Book: minor typos and corrections in radial profile script examples, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 87d68b0 12/32: astscript-radial-profile: removing --rmin option because it is not used, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master aec3057 13/32: Book: describing most important options of radial profile script, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 1b505d1 21/32: Binning the S/N column, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 4294506 32/32: astscript-radial-profile: polished the script and book,
Mohammad Akhlaghi <=
- [gnuastro-commits] master ad7fb58 26/32: Central coordinates of the cropped image, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master d085379 22/32: Radial-profile script documentation, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 8089ea3 27/32: astscript-radial-profile: Samaeh's changes included, conflicts fixed, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 04a8bec 29/32: Book: simplifying documentation of astscript-radial-profile, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 362819c 30/32: astscript-radial-profile: fixed bug when creating the temporal directory, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master c9647b5 31/32: Imported work on the radial profile script, minor conflict fixed, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 1072b2b 02/32: astscript-radial-profile: added the option -b for binning the data, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 87f5383 23/32: astscript-radial-profile: minor corrections of previous commits, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master e41c2e4 24/32: astscript-radial-profile: sigma clip parameters for measurements added, Mohammad Akhlaghi, 2021/02/24
- [gnuastro-commits] master 337e46d 18/32: The half-light radii, Mohammad Akhlaghi, 2021/02/24