[gnuastro-commits] master ef3b3f9: Book: minor edits in --sigclip-median example of Statistics

[Mohammad Akhlaghi]

branch: master
commit ef3b3f95b50706271d8e81842143f9857a5d30b9
Author: Mohammad Akhlaghi <address@hidden>
Commit: Mohammad Akhlaghi <address@hidden>

    Book: minor edits in --sigclip-median example of Statistics
    
    Some minor edits were made to make it more clear.
---
 NEWS              |  3 ++-
 doc/gnuastro.texi | 39 +++++++++++++++++++++++----------------
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/NEWS b/NEWS
index 000053b..2d70f51 100644
--- a/NEWS
+++ b/NEWS
@@ -12,7 +12,8 @@ See the end of the file for license conditions.
      sigma-clipping and only print the desired value as a single-value
      measurement. Until now sigma-clipping results included a lot of
      visually useful information, which also made automatic usage of
-     results hard. These options fix this issue.
+     results hard. These options fix this issue. Please see the example in
+     the book under `--sigclip-median' for a nice use case.
 
 ** Removed features
 
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index bcd7a13..a2e0eaf 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -16413,13 +16413,14 @@ Median after applying @mymath{\sigma}-clipping (see 
@ref{Sigma
 clipping}). @mymath{\sigma}-clipping configuration is done with the
 @option{--sigclipparams} option.
 
address@hidden Outlier
 Here is one scenario where this can be useful: assume you have a table and
-you would like to only select the rows that are within the sigma-clipping
-range. Let's assume your table is called @file{table.fits} and you want to
-only keep the rows that have a value in @code{COLUMN} within the
address@hidden range (to @mymath{3\sigma}, with a tolerance of
-0.1). This command will return the sigma-clipped median and standard
-deviation (used to define the range later).
+you would like to remove the rows that are outliers (not within the
+sigma-clipping range). Let's assume your table is called @file{table.fits}
+and you only want to keep the rows that have a value in @code{COLUMN}
+within the @mymath{\sigma}-clipped range (to @mymath{3\sigma}, with a
+tolerance of 0.1). This command will return the sigma-clipped median and
+standard deviation (used to define the range later).
 
 @example
 $ aststatistics table.fits -cCOLUMN --sclipparams=3,0.1 \
@@ -16429,14 +16430,16 @@ $ aststatistics table.fits -cCOLUMN 
--sclipparams=3,0.1 \
 @cindex GNU AWK
 You can then use the @option{--range} option of Table (see @ref{Table}) to
 select the proper rows. But for that, you need the actual starting and
-ending values of the range (@mymath{\rm{median}\pm s\times\sigma}). So
-these raw numbers alone aren't enough.
+ending values of the range (@mymath{m\pm s\sigma}; where @mymath{m} is the
+median and @mymath{s} is the multiple of sigma to define an
+outlier). Therefore, the raw outputs of Statistics in the command above
+aren't enough.
 
-To get starting and ending of the range (and put a address@hidden,}' between 
them,
-ready to be used in @option{--range}), pipe the result into AWK. But in
-AWK, we'll also need the multiple of @mymath{\sigma}, so we'll define it as
-a shell variable (@code{s}) before calling Statistics (note how @code{$s}
-is used two times now):
+To get the starting and ending values of the non-outlier range (and put a
address@hidden,}' between them, ready to be used in @option{--range}), pipe the
+result into AWK. But in AWK, we'll also need the multiple of
address@hidden, so we'll define it as a shell variable (@code{s}) before
+calling Statistics (note how @code{$s} is used two times now):
 
 @example
 $ s=3
@@ -16445,9 +16448,9 @@ $ aststatistics table.fits -cCOLUMN 
--sclipparams=$s,0.1 \
      | awk '@{s='$s'; printf("%f,%f\n", $1-s*$2, $1+s*$2)@}'
 @end example
 
-We'll just need to save the printed value from the command above in another
-shell variable (@code{r}), not print it. In Bash, can do this by putting
-the whole statement within a @code{$()}:
+To pass it onto Table, we'll need to keep the printed output from the
+command above in another shell variable (@code{r}), not print it. In Bash,
+can do this by putting the whole statement within a @code{$()}:
 
 @example
 $ s=3
@@ -16464,6 +16467,10 @@ rows that have a value in @code{COLUMN} within the 
desired range:
 $ asttable table.fits --range=COLUMN,$r
 @end example
 
+To save the resulting table (that is clean of outliers) in another file
+(for example named @file{cleaned.fits}, it can also have a @file{.txt}
+suffix), just add @option{--output=cleaned.fits} to the command above.
+
 
 @item --sigclip-mean
 Mean after applying @mymath{\sigma}-clipping (see @ref{Sigma