Header can print or manipulate the header information in an extension of an astronomical data file. The executable name is astheader with the following general template
$ astheader [OPTION...] ASTRdata
One line examples:
$ astheader image.fits $ astheader --update=OLDKEY,153.034,"Old keyword comment" $ astheader --remove=COMMENT --comment="Anything you like ;-)." $ astheader --write=MYKEY1,20.00,"An example keyword" --write=MYKEY2,fd
If no keyword modification options are given, the full header of the given HDU will be printed on the command-line. If any of the keywords are to be modified, the headers of the input file will be changed. If you want to keep the original FITS file, it is easiest to create a copy first and then run Header on that. In the FITS standard, keywords are always uppercase. So case does not matter in the input or output keyword names you specify.
Most of the options can accept multiple instances in one command. For example you can add multiple keywords to delete by calling delete multiple times, since repeated keywords are allowed, you can even delete the same keyword multiple times. The action of such options will start from the top most keyword.
|
FITS STANDARD KEYWORDS: Some header keywords are necessary for later operations on a FITS file, for example BITPIX or NAXIS, see the FITS standard for their full list. If you modify (for example remove or rename) such keywords, the FITS file extension might not be usable any more. Also be careful for the world coordinate system keywords, if you modify or change their values, any future world coordinate system (like RA and Dec) measurements on the image will also change. |
|
PRECEDENCE: The order of operations are as follows. Note that while the order within each class of actions is preserved, the order of individual actions is not. So irrespective of what order you called --delete and --update. First all the delete operations are going to take effect then the update operations.
All possible syntax errors will be reported before the keywords are actually written. FITS errors during any of these actions will be reported, but Header won’t stop until all the operations are complete. If quitonerror is called, then Header will immediately stop upon the first error. |
If only a certain set of header keywords are desired, it is easiest to pipe the output of Header to GNU Grep. Grep is a very powerful and advanced tool to search strings which is precisely made for such situations. For example if you only want to check the size of an image FITS HDU, you can run:
$ astheader input.fits | grep NAXIS
The options particular to Header can be seen below. See Common options for a list of the options that are common to all Gnuastro programs, they are not repeated here.
(=STR) Write the string within this argument exactly into the FITS file header with no modifications. If it does not conform to the FITS standards, then it might cause trouble, so please be very careful with this option. If you want to define the keyword from scratch, it is best to use the --write option (see below) and let CFITSIO worry about the standards. The best way to use this option is when you want to add a keyword from one FITS file to another unchanged and untouched. Below is an example of such a case that can be very useful sometimes:
$ key=$(astheader firstimage.fits | grep KEYWORD) $ astheader --asis="$key" secondimage.fits
In particular note the double quotation signs (") around the
reference to the key shell variable ($key), since
FITS keywords usually have lots of space characters, if this variable
is not enclosed within double quotation marks, the shell will only
give the first word in the full keyword to this option, which will
definitely be a non-standard FITS keyword and will make it hard to
work on the file afterwords. See the “Quoting” section of the GNU
Bash manual for more information if your keyword has the special
characters $, `, or \.
(=STR) Delete one instance of the desired keyword. Multiple instances of --delete can be given (possibly even for the same keyword). All keywords given will be removed from the headers in the opposite order (last given keyword will be deleted first). If the keyword doesn’t exist, Header will give a warning and return with a non-zero value, but will not stop.
(=STR) Rename a keyword to a new value. The old name and the new name should be separated by either a comma (,) or a space character. Note that if you use a space character, you have to put the value to this option within double quotation marks (") so the space character is not interpreted as an option separator. Multiple instances of --rename can be given in one command. The keywords will be renamed in the specified order.
(=STR) Update a keyword, its value, its comments and its units all defined separately. If there are multiple instances of the keyword in the header, they will be changed from top to bottom (with multiple --update options).
The format of the values to this option can best be specified with an example:
--update=KEYWORD,value,"comments for this keyword",unit
The value can be any numerical or string value48. Other than the KEYWORD, all
the other values are optional. To leave a given token empty, follow the
preceding comma (,) immediately with the next. If any space character
is present around the commas, it will be considered part of the respective
token. So if more than one token has space characters within it, the safest
method to specify a value to this option is to put double quotation marks
around each individual token that needs it. Note that without double
quotation marks, space characters will be seen as option separators and can
lead to undefined behavior.
(=STR) Write a keyword to the header. For the possible value input formats, comments and units for the keyword, see the --update option above.
(=STR) Add a HISTORY keyword to the header. The string
given to this keyword will be separated into multiple keyword cards if
it is longer than 70 characters. With each run only one value for the
--history option will be read. If there are multiple, it is
the last one.
(=STR) Add a COMMENT keyword to the header. Similar to
the explanation for --history above.
Put the current date and time in the header. If the DATE
keyword already exists in the header, it will be updated.
Quit if any of the operations above are not successful. By default if an error occurs, Header will warn the user of the faulty keyword and continue with the rest of actions.
Some tricky
situations arise with values like ‘87095e5’, if this was intended
to be a number it will be kept in the header as 8709500000 and there
is no problem. But this can also be a shortened Git commit hash. In the
latter case, it should be treated as a string and stored as it is
written. Commit hashes are very important in keeping the history of a file
during your research and such values might arise without you noticing them
in your reproduction pipeline. One solution is to use git
describe instead of the short hash alone. A less recommended solution is
to add a space after the commit hash and Header will write the value as
‘87095e5 ’ in the header. If you later compare the strings on the
shell, the space character will be ignored by the shell in the latter
solution and there will be no problem.
GNU Astronomy Utilities 0.2.28-34fb manual, October 2016.