[gnuastro-commits] master 8943dd4: CosmicCalculator: new --listlinesatz option for wavelengths at z

[Mohammad Akhlaghi]

branch: master
commit 8943dd47746e8ff1a5d3282dec73938f8b974fe7
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    CosmicCalculator: new --listlinesatz option for wavelengths at z
    
    Until now, CosmicCalculator would just print the observed wavelength of one
    line at the given redshift with '--lineatz'. But sometimes a more general
    view of the shifted spectra can be useful. However, the '--listlines'
    option only printed the lines at rest frame.
    
    With this commit, the newly added '--listlinesatz' option does the same
    thing as '--listlines' (infact is uses the same function too!), but instead
    of printing the restframe wavelength, it prints the observed wavelength. It
    very convenient to match/demonstrate spectra for example, when one line is
    known/recognized.
    
    Also, with the number of spectral-line features in CosmicCalculator
    increasing, I moved their documentation in the book to a new and dedicated
    sub-section.
---
 NEWS                 |   8 ++++
 bin/cosmiccal/args.h |  91 +++++++++++++++++++++++++-----------------
 bin/cosmiccal/main.h |   1 +
 bin/cosmiccal/ui.c   |  44 ++++++++++++++++++---
 bin/cosmiccal/ui.h   |   4 +-
 doc/gnuastro.texi    | 109 +++++++++++++++++++++++++++++++++------------------
 6 files changed, 176 insertions(+), 81 deletions(-)

diff --git a/NEWS b/NEWS
index 0d5126b..6cacb94 100644
--- a/NEWS
+++ b/NEWS
@@ -14,6 +14,14 @@ See the end of the file for license conditions.
      will be read as floating point. This also applies to column arithmetic
      in Table.
 
+  CosmicCalculator:
+   --listlinesatz: Print the wavelength of all pre-defined spectral lines
+     at given redshift as a simple table with the line names. This is very
+     convenient and can be used in conjunction with '--obsline' for example
+     to print the observed wavelength of all lines when Lyman-alpha is at
+     4000 Angstroms with this simple command:
+        astcosmiccal --obsline=lyalpha,4000 --listlinesatz
+
   FITS:
    - New '--wcsdistortion' option allows conversion between the various WCS
      distortions. For example if you have a FITS image with the TPV-based
diff --git a/bin/cosmiccal/args.h b/bin/cosmiccal/args.h
index 63dc39a..947098c 100644
--- a/bin/cosmiccal/args.h
+++ b/bin/cosmiccal/args.h
@@ -115,29 +115,11 @@ struct argp_option program_options[] =
 
 
 
-    /* Output options */
-    {
-      "listlines",
-      UI_KEY_LISTLINES,
-      0,
-      0,
-      "List known spectral lines.",
-      GAL_OPTIONS_GROUP_OUTPUT,
-      &p->listlines,
-      GAL_OPTIONS_NO_ARG_TYPE,
-      GAL_OPTIONS_RANGE_0_OR_1,
-      GAL_OPTIONS_NOT_MANDATORY,
-      GAL_OPTIONS_NOT_SET
-    },
-
-
-
-
-
+    /* Basic cosmology */
     {
       0, 0, 0, 0,
-      "Specific calculations",
-      UI_GROUP_SPECIFIC
+      "Basic cosmology calculations",
+      UI_GROUP_BASIC
     },
     {
       "usedredshift",
@@ -145,7 +127,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Used redshift in this run.",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -159,7 +141,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Age of universe now (Ga: Giga Annum).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -173,7 +155,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Critical density now (g/cm^3).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -187,7 +169,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Proper distance to z (Mpc).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -201,7 +183,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Angular diameter distance (Mpc).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -215,7 +197,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Tangential dist. covered by 1arcsec at z (kpc).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -229,7 +211,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Luminosity distance to z (Mpc).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -243,7 +225,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Distance modulus at z (no units).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -257,7 +239,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Conversion to absolute magnitude (no unit).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -271,7 +253,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Age of universe at z (Ga: Giga Annum).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -285,7 +267,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Look back time to z (Ga: Giga Annum).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -299,7 +281,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Critical density at z (g/cm^3).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -313,7 +295,7 @@ struct argp_option program_options[] =
       0,
       0,
       "Comoving volume (4pi str) to z (Mpc^3).",
-      UI_GROUP_SPECIFIC,
+      UI_GROUP_BASIC,
       &p->specific,
       GAL_OPTIONS_NO_ARG_TYPE,
       GAL_OPTIONS_RANGE_0_OR_1,
@@ -321,13 +303,50 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET,
       ui_add_to_single_value,
     },
+
+
+
+
+
+    /* Spectral line options. */
+    {
+      0, 0, 0, 0,
+      "Spectral lines",
+      UI_GROUP_SPECTRAL_LINES
+    },
+    {
+      "listlines",
+      UI_KEY_LISTLINES,
+      0,
+      0,
+      "List known lines and rest frame wavelength.",
+      UI_GROUP_SPECTRAL_LINES,
+      &p->listlines,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
+      "listlinesatz",
+      UI_KEY_LISTLINESATZ,
+      0,
+      0,
+      "List known spectral lines at given redshift.",
+      UI_GROUP_SPECTRAL_LINES,
+      &p->listlinesatz,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_0_OR_1,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
     {
       "lineatz",
       UI_KEY_LINEATZ,
       "STR/FLT",
       0,
-      "Wavelength of given line at chosen redshift",
-      UI_GROUP_SPECIFIC,
+      "Wavelength of line (name or wavelength) at z.",
+      UI_GROUP_SPECTRAL_LINES,
       &p->specific,
       GAL_TYPE_STRING,
       GAL_OPTIONS_RANGE_ANY,
diff --git a/bin/cosmiccal/main.h b/bin/cosmiccal/main.h
index 5b53222..8fb700c 100644
--- a/bin/cosmiccal/main.h
+++ b/bin/cosmiccal/main.h
@@ -53,6 +53,7 @@ struct cosmiccalparams
   double            oradiation; /* Current radiation density.           */
   gal_data_t          *obsline; /* Observed wavelength of a line.       */
   uint8_t            listlines; /* List the known spectral lines.       */
+  uint8_t         listlinesatz; /* List the known spectral lines.       */
 
   /* Outputs. */
   gal_list_i32_t     *specific; /* Codes for single row calculations.   */
diff --git a/bin/cosmiccal/ui.c b/bin/cosmiccal/ui.c
index 8bc5e9d..c5d73c5 100644
--- a/bin/cosmiccal/ui.c
+++ b/bin/cosmiccal/ui.c
@@ -388,6 +388,19 @@ ui_read_check_only_options(struct cosmiccalparams *p)
           "and radiation ('oradiation') densities are given as %.8f, %.8f, "
           "%.8f", sum, p->olambda, p->omatter, p->oradiation);
 
+  /* Make sure that '--listlines' and '--listlinesatz' aren't called
+     together. */
+  if(p->listlines && p->listlinesatz)
+    error(EXIT_FAILURE, 0, "'--listlines' and '--listlinesatz' can't be "
+          "called together");
+
+  /* Make sure that atleast one of '--redshift' or '--obsline' are given
+     for the running redshift. Except when '--listlines' is used (that
+     doesn't need any redshift). */
+  if(isnan(p->redshift) && p->obsline==NULL && p->listlines==0)
+    error(EXIT_FAILURE, 0, "no redshift specified! Please use '--redshift' "
+          "or '--obsline' to specify a redshift");
+
   /* Make sure that '--redshift' and '--obsline' aren't called together. */
   if(!isnan(p->redshift) && p->obsline)
     error(EXIT_FAILURE, 0, "'--redshift' and '--obsline' cannot be called "
@@ -421,13 +434,25 @@ ui_list_lines(struct cosmiccalparams *p)
 {
   size_t i;
 
-  /* First print the metadata */
-  printf("# Column 1: Wavelength [Angstrom,f32] Pre-defined line 
wavelength.\n");
-  printf("# Column 2: Name       [name,  str10] Pre-defined line name.\n");
+  /* Print basic information. Note that '--listlinesatz' is requested, also
+     print the redshift used. */
+  printf("# %s\n", PROGRAM_STRING);
+  if(p->listlinesatz)
+    printf("# Assumed redshift: %g\n", p->redshift);
+
+  /* Print column metadata. */
+  printf("# Column 1: Wavelength [Angstrom,f32] %s.\n",
+         ( p->listlinesatz
+           ? "Line wavelength at assumed redshift"
+           : "Rest frame wavelength of the line"));
+  printf("# Column 2: Name       [name,  str10] Line name in Gnuastro.\n");
 
   /* Print the line information. */
   for(i=1;i<GAL_SPECLINES_INVALID_MAX;++i)
-    printf("%-15g%s\n", gal_speclines_line_angstrom(i),
+    printf("%-15g%s\n",
+           ( p->listlinesatz
+             ? ( gal_speclines_line_angstrom(i) * (1+p->redshift) )
+             : gal_speclines_line_angstrom(i) ),
            gal_speclines_line_name(i));
 
   /* Abort the program. */
@@ -443,8 +468,10 @@ ui_preparations(struct cosmiccalparams *p)
 {
   double *obsline = p->obsline ? p->obsline->array : NULL;
 
-  /* If '--listlines' is given, print them and abort, don't continue with
-     the preparations. */
+  /* If '--listlines' is given, print them and abort the program
+     successfully, don't continue with the preparations. Note that
+     '--listlines' is the rest-frame lines. So we don't need any
+     redshift. */
   if(p->listlines)
     ui_list_lines(p);
 
@@ -461,6 +488,11 @@ ui_preparations(struct cosmiccalparams *p)
      check.*/
   if(p->redshift==0.0f) p->redshift=MAIN_REDSHIFT_ZERO;
 
+  /* Now that we have the redshift, we can print the 'listlinesatz'
+     option. */
+  if(p->listlinesatz)
+    ui_list_lines(p);
+
   /* The list is filled out in a first-in-last-out order. By the time
      control reaches here, the list is finalized. So we should just reverse
      it so the user gets values in the same order they requested them. */
diff --git a/bin/cosmiccal/ui.h b/bin/cosmiccal/ui.h
index 1584718..142d79f 100644
--- a/bin/cosmiccal/ui.h
+++ b/bin/cosmiccal/ui.h
@@ -33,7 +33,8 @@ along with Gnuastro. If not, see 
<http://www.gnu.org/licenses/>.
 /* Option groups particular to this program. */
 enum program_args_groups
 {
-  UI_GROUP_SPECIFIC = GAL_OPTIONS_GROUP_AFTER_COMMON,
+  UI_GROUP_BASIC = GAL_OPTIONS_GROUP_AFTER_COMMON,
+  UI_GROUP_SPECTRAL_LINES,
 };
 
 
@@ -73,6 +74,7 @@ enum option_keys_enum
   /* Only with long version (start with a value 1000, the rest will be set
      automatically). */
   UI_KEY_LISTLINES           = 1000,
+  UI_KEY_LISTLINESATZ,
 };
 
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 0c17cf6..f97097f 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -573,7 +573,8 @@ CosmicCalculator
 Invoking CosmicCalculator
 
 * CosmicCalculator input options::  Options to specify input conditions.
-* CosmicCalculator specific calculations::  Requesting specific outputs.
+* CosmicCalculator basic cosmology calculations::  Like distance modulus, 
distances and etc.
+* CosmicCalculator spectral line calculations::  How they get affected by 
redshift.
 
 Library
 
@@ -17425,6 +17426,10 @@ $ astcosmiccal -z0.4 -LAg
 ## 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
+
+## Print wavelength of all pre-defined spectral lines when
+## Lyman-alpha is observed at 4000 Angstroms.
+$ astcosmiccal --obsline=lyalpha,4000 --listlinesatz
 @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}.
@@ -17432,18 +17437,22 @@ For a definition of the different parameters, please 
see the sections prior to t
 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}.
 
-When only a redshift is given, CosmicCalculator will print all calculations 
(one per line) with some explanations before each.
+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 calculations are requested, only the requested 
values will be calculated and printed with one character space between them.
-In this case, no description will be printed.
-See @ref{CosmicCalculator specific calculations} for the full list of these 
options along with some explanations how when/how they can be useful.
+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 sitatuions, please see 
@ref{CosmicCalculator spectral line calculations}.
 
 @menu
 * CosmicCalculator input options::  Options to specify input conditions.
-* CosmicCalculator specific calculations::  Requesting specific outputs.
+* CosmicCalculator basic cosmology calculations::  Like distance modulus, 
distances and etc.
+* CosmicCalculator spectral line calculations::  How they get affected by 
redshift.
 @end menu
 
-@node CosmicCalculator input options, CosmicCalculator specific calculations, 
Invoking astcosmiccal, Invoking astcosmiccal
+@node CosmicCalculator input options, CosmicCalculator basic cosmology 
calculations, Invoking astcosmiccal, Invoking astcosmiccal
 @subsubsection CosmicCalculator input options
 
 The inputs to CosmicCalculator can be specified with the following options:
@@ -17451,7 +17460,9 @@ The inputs to CosmicCalculator can be specified with 
the following options:
 
 @item -z FLT
 @itemx --redshift=FLT
-The redshift of interest. This cannot be called with @option{--obsline}.
+The redshift of interest.
+You can also specify the target redshift from spectral lines and their 
observed wavelengths, for that see @option{--obsline}.
+Note that this option cannot be called with @option{--obsline}.
 
 @item -H FLT
 @itemx --H0=FLT
@@ -17469,30 +17480,12 @@ Matter (including massive neutrinos) density divided 
by the critical density in
 @itemx --oradiation=FLT
 Radiation density divided by the critical density in the current Universe 
(@mymath{\Omega_{r,0}}).
 
-@item --listlines
-List the pre-defined spectral line wavelengths and 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.
-
-These names can be used with the options that deal with spectral lines, for 
example @option{--obsline} (below) and @option{--lineatz} 
(@ref{CosmicCalculator specific calculations}).
-
-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:
-
-@example
-$ astcosmiccal --listlines \
-               | asttable --range=wavelength,4000,6000
-@end example
-
-@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 -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 can be used instead of @option{--redshift}.
 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.
@@ -17616,8 +17609,8 @@ You can get this list on the command-line with the 
@option{--listlines}.
 
 
 
-@node CosmicCalculator specific calculations,  , CosmicCalculator input 
options, Invoking astcosmiccal
-@subsubsection CosmicCalculator specific calculations
+@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.
@@ -17658,7 +17651,7 @@ The other calculations will also be done, but they are 
so fast that you will not
 $ astcosmiccal --redshift=0.832 | grep volume
 @end example
 
-The full list of CosmicCalculator's specific calculations is present below.
+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
@@ -17722,24 +17715,64 @@ The critical density at given redshift in grams per 
centimeter-cube (@mymath{g/c
 @itemx --onlyvolume
 The comoving volume in Megaparsecs cube (Mpc@mymath{^3}) until the desired 
redshift based on the input parameters.
 
-@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).
-
 @end table
 
 
 
 
+@node CosmicCalculator spectral line calculations,  , CosmicCalculator basic 
cosmology calculations, Invoking astcosmiccal
+@subsubsection CosmicCalculator spectral line calculations
+
+@cindex Rest frame wavelength
+At different redhifts, 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.
+
+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.
 
+@example
+$ astcosmiccal --obsline=lyalpha,8000 --lineatz=halpha
+$ astcosmiccal --obsline=lyalpha,8000 --listlinesatz
+@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}.
+
+@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.
+
+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}).
+
+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:
+
+@example
+$ astcosmiccal --listlines \
+               | asttable --range=wavelength,4000,6000
+@end example
 
+@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}.
 
+@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).
 
+@end table