Edit datamodel file headers
dmhedit infile filelist operation key value [datatype] [unit] [comment]
[verbose]
Edits the header of a file in place, modifying the original
file. There are two ways to use dmhedit: specifying
parameters on the command line to change one keyword or with
an ASCII edit list file to modify several keywords at once.
The syntax for each method is illustrated in the EXAMPLES.
The edit list file can contain two kinds of lines, control
lines and edit lines. The control lines, which must begin
with a pound sign (#), specify what to do with the
edit lines that follow it. The valid control lines are:
-
"#add" : add a new keyword at
the end of the block header
-
"#delete" : remove an existing keyword
-
"#add after KEYNAME" : add a new keyword
after an existing one
-
"#move after KEYNAME" : move one existing
keyword to after another one
Anything other line beginning with a pound sign is treated
as a comment. Note that there may not be any blank lines in
the edit list file or the tool will complain; also, there may
not be a space between the pound sign and the command in the
control lines. A control line applies to all following
commands until a new control line is encountered.
Each edit line has the format
KEYNAME = value / [unit] comment
The entries must be space delimited, tabs are not allowed.
The unit and comment may be omitted; if both are omitted, the
slash following the value should be omitted as well. If the
value is a string value, it should be included in single
quotes.
Any string value that contains a forward slash
("/") must be enclosed in single quotes within
double quotes when setting the parameter,
i.e. value="'/this/is/a/string/'".
The tool can also add comments to the header (i.e. COMMENT and
HISTORY keywords). In this case, only the "key" and
"value" parameters are used, with the latter
containing the comment text. Since comments do not have
unique key names, it is not possible to delete existing ones.
Users should be aware that dmhedit can also set structural
FITS keywords which are normally hidden by the Data Model.
However, this is not recommended and can easily corrupt files.
dmhedit in.fits filelist=none operation=add key=LIVETIME value=123.3
datatype=indef
This is an example of using dmhedit to update a single
keyword. The default block of the input file is modified to
update the keyword LIVETIME with value 123.3 using the existing
datatype.
dmhedit in.fits none add NEWTIME "123.3 / [s] New time" datatype=double
Single key mode is again used to add the keyword NEWTIME with
double value 123.3, units of seconds, and the comment "New
time". This example shows how the value, unit, and
comment may all be included in the "value" parameter.
dmhedit in.fits none add LIVETIME 'some string value' datatype=string
The existing keyword LIVETIME (which has a double datatype) is
updated with a string value.
dmhedit in.fits none operation="add after OBJECT" key=AGNCLASS
value='Type 2 Seyfert' datatype=string
A new keyword, AGNCLASS, is added after the OBJECT key.
dmhedit in.fits none operation="move after DEC_NOM" key=RA_NOM
The order of RA_NOM and DEC_NOM is switched via the "move
after KEYNAME" operation. Since RA_NOM is an existing
keyword, it is not necessary to supply a value, datatype, etc.
dmhedit in.fits none add GAINFILE "'/path/name/gain.fits'" unit=''
comment='Gain file'
This shows the correct syntax when working with a string with
forward slashes in it (in this case, a directory path).
dmhedit in.fits edit.list
dmhedit is used in edit list mode to make multiple changes
with one command. The file "edit.list" might look
like:
#add
LIVETIME = 142.3 / [s] Live time
INSTRUME = 'HRC-S'
#delete
PHAMAX
#add
GAUSS.POWER = -1.8 / Power law index
Parameter=infile (file required filetype=input stacks=yes)
Input dataset
Input FITS file, or stack of files (see "ahelp
stack" for more information), with an optional FITS
extension in brackets, e.g. "filename.fits[GTI2]".
The same header edits are applied to all files in the stack.
An ASCII edit list file
A file containing control and edit lines, see the full
explanation in the DESCRIPTION. If set to "none" or
empty, dmhedit uses the " operation",
"key", and "value" parameter. If a
filelist is given and the other parameters are specified, the
filelist takes precedence.
Add/change or delete the key
Specifies what operation should be performed on the given
keyword. Valid options are "add" and
"delete". Use the "add" operation to update an
existing key.
Keyword to change
Name of the new keyword to add or an existing keyword to edit
or delete. The syntax
value="value / [unit] comment"
may be used to provide the value, unit, and comment at the
same time (e.g. value="45.89 / [ks] New time").
Value of the keyword that is being modified
Remember that string values which contain forwarded slashes
must be enclosed in single quotes within double quotes when
setting the parameter,
i.e. value="'/this/is/a/string/'".
Datatype of the keyword value
The datatype of the value when the "add" operation
is being used. Possibilities are "string",
"double", "float", "long",
"short", "ulong", "ushort",
"boolean", or "indef".
If "datatype=indef" and the keyword exists, the
datatype will be set to that of the existing keyword. If
"datatype" is set to anything else or a new key is
being added, the tool will attempt to write the keyword using
the specified datatype.
Any value can be written as a string, while only type-specific
numeric values can be written using the numeric datatypes. If
the value is a number and contains a decimal point, it will be
written as a double; otherwise, numbers are written as
short integers. If the value is not a number, it will be
written as a string. Allowed values to update a
boolean keyword are "T", "F",
"TRUE", and "FALSE", all case-insensitive.
Unit of the value
If there is a unit associated with the keyword value, it is
input via this parameter.
Keyword comment
A description of the keyword or other related comment.
Verbose level
Reports the input filenames and the key to be changed, as well
as any warnings.
Support for IRAF QPOE files has been removed from CIAO.
|
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}