Description
This task allows the user to manipulate metadata associated with a CASA image. Both float and complex valued images are fully supported.
NOTE: For measurement sets, the task vishead should be used.
The supported mode values are:
Values |
Description |
---|---|
add | Add a new metadata value to the image. |
del | Delete a key or reset its value to a fidicual value if possible. Ignores hdvalue parameter. |
get | Return the specified keyword value. Ignores the hdvalue parameter. |
history | Log image history. Ignores the hdkey and hdvalue parameters. |
list | Show supported keywords and their values. Ignores the hdkey and hdvalue parameters. |
put | Modify the specified value associated with the keyword using the specified value. |
summary | Log a summary of the image and return a dictionary of various metadata values. Ignores the hdkey and hdvalue parameters. |
See below for details about how these modes act for specific keywords.
ALERT: Only limited checking is implemented to ensure modifying a specific value will leave the image metadata in a consistent state, so, if one is not careful, one could end up with an image that has an inconsistent set of metadata and is therefore, nonsensical and useless.
That is, PROCEED AT YOUR OWN RISK when using modes add, del, or put.
Notes for mode='list'
Supported keywords can be listed using mode='list'
Values | Description |
---|---|
beammajor/bmaj | Major axis of the clean beam |
beamminor/bmin | Minor axis of the clean beam |
beampa/bpa | Position angle of the clean beam. NOTE: If the image contains multiple beams, use mode='summary' to list them with verbose=True. |
bunit | Image units (K, Jy/beam, etc) |
cdeltn | Pixel size, nth axis. n is one-based. |
crpixn | The pixel designated as the reference location, nth axis n is one-based. |
crvaln | World coordinate value of the reference pixel for the nth axis. n is one-based. |
ctypen | Name of nth axis. n is one-based. |
cunitn | Units of nth axis. n is one based. |
datamax | Maximum pixel value. |
datamin | Minimum pixel value. |
date-obs | Date (epoch) of the observation. |
equinox | Direction reference frame. |
imtype | Image type (eg Intensity) |
minpos | World coordinate position of minimum pixel value. |
minpixpos | Pixel coordinate position of minimum pixel value. |
maxpos | World coordinate position of maximum pixel value. |
maxpixpos | Pixel coordinate position of maximum pixel value. |
object | Source name |
observer | Observer name |
projection | Direction coordinate projection (eg 'SIN','TAN', or 'ZEA'). |
reffreqtype | Spectral reference frame. |
restfreq | Rest Frequency. |
shape | Number of pixels along each axis. |
telescope | Telescope name. |
Notes for mode='add'
The behavior of mode='add' depends on the keyword. Below is a summary of the per keyword behavior of this mode. In general, the return value will be True if the operation succeeds, or False if it fails or is not supported. If unsuccessful or not supported, a message is normally logged which describes the failure. In most cases, you probably want to use mode='put' rather than mode='add'. We continue to support mode='add' mainly for backward compatibility.
Values | Description |
---|---|
beammajor or bmaj | If image has no beam(s), a single, global, circular beam of diameter specified in hdvalue is added. hdvalue must be a valid angular quantity (string or dictionary) or the operation will fail and False will be returned. If the image has a beam(s), the operation fails and False is returned. Examples of acceptable values of hdvalue are "4arcsec", qa.quantity("4arcsec"), {'unit': 'arcsec', 'value': 4.0}. If you wish an image to have multiple beams, use ia.setrestoringbeam(). |
beamminor or bmin | Behavior is the same as that for beammajor or bmaj. |
beampa or bpa | Operation has no effect and always returns false. If you wish to add a beam, use beammajor, bmaj, beamminor, or bmin. |
bunit | If image has no brightness unit, add the value specified in hdvalue which must be a unit supported by CASA. Else do nothing and return False. |
cdelt* | No effect. Addition of coordinate system parameters is not supported. Always returns False. Use the cs tool to add coordinates. |
crpix* | No effect. Addition of coordinate system parameters is not supported. Always returns False. Use the cs tool to add coordinates. |
crval* | No effect. Addition of coordinate system parameters is not supported. Always returns False. Use the cs tool to add coordinates. |
ctype* | No effect. Addition of coordinate system parameters is not supported. Always returns False. Use the cs tool to add coordinates. |
cunit* | No effect. Addition of coordinate system parameters is not supported. Always returns False. Use the cs tool to add coordinates. |
datamax | No effect. Addition of statistical parameters is not supported. |
datamin | No effect. Addition of statistical parameters is not supported. |
date-obs or epoch | No effect. |
equinox | No effect. |
imtype | If image type does not exist, add the type specified in hdvalue. hdvalue must be one of "Undefined", "Intensity", "Beam", "Column Density", "Depolarization Ratio", "Kinetic Temperature", "Magnetic Field", "Optical Depth", "Rotation Measure", "Rotational Temperature", "Spectral Index","Velocity", or "Velocity Dispersion". |
masks | No effect. Addition of masks is not supported. Use ia.calcmask(). |
maxpos | No effect. Addition of statistical parameters is not supported. |
maxpixpos | No effect. Addition of statistical parameters is not supported. |
minpos | No effect. Addition of statistical parameters is not supported. |
minpixpos | No effect. Addition of statistical parameters is not supported. |
object | If image has no object, add the value specified in hdvalue. Else do nothing and return False. |
observer | If image has no observer, add the value specified in hdvalue. Else do nothing and return False. |
projection | No effect. |
reffreqtype | No effect. |
restfreq | If image has a spectral coordinate and no rest frequency, set the rest frequency to the value specified in hdvalue. This value must be a valid CASA quantity with frequency units. Else do nothing and return False. Examples of valid values are "1GHz", qa.quantity("1GHz"), {'unit': 'GHz', 'value': 1.0} |
shape | No effect. |
telescope | If image has no telescope, add the value specified in hdvalue. Else do nothing and return False. |
any user defined keyword | Add the key-value pair if the key does not exist. Else do nothing and return False. |
Notes for mode='del'
The behavior of mode='del' depends on the keyword. Below is a summary of the per keyword behavior of this mode. In general, the return value will be True if the operation succeeds, or False if it fails or is not supported. If unsuccessful or not supported, a warning message is normally logged which describes the failure.
Values | Description |
---|---|
beammajor or bmaj | Deletes all beams. Returns False if the image has no beams. |
beamminor or bmin | Deletes all beams. Returns False if the image has no beams. |
beampa or bpa | Deletes all beams. Returns False if the image has no beams. |
bunit | Sets the associated value to the empty string. |
cdelt* | No effect. Deletion of coordinate system parameters is not supported. |
crpix* | No effect. Deletion of coordinate system parameters is not supported. |
crval* | No effect. Deletion of coordinate system parameters is not supported. |
ctype* | No effect. Deletion of coordinate system parameters is not supported. |
cunit* | No effect. Deletion of coordinate system parameters is not supported. |
datamax | No effect. Deletion of statistical parameters is not supported. |
datamin | No effect. Deletion of statistical parameters is not supported. |
date-obs or epoch | No effect. |
equinox | No effect. |
imtype | No effect. |
masks | Deletes the single mask specified in hdvalue, or if hdvalue='', deletes all masks. |
maxpos | No effect. Deletion of statistical parameters is not supported. |
maxpixpos | No effect. Deletion of statistical parameters is not supported. |
minpos | No effect. Deletion of statistical parameters is not supported. |
minpixpos | No effect. Deletion of statistical parameters is not supported. |
object | Sets the associated value to the empty string. |
observer | Sets the associated value to the empty string. |
projection | No effect. |
reffreqtype | No effect. |
restfreq | No effect. |
shape | No effect. |
telescope | Sets the associated value to the empty string. |
any user defined keyword | Deletes the key-value pair. |
Notes for mode='get'
The data type of the value returned by imhead when mode='get' depends on the keyword. Below is a list of keywords on the data type that will be returned when mode='get' for each. A "quantity dictionary" is a dictionary with 'value' and 'unit' keys that can be used as input to various methods of the qa tool.
Values | Description |
---|---|
beammajor or bmaj | quantity dictionary |
beamminor or bmin | quantity dictionary |
beampa or bpa | quantity dictionary |
bunit | string |
cdelt* | quantity dictionary |
crpix* | float |
crval* | quantity dictionary, unless the value for the stokes axis is requested in which case an array of strings is returned |
ctype* | string |
cunit* | string |
datamax | image pixel data type |
datamin | image pixel data type |
date-obs or epoch | string (YYYY/MM/DD/hh:mm:ss format) |
equinox | string |
imtype | string |
masks | string array |
maxpos | string |
maxpixpos | integer array |
minpos | string |
maxpixpos | integer array |
object | string |
observer | string |
projection | string |
reffreqtype | string |
restfreq | quantity dictionary |
shape | integer array |
telescope | string |
any user defined keword | string |
Notes for mode='put'
In general, mode='put' will modify the specified key to the specified value. True is returned if the metadatum was successfully modified, False otherwise. Normally, a diagnostic message is logged if there is a failure. Only the parameter specified is modified; e.g., no modification of reference direction occurs to implicitly account for precession to a new reference frame. The following are the exceptional cases for mode='put'.
Values | Description |
---|---|
beammajor or bmaj | Will always fail if image has multiple beams. Use ia.setrestoringbeam(). in this case. If image has no beam(s), a single, global, circular beam of diameter specified in hdvalue is added. hdvalue must be a valid angular quantity (string or dictionary) or the operation will fail and False will be returned. If the image has a single beam, the value of the major axis will be modified, unless the specified value is smaller than the minor axis of the existing beam, in which case nothing is modified and False is returned. Examples of acceptable values of hdvalue are "4arcsec", qa.quantity("4arcsec"), {'unit': 'arcsec', 'value': 4.0}. |
beamminor or bmin | Behavior is the same for bmaj, although of course if the image already has a single beam, the specified value must be less than the existing major axis value, or nothing is modified and False is returned. |
beampa or bpa | If the image does not already have a single beam, nothing is modified and False is returned. Angular units are required. |
bunit | Fails if hdvalue is not a supported CASA unit. |
cdeltn | One-based axis n must be less than or equal to the number of axes in the image. hdvalue type must be a number (in which case the unit of the corresponding axis is assumed) or a quantity (string or dictionary). If a quantity, the unit must conform to the existing axis unit. |
crpixn | One-based axis n must be less than or equal to the number of axes in the image. hdvalue type must be a number. Will fail if the polarization axis is specified. |
crvaln | One-based axis n must be less than or equal to the number of axes in the image. If not the polarization/stokes axis, hdvalue type must be a number (in which case the unit of the corresponding axis is assumed), a quantity (string or dictionary), or a valid measure format (such as a sexigesimal direction axis specification for an axis with angular units). If a quantity, the unit must conform to the existing axis unit. If the stokes/polarization axis, one must provide an array of stokes/polarization strings (eg, ["I", "Q", "XX"]) that is the same length as the stokes axis. If the stokes axis is degenerate, one can alternatively provide a string indicating the stokes value (eg "U"). |
ctypen | One-based axis n must be less than or equal to the number of axes in the image. hdvalue type must be a string. |
cunitn | One-based axis n must be less than or equal to the number of axes in the image. Specified unit must conform to the existing axis unit. Will fail if stokes/polarization axis is specified. |
datamax | This cannot be modified. False is always returned. |
datamin | This cannot be modified. False is always returned. |
date-obs or epoch | A valid time specification must be given. |
equinox | A valid direction reference frame specification string must be given. |
imtype | A CASA-supported image type string must be given or the image type will be set to 'Intensity' |
masks | Masks may not be modified. False is always returned. |
maxpos | This cannot be modified. |
maxpixpos | This cannot be modified. |
minpos | This cannot be modified. |
minpixpos | This cannot be modified. |
object | hdvalue must be a string. |
projection | hdvalue must be a string representing a supported CASA projection specification. |
reffreqtype | hdvalue must be a string representing a supported CASA velocity reference frame specification. |
restfreq | hdvalue can be a number (in which case frequency axis units are assumed) or a valid quantity string or quantity dictionary in which case the unit must conform to Hz. Only the active rest frequency may be modified. For more functionality, see cs.setrestfrequency(). |
shape | This cannot be modified. |
telescope | hdvalue must be a string. |
any user defined keyword | hdvalue can be practically any supported input parameter type. |