[gnuastro-commits] master c2761b6 1/3: Book: dealing with time zones in sort-by-night script

[Mohammad Akhlaghi]

branch: master
commit c2761b6610ddaf666a881d769888660c43af54aa
Author: Raul Infante-Sainz <address@hidden>
Commit: Raul Infante-Sainz <address@hidden>

    Book: dealing with time zones in sort-by-night script
    
    With this commit, documentation about how to deal with difference in
    time zones when using `sort-by-night' script has been improved.
    Basically, it is explained how to modify the definition of "nights" when
    clasifying and sorgint images taken from different nights with the help
    of the argument `--hour'.
    
    Since this commit has been done in a Mac OS system laptop, I also
    include `.DS_Store' files to be ignored in `.gitignore'. This files are
    created automatically by `Finder' application and they are irrelevant
    for the git history. From Wikipedia: In the Apple macOS operating
    system, .DS_Store is a file that stores custom attributes of its
    containing folder, such as the position of icons or the choice of a
    background image.
---
 .gitignore                  |  1 +
 bin/script/sort-by-night.in | 19 ++++++++++++-------
 doc/gnuastro.texi           | 15 +++++++++++++++
 3 files changed, 28 insertions(+), 7 deletions(-)

diff --git a/.gitignore b/.gitignore
index 426315e..3205af4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -88,6 +88,7 @@ astmatch
 ltmain.sh
 .dirstamp
 configure
+.DS_Store
 .gnuastro
 astmkprof
 astheader
diff --git a/bin/script/sort-by-night.in b/bin/script/sort-by-night.in
index 31c4d26..949449c 100644
--- a/bin/script/sort-by-night.in
+++ b/bin/script/sort-by-night.in
@@ -58,13 +58,17 @@ Usage: $scriptname [OPTION] FITS-files
 
 This script is part of GNU Astronomy Utilities $version.
 
-This script will look into a HDU/extension for a header keyword in the
-given FITS files and interpret the value as a date. The inputs will be
-separated by "night"s. It will then print a list of all the input files
-along with the following two columns: night number and file number in that
-night (sorted by time). With '--link' a symbolic link (one for each input)
-will be made with names including the night classifier. With '--copy'
-instead of a link, a copy of the inputs will be made.
+This script will look into a HDU/extension for a header keyword in the given
+FITS files and interpret the value as a date. The inputs will be separated
+by "nights". The definition of "nights" is set with the agrument '--hour'.
+Be careful about differences in time zones! While the organization of images
+by date used to be in local time, the time expressed in '--key' is ussually
+defined in UTC (Universal Time Coordinate) time. It will then print a list
+of all the input files along with the following two columns: night number
+and file number in that night (sorted by time). With '--link' a symbolic
+link (one for each input) will be made with names including the night
+classifier. With '--copy' instead of a link, a copy of the inputs will be
+made.
 
 For more information, please run any of the following commands. In
 particular the first contains a very comprehensive explanation of this
@@ -84,6 +88,7 @@ $scriptname options:
   -h, --hdu=STR           HDU/extension of all input FITS files.
   -k, --key=STR           Header keyword specifying date to use.
   -H, --hour=FLT          Hour in next day to be included in night.
+                          Be aware of time zones whith this argument!
 
  Output:
   -l, --link              list of inputs with night and file number.
diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 1f1ba32..20df7d8 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -10879,6 +10879,21 @@ the files (in that directory) will all start with 
@file{img-}.
 @end table
 
 
address@hidden
address@hidden
address@hidden with time zones:} Time in @code{DATE-OBS} keyword in the
+header of the images is usually expressed in UTC (Universal Time Coordinate)
+time.  However, the organization of the images taken during the night used
+to be local time based. It is possible to take into account this time shift
+zone in the organization of the files with the @option{--hour} argument. For
+example, consider you have a set of images that were taken in Auckland (New
+Zeland, UTC+12) along different nights. If you want to organize these images
+by nights, you have to know at which time (in UTC time) Sun rises (or
+whatever consideration you need to make the definition of "different
+night"). In this particular example, you will set the argument
address@hidden, because in this city, sunrise happens (roughly) at 21h
+UTC time.
address@hidden cartouche