STScI Logo

hselect images.imutil



hselect - extract keyword values from images satisfying a selection expression


hselect images fields expr


Images forming the set from which selected images are to be drawn.
Comma separated list of keywords or keyword patterns to be extracted from each selected image. The list elements are matched against the set of keywords in the header except for those beginning with "$" which are special values or explicit checks for keywords that might be missing.
The boolean expression to be used as the selection criteria. The expression is evaluated independently for each image.
missing = "INDEF"
Output value for missing keywords. Note that this will only occur when the fields are specified with leading "$".


The function of hselect is to extract keyword values from a subset of images satisfying a boolean selection expression. The resultant table of keyword values is output in list form, suitable for further analysis or for use to generate a list of images to be processed by another task.

The form of the boolean expression expr is fully documented in the manual page for the hedit task. In the case of hselect task, however, the expression need not be parenthesized to be evaluated as an expression.

The keywords whose values are to be output are specified by the fields parameter. This is a comma delimited list of keywords and patterns. The keywords and patterns are matched against the set of keywords in the image. Of particular importance is that explicit keywords, that is without any wildcard, are matched against the header and so if the keyword is not in the header then the keyword value is not output. If one wants to explicitly output a place holder for a missing keyword use a leading $; e.g. $mykey. If the keyword is absent then the value given by the missing parameter will be output. This is useful when scanning the output.

In addition to escaping the keyword matching, the leading $ character is also used to select special values such as "$I" for the name of the current image. See hedit for more on the special values and pattern syntax.


1. Compute the mean exposure time for all the images in a database. Note that the argument "yes" is a trivial case of a general boolean expression and hence need not be quoted.

cl> hselect n1.* exp yes | average

2. Print the name, length of axes 1 and 2, and title of all two dimensional images in a database.

	cl> hselect n1.* $I,naxis[12],title 'naxis == 2'
	n1.0001	512	512	quartz
	n1.0002 512	512	"dome flat"
	n1.0005 384	800	"ngc 3127 at 45 degrees"

3. Produce an image name list for use to drive another task. The selection criterium is all images for which the value of the parameter "q-flag" has the value 1. Note carefully the use of quotes. If the @ operator is unfamiliar read the manual page for hedit .

cl> hselect n1.* $I @"q-flag" == 1 > imlist

If the parameter "q-flag" were instead named "qflag", the following simpler expression would suffice.

cl> hselect n1.* $I qflag == 1 > imlist

4. Scan a set of keyword and allow for missing keywords.

	cl> hselect pix $I,$exptime,$airmass yes missing=INDEF |
	>>> scan (s1, x, y)

Note that when checking for missing values the missing value must be of the appropriate type or else you need to use string variables or nscan to check. The default missing value is "INDEF" which can be scanned into both string and numerical variables.


Since individual image headers are currently stored as separate files, selection from a large database is quite slow.


hedit, imgets, imheader

Source Code · Search Form · STSDAS