[gnuastro-commits] master 1b0046b 051/113: Recent additions in master imported here, no conflicts

[Mohammad Akhlaghi]

branch: master
commit 1b0046bbf0002375962f1faf7a4118907f6b29c0
Merge: fd51c80 969da3f
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Recent additions in master imported here, no conflicts
    
    Recent work in the master branch (in particular the new addition to the
    Statistics program) is now available here.
---
 NEWS                        |  4 +++
 bin/statistics/args.h       | 13 +++++++++
 bin/statistics/main.h       |  1 +
 bin/statistics/statistics.c | 48 ++++++++++++++++++++++++++------
 bin/statistics/ui.c         | 11 ++++----
 bin/statistics/ui.h         |  1 +
 doc/gnuastro.texi           | 67 ++++++++++++++++++++++++++++++---------------
 7 files changed, 109 insertions(+), 36 deletions(-)

diff --git a/NEWS b/NEWS
index 7f3782f..19c3ca3 100644
--- a/NEWS
+++ b/NEWS
@@ -5,6 +5,10 @@ GNU Astronomy Utilities NEWS                          -*- 
outline -*-
 
 ** New features
 
+  Statistics: the new `--manualbinrange' allows the bins in histograms or
+  cumulative frequency plots to be set outside the minimum or maximum
+  values of the dataset.
+
 ** Removed features
 
 ** Changed features
diff --git a/bin/statistics/args.h b/bin/statistics/args.h
index 227540f..6b0fbb9 100644
--- a/bin/statistics/args.h
+++ b/bin/statistics/args.h
@@ -595,6 +595,19 @@ struct argp_option program_options[] =
       GAL_OPTIONS_NOT_SET
     },
     {
+      "manualbinrange",
+      UI_KEY_MANUALBINRANGE,
+      0,
+      0,
+      "Set min/max of bins manually, not from data.",
+      UI_GROUP_HIST_CFP,
+      &p->manualbinrange,
+      GAL_OPTIONS_NO_ARG_TYPE,
+      GAL_OPTIONS_RANGE_GT_0,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET
+    },
+    {
       "onebinstart",
       UI_KEY_ONEBINSTART,
       "FLT",
diff --git a/bin/statistics/main.h b/bin/statistics/main.h
index 4557a6b..01c437b 100644
--- a/bin/statistics/main.h
+++ b/bin/statistics/main.h
@@ -79,6 +79,7 @@ struct statisticsparams
   size_t      numasciibins;  /* Number of bins in ASCII plots.           */
   size_t       asciiheight;  /* Height of ASCII histogram or CFP plots.  */
   uint8_t        normalize;  /* set the sum of all bins to 1.            */
+  uint8_t   manualbinrange;  /* Set bin min/max manually, not from data. */
   float        onebinstart;  /* Shift bins to start at this value.       */
   uint8_t        maxbinone;  /* Set the maximum bin to 1.                */
   float         mirrordist;  /* Maximum distance after mirror for mode.  */
diff --git a/bin/statistics/statistics.c b/bin/statistics/statistics.c
index 42a80dc..62bf0ec 100644
--- a/bin/statistics/statistics.c
+++ b/bin/statistics/statistics.c
@@ -303,8 +303,8 @@ statistics_on_tile(struct statisticsparams *p)
           type=GAL_TYPE_FLOAT64; break;
 
         default:
-          error(EXIT_FAILURE, 0, "%s: a bug! %d is not a recognized operation "
-                "code", __func__, operation->v);
+          error(EXIT_FAILURE, 0, "%s: a bug! %d is not a recognized "
+                "operation code", __func__, operation->v);
         }
 
       /* Allocate the space necessary to keep the value for each tile. */
@@ -470,13 +470,37 @@ print_ascii_plot(struct statisticsparams *p, gal_data_t 
*plot,
 
 
 
+
+/* Data structure that must be fed into `gal_statistics_regular_bins'.*/
+static gal_data_t *
+set_bin_range_params(struct statisticsparams *p)
+{
+  size_t rsize=2;
+  gal_data_t *range=NULL;
+
+  if(p->manualbinrange)
+    {
+      /* Allocate the range data structure. */
+      range=gal_data_alloc(NULL, GAL_TYPE_FLOAT32, 1, &rsize, NULL, 0, -1,
+                           NULL, NULL, NULL);
+      ((float *)(range->array))[0]=p->greaterequal;
+      ((float *)(range->array))[1]=p->lessthan;
+    }
+  return range;
+}
+
+
+
+
+
 static void
 ascii_plots(struct statisticsparams *p)
 {
-  gal_data_t *bins, *hist, *cfp=NULL;
+  gal_data_t *bins, *hist, *cfp=NULL, *range=NULL;
 
   /* Make the bins and the respective plot. */
-  bins=gal_statistics_regular_bins(p->input, NULL, p->numasciibins, NAN);
+  range=set_bin_range_params(p);
+  bins=gal_statistics_regular_bins(p->input, range, p->numasciibins, NAN);
   hist=gal_statistics_histogram(p->input, bins, 0, 0);
   if(p->asciicfp)
     {
@@ -586,13 +610,13 @@ static void
 save_hist_and_or_cfp(struct statisticsparams *p)
 {
   char *suf, *contents;
-  gal_data_t *bins, *hist, *cfp=NULL;
-
+  gal_data_t *bins, *hist, *cfp=NULL, *range=NULL;
 
   /* Set the bins and make the histogram, this is necessary for both the
      histogram and CFP (recall that the CFP is built from the
      histogram). */
-  bins=gal_statistics_regular_bins(p->input, NULL, p->numbins,
+  range=set_bin_range_params(p);
+  bins=gal_statistics_regular_bins(p->input, range, p->numbins,
                                    p->onebinstart);
   hist=gal_statistics_histogram(p->input, bins, p->normalize, p->maxbinone);
 
@@ -636,6 +660,10 @@ save_hist_and_or_cfp(struct statisticsparams *p)
 
   /* Set the output file name. */
   write_output_table(p, bins, suf, contents);
+
+
+  /* Clean up. */
+  gal_data_free(range);
 }
 
 
@@ -770,7 +798,7 @@ print_basics(struct statisticsparams *p)
   int namewidth=40;
   float mirrdist=1.5;
   double mean, std, *d;
-  gal_data_t *tmp, *bins, *hist;
+  gal_data_t *tmp, *bins, *hist, *range=NULL;
 
   /* Define the input dataset. */
   print_input_info(p);
@@ -830,14 +858,16 @@ print_basics(struct statisticsparams *p)
      range of the histogram. In that case, we want to print the histogram
      information. */
   printf("-------");
+  range=set_bin_range_params(p);
   p->asciiheight = p->asciiheight ? p->asciiheight : 10;
   p->numasciibins = p->numasciibins ? p->numasciibins : 70;
-  bins=gal_statistics_regular_bins(p->input, NULL, p->numasciibins, NAN);
+  bins=gal_statistics_regular_bins(p->input, range, p->numasciibins, NAN);
   hist=gal_statistics_histogram(p->input, bins, 0, 0);
   if(p->refcol==NULL) printf("\nHistogram:\n");
   print_ascii_plot(p, hist, bins, 1, p->refcol ? 1 : 0);
   gal_data_free(bins);
   gal_data_free(hist);
+  gal_data_free(range);
 }
 
 
diff --git a/bin/statistics/ui.c b/bin/statistics/ui.c
index 4c4b652..2e1d57f 100644
--- a/bin/statistics/ui.c
+++ b/bin/statistics/ui.c
@@ -765,11 +765,12 @@ ui_read_columns(struct statisticsparams *p)
 
       /* Print an error if there are too many columns: */
       if(toomanycols)
-        gal_tableintern_error_col_selection(p->inputname, p->cp.hdu, "too many 
"
-                                            "columns were selected by the "
-                                            "given values to the `--column' "
-                                            "and/or `--refcol' options. Only "
-                                            "one is acceptable for each.");
+        gal_tableintern_error_col_selection(p->inputname, p->cp.hdu, "too "
+                                            "many columns were selected by "
+                                            "the given values to the "
+                                            "`--column' and/or `--refcol' "
+                                            "options. Only one is "
+                                            "acceptable for each.");
     }
 
   /* Clean up. */
diff --git a/bin/statistics/ui.h b/bin/statistics/ui.h
index 3e96f5b..e8d4bef 100644
--- a/bin/statistics/ui.h
+++ b/bin/statistics/ui.h
@@ -87,6 +87,7 @@ enum option_keys_enum
   UI_KEY_NUMASCIIBINS,
   UI_KEY_ASCIIHEIGHT,
   UI_KEY_LOWERBIN,
+  UI_KEY_MANUALBINRANGE,
   UI_KEY_ONEBINSTART,
   UI_KEY_MAXBINONE,
   UI_KEY_KHDU,
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index b2adc79..c0b76b6 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -13026,9 +13026,9 @@ dataset.
 
 @cindex AWK
 @cindex GNU AWK
-The group of options below can used to get a single value measurement of
-the whole dataset. They will print only the requested value as one field in
-a line/row, like the @option{--mean}, @option{--median} options. These
+The group of options below can be used to get single value measurement(s)
+of the whole dataset. They will print only the requested value as one field
+in a line/row, like the @option{--mean}, @option{--median} options. These
 options can be called any number of times and in any order. The outputs of
 all such options will be printed on one line following each other (with a
 space character between them). This feature makes these options very useful
@@ -13213,9 +13213,10 @@ table. The first column is the value at the center of 
the bin and the
 second is the number of points in that bin. If the @option{--cumulative}
 option is also called with this option in a run, then the table will have
 three columns (the third is the cumulative frequency plot). Through the
-@option{--numbins} and @option{--lowerbin} you can modify the first column
-values and with @option{--normalize} and @option{--maxbinone} you can
-modify the second columns. See below for the description of each.
+@option{--numbins}, @option{--onebinstart}, or @option{--manualbinrange},
+you can modify the first column values and with @option{--normalize} and
+@option{--maxbinone} you can modify the second columns. See below for the
+description of each.
 
 By default (when no @option{--output} is specified) a plain text table will
 be created, see @ref{Gnuastro text table format}. If a FITS name is
@@ -13303,20 +13304,41 @@ can be very useful.
 @item --onebinstart=FLT
 Make sure that one bin starts with the value to this option. In practice,
 this will shift the bins used to find the histogram and cumulative
-frequency plot such that one bin's lower interval becomes this value. For
-example when the histogram range includes negative and positive values and
-zero has a special significance in your analysis, then zero will be
-somewhere in one bin and will mix counts of positive and negative. By
-setting @option{--onebinstart=0}, you can make sure that the viewers of the
-histogram will not be confused without doing the math of setting a range
-and number of bins.
+frequency plot such that one bin's lower interval becomes this value.
+
+For example when a histogram range includes negative and positive values
+and zero has a special significance in your analysis, then zero might fall
+somewhere in one bin. As a result that bin will have counts of positive and
+negative. By setting @option{--onebinstart=0}, you can make sure that one
+bin will only count negative values in the vicinity of zero and the next
+bin will only count positive ones in that vicinity.
 
 @cindex NaN
 Note that by default, the first row of the histogram and cumulative
 frequency plot show the central values of each bin. So in the example above
 you will not see the 0.000 in the first column, you will see two symmetric
-values. If the value is not within the usable input range, this option will
-be ignored.
+values.
+
+If the value is not within the usable input range, this option will be
+ignored. When it is, this option is the last operation before the bins are
+finalized, therefore it has a higher priority than options like
+@option{--manualbinrange}.
+
+@item --manualbinrange
+Use the values given to the @option{--greaterequal} and @option{--lessthan}
+to define the range of all bin-based calculations like the histogram. This
+option itself doesn't take any value, but just tells the program to use the
+values of those two options instead of the minimum and maximum values of a
+plot. If any of the two options are not given, then the minimum or maximum
+will be used respectively. Therefore, if none of them are called calling
+this option is redundant.
+
+The @option{--onebinstart} option has a higher priority than this option.
+In other words, @option{--onebinstart} takes effect after the range has
+been finalized and the initial bins have been defined, therefore it has the
+power to (possibly) shift the bins. If you want to manually set the range
+of the bins @emph{and} have one bin on a special value, it is thus better
+to avoid @option{--onebinstart}.
 
 @end table
 
@@ -21446,14 +21468,15 @@ The FITS format is the most common format to store 
data (images and tables)
 in astronomy. The CFITSIO library already provides a very good low-level
 collection of functions for manipulating FITS data. The low-level nature of
 CFITSIO is defined for versatility and portability. As a result, even a
-simple a basic operation, like reading an image or table column into
+simple and basic operation, like reading an image or table column into
 memory, will require a special sequence of CFITSIO function calls which can
-be inconvenient and buggy to manage in separate locations. Therefore
-Gnuastro library provides wrappers for CFITSIO functions to make it much
-easier to read/write/modify FITS file data, header keywords and
-extensions. Hence, if you feel these functions don't exactly do what you
-want, we strongly recommend reading the CFITSIO manual to use its great
-features directly.
+be inconvenient and buggy to manage in separate locations. To ease this
+process, Gnuastro's library provides wrappers for CFITSIO functions. With
+these, it much easier to read, write, or modify FITS file data, header
+keywords and extensions. Hence, if you feel these functions don't exactly
+do what you want, we strongly recommend reading the CFITSIO manual to use
+its great features directly (afterwards, send us your wrappers so we can
+include it here for others to benefit also).
 
 All the functions and macros introduced in this section are declared in
 @file{gnuastro/fits.h}.  When you include this header, you are also