Gnuastro 0.22 released [stable]

[Mohammad Akhlaghi]

Dear all,

I am happy to share the 22nd stable release of GNU Astronomy Utilities 
(Gnuastro).

There have been 97 commits by 7 people in the 15 weeks since 0.21, see 
[1] below for the full list. For all the new features, as well as 
changes and bug fixes, see the NEWS file entry for this version; shown 
in [2] below.

If you are using Gnuastro in your projects, take a few minutes to read 
[2] below.

Gnuastro is an official GNU package, consisting of various command-line 
programs, C/C++ library functions and Makefile extensions for the 
manipulation and analysis of (astronomical) data. All the programs share 
the same basic command-line user interface (modeled on GNU Coreutils). 
For the Gnuastro web page, hands-on tutorials (recommended place to 
start using Gnuastro), list of Gnuastro's library and its programs, 
please see the links below respectively:

https://www.gnu.org/s/gnuastro
https://www.gnu.org/s/gnuastro/manual/html_node/Tutorials.html
https://www.gnu.org/s/gnuastro/manual/html_node/Gnuastro-library.html
https://www.gnu.org/s/gnuastro/manual/html_node/Gnuastro-programs-list.html

Here is the compressed source and the GPG detached signature for this 
release. To uncompress Lzip tarballs, see [3]. To check the validity of 
the tarballs using the GPG detached signature (*.sig) see [4]. See [5] 
for the list of software used to bootstrap this tarball.

https://ftp.gnu.org/gnu/gnuastro/gnuastro-0.22.tar.lz    (4.6MB)
https://ftp.gnu.org/gnu/gnuastro/gnuastro-0.22.tar.gz    (7.4MB)
https://ftp.gnu.org/gnu/gnuastro/gnuastro-0.22.tar.lz.sig (833B)
https://ftp.gnu.org/gnu/gnuastro/gnuastro-0.22.tar.gz.sig (833B)

Here are the SHA1 and SHA256 checksums (other ways to check if the 
tarball you download is what we distributed). Just note that the SHA256 
checksum is base64 encoded, instead of the hexadecimal encoding that 
most checksum tools default to (see [6] on how to generate it).

  0171c1547fff343bed905662df50a76ef899dfc5  gnuastro-0.22.tar.gz
  f9fxaga95VrtliggkM2SITW+6pAjaeWvgUOJ6rnMcwg=  gnuastro-0.22.tar.gz
  bfb22c3d74400f8a3beacc22010e8394363736cf  gnuastro-0.22.tar.lz
  H7uEkvVx3VDJkMUlJ+tmBoH9kj/y4hOi3b6lXkOXNJc=  gnuastro-0.22.tar.lz

If any of Gnuastro's programs or libraries are useful in your work, 
please don't forget to cite _and_ acknowledge them. For citation and 
acknowledgment guidelines, run the relevant programs with a `--cite' 
option (it can be different for different programs, so run it for all 
the programs you use). Citations _and_ acknowledgments are vital for the 
continued work on Gnuastro, so please don't forget to support us by 
doing so.

Best wishes,
Mohammad

--
Dr. Mohammad Akhlaghi
Staff Researcher
Centro de Estudios de Física del Cosmos de Aragón (CEFCA),
Plaza San Juan 1, Planta 2, Teruel 44001, Spain





[1] Thanks to everyone who has contributed!

The following people contributed changes to this release (the number in 
parenthesis is the number of Git commits).

  Boud Roukema (2)
  Elham Saremi (1)
  Faezeh Bidjarchian (9)
  Mohammad Akhlaghi (53)
  Raul Infante-Sainz (24)
  Sepideh Eskandarlou (5)
  Thorsten Alteholz (3)

The following people provided comments, suggestions or found bugs:

  Alberto Moreno Signes
  Boud Roukema
  Helena Domínguez Sánchez
  Ignacio Ruiz Cejudo
  Rahna Payyasseri Thanduparackal
  Raul Infante-Sainz
  Sepideh Eskandarlou
  Teet Kuutma
  Thorsten Alteholz





[2] Noteworthy changes in release 0.22

** New publications
  - https://ui.adsabs.harvard.edu/abs/2023RNAAS...7..269E by 
Eskandarlou et al. on Gnuastro's zero point measurement script for 
calibration of astronomical images ('astscript-zeropoint').
  - https://ui.adsabs.harvard.edu/abs/2024RNAAS...8...10I by 
Infante-Sainz & Akhlaghi on Gnuastro's script to visualize the full 
dynamic range of astronomical images ('astscript-color-faint-gray').
  - https://ui.adsabs.harvard.edu/abs/2024RNAAS...8...22I by 
Infante-Sainz et al. on Gnuastro's script to measure the radial profile 
of a given source ('astscript-radial-profile').

** New features
*** New program
  - 'astscript-color-faint-gray': a new installed script to maximize 
the visualization of the contents within your astronomical images. It 
does this by showing the brighter parts of the image as color, 
intermediate regions as black and the noisy/faint regions as gray/white.

*** All programs
  - The following options are now available in all programs to allow 
customization of which metadata is printed in the 0-th HDU of the FITS 
output of all Gnuastro programs. Also see the "Changed features" list 
for an important change in this regard to all Gnuastro output FITS files.
    --outfitsnoconfig: do not print any metadata in the 0-th HDU 
(including the used options and their values, the date, the versions and 
git commit of running directory).
    --outfitsnodate: do not write the 'DATE' keyword.
    --outfitsnoversions: do not write the versions of Gnuastro and 
mandatory dependencies.
    --outfitsnocommit: do not write the Git commit.

*** Arithmetic
  --arguments: takes the name of plain-text file that contains the list 
of arguments to the program. This option is critical if you have very 
long (thousands) of operands and operators (which happen in large 
pipelines where the arguments are constructed automatically). Without 
this option, the shell is going to abort with an "Argument list too 
long" error message.

  - New operators:
    - rotate-coord: given a 2D point's coordinates, return the 
coordinates after it has been rotated by your requested angle around 
your requested center (see documentation for example).
    - mad: Median Absolute Deviation (MAD) stacking.
    - madclip-mad: MAD after MAD-clipping stacking.
    - madclip-std: Standard deviation after MAD-clipping stacking.
    - madclip-mean: Mean after MAD-clipping stacking.
    - madclip-median: Median after MAD-clipping stacking.
    - madclip-number: Number of elements after MAD-clipping stacking.
    - madclip-fill-mad: MAD after filled MAD-clipping stacking: this 
involves a two-phase clipping: after the first clipping, Arithmetic will 
"fill" the unclipped holes in each input and masks them for a second 
round. This is critical for clipping more diffuse outliers: where a 
pixel may not be clipped individually and will produce biased results, 
but due to proximity with many nearby clipped pixels, it can be 
discarded and thus its effect on the final stack be removed.
    - madclip-fill-std: Standard deviation after filled MAD-clipping 
stacking.
    - madclip-fill-mean: Mean after filled MAD-clipping stacking.
    - madclip-fill-median: Median after filled MAD-clipping stacking.
    - madclip-fill-number: Num. of elements after filled MAD-clipping 
stacking.
    - sigclip-fill-mad: MAD after filled MAD-clipping stacking.
    - sigclip-fill-std: Standard deviation after filled MAD-clipping 
stacking.
    - sigclip-fill-mean: Mean after filled MAD-clipping stacking.
    - sigclip-fill-median: Median after filled MAD-clipping stacking.
    - sigclip-fill-number: Num. of elements after filled MAD-clipping 
stacking.
    - sigclip-mad: MAD after sigma-clipping stacking.
    - collapse-madclip-mad: Collapse dim. by MAD-clipped MAD.
    - collapse-madclip-std: Collapse dim. by MAD-clipped STD.
    - collapse-madclip-mean: Collapse dim. by MAD-clipped mean.
    - collapse-madclip-median: Collapse dim. by MAD-clipped median.
    - collapse-madclip-number: Collapse dim. by MAD-clipped number.
    - collapse-madclip-fill-mad: Collapse dim. by filled MAD-clipped MAD.
    - collapse-madclip-fill-std: Collapse dim. by filled MAD-clipped STD.
    - collapse-madclip-fill-mean: Collapse dim. by filled MAD-clipped mean.
    - collapse-madclip-fill-median: Collapse dim. by filled MAD-clipped 
median.
    - collapse-madclip-fill-number: Collapse dim. by filled MAD-clipped 
num.
    - collapse-sigclip-mad: Collapse dim. by sigma-clipped MAD.
    - collapse-sigclip-fill-mad: Collapse dim. by filled sigma-clipped MAD.
    - collapse-sigclip-fill-std: Collapse dim. by filled sigma-clipped STD.
    - collapse-sigclip-fill-mean: Collapse dim. by filled sigma-clipped 
mean.
    - collapse-sigclip-fill-median: Collapse dim. by filled sigma-clip. 
median.
    - collapse-sigclip-fill-number: Collapse dim. by filled 
sigma-clipped num.

*** Fits
  --arguments: takes the name of plain-text file that contains the list 
of arguments to the program. Currently this only works with '--keyvalue' 
and is necessary when you want to get the keywords of a very long list 
of files (~thousands!). Without this option, the shell is going to abort 
with an "Argument list too long" error message.
  --datasum-encoded: new option that will return an ASCII encoded 
16-character string for the value of the 'DATASUM' concept in FITS data 
verification.

*** Statistics
  --checkskynointerp: similar to '--checksky', but stop as soon as the 
good tiles are found (do not continue to interpolation and smoothing of 
the tiles which can be time consuming if not needed).
  --mad: Median Absolute Deviation (MAD) of input dataset.
  --madclip: MAD-clipping, showing intermediate results.
  --sigclip-mad: MAD of input after sigma-clipping.
  --madclip-number: Number of input elements after MAD-clipping.
  --madclip-median: Median of input elements after MAD-clipping.
  --madclip-mean: Mean of input elements after MAD-clipping.
  --madclip-std: Standard deviation of input elements after MAD-clipping.
  --madclip-mad: MAD of input elements after MAD-clipping.
  --mclipparams: Parameters of MAD-clipping, similar to sigma-clipping. 
Note that in a Gaussian distribution, MAD = 0.67 sigma, so if you want 
something similar to 3-sigma (the default), you should set the MAD 
multiple to 5 (the default).

*** Makefile extension
  - 'ast-text-to-upper': convert input string to upper-case.
  - 'ast-text-to-lower': convert input string to lower-case.

*** Library
**** Functions
  - gal_dimension_collapse_mclip_mad: MAD-clipped MAD.
  - gal_dimension_collapse_mclip_fill_mad: filled MAD-clipped MAD.
  - gal_dimension_collapse_mclip_std: MAD-clipped STD.
  - gal_dimension_collapse_mclip_fill_std: filled MAD-clipped STD.
  - gal_dimension_collapse_mclip_mean: MAD-clipped mean.
  - gal_dimension_collapse_mclip_fill_mean: filled MAD-clipped mean
  - gal_dimension_collapse_mclip_median: MAD-clipped median.
  - gal_dimension_collapse_mclip_fill_median: filled MAD-clipped median.
  - gal_dimension_collapse_mclip_number: MAD-clipped number.
  - gal_dimension_collapse_mclip_fill_number: filled MAD-clipped number.
  - gal_dimension_collapse_sclip_mad: sigma-clipped MAD
  - gal_dimension_collapse_sclip_fill_mad: filled sigma-clipped MAD.
  - gal_dimension_collapse_sclip_fill_std: filled sigma-clipped STD.
  - gal_dimension_collapse_sclip_fill_mean: filled sigma-clipped mean
  - gal_dimension_collapse_sclip_fill_median: filled sigma-clipped median.
  - gal_dimension_collapse_sclip_fill_number: filled sigma-clipped number.
  - gal_fits_hdu_datasum_encoded: the 16-character encoded sting datasum.
  - gal_fits_key_list_add_date: add 'DATE' to current list of keywords.
  - gal_fits_key_list_add_git_commit: add the Git commit information of 
the running directory to the input list of keywords (if built with libgit2).
  - gal_fits_key_list_add_software_versions: add versions of Gnustro 
and its mandatory dependencies to the input list of keywords.
  - gal_statistics_clip_mad: MAD clipping of given input.
  - gal_statistics_mad: return median absolute deviation (MAD).
  - gal_statistics_median_mad: return median and MAD.
  - gal_txt_read_to_list: read all the space-separated words of the 
input plain-text file as a separate node in a linked list of strings.

**** Macros
  - Used by 'gal_arithmetic':
    - GAL_ARITHMETIC_OP_SIGCLIP_MAD: Sigma-clipped MAD.
    - GAL_ARITHMETIC_OP_SIGCLIP_MAD: Sigma-clipped STD.
    - GAL_ARITHMETIC_OP_SIGCLIP_FILL_NUMBER: MAD-clipped num. of arrays.
    - GAL_ARITHMETIC_OP_SIGCLIP_FILL_MEAN: MAD-clipped mean of arrays.
    - GAL_ARITHMETIC_OP_SIGCLIP_FILL_MEDIAN: MAD-clipped median of arrays.
    - GAL_ARITHMETIC_OP_SIGCLIP_FILL_STD: MAD-clipped STD of arrays.
    - GAL_ARITHMETIC_OP_SIGCLIP_FILL_MAD: MAD-clipped STD of arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_NUMBER: MAD-clipped number of mult. arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_MEAN: MAD-clipped mean of multiple arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_MEDIAN: MAD-clipped median of mult. arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_STD: MAD-clipped STD of multiple arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_MAD: MAD-clipped STD of multiple arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_FILL_NUMBER: MAD-clipped num. of arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_FILL_MEAN: MAD-clipped mean of arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_FILL_MEDIAN: MAD-clipped median of arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_FILL_STD: MAD-clipped STD of arrays.
    - GAL_ARITHMETIC_OP_MADCLIP_FILL_MAD: MAD-clipped STD of arrays.
  - Used by 'gal_statistics_clip_sigma' and 'gal_statistics_clip_mad':
    - GAL_STATISTICS_CLIP_OUTCOL_NUMBER_USED: index of final number in 
output.
    - GAL_STATISTICS_CLIP_OUTCOL_MEAN: index of clipped mean in output.
    - GAL_STATISTICS_CLIP_OUTCOL_STD: index of clipped STD in output.
    - GAL_STATISTICS_CLIP_OUTCOL_MEDIAN: index of clipped median in output.
    - GAL_STATISTICS_CLIP_OUTCOL_MAD: index of clipped MAD in output.
    - GAL_STATISTICS_CLIP_OUTCOL_NUMBER_CLIPS: index of clipped number 
in output.
    - GAL_STATISTICS_CLIP_OUTCOL_OPTIONAL_MEAN: bit flag for measuring 
mean.
    - GAL_STATISTICS_CLIP_OUTCOL_OPTIONAL_STD: bit flag for measuring STD.
    - GAL_STATISTICS_CLIP_OUTCOL_OPTIONAL_MAD: bit flag for measuring MAD.

** Removed features
*** Library
  - gal_fits_key_write_version: redundant with the new 
'gal_fits_key_list_add_software_versions'.
  - gal_fits_key_write_version_in_ptr: as in gal_fits_key_write_version.
  - gal_fits_key_write_config: redundant since all configuration 
(options) are stored as generic keys.

** Changed features
*** All programs
  - Date and versions FITS keywords are only written in the 0-th HDU of 
output FITS files (along with the options names and values), not the 
HDU(s) containing data. Until now, the data and versions metadata were 
written in the data HDU. However, ultimately, these are also metadata 
and are better suited for the 0-th HDU. For example when everything else 
is identical, you expect an exactly reproducible HDU (to verify with the 
FITS 'CHECKSUM' for example), but every time you run, 'DATE' will be 
different! Similarly for the versions of the software or Git commit 
(they may change, while your dataset doesn't). To disable these in the 
0-th HDU also, see the newly added '--outfitsno*' options in the new 
features.

*** Arithmetic
  - Binary operators (like '+' or 'x') that are given two integers will 
crash with an error if the input operands have the same width but 
different signs. Until now, they would just report a warning and print 
the output. However, in large scripts, users could miss the warning and 
not be aware of a possibly wrong result. Therefore it is more robust to 
crash with an error rather than print a warning. This was suggested by 
Sepideh Eskandarlou and implemented by Faezeh Bidjarchian after a poll 
on Gnuastro's Matrix chat channel (#gnuastro:openastronomy.org).

*** CosmicCalculator
  - In a non-FLRW model (when the sum of the densities is not 1.0), 
CosmicCalculator no longer crashes with an error since calculations like 
the radial comoving distance ('--properdistance') are still valid in a 
curved cosmology. Instead a warning is printed informing the user that 
with Gnuastro's current implementation angular diameter based 
calculations will be wrong. This was implemented by Boud Roukema.
  --angulardiamdist is the new name for the old '--angulardimdist' 
option. This was necessary to avoid confusion of 'dim' in the old name 
with "dimension"; 'diam' makes it clear that this is a "diameter", not 
'dimension'. This was suggested by Boud Roukema.

*** Crop
  - The 'ICF*' keywords are now written in the 0-th HDU of Crop's 
outputs (the extension with no data, only metadata). Therefore, the WCS 
is now the only metadata in the HDU containing data.

*** astscript-psf-stamp
  - When no name is given to the temporary directory, the default name 
will contain the center coordinates as a suffix (to avoid being confused 
with other calls for other centers), and the contents of the temporary 
directy will have the same filename. Until now, the temporary directory 
name would be the same for different calls, and the coordinates suffix 
would be in the temporary file names. This could cause confusions and 
bugs (for example one call to this script could delete the temporary 
directory that was being used by a later call).

*** Library
  - gal_cosmology_age: a 'quiet' argument is added to disable warnings.
  - gal_cosmology_proper_distance: similar 'gal_cosmology_age'.
  - gal_cosmology_comoving_volume: similar 'gal_cosmology_age'.
  - gal_cosmology_critical_density: similar 'gal_cosmology_age'.
  - gal_cosmology_angular_distance: similar 'gal_cosmology_age'.
  - gal_cosmology_luminosity_distance: similar 'gal_cosmology_age'.
  - gal_cosmology_distance_modulus: similar 'gal_cosmology_age'.
  - gal_cosmology_to_absolute_mag: similar 'gal_cosmology_age'.
  - gal_fits_key_write: to generalize, the "title" argument has been 
removed (because it is a keyword). It can also create the file if it 
doesn't exist and can optionally free the list of keywords (until now, 
it would always free them).
  - gal_fits_key_write_in_ptr: similar to 'gal_fits_key_write'.
  - gal_fits_img_write: no more 'program_name'; it is a keyword title; 
added 'freekeys' argument to optionally free the input keyword list.
  - gal_fits_img_write_to_type: as in 'gal_fits_img_write'.
  - gal_fits_img_write_corr_wcs_str: as in 'gal_fits_img_write'.
  - gal_fits_tab_write: as in 'gal_fits_img_write'.
  - GAL_STATISTICS_CLIP_MAX_CONVERGE: new name for the old 
'GAL_STATISTICS_SIG_CLIP_MAX_CONVERGE'. Since we now also have MAD-clipping.
  - gal_statistics_clip_sigma: new name for 'gal_statistics_sigma_clip'.
  - gal_table_write: as in 'gal_fits_img_write'.
  - gal_tile_full_values_write: as in 'gal_fits_img_write'.
  - gal_wcs_write: as in 'gal_fits_img_write'.

** Bugs fixed
  - bug #46225: Programs don't depend on libs in Makefiles; reported by 
Mosè Giordano and fixed by Thorsten Alteholz.
  - bug #52295: Cosmology library integrals crash for high z; fixed by 
Thorsten Alteholz.
  - bug #52674: Correcting Clang warnings on macOS during compilation; 
fixed with help of Thorsten Alteholz and Raul Infante-Sainz.
  - bug #61476: astscript-ds9-region: output created when input file 
does not exist; reported by Sepideh Eskandarlou, fixed by Thorsten Alteholz.
  - bug #64825: astscript-fits-view only takes the last HDU provided; 
reported by Teet Kuumta and fixed by Raul Infante-Sainz.
  - bug #64852: astscript-zeropoint: crash when input is in 0-th HDU; 
reported in https://savannah.gnu.org/support/?110952; fixed by Sepideh 
Eskandarlou.
  - bug #64915: Segment's SKY_STD output HDU does not have WCS; 
reported by Sepideh Eskandarlou.
  - bug #64952: Table error message for incorrect column name was not 
complete; reported by Sepideh Eskandarlou.
  - bug #65005: astscript-psf-unit not accounting for --innerhdu; 
reported by Ignacio Ruiz Cejudo.
  - bug #65050: Use --libtool option in the TEMPLATE usage; found and 
fixed by Faezeh Bidjarchian.
  - bug #65055: Columns of empty FITS tables (with no rows) read in 
reverse.
  - bug #65084: Fits program's --skycoverage prints connected numbers 
for cubes; found with help of Rahna Payyasseri Thanduparackal.
  - bug #65106: Necessity of --oversample with astscript-radial-profile 
when a 2D profile is to be created with '--customtable' of MakeProfile; 
reported by Sepideh Eskandarlou.
  - bug #65141: MakeCatalog crash when labled image is all blank; 
reported by Sepideh Eskandarlou.
  - bug #65149: MakeCatalog '--frac-max*-*' measurements done without 
'--frac-max'; reported by Helena Domínguez Sánchez.
  - bug #65194: --quiet does not disable the warning for un-given 
minmapsize; reported by Boud Roukema.
  - bug #65195: CosmicCalculator prevents non-flat FLRW models and 
angular diameter distance only correct in flat models. Found and fixed 
by Boud Roukema.




[3] Lzip has better compression ratio and archival features compared to 
the '.gz' or '.xz' formats. Therefore Gnuastro's alpha/test releases are 
only in this format, but for historical reasons we also include `.gz' 
tarballs in the official releases. If you don't have Lzip (you can check 
with `lzip --version' command), download and install it from its webpage:

https://www.nongnu.org/lzip/lzip.html

If Lzip is present and you use GNU Tar, then the single command below 
should uncompress and un-pack the tarball:

  $ tar xf gnuastro-0.22.tar.lz

If the command above doesn't work, you have to un-compress and un-pack 
it with two separate commands (or use a pipe to feed the output of the 
first into the second: `lzip -cd gnuastro-0.22.tar.lz | tar -xf -'):

  $ lzip -d gnuastro-0.22.tar.lz
  $ tar xf gnuastro-0.22.tar





[4] Use a .sig file to verify that the corresponding file (without the 
.sig suffix) is intact.  First, be sure to download both the .sig file 
and the corresponding tarball. Then, run a command like this:

  gpg --verify gnuastro-0.22.tar.gz.sig

The signature should match the fingerprint of the following key:

  pub   rsa4096 2018-12-08 [SC]
        52B0 4484 D806 C90D CB52  7249 71E8 9901 2D17 4B66
  uid           [ unknown] Mohammad Akhlaghi <mohammad@akhlaghi.org>

If that command fails because you don't have the required public key, or 
that public key has expired, try the following commands to retrieve or 
refresh it, and then rerun the 'gpg --verify' command.

  gpg --recv-keys 71E899012D174B66

As a last resort to find the key, you can try the official GNU keyring:

  wget -q https://ftp.gnu.org/gnu/gnu-keyring.gpg
  gpg --keyring gnu-keyring.gpg --verify gnuastro-0.22.tar.gz.sig





[5] This tarball was bootstrapped (created) with the tools below. Note 
that you don't need these to build Gnuastro from the tarball, these are 
the tools that were used to make the tarball itself. They are only 
mentioned here to be able to reproduce/recreate this tarball later.

  Texinfo 7.1
  Autoconf 2.72
  Automake 1.16.5
  Help2man 1.49.3
  ImageMagick 7.1.1-27
  Gnulib v0.1-7045-g7bc53cd0bc
  Autoconf archives v2023.02.20-50-geb940c6

The dependencies to build Gnuastro from this tarball on your system are 
described here:

https://www.gnu.org/s/gnuastro/manual/html_node/Dependencies.html





[6] To get the base64 SHA256 checksum, you can use the command below 
(assuming you already have the 'openssl' command-line program).

  cat gnuastro-0.22.tar.lz \
      | openssl dgst -binary -sha256 | openssl base64 -A