[gnuastro-commits] master 38fbcf50: Library (arithmetic): new operators to convert counts to nanomaggies

[Mohammad Akhlaghi]

branch: master
commit 38fbcf501c334d33023864672c982fd91e0d8377
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Library (arithmetic): new operators to convert counts to nanomaggies
    
    Until now, there was no easy way to convert the counts of an image to
    nanomaggies (used by SDSS and many others, with a fixed zeropoint of 22.5)
    or vice-versa.
    
    With this commit, the necessary library functions have been written and the
    interface to the 'arithmetic.h' library has been added to allow this
    operation easily in both the Arithmetic and Table programs.
    
    This was suggested by Giulia Golini.
---
 NEWS                      |  9 +++++++++
 doc/gnuastro.texi         | 43 ++++++++++++++++++++++++++++++++++++++-----
 lib/arithmetic.c          | 12 ++++++++++++
 lib/gnuastro/arithmetic.h |  2 ++
 lib/gnuastro/units.h      |  6 ++++++
 lib/units.c               | 31 +++++++++++++++++++++++++++++++
 6 files changed, 98 insertions(+), 5 deletions(-)

diff --git a/NEWS b/NEWS
index 4c0ec264..d2550a3f 100644
--- a/NEWS
+++ b/NEWS
@@ -20,6 +20,11 @@ See the end of the file for license conditions.
      - counter: similar to 'index', but integers start with 1.
      - indexonly: similar to 'index', but pops the top stack dataset.
      - counteronly: similar to 'counter', but pops the top stack dataset.
+     - counts-to-nanomaggy: convert counts to Nanomaggy (with fixed
+       zeropoint of 22.5, used as the pixel units of many surveys like
+       SDSS). This was suggested by Giulia Golini.
+     - nanomaggy-to-counts: convert nanomaggy to counts. This was suggested
+       by Giulia Golini.
 
    Crop:
    --append: if the output file already exists, append the cropped image
@@ -50,6 +55,10 @@ See the end of the file for license conditions.
    - GAL_ARITHMETIC_OP_INDEXONLY: Similar to 'GAL_ARITHMETIC_OP_INDEX'.
    - GAL_ARITHMETIC_OP_COUNTER: A counter (counting from 1) for every element.
    - GAL_ARITHMETIC_OP_COUNTERONLY: Similar to 'GAL_ARITHMETIC_OP_COUNTER'.
+   - GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY: convert counts to nanomaggy.
+   - GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS: convert nanomaggy to counts.
+   - gal_units_counts_to_nanomaggy: Convert counts to nanomaggy.
+   - gal_units_nanomaggy_to_counts: Convert nanomaggy to counts.
    - gal_data_alloc_empty: Allocate an empty dataset with a given number of
      dimensions.
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index a5f595aa..0e0a9ed7 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16775,6 +16775,25 @@ $ astarithmetic sdss-image.fits 22.5 counts-to-jy
 Convert Janskys to counts (usually CCD outputs) through an AB-magnitude based 
zero point.
 This is the inverse operation of the @code{counts-to-jy}, see there for usage 
example.
 
+@item counts-to-nanomaggy
+@cindex Nanomaggy
+Convert counts to Nanomaggy (with fixed zeropoint of 22.5, used as the pixel 
units of many surveys like SDSS).
+For example if your image has a zeropoint of 24.93, you can convert it to 
Nanomaggies with the command below:
+
+@example
+$ astarithmetic image.fits 24.93 counts-to-nanomaggy
+@end example
+
+@item nanomaggy-to-counts
+@cindex Nanomaggy
+Convert Nanomaggy to counts.
+Nanomaggy is defined to have a fixed zeropoint of 22.5 and is the pixel units 
of many surveys like SDSS.
+For example if you would like to convert an image in units of Nanomaggy (for 
example from SDSS) to the counts of a camera with a zeropoint of 25.92, you can 
use the command below:
+
+@example
+$ astarithmetic image.fits 25.92 nanomaggy-to-counts
+@end example
+
 @item mag-to-jy
 Convert AB magnitudes to Janskys, see @ref{Brightness flux magnitude}.
 
@@ -23780,8 +23799,9 @@ Using the zero point magnitude (@mymath{Z}), we can 
write the magnitude relation
 @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}).
-This enables direct pixel-based comparisons with images from other 
instruments@footnote{Comparing data from different instruments assumes 
instrument and observation signatures are properly corrected, things like the 
flat-field or the Sky absorption}.
+Having the zero point of an image, you can convert its pixel values to 
physical units like microJanskys (or @mymath{\mu{}Jy}).
+This enables direct pixel-based comparisons with images from other 
instruments@footnote{Comparing data from different instruments assumes 
instrument and observation signatures are properly corrected, things like the 
flat-field or the Sky absorption.
+It is also valid for pixel values, assuming that factors that can change the 
morphology (like the @ref{PSF}) are the same.}.
 Jansky is a commonly used unit for measuring spectral flux density and one 
Jansky is equivalent to @mymath{10^{-26} W/m^2/Hz} (watts per square meter per 
hertz).
 
 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}.
@@ -34676,11 +34696,14 @@ The latter two are the opposite.
 @deffnx Macro GAL_ARITHMETIC_OP_JY_TO_COUNTS
 @deffnx Macro GAL_ARITHMETIC_OP_MAG_TO_JY
 @deffnx Macro GAL_ARITHMETIC_OP_JY_TO_MAG
+@deffnx Macro GAL_ARITHMETIC_OP_MAG_TO_NANOMAGGY
+@deffnx Macro GAL_ARITHMETIC_OP_NANOMAGGY_TO_MAG
 @cindex Surface Brightness
 Binary operators for converting brightness and surface brightness units to and 
from each other.
-The first operand to all of them are the values in the respective input unit.
-The second popped operand is the zero point, except for the operators that 
involve surface brightness (those with @code{SB}).
-For the surface brightness related operators, the second popped operand is the 
area in units of arcsec@mymath{^2}.
+The first operand to all of them are the values in the input unit (left of the 
@code{-TO-}, for example counts in @code{COUNTS_TO_MAG}).
+The second popped operand is the zero point (right of the @code{-TO-}, for 
example magnitudes in @code{COUNTS_TO_MAG}).
+The exceptions are the operators that involve surface brightness (those with 
@code{SB}).
+For the surface brightness related operators, the second popped operand is the 
area in units of arcsec@mymath{^2} and the third popped operand is the final 
unit.
 @end deffn
 
 @deffn  Macro GAL_ARITHMETIC_OP_COUNTS_TO_SB
@@ -37993,6 +38016,16 @@ Convert the input value (assumed to be in Astronomical 
Units) to Parsecs.
 For the conversion equation, see the description of @code{au-to-pc} operator 
in @ref{Arithmetic operators}.
 @end deftypefun
 
+@deftypefun double gal_units_counts_to_nanomaggy (double @code{counts}, double 
@code{zeropoint_ab})
+@cindex Nanomaggy
+@cindex Magnitude (nanomaggy)
+Convert counts to Nanomaggy (with fixed zeropoint of 22.5) through an AB 
magnitude-based zero point.
+@end deftypefun
+
+@deftypefun double gal_units_nanomaggy_to_counts (double @code{counts}, double 
@code{zeropoint_ab})
+Convert Nanomaggy (with fixed zeropoint of 22.5) to counts through an AB 
magnitude-based zero point.
+@end deftypefun
+
 @deftypefun double gal_units_pc_to_au (double @code{pc})
 Convert the input value (assumed to be in Parsecs) to Astronomical Units (AUs).
 For the conversion equation, see the description of @code{au-to-pc} operator 
in @ref{Arithmetic operators}.
diff --git a/lib/arithmetic.c b/lib/arithmetic.c
index da5d33f2..7c29d9ee 100644
--- a/lib/arithmetic.c
+++ b/lib/arithmetic.c
@@ -2451,6 +2451,10 @@ arithmetic_function_binary_flt(int operator, int flags, 
gal_data_t *il,
       BINFUNC_F_OPERATOR_SET( gal_units_counts_to_jy, +0 ); break;
     case GAL_ARITHMETIC_OP_JY_TO_COUNTS:
       BINFUNC_F_OPERATOR_SET( gal_units_jy_to_counts, +0 ); break;
+    case GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY:
+      BINFUNC_F_OPERATOR_SET( gal_units_counts_to_nanomaggy, +0 ); break;
+    case GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS:
+      BINFUNC_F_OPERATOR_SET( gal_units_nanomaggy_to_counts, +0 ); break;
     default:
       error(EXIT_FAILURE, 0, "%s: operator code %d not recognized",
             __func__, operator);
@@ -3018,6 +3022,10 @@ gal_arithmetic_set_operator(char *string, size_t 
*num_operands)
     { op=GAL_ARITHMETIC_OP_COUNTS_TO_JY;      *num_operands=2;  }
   else if (!strcmp(string, "jy-to-counts"))
     { op=GAL_ARITHMETIC_OP_JY_TO_COUNTS;      *num_operands=2;  }
+  else if (!strcmp(string, "counts-to-nanomaggy"))
+    { op=GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY; *num_operands=2;}
+  else if (!strcmp(string, "nanomaggy-to-counts"))
+    { op=GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS; *num_operands=2;}
   else if (!strcmp(string, "mag-to-jy"))
     { op=GAL_ARITHMETIC_OP_MAG_TO_JY;         *num_operands=1;  }
   else if (!strcmp(string, "jy-to-mag"))
@@ -3269,6 +3277,8 @@ gal_arithmetic_operator_string(int operator)
     case GAL_ARITHMETIC_OP_SB_TO_COUNTS:    return "sb-to-counts";
     case GAL_ARITHMETIC_OP_COUNTS_TO_JY:    return "counts-to-jy";
     case GAL_ARITHMETIC_OP_JY_TO_COUNTS:    return "jy-to-counts";
+    case GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY: return "counts-to-nanomaggy";
+    case GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS: return "nanomaggy-to-counts";
     case GAL_ARITHMETIC_OP_MAG_TO_JY:       return "mag-to-jy";
     case GAL_ARITHMETIC_OP_JY_TO_MAG:       return "jy-to-mag";
     case GAL_ARITHMETIC_OP_AU_TO_PC:        return "au-to-pc";
@@ -3440,6 +3450,8 @@ gal_arithmetic(int operator, size_t numthreads, int 
flags, ...)
     case GAL_ARITHMETIC_OP_COUNTS_TO_JY:
     case GAL_ARITHMETIC_OP_COUNTS_TO_MAG:
     case GAL_ARITHMETIC_OP_MAG_TO_COUNTS:
+    case GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS:
+    case GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY:
       d1 = va_arg(va, gal_data_t *);
       d2 = va_arg(va, gal_data_t *);
       out=arithmetic_function_binary_flt(operator, flags, d1, d2);
diff --git a/lib/gnuastro/arithmetic.h b/lib/gnuastro/arithmetic.h
index 5304f8cb..3e158519 100644
--- a/lib/gnuastro/arithmetic.h
+++ b/lib/gnuastro/arithmetic.h
@@ -156,6 +156,8 @@ enum gal_arithmetic_operators
   GAL_ARITHMETIC_OP_JY_TO_COUNTS, /* Janskys to Counts with AB-mag zeropoint. 
*/
   GAL_ARITHMETIC_OP_MAG_TO_JY,    /* Magnitude to Janskys. */
   GAL_ARITHMETIC_OP_JY_TO_MAG,    /* Janskys to Magnitude. */
+  GAL_ARITHMETIC_OP_COUNTS_TO_NANOMAGGY,/* Counts to SDSS nanomaggies. */
+  GAL_ARITHMETIC_OP_NANOMAGGY_TO_COUNTS,/* SDSS nanomaggies to counts. */
   GAL_ARITHMETIC_OP_AU_TO_PC,     /* Astronomical units (AU) to Parsecs (PC). 
*/
   GAL_ARITHMETIC_OP_PC_TO_AU,     /* Parsecs (PC) to Astronomical units (AU). 
*/
   GAL_ARITHMETIC_OP_LY_TO_PC,     /* Astronomical units (AU) to Parsecs (PC). 
*/
diff --git a/lib/gnuastro/units.h b/lib/gnuastro/units.h
index 4e3304b5..31a5f994 100644
--- a/lib/gnuastro/units.h
+++ b/lib/gnuastro/units.h
@@ -99,6 +99,12 @@ gal_units_counts_to_jy(double counts, double zeropoint_ab);
 double
 gal_units_jy_to_counts(double jy, double zeropoint_ab);
 
+double
+gal_units_counts_to_nanomaggy(double counts, double zeropoint_ab);
+
+double
+gal_units_nanomaggy_to_counts(double counts, double zeropoint_ab);
+
 double
 gal_units_jy_to_mag(double jy);
 
diff --git a/lib/units.c b/lib/units.c
index 2732ee7b..abb7a413 100644
--- a/lib/units.c
+++ b/lib/units.c
@@ -465,6 +465,37 @@ gal_units_jy_to_counts(double jy, double zeropoint_ab)
 
 
 
+/* Convert counts to nanomaggy. The job of this function is equivalent to
+   the double-call bellow. We just don't want to repeat some extra
+   multiplication/divisions.
+
+     gal_units_jy_to_counts(gal_units_counts_to_jy(counts, zeropoint_ab),
+                            22.5)
+*/
+double
+gal_units_counts_to_nanomaggy(double counts, double zeropoint_ab)
+{
+  return ( counts
+           * pow(10, -1 * zeropoint_ab / 2.5)
+           / pow(10, -1 * 22.5         / 2.5) );
+}
+
+
+
+
+
+double
+gal_units_nanomaggy_to_counts(double counts, double zeropoint_ab)
+{
+  return ( counts
+           / pow(10, -1 * zeropoint_ab / 2.5)
+           * pow(10, -1 * 22.5         / 2.5) );
+}
+
+
+
+
+
 double
 gal_units_jy_to_mag(double jy)
 {