GNU Astronomy Utilities Astronomical data manipulation and analysis programs and libraries for version 0.7, 8 August 2018 Mohammad Akhlaghi Gnuastro (source code, book and webpage) authors (sorted by number of commits): Mohammad Akhlaghi ([email protected], 1101) Mos`eGiordano ([email protected], 29) Vladimir Markelov ([email protected], 18) Boud Roukema ([email protected], 7) Leindert Boogaard ([email protected], 1) Lucas MacQuarrie ([email protected], 1) Th´er`eseGodefroy ([email protected], 1) This book documents version 0.7 of the GNU Astronomy Utilities (Gnuastro). Gnuastro provides various programs and libraries for astronomical data manipulation and analysis. Copyright c 2015-2018 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled \GNU Free Documentation License". For myself, I am interested in science and in philosophy only because I want to learn something about the riddle of the world in which we live, and the riddle of man's knowledge of that world. And I believe that only a revival of interest in these riddles can save the sciences and philosophy from narrow specialization and from an obscurantist faith in the expert's special skill, and in his personal knowledge and authority; a faith that so well fits our `post-rationalist' and `post- critical' age, proudly dedicated to the destruction of the tradition of rational philosophy, and of rational thought itself. |Karl Popper. The logic of scientific discovery. 1959. i Short Contents 1 Introduction :::::::::::::::::::::::::::::::::::::::::: 1 2 Tutorials:::::::::::::::::::::::::::::::::::::::::::: 16 3 Installation:::::::::::::::::::::::::::::::::::::::::: 57 4 Common program behavior :::::::::::::::::::::::::::: 87 5 Data containers ::::::::::::::::::::::::::::::::::::: 120 6 Data manipulation::::::::::::::::::::::::::::::::::: 138 7 Data analysis ::::::::::::::::::::::::::::::::::::::: 193 8 Modeling and fitting ::::::::::::::::::::::::::::::::: 265 9 High-level calculations :::::::::::::::::::::::::::::::: 288 10 Library :::::::::::::::::::::::::::::::::::::::::::: 297 11 Developing ::::::::::::::::::::::::::::::::::::::::: 415 A Gnuastro programs list ::::::::::::::::::::::::::::::: 437 B Other useful software::::::::::::::::::::::::::::::::: 439 C GNU Free Doc. License::::::::::::::::::::::::::::::: 444 D GNU Gen. Pub. License v3 ::::::::::::::::::::::::::: 452 Index: Macros, structures and functions ::::::::::::::::::::: 463 Index ::::::::::::::::::::::::::::::::::::::::::::::::: 467 ii Table of Contents 1 Introduction ::::::::::::::::::::::::::::::::::::: 1 1.1 Quick start ::::::::::::::::::::::::::::::::::::::::::::::::::::: 1 1.2 Science and its tools :::::::::::::::::::::::::::::::::::::::::::: 2 1.3 Your rights ::::::::::::::::::::::::::::::::::::::::::::::::::::: 6 1.4 Naming convention ::::::::::::::::::::::::::::::::::::::::::::: 7 1.5 Version numbering:::::::::::::::::::::::::::::::::::::::::::::: 7 1.5.1 GNU Astronomy Utilities 1.0 :::::::::::::::::::::::::::::: 8 1.6 New to GNU/Linux? ::::::::::::::::::::::::::::::::::::::::::: 8 1.6.1 Command-line interface :::::::::::::::::::::::::::::::::::: 9 1.7 Report a bug :::::::::::::::::::::::::::::::::::::::::::::::::: 11 1.8 Suggest new feature ::::::::::::::::::::::::::::::::::::::::::: 12 1.9 Announcements ::::::::::::::::::::::::::::::::::::::::::::::: 13 1.10 Conventions :::::::::::::::::::::::::::::::::::::::::::::::::: 13 1.11 Acknowledgments :::::::::::::::::::::::::::::::::::::::::::: 14 2 Tutorials :::::::::::::::::::::::::::::::::::::::: 16 2.1 Sufi simulates a detection :::::::::::::::::::::::::::::::::::::: 17 2.2 General program usage tutorial :::::::::::::::::::::::::::::::: 24 2.3 Detecting large extended targets ::::::::::::::::::::::::::::::: 44 2.4 Hubble visually checks and classifies his catalog :::::::::::::::: 53 3 Installation ::::::::::::::::::::::::::::::::::::: 57 3.1 Dependencies:::::::::::::::::::::::::::::::::::::::::::::::::: 57 3.1.1 Mandatory dependencies:::::::::::::::::::::::::::::::::: 58 3.1.1.1 GNU Scientific library ::::::::::::::::::::::::::::::: 58 3.1.1.2 CFITSIO :::::::::::::::::::::::::::::::::::::::::::: 58 3.1.1.3 WCSLIB :::::::::::::::::::::::::::::::::::::::::::: 59 3.1.2 Optional dependencies :::::::::::::::::::::::::::::::::::: 60 3.1.3 Bootstrapping dependencies :::::::::::::::::::::::::::::: 62 3.1.4 Dependencies from package managers ::::::::::::::::::::: 64 3.2 Downloading the source ::::::::::::::::::::::::::::::::::::::: 66 3.2.1 Release tarball:::::::::::::::::::::::::::::::::::::::::::: 67 3.2.2 Version controlled source:::::::::::::::::::::::::::::::::: 68 3.2.2.1 Bootstrapping ::::::::::::::::::::::::::::::::::::::: 68 3.2.2.2 Synchronizing:::::::::::::::::::::::::::::::::::::::: 70 3.3 Build and install :::::::::::::::::::::::::::::::::::::::::::::: 71 3.3.1 Configuring::::::::::::::::::::::::::::::::::::::::::::::: 72 3.3.1.1 Gnuastro configure options::::::::::::::::::::::::::: 72 3.3.1.2 Installation directory::::::::::::::::::::::::::::::::: 74 3.3.1.3 Executable names:::::::::::::::::::::::::::::::::::: 78 3.3.1.4 Configure and build in RAM ::::::::::::::::::::::::: 79 3.3.2 Separate build and source directories:::::::::::::::::::::: 80 iii 3.3.3 Tests ::::::::::::::::::::::::::::::::::::::::::::::::::::: 83 3.3.4 A4 print book :::::::::::::::::::::::::::::::::::::::::::: 84 3.3.5 Known issues ::::::::::::::::::::::::::::::::::::::::::::: 84 4 Common program behavior ::::::::::::::::::: 87 4.1 Command-line::::::::::::::::::::::::::::::::::::::::::::::::: 87 4.1.1 Arguments and options ::::::::::::::::::::::::::::::::::: 87 4.1.1.1 Arguments::::::::::::::::::::::::::::::::::::::::::: 88 4.1.1.2 Options:::::::::::::::::::::::::::::::::::::::::::::: 89 4.1.2 Common options ::::::::::::::::::::::::::::::::::::::::: 91 4.1.2.1 Input/Output options:::::::::::::::::::::::::::::::: 91 4.1.2.2 Processing options ::::::::::::::::::::::::::::::::::: 93 4.1.2.3 Operating mode options ::::::::::::::::::::::::::::: 95 4.2 Configuration files ::::::::::::::::::::::::::::::::::::::::::::: 99 4.2.1 Configuration file format:::::::::::::::::::::::::::::::::: 99 4.2.2 Configuration file precedence :::::::::::::::::::::::::::: 100 4.2.3 Current directory and User wide ::::::::::::::::::::::::: 101 4.2.4 System wide::::::::::::::::::::::::::::::::::::::::::::: 101 4.3 Multi-threaded operations :::::::::::::::::::::::::::::::::::: 102 4.3.1 A note on threads ::::::::::::::::::::::::::::::::::::::: 102 4.3.2 How to run simultaneous operations ::::::::::::::::::::: 103 4.4 Numeric data types :::::::::::::::::::::::::::::::::::::::::: 104 4.5 Tables:::::::::::::::::::::::::::::::::::::::::::::::::::::::: 106 4.5.1 Recognized table formats :::::::::::::::::::::::::::::::: 107 4.5.2 Gnuastro text table format :::::::::::::::::::::::::::::: 109 4.5.3 Selecting table columns :::::::::::::::::::::::::::::::::: 111 4.6 Tessellation :::::::::::::::::::::::::::::::::::::::::::::::::: 112 4.7 Getting help ::::::::::::::::::::::::::::::::::::::::::::::::: 114 4.7.1 --usage ::::::::::::::::::::::::::::::::::::::::::::::::: 114 4.7.2 --help :::::::::::::::::::::::::::::::::::::::::::::::::: 115 4.7.3 Man pages :::::::::::::::::::::::::::::::::::::::::::::: 116 4.7.4 Info ::::::::::::::::::::::::::::::::::::::::::::::::::::: 116 4.7.5 help-gnuastro mailing list :::::::::::::::::::::::::::::::: 117 4.8 Automatic output :::::::::::::::::::::::::::::::::::::::::::: 117 4.9 Output headers :::::::::::::::::::::::::::::::::::::::::::::: 118 5 Data containers ::::::::::::::::::::::::::::::: 120 5.1 Fits :::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 120 5.1.1 Invoking Fits :::::::::::::::::::::::::::::::::::::::::::: 122 5.1.1.1 HDU manipulation ::::::::::::::::::::::::::::::::: 123 5.1.1.2 Keyword manipulation:::::::::::::::::::::::::::::: 124 5.2 ConvertType ::::::::::::::::::::::::::::::::::::::::::::::::: 127 5.2.1 Recognized file formats :::::::::::::::::::::::::::::::::: 128 5.2.2 Color:::::::::::::::::::::::::::::::::::::::::::::::::::: 130 5.2.3 Invoking ConvertType ::::::::::::::::::::::::::::::::::: 131 5.3 Table :::::::::::::::::::::::::::::::::::::::::::::::::::::::: 135 5.3.1 Invoking Table :::::::::::::::::::::::::::::::::::::::::: 136 iv 6 Data manipulation :::::::::::::::::::::::::::: 138 6.1 Crop ::::::::::::::::::::::::::::::::::::::::::::::::::::::::: 138 6.1.1 Crop modes ::::::::::::::::::::::::::::::::::::::::::::: 138 6.1.2 Crop section syntax ::::::::::::::::::::::::::::::::::::: 141 6.1.3 Blank pixels ::::::::::::::::::::::::::::::::::::::::::::: 141 6.1.4 Invoking Crop ::::::::::::::::::::::::::::::::::::::::::: 142 6.1.4.1 Crop options ::::::::::::::::::::::::::::::::::::::: 143 6.1.4.2 Crop output :::::::::::::::::::::::::::::::::::::::: 147 6.2 Arithmetic ::::::::::::::::::::::::::::::::::::::::::::::::::: 148 6.2.1 Reverse polish notation :::::::::::::::::::::::::::::::::: 149 6.2.2 Arithmetic operators :::::::::::::::::::::::::::::::::::: 149 6.2.3 Invoking Arithmetic ::::::::::::::::::::::::::::::::::::: 159 6.3 Convolve ::::::::::::::::::::::::::::::::::::::::::::::::::::: 162 6.3.1 Spatial domain convolution :::::::::::::::::::::::::::::: 162 6.3.1.1 Convolution process :::::::::::::::::::::::::::::::: 163