9 NDF Sections

 9.1 Specifying Lower and Upper Bounds
 9.2 Specifying Centre and Extent
 9.3 Using World or Axis Co-ordinates to Specify Sections
 9.4 Specifying Fractional Extents
 9.5 Changing Dimensionality
 9.6 Mixing Bounds Expressions

You will frequently want to examine or process only a portion of your dataset, be it to focus on a given object in an image, or a single spectrum between nominated wavelengths, or a plane of a cube. You could use NDFCOPY or MANIC in some circumstances to make a new NDF containing the required data, but this would be inconvenient as you would need more disc space, and to invent and remember a new filename. You will be pleased to learn that there is a succinct and powerful alternative that obviates the need to create a new file—the NDF section. The application just processes a ‘rectangular’ subset, or section, of the NDF that you nominate. Certainly, it requires you to learn a little syntax, but after you use it a few times it will seem cheap at the price for the advantages it offers.

An NDF section is defined by specifying the bounds of the portion of the NDF to be processed immediately following the name of the NDF. You can do this in any place where an NDF name alone would suffice, for example, on the command line or in response to a prompt or as a default in an interface file. The syntax is a series of subscripts within parentheses and may be given in several ways. Here is a simple example.

  ICL> stats cluster(101:200,51:150)

This would derive statistics of a 100×100-pixel region starting at pixel indices (101, 51) in the NDF called cluster. Alternatively, ranges of axis co-ordinates may be given instead of pixel indices. Besides giving lower and upper bounds as above, you may specify a centre and extent. Sections are not limited to subsets—supersets are allowed. See the paragraphs below for more details of these features.

If you do want to make a new NDF from a portion of an existing one, you should use the command NDFCOPY. An NDF’s shape may be changed in situ by SETBOUND.

Note if you supply an NDF section on a C-shell command line, you must escape the parentheses. For example, the following are both equivalent to the earlier example.

  % stats cluster"(101:200,51:150)"
  % stats cluster\(101:200,51:150\)

9.1 Specifying Lower and Upper Bounds

The subscript expression appended to an NDF name to specify a section may be given in several ways. One possible method (corresponding with the example above) is to give the lower and upper bounds in each dimension, as follows

  NAME( a:b, c:d, ... )

where ‘a:b’, ‘c:d’, (etc.) specify the lower and upper bounds. The bounds specified need not necessarily lie within the actual bounds of the NDF, because bad pixels (see Section 15) will be supplied in the usual way, if required, to pad out the NDF’s array components whenever they are accessed. However, none of the lower bounds should exceed the corresponding upper bound.

Omitting any of the bounds from the subscript expression will cause the appropriate (lower or upper) bound of the NDF to be used instead. If you also omit the separating ‘:’, then the lower and upper bounds of the section will both be set to the same value, so that a single pixel will be selected for that dimension. Omitting the bounds entirely for a dimension (but still retaining the comma) will cause the entire extent of that dimension to be used. Thus,

  image(,64)

could be used to specify row 64 of a two-dimensional image, while

  cube( 1, 257:, 100 )

would specify column 1, pixels 257 onwards, selected from plane number 100 of a three-dimensional ‘data cube’, forming a one-dimensional section.

9.2 Specifying Centre and Extent

An alternative form for the subscript expression involves specifying the centre and extent of the region required along each dimension, as follows

  name( p~q, r~s ... )

where ‘p q’, ‘r s’, (etc.) specify the centre and extent respectively. The extent must be positive. Thus,

  name(100~11,200~5)

would refer to an 11×5-pixel region of an image centred on pixel (100, 200).

If the value before the delimiting ‘ ’ is omitted, it will default to the index of the central pixel in that dimension (rounded downwards if there are an even number of pixels). If the value following the ‘ ’ is omitted, it will default to the number of pixels in that dimension. Thus,

  image( ~100, ~100)

could be used to refer to a 100×100-pixel region located centrally within an image, while

  image( 10~, 20~ )

would specify a section that is the same size as the original image, but displaced so that it is centred on pixel (10, 20).

9.3 Using World or Axis Co-ordinates to Specify Sections

Not only can you specify sections in terms of pixel indices but also in terms of more-tangible co-ordinates such as right ascension and declination, wavelength, frequency, and time. Section locations in such world co-ordinate systems (WCS) (see Section 12) are indicated by non-integer values; whereas integer values in an NDF section are intepreted as pixel indices. Here an integer value is defined as one neither containing a decimal point nor an exponent. The WCS bounds of each section are converted to the nearest pixel indices in order to specify the included data elements.

Since there may be many co-ordinate systems that could represent your desired section, some rules are necessary to decide how to interpret the section limits. First, to retain backwards compatibility (with pre-V1.8 Kappa), if your NDF has AXIS components then non-integer values will refer to axis co-ordinates (see “Co-ordinate Frames, Axes and Domains” for a description). Otherwise the values are specified within the co-ordinate system represented by the current Frame in the NDF’s FrameSet . Command NDFTRACE will show whether or not an NDF has AXIS components, and if so, it reports their extents, labels, and units. NDFTRACE also summarises the properties of the current WCS Frame (or optionally all the WCS Frames present), if the NDF has a WCS component. You can change the current Frame with WCSFRAME.

9.3.1 World co-ordinates:

The standard formats used to specify WCS co-ordinates apply.See SUN/210 AST_UNFORMAT sections “Frame Input Format” and“SkyFrame Input Format” for details and examples.

Here are some examples of WCS co-ordinates defining NDF sections.

  spectrum(9000:2E4)

This could specify a region of a spectrum between 9000 and 20000 Ångstrom.

  image(12h59m49s~4.5m,27.5d:28d29.8m)

This could refer to a region approximately one degree on each side centred the Coma Cluster. The section is 4.5 minutes of time along the right-ascension axis centred at 12h59m49s , and extends from +27°30′ to +28°29′48′′ in declination.

  ifu(1h34m10.1s:1h34m12.4s,-2d35m:-2d35.5m,6563)

This might specify a region of sky 2.3 seconds of time by 0.5 arcminutes in Hα light from an integral-field unit.

It is possible to use a colon to separate the fields in sexagesimal celestial and time co-ordinates, as in the following example that defines the equivalent section as the preceding Coma Cluster example.

  image(12:57:34;13:02:04,27:30:00;28:29:48)

There is a cost; you must use a semicolon to demarcate lower and upper bounds. This is to enable differentiation of the two uses of the colon.

Using the colon as co-ordinate field separator can leave some degree of ambiguity. For instance, a subscript expression of “12:34” could mean “use pixel indices 12 to 34”, or could mean “use the single declination value 12:34”. It is also harder to read, is an extra rule to remember, and could be error prone. For these reasons, the strong recommendation is to use the dms and hms notation for celestial and time co-ordinates.

Even given no sky co-ordinate range as in this example,

  cube(12:34:56.7,-41:52:09,-100.0;250.0)

do not mix colons for the two uses in the same expression. Hence there is a semicolon to define the range in the third co-ordinate. The semicolon expression delimiter works with all classes of co-ordinate system. This example might extract a spectrum from a cube at the right ascension 12h34m56.7s declination −41°52′9′′ between 100 and 250 km s1 velocity.

You should also be aware that the non-integer co-ordinates within an NDF section apply to WCS axes, in contrast to integer bounds that define pixel indices along pixel axes. These are not necessarily the same. For example, the WCS axes may be rotated or permuted. If the WCS axes are rotated, the NDF section actually used will be a box just large enough to hold the requested range of WCS-axis values. Be careful.

9.3.2 Axis co-ordinates:

For axis co-ordinates double-precision arithmetic is used to process the section values, but either double- or single-precision notation may be used when supplying them. Both linear and non-linear axis co-ordinates are supported, the values supplied being automatically converted into the corresponding pixel indices before use. For instance,

  spectrum(6500.0:7250.0)

could be used to select the appropriate region of a spectrum calibrated in Ångstroms, while

  spectrum(6000.0~500.0)

would select a region of the spectrum approximately from 5750 to 6250.0 Ångstroms (the exact extent depending the values of the axis co-ordinates), and

  spectrum(5500.0~21)

would select a 21-pixel-wide region of the spectrum centred on 5500 Ångstroms.

9.4 Specifying Fractional Extents

A further form for the subscript expression involves specifying a fractional position along each dimension as a percentage, as follows

  name( p%~q%, r%:s%, ... )

where ‘p% q%’ specifies the centre and extent as percentages, and ‘r%:s%’ specifies a percentage range. Thus,

  image(25%:75%,50%:~50%)

would refer to the central quarter of the image. Both sections are equivalent. The percentages are converted to the nearest pixel centre to decide the centre and extents of the sections.

The rules concerning omitted values before or after the delimiting apply. Thus,

  image(40%~, ~50%)

could be used to refer to a full-width, half-height section centred at the (40%, 50%) fractional position.

A percentage value is not limited to the range 0–100%. In such circumstances the areas beyond the bounds of the NDF are set to bad. For example,

  image(~110%, -5%:105%)

would give an enclosing border of bad pixels, extending 5% of the original dimensions. Both sections are equivalent.

9.5 Changing Dimensionality

The number of dimensions given when specifying an NDF section need not necessarily correspond with the actual number of NDF dimensions, although usually it will do so.

If you specify fewer dimensions than there are NDF dimensions, then any unspecified bounds will be set to (1:1) for the purposes of identifying the pixels to which the section should refer. Conversely, if extra dimensions are given, then the shape of the NDF will be padded with extra bounds set to (1:1) in order to match the number of dimensions. In all cases, the resulting section will have the number of dimensions you have actually specified, the padding serving only to identify the pixels to which the section should refer.

In Kappa there are a number of applications that can only handle a fixed number of dimensions (e.g. DISPLAY, LINPLOT, MEDIAN). NDF sections permit such applications to have wider applicability, since the applications can operate on full NDFs of arbitrary dimensionality. So for instance, DISPLAY could show planes of a datacube.

9.6 Mixing Bounds Expressions

In the last example (in Section 9.3) both axis co-ordinates and pixel indices were mixed in the same subscript expression. In fact, any of the features described earlier may be combined when specifying an NDF section, the only restrictions are as follows.

(1)
When the shape of the resulting section is expressed in pixel indices, the lower bound must not exceed the upper bound in any dimension.
(2)
If the bounds for an axis are specified by centre and width values (rather than as lower and upper bounds), then a WCS value should not be used with a pixel index. That is, the centre and width values must both refer to the same co-ordinate system.

Thus, all the following might be used as valid specifications for NDF sections

  ndf(3.7)
  ndf(,5:)
  ndf(-77:01h23m45s,,4)
  ndf(66~9,4:17)
  ndf(~5,6~)
  ndf(~,:)
  ndf(5500.0~150,)
  ndf(2.137~10%)
  ndf(3.0~1.5,-78.06D-3:13.0545,,,,)

Many other combinations are obviously possible. In cases where some bounds are given in pixel indices and some in WCS co-ordinates, two boxes will be formed; one representing the pixel-index bounds and one representing the WCS bounds. The actual NDF section used will be the overlap of the two boxes. The pixel box will inherit any pixel index limits supplied in the bounds expression, and will use default values for any missing limits. These default pixel-index bounds are just the bounds of the full NDF. Likewise, the WCS box will inherit any WCS limits supplied in the bounds expression, and will use default values for any missing limits. The default WCS limits are the bounds of a box that just includes the whole pixel box.