[gnuastro-commits] master 912755de 2/2: Book: 3D cubes spectra includes section with logarithmic axises

[Mohammad Akhlaghi]

branch: master
commit 912755de722a5c4dc4cc287a9052a72109e5e419
Author: Rahna Payyasseri <rpayyasseri@cefca.es>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: 3D cubes spectra includes section with logarithmic axises
    
    Until now, this tutorial only described linear spectral coordinates
    (because they are the way MUSE cubes are designed). But other surveys like
    MaNGA provide logarithmic units in the third dimension.
    
    With this commit, to simplify the usage of such cubes, a new short section
    was added to this tutorial with a description and commands now how they can
    identify such cubes and how they can plot the measured spectra.
---
 doc/gnuastro.texi | 34 ++++++++++++++++++++++++++++++++--
 1 file changed, 32 insertions(+), 2 deletions(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index ea899289..8ac5e2cb 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -333,6 +333,7 @@ Detecting lines and extracting spectra in 3D data
 * 3D detection with NoiseChisel::  Finding emission-lines and their spectra.
 * 3D measurements and spectra::  Measuring 3d properties including spectra.
 * Extracting a single spectrum and plotting it::  Extracting a single vector 
row.
+* Cubes with logarithmic third dimension::  When the wavelength/frequency is 
logarithmic.
 * Pseudo narrow-band images::   Collapsing the third dimension into a 2D image.
 
 Color images with full dynamic range
@@ -7946,6 +7947,7 @@ We will finish with creating pseudo narrow-band images 
optimized for some of the
 * 3D detection with NoiseChisel::  Finding emission-lines and their spectra.
 * 3D measurements and spectra::  Measuring 3d properties including spectra.
 * Extracting a single spectrum and plotting it::  Extracting a single vector 
row.
+* Cubes with logarithmic third dimension::  When the wavelength/frequency is 
logarithmic.
 * Pseudo narrow-band images::   Collapsing the third dimension into a 2D image.
 @end menu
 
@@ -8543,7 +8545,7 @@ $ astmkcatalog seg.fits --ids --ra --dec --w3 --sum  \
                --output=cat-with-continuum.fits
 @end example
 
-@node Extracting a single spectrum and plotting it, Pseudo narrow-band images, 
3D measurements and spectra, Detecting lines and extracting spectra in 3D data
+@node Extracting a single spectrum and plotting it, Cubes with logarithmic 
third dimension, 3D measurements and spectra, Detecting lines and extracting 
spectra in 3D data
 @subsection Extracting a single spectrum and plotting it
 
 In @ref{3D measurements and spectra} we measured the spectra of all the 
objects with the MUSE data cube of this demonstration tutorial.
@@ -8615,8 +8617,36 @@ Un-select the ``Mark'' item that was originally selected.
 
 @noindent
 Of course, the table in @file{spectrum-obj-198.fits} can be plotted using any 
other plotting tool you prefer to use in your scientific papers.
+In the next section (@ref{Cubes with logarithmic third dimension}), we'll 
review the necessary modifications to the recipes in this section for cubes 
where the third dimension is logarithmic, not linear (as in MUSE cubes).
+Finally, in @ref{Cubes with logarithmic third dimension}, you'll see how you 
can make narrow-band images of your desired target around your desired emission 
line.
 
-@node Pseudo narrow-band images,  , Extracting a single spectrum and plotting 
it, Detecting lines and extracting spectra in 3D data
+@node Cubes with logarithmic third dimension, Pseudo narrow-band images, 
Extracting a single spectrum and plotting it, Detecting lines and extracting 
spectra in 3D data
+@subsection Cubes with logarithmic third dimension
+In @ref{Extracting a single spectrum and plotting it}, a single object's 
spectrum was extracted from the catalog and plotted.
+Extracting the wavelength of each slice was easy there because MUSE data cubes 
provide a linear third dimension.
+However, it can happen that the third axis of a cube is logarithmic not linear 
(as in the MUSE cube used in this tutorial).
+An example in the optical regime is the data cubes of the 
@url{https://www.sdss4.org/surveys/manga/, MaNGA survey}@footnote{An example 
data cube from the MaNGA survey can be downloaded from here: 
@url{https://data.sdss.org/sas/dr17/manga/spectro/redux/v3_1_1/7443/stack/manga-7443-12703-LOGCUBE.fits.gz}}.
+To identify if an axis is logarithmic or linear, the 
@url{https://ui.adsabs.harvard.edu/abs/2006A&A...446..747G, FITS WCS standard} 
(Section 3.2) says that you should look at the @code{CTYPE} keywords and check 
if any have a @code{-LOG} suffix.
+For example, here is the output on a MaNGA data cube:
+
+@example
+$ astfits manga.fits -h1 | grep CTYPE
+CTYPE1  = 'RA---TAN'
+CTYPE2  = 'DEC--TAN'
+CTYPE3  = 'WAVE-LOG'
+@end example
+
+In the same section, the FITS standard describes how the ``world coordinate'' 
(wavelengh in this case) can be calculated in such cases.
+The column arithmetic command to add the wavelength to each slice's 
measurement looks is shown below (just for the first object in the catalog; 
replace @option{--head=1} as you wish).
+For the @code{d}, @code{lr} and @code{sr} shell variables that are used in 
this command, see @ref{Extracting a single spectrum and plotting it}.
+
+@example
+$ asttable cat.fits --head=1 -csum-in-slice --transpose \
+           | asttable -c'arith $1 index '$d' x '$lr' / set-p set-s \
+                               e p pow '$lr' x s'
+@end example
+
+@node Pseudo narrow-band images,  , Cubes with logarithmic third dimension, 
Detecting lines and extracting spectra in 3D data
 @subsection Pseudo narrow-band images
 
 In @ref{Continuum subtraction} we subtracted/separated the continuum from the 
emission/absorption lines of our galaxy in the MUSE cube.