The meta-data in each header data unit, or HDU (also known as extension, see Fits) is stored as “keyword”s. Each keyword consists of a name, value, unit, and comments. The Fits program (see Fits) options related to viewing and manipulating keywords in a FITS HDU are described below.
To see the full list of keywords in a FITS HDU, you can use the --printallkeys option. 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 or HDU, it is easiest to create a copy first and then run Fits 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.
The precedence of operations are described below. 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 Fits won’t stop until all the operations are complete. If --quitonerror is called, then Fits will immediately stop upon the first error.
If you want to inspect only a certain set of header keywords, it is easiest to pipe the output of the Fits program 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:
$ astfits input.fits | grep NAXIS
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.
The keyword related options to the Fits program are fully described below.
Write STR 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 (on the command-line or in scripts):
$ key=$(astfits firstimage.fits | grep KEYWORD) $ astfits --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
quoted, 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 \.
Delete one instance of the STR keyword from the FITS header. Multiple instances of --delete can be given (possibly even for the same keyword, when its repeated in the meta-data). All keywords given will be removed from the headers in the same given order. If the keyword doesn’t exist, Fits will give a warning and return with a non-zero value, but will not stop. To stop as soon as an error occurs, run with --quitonerror.
Rename a keyword to a new value. STR contains both the existing and new names, which 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. If the keyword doesn’t exist, Fits will give a warning and return with a non-zero value, but will not stop. To stop as soon as an error occurs, run with --quitonerror.
Update a keyword, its value, its comments and its units in the format described below. 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
If there is a writing error, Fits will give a warning and return with a non-zero value, but will not stop. To stop as soon as an error occurs, run with --quitonerror.
The value can be any numerical or string value61. Other than the
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.
Write a keyword to the header. For the possible value input formats, comments and units for the keyword, see the --update option above.
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. If there is
an error, Fits will give a warning and return with a non-zero value, but
will not stop. To stop as soon as an error occurs, run with
COMMENT keyword to the header. Similar to the explanation for
--history above. If there is a writing error, Fits will give a
warning and return with a non-zero value, but will not stop. To stop as
soon as an error occurs, run with --quitonerror.
Put the current date and time in the header. If the
already exists in the header, it will be updated. If there is a writing
error, Fits will give a warning and return with a non-zero value, but will
not stop. To stop as soon as an error occurs, run with
Print all the keywords in the specified FITS extension (HDU) on the command-line.
Quit if any of the operations above are not successful. By default if an error occurs, Fits will warn the user of the faulty keyword and continue with the rest of actions.
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
describe instead of the short hash alone. A less recommended solution is
to add a space after the commit hash and Fits 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.