Previous: HDU information and manipulation, Up: Invoking astfits [Contents][Index]
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.
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 value90.
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.
Write a keyword to the header. For the possible value input formats, comments and units for the keyword, see the --update option above. The special names (first string) below will cause a special behavior:
Write a “title” to the list of keywords.
A title consists of one blank line and another which is blank for several spaces and starts with a slash (/).
The second string given to this option is the “title” or string printed after the slash.
For example with the command below you can add a “title” of ‘My keywords’ after the existing keywords and add the subsequent K1 and K2 keywords under it (note that keyword names are not case sensitive).
$ astfits test.fits -h1 --write=/,"My keywords" \
--write=k1,1.23,"My first keyword" \
--write=k2,4.56,"My second keyword"
$ astfits test.fits -h1
[[[ ... truncated ... ]]]
/ My keywords
K1 = 1.23 / My first keyword
K2 = 4.56 / My second keyword
END
Adding a “title” before each contextually separate group of header keywords greatly helps in readability and visual inspection of the keywords. So generally, when you want to add new FITS keywords, its good practice to also add a title before them.
The reason you need to use / as the keyword name for setting a title is that / is the first non-white character.
The title(s) is(are) written into the FITS with the same order that --write is called.
Therefore in one run of the Fits program, you can specify many different titles (with their own keywords under them).
For example the command below that builds on the previous example and adds another group of keywords named A1 and A2.
$ astfits test.fits -h1 --write=/,"My keywords" \
--write=k1,1.23,"My first keyword" \
--write=k2,4.56,"My second keyword" \
--write=/,"My second group of keywords" \
--write=a1,7.89,"First keyword" \
--write=a2,0.12,"Second keyword"
Write the given STR exactly as it is, into the given FITS file header with no modifications.
If the contents of STR does not conform to the FITS standard for keywords, then it may (most probably: it will) corrupt your file and you may not be able to open it any more.
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 complying with the FITS standard.
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 shell variable ($key).
This is because FITS keyword strings 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 \.
You can also use --asis to copy multiple keywords from one file to another.
But the process will be a little more complicated. So we’ll show the process as the simple shell script below.
You can customize it in the first block of variable definitions:
1) set the names of the keywords you want to copy: it can be as many keys as you want, just put a ‘\|’ between them.
2) The input FITS file (where keywords should be read from) and its HDU.
3) The output FITS file (where keywords should be written to) and its HDU.
4) Set a “title” for the newly added keywords in the output (so they are visually separate from the existing keywords in the output).
#!/bin/bash
# Customizations (input, output and key names).
# NOTE: put a '\|' between each keyword name.
keys="KEYa\|KEYb\|KEYc\|KEYd"
ifits=original.fits; ihdu=1
ofits=to_write.fits; ohdu=1
title="Keys from $ifits (hdu $ihdu)"
# Read keywords from input and write in output.
oIFS=$IFS
IFS=''
c="astfits $ofits -h$ohdu --write=/,\"$title\""
astfits $ifits -h$ihdu \
| grep $keys \
| (while read line; \
do c="$c --asis=\"$line\""; \
done; eval $c); \
IFS=$oIFS
Since its not too long, you can also simply put the variable values of the first block into the second, and write it directly on the command line (if its just for one time).
When nothing is given afterwards, the header integrity keywords DATASUM and CHECKSUM will be calculated and written/updated.
This is calculation and writing is done fully by CFITSIO.
They thus comply with the FITS standard 4.091 that defines these keywords (its Appendix J).
If a value is given (e.g., --write=checksum,MyOwnCheckSum), then CFITSIO won’t be called to calculate these two keywords and the value (as well as possible comment and unit) will be written just like any other keyword. This is generally not recommended, but necessary in special circumstances (for example when the checksum needs to be manually updated).
DATASUM only depends on the data section of the HDU/extension, so it is not changed when you update the keywords.
But CHECKSUM also depends on the header and will not be valid if you make any further changes to the header.
This includes any further keyword modification options in the same call to the Fits program.
Therefore it is recommended to write these keywords as the last keywords that are written/modified in the extension.
You can use the --verify option (described below) to verify the values of these two keywords.
Similar to checksum, but only write the DATASUM keyword (that doesn’t depend on the header keywords, only the data).
Add a HISTORY keyword to the header with the given value. A new HISTORY keyword will be created for every instance of this option. If the string given to this option is longer than 70 characters, it will be separated into multiple keyword cards. 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 --quitonerror.
Add a COMMENT keyword to the header with the given value.
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.
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.
Print all the keywords in the specified FITS extension (HDU) on the command-line. If this option is called along with any of the other keyword editing commands, as described above, all other editing commands take precedence to this. Therefore, it will print the final keywords after all the editing has been done.
Verify the DATASUM and CHECKSUM data integrity keywords of the FITS standard.
See the description under the checksum (under --write, above) for more on these keywords.
This option will print Verified for both keywords if they can be verified.
Otherwise, if they don’t exist in the given HDU/extension, it will print NOT-PRESENT, and if they cannot be verified it will print INCORRECT.
In the latter case (when the keyword values exist but can’t be verified), the Fits program will also return with a failure.
By default this function will also print a short description of the DATASUM AND CHECKSUM keywords.
You can suppress this extra information with --quiet option.
Copy the input’s keyword records in the given range (inclusive) to the output HDU (specified with the --output and --outhdu options, for the filename and HDU/extension respectively).
The given string to this option must be two integers separated by a colon (:). The first integer must be positive (counting of the keyword records starts from 1). The second integer may be negative (zero is not acceptable) or an integer larger than the first.
A negative second integer means counting from the end.
So -1 is the last copy-able keyword (not including the END keyword).
To see the header keywords of the input with a number before them, you can pipe the output of the FITS program (when it prints all the keywords in an extension) into the cat program like below:
$ astfits input.fits -h1 | cat -n
The HDU/extension to write the output keywords of --copykeys.
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.
Interpret the value of the given keyword in the FITS date format (most generally: YYYY-MM-DDThh:mm:ss.ddd...) and return the corresponding Unix epoch time (number of seconds that have passed since 00:00:00 Thursday, January 1st, 1970).
The Thh:mm:ss.ddd... section (specifying the time of day), and also the .ddd... (specifying the fraction of a second) are optional.
The value to this option must be the FITS keyword name that contains the requested date, for example --datetosec=DATE-OBS.
This option can also interpret the older FITS date format (DD/MM/YYThh:mm:ss.ddd...) where only two characters are given to the year.
In this case (following the GNU C Library), this option will make the following assumption: values 68 to 99 correspond to the years 1969 to 1999, and values 0 to 68 as the years 2000 to 2068.
This is a very useful option for operations on the FITS date values, for example sorting FITS files by their dates, or finding the time difference between two FITS files. The advantage of working with the Unix epoch time is that you don’t have to worry about calendar details (for example the number of days in different months, or leap years, etc).
If the argument has a WCS distortion, the output (file given with the --output option) will have the distortion given to this option (for example SIP, TPV).
With this option, the FITS program will read the minimal set of keywords from the input HDU and the HDU data, it will then write them into the file given to the --output option but with a newly created set of WCS-related keywords corresponding to the desired distortion standard.
If no --output file is specified, an automatically generated output name will be used which is composed of the input’s name but with the -DDD.fits suffix, see Automatic output. Where DDD is the value given to this option (desired output distortion).
Note that all possible conversions between all standards are not yet supported. If the requested conversion is not supported, an informative error message will be printed. If this happens, please let us know and we’ll try our best to add the respective conversions.
For example with the command below, you can be sure that if in.fits has a distortion in its WCS, the distortion of out.fits will be in the SIP standard.
$ astfits in.fits --wcsdistortion=SIP --output=out.fits
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 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.
https://fits.gsfc.nasa.gov/standard40/fits_standard40aa-le.pdf
Previous: HDU information and manipulation, Up: Invoking astfits [Contents][Index]
GNU Astronomy Utilities 0.14 manual, January 2021.