GNU Astronomy Utilities

GNU Astronomy Utilities (Gnuastro) is an official GNU package consisting of various programs and library functions for the manipulation and analysis of astronomical data. All the programs share the same basic command-line user interface for the comfort of both the users and developers. Gnuastro is written to comply fully with the GNU coding standards so it integrates finely with the GNU/Linux operating system. This also enables astronomers to expect a fully familiar experience in the source code, building, installing and command-line user interaction that they have seen in all the other GNU software that they use.

In case you are new to Gnuastro, you might find these links useful:

• Videos: showing Gnuastro usage in practice.
• Quick start: To install Gnuastro.
• List of Gnuastro programs: For a complete list of the programs.
• Tutorials: for entertaining and easy to read real world examples of using Gnuastro.

Installation

Besides many operating system package managers (shown on the figure below), Gnuastro is also available in Conda. Just note the versions: if your OS has an older version of Gnuastro, it is easy to build the latest version from source: see Quick start.

Gnuastro only has three mandatory dependencies: GNU Scientific Library, CFITSIO, WCSLIB.
See Dependencies from package managers for easy installation of Gnuastro's dependencies using tools like apt-get, dnf (or yum), pacman, zypper or brew.

For a more detailed description, see the Installation chapter of the Gnuastro book. It thoroughly discusses the dependencies, downloading methods, and the building and installation of Gnuastro.

Gnuastro book (documentation)

The Gnuastro book (official Gnuastro documentation or manual) is available online in various formats, as is documentation for most GNU software. After installation, you can access the complete book, or the sections related to individual programs and library headers on the command-line (in Info format). See Getting help for more. As a summary, here are the ways you can immediately navigate to any major part of the book on the command-line:

• info gnuastro: To view the complete Gnuastro book from the beginning.
• info ProgramName: To view the complete section about a specific program. For example info NoiseChisel or info Crop.
• info astprogname: To only view the "Invoking ProgramName" sub-section of the manual. Each program has this subsection which explains the input(s), output(s) and command-line options for that particular program. For example info astnoisechisel or info astcrop.
• astprogname --help: A description and full list of options (classified by context) for this program will be printed. For example astnoisechisel --help or astcrop  --help.
• man astprogname: A man page listing the options and arguments of this program. For example man astnoisechisel, or man astcrop.

Gnuastro videos

Over the course of Gnuastro's history, some publicly shared videos have been recorded on general or specific aspects of Gnuastro. You can see a list of them below. The video links below are on PeerTube (a free software, decentralized and federated video platform, which only requires PeerTube's own Javascript and no external javascript, for more see PeerTube's Wikipedia page).

• Gnuastro tutorial at the 31st ADASS (Astronomical Data Analysis Software & Systems, 2021). This tutorial is a hands-on introduction of Gnuastro with some commonly used operations in astronomy.
• Hands-on demonstration of some (not all!) newly added features in each release. See the NEWS file for the complete list:
• New in Gnuastro 0.19: align FITS image by WCS (new in Warp) and vector graphics annotations from catalogs (new in ConvertType), presented by Pedram Ashofteh-Ardakani.
• Some relevant IAC's Short Meetings on Astro Computing Knowledge (SMACK) video series.
• SMACK 1: History of Unix-like OSs and basic command-line. This is good if you are wondering what GNU, Linux, Unix, macOS and etc are related to each other.
• SMACK 2: More on the command-line. Here we review some very basic command-line tools that are available and their usage in common astronomical data analysis.
• SMACK 3: GNU Astronomy Utilities (Gnuastro). Having introduced the Unix-like operating systems and the command-line, in this presentation we give a tutorial on doing data analysis with Gnuastro.
• SMACK 4: Shell scripting. A review of how to merge multiple commands into a higher-level program as a shell script.
• SMACK 14: Makefiles. The very basics of using GNU Make for organizing your research workflow.
• SMACK 16: LaTeX 1. LaTeX (very basic introduction).
• SMACK 17: LaTeX 2. LaTeX (some more basic concepts and tools).
• Focused on NoiseChisel and Segment:
  • Introductory talk on NoiseChisel, Segment and MakeCatalog: this is a talk presented at the Institut d'Astrophysique de Paris in December 2021. It is a set of slides, introducing the fundamental concepts behind these three core Gnuastro programs and how their non-parametric approach benefits various scientific scenarios.
  • NoiseChisel: how to detect diffuse signal in noise (hands-on): this is a hand-on demonstration of how NoiseChisel is able to dig signal very deeply within the noise. By hands-on, we mean that you will mostly see the terminal, and we will make test images on various phases. In the process, we also show how to make mock images, and review some basic statistics.

Chat rooms

Gnuastro has the following two Matrix-protocol, public chat rooms under the OpenAstronomy initiative:

• #gnuastro:openastronomy.org: General discussion (questions, ideas, related links and etc).
• #gnuastro-dev:openastronomy.org: discussions on the development work of Gnuastro.

You can use any Matrix-protocol client to access these chat rooms if you have fast questions/doubts, or would like to help answer the questions of others, or simply follow the development process that is on going. If you haven't used Matrix-protocol chat rooms before and don't know how to access those rooms above, you can use https://element.io which is free software and has both stand-alone desktop applications in common desktop and smartphone operating systems, along with a web-browser based interface. Clicking on the names above takes you to the web-browser based interface of Element where you can view the discussions anonymously.

If you would like to post messages and join the discussion in Gnuastro's rooms, you need to make a Matrix-potocol ID (which you can use on any program: for example from version 102, Thunderbird now also integrates Matrix chat!). To create an ID, in the element pages above, just click on the green "Sign Up" button at the bottom of the page.

Mailing lists

Gnuastro has the following mailing lists:

• info-gnuastro: All official Gnuastro announcements will be circulated through this mailing list.
• help-gnuastro: Get in touch with experienced Gnuastro users and developers on problems and advice in using Gnuastro (it will help if you have had a look at the documentation first).
• bug-gnuastro: Report a bug, or suggest a new feature (see Report a bug and Suggest new feature in the documentation).
• gnuastro-devel: Circulating development discussions (mainly interesting for Gnuastro developers).
• gnuastro-commits: Circulate commits made to Gnuastro's version controlled history in the official repository.

Security reports that should not be made immediately public can be sent directly to the maintainer. If there is no response to an urgent issue, you can escalate to the general security mailing list for advice.

Report a bug

The Report a bug section of the manual thoroughly explains the process to report a bug, please read that section. As a summary, first have a look at the Gnuastro bug archive. Click on the "Display criteria" (above the list), choose "Any" in the "Open/Closed" drop-down menu, and under "Category" choose the part of Gnuastro that corresponds to your bug. By clicking on the "Apply" button, only the relevant bugs will be listed. Green items have been solved and closed, while red items are still open. If your bug isn't listed, please take one of the following steps. Please try to be as descriptive as possible and include the Gnuastro version you are using along with the commands or code that created the bug so we can reproduce and thus fix it faster.

• Submit your bug through the main project management webpage. This is the recommended way to inform us of your bug. Please also fill out the meta-data (category, item group and etc) as much as possible.
• Send a mail to <bug-gnuastro::at::gnu.org> which is one of Gnuastro's mailing lists. This will be slower than the first. Because of the large number of spam messages, this mailing list is moderated and other developers will only see it after it has been approved. So to immediately let all the developers know, please use the first option.

Getting involved

The most important principle behind Gnuastro is to be easy for anyone to hack into it (add a new feature, change an existing one, fix a problem and most importantly to understand what is going on under the hood), please see Science and its tools. So you are most welcome and highly encouraged to contribute. There is even a full chapter dedicated to Developing to make it as easy as possible for you to get involved. Also see How to help GNU for joining the full GNU project.

Test releases

Trying the latest test release (when available) is always appreciated. Official alpha-releases of Gnuastro can be found on the GNU server via HTTPS,  HTTP or FTP. Only one or two of these will be available between the offical releases, but they are also archived in the URLs above.
Alternatively, the tarball corresponding to the most recent commit is also available at https://akhlaghi.org/gnuastro-latest.tar.lz, along with its PDF manual. For the changes compared to the last major release, see the NEWS file (also available in the tarball). Just note that the contents of this tarball constantly change with every commit in the Gnuastro history. So the tarball can be reproduced by bootstrapping that commit, but it will not be archived for future direct downloads.

Development

Gnuastro is still under active development. So if you are interested, please have a look at the Developing chapter of the documentation and start hacking into Gnuastro or even write your own program within it (Gnuastro has a template to help you). For development sources, bug trackers, task trackers (planned features to be added), and other information, please see the Gnuastro project page at savannah.gnu.org. The trackers can be a good starting point if you want to get involved in the coding. To stay up to date with Gnuastro's development activities, please subscribe to the gnuastro-devel, and/or the gnuastro-commits mailing lists.

Gnuastro is version controlled using Git. The version controlled source can be inspected online, or you can see the latest history. To keep a local copy, please clone it onto your system with any one of the following commands (if it works, the first one is recommended).

git clone git://git.sv.gnu.org/gnuastro
git clone https://git.sv.gnu.org/r/gnuastro.git

To configure and build the version controlled source, you will need to bootstrap it (also see bootstrapping dependencies). See the forking tutorial for a demonstration of the Gnuastro project workflow.

Maintainer

Gnuastro was created and is currently maintained by Mohammad Akhlaghi <mohammad::at::akhlaghi.org>. Please use the mailing lists for contact.

How to cite

Citations are vital for the continued work on Gnuastro. All the programs accept the common --cite option which will guide you on how to properly cite and acknowledge the work that has gone into creating and maintaining that particular program and Gnuastro in general. If any of the programs or libraries offered in Gnuastro are useful in your research, please use the output of this option to cite the program and Gnuastro in your research paper. Note that different programs may require citation of different papers specifically devoted to them.

Gnuastro has still not reached version 1.0. Therefore, there is no paper fully devoted to introducing it and its capabilities yet (we are more focused on reaching the goals of version 1.0). Until then, the paper to cite for Gnuastro in general is the paper which introduced NoiseChisel (ApJS 220, 1). It was the first published paper using Gnuastro. There have been other papers published for certain updates or new features since then. You can see the full list on the Gnuastro library on ADS (needs Javascript). The paper(s) relevant to each program can be seen by running the program with the --cite option; if a program is useful to your work, please do not forget to cite the suggested papers.

Gnuastro is also registered on the Astrophysics Source Code Library (ASCL) with ascl.net/1801.009. Please use this identifier somewhere in the body of your paper (for example in the acknowledgments or first mention of Gnuastro). For the bibliography/references list at the end of the paper, please only use the papers listed in the output of --cite.

Recent citations of Gnuastro

For the full, and up-to-date, list please see the Google Scholar page for the main article, or the "Metrics" tab of the Gnuastro ADS library, the "cited:" item of each paper on the ADS search page (ADS needs Javascript).

Licensing

GNU Astronomy Utilities (Gnuastro) is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.