10.1.1 Invoking astscript-sort-by-night ¶

This installed script will read a FITS date formatted value from the given keyword, and classify the input FITS files into individual nights. For more on installed scripts please see (see Installed scripts). This script can be used with the following general template:

$ astscript-sort-by-night [OPTION...] FITS-files

One line examples:

## Use the DATE-OBS keyword
$ astscript-sort-by-night --key=DATE-OBS /path/to/data/*.fits

## Make links to the input files with the `img-' prefix
$ astscript-sort-by-night --link --prefix=img- /path/to/data/*.fits

This script will look into a HDU/extension (--hdu) for a keyword (--key) in the given FITS files and interpret the value as a date. The inputs will be separated by "night"s (11:00a.m to next day’s 10:59:59a.m, spanning two calendar days, exact hour can be set with --hour).

The default output is 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 will be made (one for each input) that contains the night number, and number of file in that night (sorted by time), see the description of --link for more. When --copy is used instead of a link, a copy of the inputs will be made instead of symbolic link.

Below you can see one example where all the target-*.fits files in the data directory should be separated by observing night according to the DATE-OBS keyword value in their second extension (number 1, recall that HDU counting starts from 0). You can see the output after the ls command.

$ astscript-sort-by-night -pimg- -h1 -kDATE-OBS data/target-*.fits
$ ls
img-n1-1.fits img-n1-2.fits img-n2-1.fits ...

The outputs can be placed in a different (already existing) directory by including that directory’s name in the --prefix value, for example, --prefix=sorted/img- will put them all under the sorted directory.

This script can be configured like all Gnuastro’s programs (through command-line options, see Common options), with some minor differences that are described in Installed scripts. The particular options to this script are listed below:

-h STR

--hdu=STR

The HDU/extension to use in all the given FITS files. All of the given FITS files must have this extension.

-k STR

--key=STR

The keyword name that contains the FITS date format to classify/sort by.

-H FLT

--hour=FLT

The hour that defines the next “night”. By default, all times before 11:00a.m are considered to belong to the previous calendar night. If a sub-hour value is necessary, it should be given in units of hours, for example, --hour=9.5 corresponds to 9:30a.m.

Dealing with time zones: The time that is recorded in --key may be in UTC (Universal Time Coordinate). However, the organization of the images taken during the night depends on the local time. It is possible to take this into account by setting the --hour option to the local time in UTC. For example, consider a set of images taken in Auckland (New Zealand, UTC+12) during different nights. If you want to classify these images by night, you have to know at which time (in UTC time) the Sun rises (or any other separator/definition of a different night). For example, if your observing night finishes before 9:00a.m in Auckland, you can use --hour=21. Because in Auckland the local time of 9:00 corresponds to 21:00 UTC.

-l

--link

Create a symbolic link for each input FITS file. This option cannot be used with --copy. The link will have a standard name in the following format (variable parts are written in CAPITAL letters and described after it):

PnN-I.fits

P

This is the value given to --prefix. By default, its value is ./ (to store the links in the directory this script was run in). See the description of --prefix for more.

N

This is the night-counter: starting from 1. N is just incremented by 1 for the next night, no matter how many nights (without any dataset) there are between two subsequent observing nights (its just an identifier for each night which you can easily map to different calendar nights).

I

File counter in that night, sorted by time.

-c

--copy

Make a copy of each input FITS file with the standard naming convention described in --link. With this option, instead of making a link, a copy is made. This option cannot be used with --link.

-p STR

--prefix=STR

Prefix to append before the night-identifier of each newly created link or copy. This option is thus only relevant with the --copy or --link options. See the description of --link for how it is used. For example, with --prefix=img-, all the created file names in the current directory will start with img-, making outputs like img-n1-1.fits or img-n3-42.fits.

--prefix can also be used to store the links/copies in another directory relative to the directory this script is being run (it must already exist). For example, --prefix=/path/to/processing/img- will put all the links/copies in the /path/to/processing directory, and the files (in that directory) will all start with img-.

--stdintimeout=INT

Number of micro-seconds to wait for standard input within this script. This does not correspond to general inputs into the script, inputs to the script should always be given as a file. However, within the script, pipes are often used to pass the output of one program to another. The value given to this option will be passed to those internal pipes. When running this script, if you confront an error, saying “No input!”, you should be able to fix it by giving a larger number to this option (the default value is 10000000 micro-seconds or 10 seconds).