Edits an NDF FITS extension via a text file or parameters
Control of the editing can be through parameters, or from a text file
whose format is described in topic "File Format"
.
"Update"
, "Write"
, and "Amend"
editing commands. A null
value (!
) gives a blank comment. The special value "$C"
means use the current
comment. In addition "$C(
keyword)"
requests that the comment of the keyword
given between the parentheses be assigned to the keyword being edited. If this
positional keyword does not exist, the comment is unchanged for "Update"
, and is
blank for a "Write"
edit. The same applies to the "Amend"
edit, the choice
depending on whether or not the KEYWORD keyword exists. "Amend"
–- acts as option "Update"
if the keyword exists, but as the "Write"
option should the keyword be absent.
"Delete"
–- removes a named keyword.
"Exist"
–- reports TRUE
to standard output if the named keyword exists in the
header, and FALSE
if the keyword is not present.
"Move"
–- relocates a named keyword to be immediately before a second keyword
(see Parameter POSITION). When this positional keyword is not supplied, it
defaults to the END card, and if the END card is absent, the new location
is at the end of the headers.
"Null"
nullifies the value of the named keyword. Spaces substitute the
keyword’s value.
"Print"
–- causes the value of a named keyword to be displayed to standard
output. This will be a blank for a comment card.
"Rename"
–- renames a keyword, using Parameter NEWKEY to obtain the new
keyword.
"Update"
–- revises the value and/or the comment. If a secondary keyword is
defined explicitly (Parameter POSITION), the card may be relocated at the
same time. If the secondary keyword does not exist, the card being edited
is not moved. "Update"
requires that the keyword being edited exists.
"Write"
–- creates a new card given a value and an optional comment. Its
location uses the same rules as for the "Move"
command. The FITS extension
is created first should it not exist.KEYWORD = LITERAL (Read)
The keywords " "
, "COMMENT"
, and "HISTORY"
are comment cards and do not have a
value.
The keyword must exist except for the "Amend"
, "Write"
, and "Exist"
commands.
Both KEYWORD and POSITION keywords may have an occurrence specified in brackets []
following the name. This enables editing of a keyword that is not the first occurrence
of that keyword, or locate a edited keyword not at the first occurrence of the
positional keyword. Note that it is not normal to have multiple occurrences
of a keyword in a FITS header, unless it is blank, COMMENT or HISTORY. Any
text between the brackets other than a positive integer is interpreted as the
first occurrence.
"File"
, which uses a text file;
and "Interface"
which uses parameters. ["Interface"]
"Rename"
. A name may be compound to handle hierarchical
keywords, and it has the form keyword1.keyword2.keyword3 etc. The maximum number of
keywords per FITS card is twenty. Each keyword must be no longer than eight
characters, and be a valid FITS keyword comprising only alphanumeric characters,
hyphen, and underscore. The new keywords are inserted immediately before each corresponding position keyword.
If any name in it does not exist in FITS array, or the null value (!
) is supplied the
consequences will be as follows. For a "Write"
, "Amend"
(new keyword), or "Move"
edit,
the KEYWORD keyword will be inserted just before the END card or appended to FITS array
when the END card does not exist; for an "Update"
or "Amend"
(new keyword) edit, the
edit keyword is not relocated.
A positional keyword is only accessed by the "Move"
, "Amend"
, "Write"
, and "Update"
editing commands.
TRUE
value is supplied for READONLY, the NDF is
opened for reading only. An error will then be reported if any of the requested
editing operations would change the contents of the NDF. If a FALSE
value is
supplied for READONLY, the NDF is opened for both reading and writing, but an
error will be reported if the NDF file is write-protected on disk. If the MODE
parameter is set to "File"
, the dynamic default value for READONLY is FALSE
. If
MODE is set to "Interface"
, the dynamic default value for READONLY depends on
the value of the EDIT parameter: TRUE
for "Print"
and "Exist"
, and FALSE
for
all other editing commands. []
FALSE
, inferred data typing is used for the "Write"
, "Update"
, and "Amend"
editing commands. So for instance, if Parameter VALUE = "Y"
, it would appears
as logical TRUE
rather than the string ’Y ’
in the FITS header. See
topic "Value Data Type"
. When STRING is TRUE
, the value will be treated as a
string for the purpose of writing the FITS header. [FALSE]
"File Format"
. For illustrations, see under
"Examples of the File Format"
. "Update"
, "Write"
, and "Amend"
editing commands. The
special value "$V"
means use the current value of the KEYWORD keyword. This
makes it possible to modify a comment, leaving the value unaltered. In addition
"$V(
keyword)"
requests that the value of the reference keyword given between the
parentheses be assigned to the keyword being edited. This reference keyword must
exist and have a value for a "Write"
or "Amend"
(new keyword) edit; whereas the
FITS-header value is unchanged for "Update"
or "Amend"
(keyword exists) if there
are problems with this reference keyword. "Exist"
operation (see Parameter
EDIT). TRUE
or FALSE
depending on whether or not the FITS keyword BSCALE exists in the FITS extension of
the NDF called dro42. "Airmass at
mid-observation"
. The header is located just before the end. The FITS extension
is created if it does not exist. "O’Leary"
, retaining its
old comment. The modified FITS extension lies within the NDF called obe. "27"
. There is no comment. The keyword is located at the
end of the headers, but before any END card. The FITS extension is created
if it does not exist. " Detector
name"
, the leading spaces are significant. The keyword is located at the current
position keyword. The FITS extension is created if it does not exist. fitstable.txt
. Requests to move, assign values or comments, the following reserved keywords in the FITS extension are ignored: SIMPLE, BITPIX, NAXIS, NAXISn, EXTEND, PCOUNT, GCOUNT, XTENSION, BLOCKED, and END.
When an error occurs during editing, warning messages are sent at the normal reporting level, and processing continues to the next editing command.
The FITS fixed format is used for writing or updating headers, except for double-precision
values requiring more space. The comment is delineated from the value by the string " /
"
.
The comments in comment cards begin one space following the keyword or from column 10 whichever is greater.
To be sure that the resultant FITS extension is what you desired, you should inspect it using the command FITSLIST before exporting the data. If there is something wrong, you may find it convenient to use command FITSEDIT to make minor corrections.
"Update"
and "Write"
edits
require the most time. !
or #
are treated
as comments. Note that the order does matter, as the edits are performed in the order
given.
The format is summarised below:
command keyword{[occurrence]}{(keyword{[occurrence]})} {value {comment}}
where braces indicate optional values, and occur is the occurrence of the keyword. In effect there are four fields delineated by spaces that define the edit operation, keyword, value and comment.
Field 1: This specifies the editing operation. Allowed values are Amend
, Delete
, Exist
,
Move
, Null
, Print
, Rename
, Write
, and Update
, and can be abbreviated to the initial
upper-case letter. It is not case insensitive to afford some protection against typing
errors.
Delete
removes a named keyword.
Read
causes the value of a named keyword to be displayed to standard output.
Exist
reports TRUE
to standard output if the named keyword exists in the header, and
FALSE
if the keyword is not present.
Move
relocates a named keyword to be immediately before a second keyword. When this
positional keyword is not supplied, it defaults to the END card, and if the END card is
absent, the new location is at the end of the headers.
Write
creates a new card given a value and an optional comment. Its location uses the
same rules as for the Move
command.
Update
revises the value and/or the comment. If a secondary keyword is defined
explicitly, the card may be relocated at the same time. Update
requires that the
keyword exists.
Amend
acts like Update
if the keyword supplied in "Field 2"
exists, and like Write
otherwise.
Null
replaces the value of a named keyword with blanks.
Field 2: This specifies the keyword to edit, and optionally the position of that
keyword in the header after the edit (for Move
, Write
, Update
, and Amend
edits). The
new position in the header is immediately before a positional keyword, whose name is
given in parentheses concatenated to the edit keyword. See "Field 1"
for defaulting
when the position parameter is not defined or is null.
Both the editing keyword and position keyword may be compound to handle hierarchical keywords. In this case the form is keyword1.keyword2.keyword3 etc. All keywords must be valid FITS keywords. This means they must be no more than eight characters long, and the only permitted characters are uppercase alphabetic, numbers, hyphen, and underscore. Invalid keywords will be rejected.
Both the edit and position keyword may have an occurrence specified in brackets []
.
This enables editing of a keyword that is not the first occurrence of that keyword, or
locate a edited keyword not at the first occurrence of the positional keyword. Note
that it is not normal to have multiple occurrences of a keyword in a FITS header,
unless it is blank, COMMENT or HISTORY. Any text between the brackets other than a
positive integer is interpreted as the first occurrence.
Use a null value (’ ’
or " "
) if you want the card to be a comment with keyword other
than COMMENT or HISTORY. As blank keywords are used for hierarchical keywords, to write
a comment in a blank keyword you must give a null edit keyword. These have no
keyword appearing before the left parenthesis or bracket, such as ()
, []
, [2]
, or
(EPOCH)
.
Field 3: This specifies the value to assign to the edited keyword in the Write
, Update
,
and Amend
operations, or the name of the new keyword in the Rename
modification. If the
keyword exists, the existing value or keyword is replaced, as appropriate. The data
type used to store the value is inferred from the value itself. See topic "Value Data
Type"
.
For the Update
, Write
, and Amend
modifications there is a special value, $V
, which means
use the current value of the edited keyword, provided that keyword exists. This makes
it possible to modify a comment, leaving the value unaltered. In addition $V(
keyword)
requests that the value of the keyword given between the parentheses be assigned to the
keyword being edited.
The value field is ignored when the keyword is COMMENT, HISTORY or blank, and the
modification is to Update
, Write
, or Amend
.
Field 4: This specifies the comment to assign to the edited keyword for the Write
,
Update
, and Amend
operations. A leading "/"
should not be supplied.
There is a special value, $C
, which means use the current comment of the edited keyword,
provided that keyword exists. This makes it possible to modify a value, leaving the
comment unaltered. In addition $C(
keyword)
requests that the comment of the keyword
given between the parentheses be assigned to the edited keyword.
To obtain leading spaces before some commentary, use a quote (’
) or double quote ("
) as
the first character of the comment. There is no need to terminate the comment with a
trailing and matching quotation character. Also do not double quotes should one form
part of the comment.
For the text-file, values enclosed in quotes (’
) or doubled quotes ("
) are strings.
Note that numeric or logical string values must be quoted to prevent them being
converted to a numeric or logical value in the FITS extension.
For prompting the value is a string when Parameter STRING is TRUE
.
Otherwise type conversions of the first word after the keywords are made to integer, double precision, and logical types in turn. If a conversion is successful, that becomes the data type. In the case of double precision, the type is set to real when the number of significant digits only warrants single precision. If all the conversions failed the value is deemed to be a string.
TRUE
or
FALSE
to standard output. "Y"
. "Following values apply to mid-observation"
. Note the full stop. "Dr. Peter O’Leary"
, and comment "Name of principal observer"
.
Note that had the value been enclosed in single quotes (’), the apostrophe would
need to be doubled. "A User’s Guide for the Flexible Image Transport System (FITS)", NASA/Science Office of Science and Technology (1994).