[gnuastro-commits] master b7e456f: Query: new --width option to automatically select box region

[Mohammad Akhlaghi]

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

    Query: new --width option to automatically select box region
    
    In the last commit, the new 'astquery' program was added, but it could only
    select the region around the center with a radius (using '--radius'). With
    this commit, it also accepts a new '--width' option, allowing the users to
    select rows with a box centered on the given coordinate.
    
    Also, to be more similar to programs like 'asttable' and 'aststatistics',
    the short version of the '--column' option is now set to '-c' (previously
    it was '-C'), and the short version of '--center' has been changed to '-C'
    (was previously '-c').
    
    The correction of option names was suggested by Samane Raji, and Sabastian
    is now working with me to get Gnuastro installed in Anaconda.
---
 bin/query/args.h             | 19 ++++++++-
 bin/query/main.h             |  3 +-
 bin/query/query.c            | 36 ++++++++++++-----
 bin/query/ui.c               | 43 +++++++++++++++++---
 bin/query/ui.h               |  4 +-
 configure.ac                 | 16 ++++++++
 doc/announce-acknowledge.txt |  3 +-
 doc/gnuastro.texi            | 94 +++++++++++++++++++++++++++-----------------
 8 files changed, 160 insertions(+), 58 deletions(-)

diff --git a/bin/query/args.h b/bin/query/args.h
index 7eebcd1..cda9718 100644
--- a/bin/query/args.h
+++ b/bin/query/args.h
@@ -80,7 +80,7 @@ struct argp_option program_options[] =
     /* Query by center. */
     {
       0, 0, 0, 0,
-      "Calculate query by center:",
+      "Generate query by center (not compatible with '--query'):",
       UI_GROUP_BYCENTER,
     },
     {
@@ -105,10 +105,25 @@ struct argp_option program_options[] =
       "Radius around center to select targets.",
       UI_GROUP_BYCENTER,
       &p->radius,
-      GAL_TYPE_FLOAT64,
+      GAL_TYPE_STRING,
       GAL_OPTIONS_RANGE_ANY,
       GAL_OPTIONS_NOT_MANDATORY,
       GAL_OPTIONS_NOT_SET,
+      gal_options_parse_csv_float64
+    },
+    {
+      "width",
+      UI_KEY_WIDTH,
+      "FLT[,FLT]",
+      0,
+      "Width of box to select targets.",
+      UI_GROUP_BYCENTER,
+      &p->width,
+      GAL_TYPE_STRING,
+      GAL_OPTIONS_RANGE_ANY,
+      GAL_OPTIONS_NOT_MANDATORY,
+      GAL_OPTIONS_NOT_SET,
+      gal_options_parse_csv_float64
     },
     {
       "column",
diff --git a/bin/query/main.h b/bin/query/main.h
index 319212e..f1e3942 100644
--- a/bin/query/main.h
+++ b/bin/query/main.h
@@ -47,7 +47,8 @@ struct queryparams
   int                 database;  /* ID of database to use.             */
   char             *datasetstr;  /* ID of dataset in database to use.  */
   gal_data_t           *center;  /* Center position of query.          */
-  double                radius;  /* Radius around center.              */
+  gal_data_t           *radius;  /* Radius around center.              */
+  gal_data_t            *width;  /* Width of box around center.        */
   char                  *query;  /* Raw query string.                  */
   gal_list_str_t      *columns;  /* Columns to extract from database.  */
 
diff --git a/bin/query/query.c b/bin/query/query.c
index 819f3df..86d0d7f 100644
--- a/bin/query/query.c
+++ b/bin/query/query.c
@@ -90,14 +90,14 @@ query_gaia_sanitycheck(struct queryparams *p)
   if(p->center)
     {
       /* Make sure the radius is given, and that it isn't zero. */
-      if( isnan(p->radius) )
-        error(EXIT_FAILURE, 0, "the '--radius' ('-r') option is necessary "
-              "with the '--center' ('-c') option");
+      if( p->radius==NULL && p->width==NULL)
+        error(EXIT_FAILURE, 0, "the '--radius' ('-r') or '--width' ('-w') "
+              "options are necessary with the '--center' ('-C') option");
 
       /* Make sure a dataset is also given. */
       if( p->datasetstr==NULL)
         error(EXIT_FAILURE, 0, "the '--dataset' ('-s') option is necessary "
-              "with the '--center' ('-c') option");
+              "with the '--center' ('-C') option");
 
 
       /* Use simpler names for the commonly used datasets. */
@@ -131,7 +131,8 @@ query_gaia_sanitycheck(struct queryparams *p)
 void
 query_gaia(struct queryparams *p)
 {
-  double *center;
+  char *regionstr;
+  double *center, *darray;
   char *command, *columns, allcols[]="*", *querystr;
 
   /* Make sure everything is fine. */
@@ -153,16 +154,32 @@ query_gaia(struct queryparams *p)
       */
       columns = p->columns ? query_strlist_to_str(p->columns) : allcols;
 
+      /* Write the region. */
+      if(p->radius)
+        {
+          darray=p->radius->array;
+          if( asprintf(&regionstr, "CIRCLE('ICRS', %.8f, %.8f, %g) )",
+                       center[0], center[1], darray[0])<0 )
+            error(EXIT_FAILURE, 0, "%s: asprintf allocation ('regionstr')", 
__func__);
+        }
+      else if(p->width)
+        {
+          darray=p->width->array;
+          if( asprintf( &regionstr, "BOX('ICRS', %.8f, %.8f, %.8f, %.8f) )",
+                        center[0], center[1], darray[0],
+                        p->width->size==1 ? darray[0] : darray[1] )<0 )
+            error(EXIT_FAILURE, 0, "%s: asprintf allocation ('regionstr')", 
__func__);
+        }
+
       /* Write the automatically generated query string. */
       if( asprintf(&querystr,  "SELECT %s "
                    "FROM %s "
-                   "WHERE 1=CONTAINS( "
-                   "POINT('ICRS', ra, dec), "
-                   "CIRCLE('ICRS', %.8f, %.8f, %g) )", columns,
-                   p->datasetstr, center[0], center[1], p->radius)<0 )
+                   "WHERE 1=CONTAINS( POINT('ICRS', ra, dec), %s )", columns,
+                   p->datasetstr, regionstr)<0 )
         error(EXIT_FAILURE, 0, "%s: asprintf allocation ('querystr')", 
__func__);
 
       /* Clean up. */
+      free(regionstr);
       if(columns!=allcols) free(columns);
     }
 
@@ -178,7 +195,6 @@ query_gaia(struct queryparams *p)
   /* Print the calling command for the user to know. */
   if(p->cp.quiet==0)
     printf("Running: %s\n", command);
-  //exit(0);
 
   /* Run the command. */
   if(system(command))
diff --git a/bin/query/ui.c b/bin/query/ui.c
index fc050ce..653a909 100644
--- a/bin/query/ui.c
+++ b/bin/query/ui.c
@@ -110,9 +110,6 @@ ui_initialize_options(struct queryparams *p,
   cp->program_authors    = PROGRAM_AUTHORS;
   cp->coptions           = gal_commonopts_options;
 
-  /* Program-specific initializations. */
-  p->radius              = NAN;
-
   /* Modify common options. */
   for(i=0; !gal_options_is_last(&cp->coptions[i]); ++i)
     {
@@ -127,6 +124,7 @@ ui_initialize_options(struct queryparams *p,
         case GAL_OPTIONS_KEY_IGNORECASE:
         case GAL_OPTIONS_KEY_NUMTHREADS:
         case GAL_OPTIONS_KEY_MINMAPSIZE:
+        case GAL_OPTIONS_KEY_TABLEFORMAT:
         case GAL_OPTIONS_KEY_STDINTIMEOUT:
         case GAL_OPTIONS_KEY_KEEPINPUTDIR:
           cp->coptions[i].flags=OPTION_HIDDEN;
@@ -260,6 +258,8 @@ ui_parse_database(struct argp_option *option, char *arg,
 static void
 ui_read_check_only_options(struct queryparams *p)
 {
+  size_t i;
+
   /* See if database has been specified. */
   if(p->database==0)
     error(EXIT_FAILURE, 0, "no input dataset.\n\n"
@@ -272,9 +272,40 @@ ui_read_check_only_options(struct queryparams *p)
     error(EXIT_FAILURE, 0, "the '--center' and '--query' options cannot be "
           "called together (they are parallel ways to define a query)");
 
-  /* If radius is given, it should be positive. */
-  if( !isnan(p->radius) && p->radius<0 )
-    error(EXIT_FAILURE, 0, "the '--radius' option value cannot be negative");
+  /* The radius and width cannot be called together. */
+  if(p->radius && p->width)
+    error(EXIT_FAILURE, 0, "the '--radius' and '--width' options cannot be "
+          "called together");
+
+  /* If radius is given, it should be one value and positive. */
+  if(p->radius)
+    {
+      if(p->radius->size>1)
+        error(EXIT_FAILURE, 0, "only one value can be given to '--radius' "
+              "('-r') option");
+
+      if( ((double *)(p->radius->array))[0]<0 )
+        error(EXIT_FAILURE, 0, "the '--radius' option value cannot be 
negative");
+    }
+
+  /* Sanity checks on  width (if we are in the center-mode). */
+  if(p->width && p->center)
+    {
+      /* Width should have the same number of elements as the center
+         coordinates */
+      if( p->width->size > 1 && p->width->size != p->center->size )
+        error(EXIT_FAILURE, 0, "'--width' should either have a single "
+              "value (used for all dimensions), or one value for each "
+              "dimension. However, you have provided %zu coordinate "
+              "values, and %zu width values", p->center->size,
+              p->width->size);
+
+      /* All values must be positive. */
+      for(i=0;i<p->width->size;++i)
+        if( ((double *)(p->width->array))[i]<0 )
+          error(EXIT_FAILURE, 0, "the '--width' option value(s) cannot "
+                "be negative");
+    }
 
   /* If an output name isn't given, set one. */
   if(p->cp.output)
diff --git a/bin/query/ui.h b/bin/query/ui.h
index d8e3ce7..de26fcf 100644
--- a/bin/query/ui.h
+++ b/bin/query/ui.h
@@ -51,9 +51,9 @@ enum option_keys_enum
   UI_KEY_DATABASE        = 'd',
   UI_KEY_QUERY           = 'Q',
   UI_KEY_DATASET         = 's',
-  UI_KEY_CENTER          = 'c',
+  UI_KEY_CENTER          = 'C',
   UI_KEY_RADIUS          = 'r',
-  UI_KEY_COLUMN          = 'C',
+  UI_KEY_COLUMN          = 'c',
   UI_KEY_WIDTH           = 'w',
 
   /* Only with long version (start with a value 1000, the rest will be set
diff --git a/configure.ac b/configure.ac
index a7c6a00..c38be40 100644
--- a/configure.ac
+++ b/configure.ac
@@ -487,6 +487,10 @@ AC_SUBST(HAVE_PTHREAD_BARRIER, [$has_pthread_barrier])
 AC_CHECK_PROG(has_help2man, help2man, [yes], [no])
 AM_CONDITIONAL([COND_HASHELP2MAN], [test "x$has_help2man" = "xyes"])
 
+# cURL:
+AC_CHECK_PROG(has_curl, curl, [yes], [no])
+AS_IF([test "x$has_curl" = "xno"], [anywarnings=yes])
+
 # Check the libtool executable on the system. Note that Gnuastro also ships
 # with a version of Libtool. We don't want Gnuastro's Libtool, here we want
 # to see if the system has libtool independent of Gnuastro so BuildProgram
@@ -632,6 +636,8 @@ AS_IF([test "x$missing_mandatory" = "xyes"],
                       [ AS_ECHO([" - Missing Libtiff (TIFF files): 
http://libtiff.maptools.org";]) ])
                 AS_IF([test "x$has_libgit2" = "x0"],
                       [ AS_ECHO([" - Missing Libgit2: https://libgit2.org";])   
                   ])
+                AS_IF([test "x$has_curl" = "x0"],
+                      [ AS_ECHO([" - Missing cURL: https://curl.haxx.se";])     
                   ])
                 AS_IF([test "x$usable_libtool" = "xno"],
                       [ AS_ECHO([" - Unusable GNU Libtool: 
https://www.gnu.org/s/libtool";])
                         AS_IF([test "x$has_gnulibtool" = "xyes"],
@@ -1078,6 +1084,16 @@ AS_IF([test x$enable_guide_message = xyes],
                AS_ECHO(["    with an EPS output which you can convert to PDF 
by other means."])
                AS_ECHO([]) ])
 
+        AS_IF([test "x$has_curl" = "xno"],
+              [dependency_notice=yes
+               AS_ECHO(["  - cURL (https://curl.haxx.se) with the executable 
name 'curl' was not"])
+               AS_ECHO(["    found in your PATH environment variable. 
'astquery' uses it to access"])
+               AS_ECHO(["    remote databases at run-time. So not having 
'curl' won't affect this"])
+               AS_ECHO(["    build of Gnuastro, you can continue for now. But 
to use 'astquery',"])
+               AS_ECHO(["    don't forget to install cURL later (before using 
'astquery' for the"])
+               AS_ECHO(["    first time)."])
+               AS_ECHO([]) ])
+
         # Notice for obtaining the optional dependencies using a package
         # manager.
         AS_IF([test "x$dependency_notice" = "xyes"],
diff --git a/doc/announce-acknowledge.txt b/doc/announce-acknowledge.txt
index eb5d153..eba44ad 100644
--- a/doc/announce-acknowledge.txt
+++ b/doc/announce-acknowledge.txt
@@ -1,9 +1,10 @@
 Alphabetically ordered list to acknowledge in the next release.
 
+Sebastian Luna Valero
+Samane Raji
 Sachin Kumar Singh
 
 
-
 Copyright (C) 2015-2020 Free Software Foundation, Inc.
 
 Permission is granted to copy, distribute and/or modify this document under
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index d017516..7548d3b 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -4597,14 +4597,19 @@ $ sudo make install
 @node Optional dependencies, Bootstrapping dependencies, Mandatory 
dependencies, Dependencies
 @subsection Optional dependencies
 
-The libraries listed here are only used for very specific applications, 
therefore if you don't want these operations, Gnuastro will be built and 
installed without them and you don't have to have the dependencies.
+The libraries listed here are only used for very specific applications, 
therefore they are optional and Gnuastro can be built without them (with only 
those specific features disabled).
+Since these are pretty low-level tools, they are not too hard to install from 
source, but you can also use your operating system's package manager to easily 
install all of them.
+For more, see @ref{Dependencies from package managers}.
 
 @cindex GPL Ghostscript
-If the @command{./configure} script can't find these requirements, it will 
warn you in the end that they are not present and notify you of the 
operation(s) you can't do due to not having them.
-If the output you request from a program requires a missing library, that 
program is going to warn you and abort.
-In the case of program dependencies (like GPL GhostScript), if you install 
them at a later time, the program will run.
-This is because if required libraries are not present at build time, the 
executables cannot be built, but an executable is called by the built program 
at run time so if it becomes available, it will be used.
-If you do install an optional library later, you will have to rebuild Gnuastro 
and reinstall it for it to take effect.
+If the @command{./configure} script can't find any of these optional 
dependencies, it will notify you of the operation(s) you can't do due to not 
having them.
+If you continue the build and request an operation that uses a missing 
library, Gnuastro's programs will warn that the optional library was missing at 
build-time and abort.
+Since Gnuastro was built without that library, installing the library 
afterwards won't help.
+The only way is to re-build Gnuastro from scratch (after the library has been 
installed).
+However, for program dependencies (like cURL or GhostScript) things are 
easier: you can install them after building Gnuastro also.
+This is because libraries are used to build the internal structure of 
Gnuastro's executables.
+However, a program dependency is called by Gnuastro's programs at run-time and 
has no effect on their internal structure.
+So if a dependency program becomes available later, it will be used next time 
it is requested.
 
 @table @asis
 
@@ -4651,14 +4656,16 @@ libtiff is used by ConvertType and the libraries to 
read TIFF images, see @ref{R
 @url{http://www.simplesystems.org/libtiff/, libtiff} is a very basic library 
that provides tools to read and write TIFF images, most Unix-like operating 
system graphic programs and libraries use it.
 Therefore even if you don't have it installed, it must be easily available in 
your package manager.
 
+@item cURL
+@cindex cURL (downloading tool)
+cURL's executable (@command{curl}) is called by @ref{Query} for submitting 
queries to remote datasets and retrieving the results.
+It isn't necessary for the build of Gnuastro from source (only a warning will 
be printed if it can't be found at configure time), so if you don't have it at 
build-time there is no problem.
+Just be sure to have it when you run @command{astquery}, otherwise you'll get 
an error about not finding @command{curl}.
 
 @item GPL Ghostscript
 @cindex GPL Ghostscript
 GPL Ghostscript's executable (@command{gs}) is called by ConvertType to 
compile a PDF file from a source PostScript file, see @ref{ConvertType}.
 Therefore its headers (and libraries) are not needed.
-With a very high probability you already have it in your GNU/Linux 
distribution.
-Unfortunately it does not follow the standard GNU build style so installing it 
is very hard.
-It is best to rely on your distribution's package managers for this.
 
 @end table
 
@@ -4829,7 +4836,7 @@ This arguably makes Debian-based OSs the largest, and 
most used, class of GNU/Li
 All of them use Debian's Advanced Packaging Tool (APT, for example 
@command{apt-get}) for managing packages.
 @example
 $ sudo apt-get install ghostscript libtool-bin libjpeg-dev  \
-                       libtiff-dev libgit2-dev lzip         \
+                       libtiff-dev libgit2-dev curl lzip    \
                                                             \
                        libgsl0-dev libcfitsio-dev wcslib-dev
 @end example
@@ -4853,9 +4860,9 @@ But since it is free software, many other teams use its 
code to spin-off their o
 Red Hat-based GNU/Linux distributions initially used the ``Yellowdog Updated, 
Modifier'' (YUM) package manager, which has been replaced by ``Dandified yum'' 
(DNF).
 If the latter isn't available on your system, you can use @command{yum} 
instead of @command{dnf} in the command below.
 @example
-$ sudo dnf install ghostscript libtool libjpeg-devel        \
-                   libtiff-devel libgit2-devel lzip         \
-                                                            \
+$ sudo dnf install ghostscript libtool libjpeg-devel     \
+                   libtiff-devel libgit2-devel lzip curl \
+                                                         \
                    gsl-devel cfitsio-devel wcslib-devel
 @end example
 
@@ -4873,9 +4880,9 @@ If not already installed, first obtain Homebrew by 
following the instructions at
 Homebrew manages packages in different `taps'.
 To install WCSLIB (discussed in @ref{Mandatory dependencies}) via Homebrew you 
will need to @command{tap} into @command{brewsci/science} first (the tap may 
change in the future, but can be found by calling @command{brew search wcslib}).
 @example
-$ brew install ghostscript libtool libjpeg libtiff          \
-               libgit2 lzip                                 \
-                                                            \
+$ brew install ghostscript libtool libjpeg libtiff \
+               libgit2 curl lzip                   \
+                                                   \
                gsl cfitsio
 $ brew tap brewsci/science
 $ brew install wcslib
@@ -4888,9 +4895,9 @@ $ brew install wcslib
 It ``focuses on elegance, code correctness, minimalism and simplicity, and 
expects the user to be willing to make some effort to understand the system's 
operation''.
 Arch Linux uses ``Package manager'' (Pacman) to manage its packages/components.
 @example
-$ sudo pacman -S ghostscript libtool libjpeg libtiff        \
-                 libgit2 lzip                               \
-                                                            \
+$ sudo pacman -S ghostscript libtool libjpeg libtiff \
+                 libgit2 curl lzip                   \
+                                                     \
                  gsl cfitsio wcslib
 @end example
 
@@ -4904,10 +4911,11 @@ openSUSE and SLES use @command{zypper} (cli) and YaST 
(GUI) for managing reposit
 packages.
 
 @example
-$ sudo zypper install ghostscript_any libtool pkgconfig    \
-              cfitsio-devel gsl-devel libcurl-devel        \
-              libgit2-devel libjpeg62-devel libtiff-devel  \
-              wcslib-devel
+$ sudo zypper install ghostscript_any libtool pkgconfig   \
+              libcurl-devel libgit2-devel libjpeg62-devel \
+              libtiff-devel curl                          \
+                                                          \
+              gsl-devel cfitsio-devel wcslib-devel
 @end example
 @noindent
 When building Gnuastro, run the configure script with the following 
@code{CPPFLAGS} environment variable:
@@ -18320,19 +18328,24 @@ One line examples:
 
 @example
 ## Import all the columns of all entries in the Gaia DR2 catalog within
-## 0.1 degrees of the given coordinate.
-$ astquery  --database=gaia --dataset=dr2 --output=sub-gaia.fits \
-            --center=113.8729761,31.9027152 --radius=0.1
+## 20 arc-minutes of the given coordinate.
+$ astquery --database=gaia --dataset=dr2 --output=my-gaia.fits \
+           --center=113.8729761,31.9027152 --radius=20/60
 
-## Similar to above, but only import the ID, RA, Dec and G-band
+## Similar to above, but return all objects within a square box of
+## 30 arcminutes (can also be rectangular, see '--width').
+$ astquery --database=gaia --dataset=dr2 --output=my-gaia.fits \
+           --center=113.8729761,31.9027152 --width=30/60
+
+## Similar to first example, but only import the ID, RA, Dec and G-band
 ## magnitude of the sources (not all the columns).
-$ astquery  --database=gaia --dataset=dr2 --output=sub-gaia.fits \
-            --center=113.8729761,31.9027152 --radius=0.1 \
-            --column=source_id,ra,dec,phot_g_mean_mag
+$ astquery --database=gaia --dataset=dr2 --output=my-gaia.fits \
+           --center=113.8729761,31.9027152 --radius=0.1 \
+           --column=source_id,ra,dec,phot_g_mean_mag
 
 ## Use a custom query to extract entries in the Gaia DR2 catalog.
-## The 'XXXX YYYY ZZZZ' can be a query of any size on the command-line.
-$ astquery --database=esa --query="XXXX YYYY ZZZZ" --output=my-gaia.fits
+## The 'XXXX YYYY' can be a query of any size on the command-line.
+$ astquery --database=gaia --query="XXXX YYYY" --output=my-gaia.fits
 @end example
 
 Query doesn't take any input argument, because the main goal is to retreive 
data from external sources.
@@ -18370,16 +18383,25 @@ The query given to this database will be submitted to 
@code{https://gea.esac.esa
 Directly specify the query to be passed onto the database.
 The queries will generally contain space and other meta-characters, so we 
recommend placing the query within quotations.
 
-@item -c FLT,FLT
+@item -C FLT,FLT
 @itemx --center=FLT,FLT
 The center to use for the automatically generated query (not compatible with 
@option{--query}).
 All objects within a certain distance of the requested center position will be 
requested from the dataset.
 The distance can be specified with the @option{--radius} option.
 
 @item -r FLT
-@itemx --radius FLT
+@itemx --radius=FLT
 The radius about the requested center to use for the automatically generated 
query (not compatible with @option{--query}).
-Since the center is usually determined in units of degrees, the radius to 
select sources is also in the same units.
+The radius is in units of degrees, but you can use simple division with this 
option directly on the command-line.
+For example if you want a radius of 20 arc-minutes or 20 arc-seconds, you can 
use @option{--radius=20/60} or @option{--radius=20/3600} respectively (which is 
much more human-friendly than @code{0.3333} or @code{0.005556}).
+
+@item -w FLT[,FLT]
+@itemx --width=FLT[,FLT]
+The square (or rectangle) side length (width) about the requested center to 
use for the automatically generated query (not compatible with 
@option{--query}).
+If only one value is given to @code{--width} the region will be a square, but 
if two values are given, the widths of the query box along each dimension will 
be different.
+The value(s) is(are) in units of degrees, but you can use simple division for 
each value directly on the command-line, see the description of 
@option{--radius} for more on using division.
+
+
 
 @item -s STR
 @itemx --dataset=STR
@@ -18404,7 +18426,7 @@ Below is a list of the simplified names for the 
databases that have them.
 @end itemize
 @end table
 
-@item -C STR
+@item -c STR
 @itemx --column=STR[,STR[,...]]
 The optional column name(s) to retrieve from the dataset in the automatically 
generated query (not compatible with @option{--query}).
 If not given, all the dataset's columns for the selected rows will be used 
(which can be large!).