[gnuastro-commits] master 0ab1c352: Book: added example for Query's --overlapwith optimization

[Mohammad Akhlaghi]

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

    Book: added example for Query's --overlapwith optimization
    
    Until now, there was no example to guide the user on how to only keep
    sources that we actually have data for in the '--overlapwith' option of
    Query. Also, while reviewing some of the code, I noticed some parts of the
    table program had lines longer than 75 characters and there was a wrongly
    placed set of empty lines at the start of 'type.h'.
    
    With this commit, a complete set of commands have been added to demonstrate
    how to limit the output of Query's '--overlapwith' to those that are within
    the given input image. Both the stylistic issues have also been addressed
    with this commit.
    
    This issue was raised by Raul Infante-Sainz.
    
    This addresses the issue raised in bug #66867.
---
 NEWS                |  5 +++++
 bin/table/table.c   | 18 +++++++++--------
 bin/table/ui.c      | 58 +++++++++++++++++++++++++++--------------------------
 doc/gnuastro.texi   | 26 ++++++++++++++++++++++++
 lib/gnuastro/type.h | 21 -------------------
 5 files changed, 71 insertions(+), 57 deletions(-)

diff --git a/NEWS b/NEWS
index 0743037e..d27ec55a 100644
--- a/NEWS
+++ b/NEWS
@@ -165,6 +165,11 @@ See the end of the file for license conditions.
   - bug #66693: MakeProfile crashes with segmentation fault with when
     --customimg is given and the oversampling factor is larger than 1.
 
+  - bug #66867: Example added in book to show how to remove outputs of
+    Query's '--overlapwith' option when sources outside of the image are
+    also retrieved (for example due to a rotated image or the server not
+    accounting for spherical distortion). Reported by Raul Infante-Sainz.
+
   - bug #66869: Crop segmentation fault leading to unpredictable return
     values. Reported by Raul Infante-Sainz.
 
diff --git a/bin/table/table.c b/bin/table/table.c
index 0cb9b71e..c8d6654f 100644
--- a/bin/table/table.c
+++ b/bin/table/table.c
@@ -346,7 +346,8 @@ table_selection_equal_or_notequal(struct tableparams *p, 
gal_data_t *col,
           /* Read the stored string as a float64. */
           if( gal_type_from_string(&varr, strarr[i], GAL_TYPE_FLOAT64) )
             {
-              fprintf(stderr, "%s couldn't be read as a number.\n", strarr[i]);
+              fprintf(stderr, "%s couldn't be read as a number.\n",
+                      strarr[i]);
               exit(EXIT_FAILURE);
             }
 
@@ -427,12 +428,13 @@ table_select_by_value(struct tableparams *p)
       for(col=p->table;col!=NULL;col=col->next)
         if(tmp->col->dsize[0]!=col->dsize[0])
           error(EXIT_FAILURE, 0, "the number of rows in the column given "
-                "for selection by value (for example '--range' or '--equal') "
-                "is not the same as the number of rows in the table when "
-                "they are applied. This may happen due to operators like "
-                "'--transpose'. In such cases, you probably want row-based "
-                "operators to have precedence over column-based operators. "
-                "If this is your case, please call '--rowfirst'");
+                "for selection by value (for example '--range' or "
+                "'--equal') is not the same as the number of rows in the "
+                "table when they are applied. This may happen due to "
+                "operators like '--transpose'. In such cases, you "
+                "probably want row-based operators to have precedence "
+                "over column-based operators. If this is your case, "
+                "please call '--rowfirst'");
 
       /* Do the specific type of selection. */
       switch(tmp->type)
@@ -445,7 +447,7 @@ table_select_by_value(struct tableparams *p)
         case SELECT_TYPE_INPOLYGON:
         case SELECT_TYPE_OUTPOLYGON:
           addmask=table_selection_polygon(p, tmp->col, tmp->next->col,
-                                          tmp->type==SELECT_TYPE_INPOLYGON);
+                                      tmp->type==SELECT_TYPE_INPOLYGON);
           tmp=tmp->next;
           break;
 
diff --git a/bin/table/ui.c b/bin/table/ui.c
index 502f83b9..eb611710 100644
--- a/bin/table/ui.c
+++ b/bin/table/ui.c
@@ -245,15 +245,15 @@ ui_check_only_options(struct tableparams *p)
       {
         /* Range needs two input numbers. */
         if(tmp->size!=2)
-          error(EXIT_FAILURE, 0, "two values (separated by ':' or ',') are "
-                "necessary for '--range' in this format: "
+          error(EXIT_FAILURE, 0, "two values (separated by ':' or ',') "
+                "are necessary for '--range' in this format: "
                 "'--range=COLUMN,min:max'");
 
         /* The first must be smaller than the second. */
         darr=tmp->array;
         if( darr[0] > darr[1] )
-          error(EXIT_FAILURE, 0, "first value (%g) given to '--range' must "
-                "be smaller than the second (%g)", darr[0], darr[1]);
+          error(EXIT_FAILURE, 0, "first value (%g) given to '--range' "
+                "must be smaller than the second (%g)", darr[0], darr[1]);
       }
 
   /* Basic checks for '--inpolygon' or '--outpolygon'. */
@@ -322,10 +322,10 @@ ui_check_only_options(struct tableparams *p)
       if( darr[0] > darr[1] )
         error(EXIT_FAILURE, 0, "the first value to '--rowrange' (%g) is "
               "larger than the second (%g). This option's values defines "
-              "a row-counter interval, assuming the first value is the top "
-              "of the desired interval (smaller row counter) and the "
-              "second value is the bottom of the desired interval (larger "
-              "row counter)", darr[0], darr[1]);
+              "a row-counter interval, assuming the first value is the "
+              "top of the desired interval (smaller row counter) and the "
+              "second value is the bottom of the desired interval "
+              "(larger row counter)", darr[0], darr[1]);
     }
 
   /* If '--colmetadata' is given, make sure none of the given options have
@@ -333,9 +333,10 @@ ui_check_only_options(struct tableparams *p)
   if(p->colmetadata)
     for(tmp=p->colmetadata;tmp!=NULL;tmp=tmp->next)
       if(tmp->size>3)
-        error(EXIT_FAILURE, 0, "at most three values can be given to each "
-              "call of '--colmetadata' ('-m') after the original columns "
-              "name or number. But %zu strings have been given", tmp->size);
+        error(EXIT_FAILURE, 0, "at most three values can be given to "
+              "each call of '--colmetadata' ('-m') after the original "
+              "columns name or number. But %zu strings have been given",
+              tmp->size);
 
   /* If '--catcolumns' is given (to only concatenate certain columns), but
      no file has been given for appending from (to '--catcolumnfile'), then
@@ -388,11 +389,11 @@ ui_check_options_and_arguments(struct tableparams *p)
   if(p->filename)
     {
       if( gal_fits_file_recognized(p->filename) && p->cp.hdu==NULL )
-        error(EXIT_FAILURE, 0, "no HDU specified. When the input is a FITS "
-              "file, a HDU must also be specified, you can use the '--hdu' "
-              "('-h') option and give it the HDU number (starting from "
-              "zero), extension name, or anything acceptable by CFITSIO");
-
+        error(EXIT_FAILURE, 0, "no HDU specified. When the input is a "
+              "FITS file, a HDU must also be specified, you can use the "
+              "'--hdu' ('-h') option and give it the HDU number "
+              "(starting from zero), extension name, or anything "
+              "acceptable by CFITSIO");
     }
 }
 
@@ -545,8 +546,8 @@ ui_colpack_add_new_to_end(struct column_pack **list)
   errno=0;
   node=malloc(sizeof *node);
   if(node==NULL)
-    error(EXIT_FAILURE, errno, "%s: couldn't allocate new node (%zu bytes)",
-          __func__, sizeof *node);
+    error(EXIT_FAILURE, errno, "%s: couldn't allocate new node (%zu "
+          "bytes)", __func__, sizeof *node);
 
   /* Initialize its elements. */
   node->next=NULL;
@@ -739,7 +740,7 @@ ui_columns_prepare(struct tableparams *p, gal_list_str_t 
*lines)
   struct column_pack *node, *last;
   gal_list_str_t *tmp, *colstoread=NULL;
   size_t i, totcalled=0, numcols, numrows, numsimple;
-  char *c, *str, countstr[11]; /* an un-signed 32-bit integer takes 10 chars */
+  char *c, *str, countstr[11]; /* un-signed 32-bit int takes 10 chars */
 
   /* Go over the list of requested columns from the main input. */
   for(tmp=p->columns;tmp!=NULL;tmp=tmp->next)
@@ -782,8 +783,8 @@ ui_columns_prepare(struct tableparams *p, gal_list_str_t 
*lines)
               if(numcols>999)
                 error(EXIT_FAILURE, 0, "the '$_all' feature is currently "
                       "only implemented for tables with fewer than 999 "
-                      "columns. Please contact us at %s to add more columns",
-                      PACKAGE_BUGREPORT);
+                      "columns. Please contact us at %s to add more "
+                      "columns", PACKAGE_BUGREPORT);
 
               /* Repeat the arithmetic command for each column. */
               for(i=1;i<=numcols;++i)
@@ -791,8 +792,8 @@ ui_columns_prepare(struct tableparams *p, gal_list_str_t 
*lines)
                   gal_checkset_allocate_copy(str, &tstr);
                   sprintf(tstr+arithallind+1, "%-3zu", i);
                   tstr[arithallind+4]=' ';
-                  ui_columns_prepare_arith(p, colinfo, &colstoread, &totcalled,
-                                           numcols, tstr);
+                  ui_columns_prepare_arith(p, colinfo, &colstoread,
+                                           &totcalled, numcols, tstr);
                   free(tstr);
                 }
             }
@@ -870,7 +871,8 @@ ui_columns_prepare(struct tableparams *p, gal_list_str_t 
*lines)
                   {
                     printf("\tOperator: %d\n", atmp->operator);
                     if(atmp->name_def)
-                      printf("\t\t(Name definition: %s)\n", atmp->name_def);
+                      printf("\t\t(Name definition: %s)\n",
+                             atmp->name_def);
                   }
                 else if(atmp->constant) printf("\tConstant number\n");
                 else if(atmp->name_use) printf("\tName usage: %s\n",
@@ -1095,10 +1097,10 @@ ui_check_select_sort_before(struct tableparams *p, 
gal_list_str_t *lines,
     for(i=0;i<*nselect;++i)
       if(selectind[i]!=GAL_BLANK_SIZE_T && selectind[i]>=numcols)
         error(EXIT_FAILURE, 0, "%s has %zu columns, less than the column "
-              "number given to  '--range', '--inpolygon', '--outpolygon', "
-              "'--equal', or '--sort' (%zu)",
-              gal_fits_name_save_as_string(p->filename, p->cp.hdu), numcols,
-              selectind[i]);
+              "number given to  '--range', '--inpolygon', "
+              "'--outpolygon', '--equal', or '--sort' (%zu)",
+              gal_fits_name_save_as_string(p->filename, p->cp.hdu),
+              numcols, selectind[i]);
 
 
   /* If any of the columns isn't specified by an index, go over the table
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index db4dd709..4d96aa56 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -20339,9 +20339,35 @@ Based on the image's WCS and pixel size, the sky 
coverage of the image is estima
 Hence this option cannot be used with @code{--center}, @code{--width} or 
@code{--radius}.
 Also, since it internally generates the query, it cannot be used with 
@code{--query}.
 
+If the image is rotated in relation to RA/DEC, or the image has a large 
coverage on the sky, or it has WCS distortions (that the server can't know 
about), the retrieved catalog may not overlap with the image, or correspond to 
a larger area in the sky.
+To be sure that the final catalog you use actually has sources within the 
image, use the commands below (the last two commands are just for validation).
+
+@example
+$ astquery gaia --dataset=dr3 --overlapwith=image.fits \
+           -cra,dec --output=gaia.fits
+
+$ astcrop image.fits --catalog=gaia.fits --coordcol=ra \
+          --coordcol=dec --mode=wcs --width=1 \
+          --widthinpix --log --oneelemstdout --quiet \
+          --output=crop-log.fits > /dev/null
+
+$ asttable gaia.fits --catcolumnfile=crop-log.fits \
+           --catcolumns=NUM_INPUTS -O \
+           | asttable --equal=NUM_INPUTS,1 \
+                      --output=gaia-in-image.fits
+
+$ astscript-ds9-region gaia-in-image.fits -cra,dec \
+                       --radius=5 --width=5 \
+                       --output=stars-in.reg
+
+$ astscript-fits-view image.fits --region=stars-in.reg
+@end example
+
 Note that if the image has WCS distortions and the reference point for the WCS 
is not within the image, the WCS will not be well-defined.
 Therefore the resulting catalog may not overlap, or correspond to a 
larger/small area in the sky.
 
+
+
 @item -C FLT,FLT
 @itemx --center=FLT,FLT
 The spatial center position (mostly RA and Dec) to use for the automatically 
generated query (not compatible with @option{--query}).
diff --git a/lib/gnuastro/type.h b/lib/gnuastro/type.h
index ba7f0079..20b78571 100644
--- a/lib/gnuastro/type.h
+++ b/lib/gnuastro/type.h
@@ -1,24 +1,3 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
 /*********************************************************************
 Type -- Type information and basic operations.
 This is part of GNU Astronomy Utilities (Gnuastro) package.