1.86. gridding

Full Name: herschel.hifi.dp.otf.GriddingTask
Alias: gridding
Type: Java Task - Java Task
Import: from herschel.hifi.dp.otf import GriddingTask
Category

HIFI/Analysis

Description

produces a cube of images from a HifiTimelineProduct,

makes a cube for each given subband (segment). The images are produced by performing two dimensional gridding of a number of spectra irregularly distributed over some area of the sky observed in a mapping mode. The spectra are read from a number of SpectrumContainers within an SpectrumContainerBox or from a single SpectrumContainer.

This task computes a regular grid that covers the region of the sky where the spectra have been observed.

For each pixel of that grid, the task computes a normalized convolution of those spectra which fall in the convolution kernel around such pixel.

The user can choose between assigning the same weight to every spectrum or using the weights computed by the generic part of the HIFI pipeline (i.e. use the weights columns of the HifiSpectrumDatasets).

Besides, the user has to choose between several type of filter functions to compute the contribution of each spectrum to each pixel, based on the distance of the spectrum to the centre of the kernel.

The user can also use an smoothing factor and provide some other parameters, e.g. to control the geometry of the regular grid and the range of channels to use to create the cube (i.e. to clip the wave range).

Examples

Example 1: make cube for first subband
subband = 1
cubesContext,cubes,cube,x,y,cTable=gridding(container=spectContainer,segments=Int1d([subband]),beam=Double1d([25.0]))
Example 2: make cubes for all the subbands, then Display the first one
cubesContext, cubes, cube, x, y, cTable = gridding(containerBox=spectrumContainerBox,beam=Double1d([25.0]))
cubesCount = len(cubes)
Display(cube)  # displays cube[0]
Example 3: make cubes for the subbands 1 and 3, then Display the first one
cubesContext, cubes, cube, xPoints, yPoints, convolutionTable  =
     gridding(containerBox=spectContainerBox, segments=Int1d([1,3]), beam=Double1d([25.0]))
cubesCount = len(cubes)
cube_subband_1 = cubes[0]
cube_subband_3 = cubes[1]
Display(cube)

API details

Properties

SpectrumContainer container [INPUT, OPTIONAL, default=no default value]

container of the spectra to be convolved into a regular grid to produce a cube of images.

SpectrumContainerBox containerBox [INPUT, OPTIONAL, default=no default value]

set of containers of spectra to be convolved into a regular grid to produce a cube of images.

Int1d subbands [INPUT, OPTIONAL, default=no default value]

specifies the subbands to be used, to produce a cube for each given subband of the input HifiTimelineProduct.

necessary only when the spectra in the given HifiTimelineProduct have several subbands.

Double beamSize [INPUT, OPTIONAL, default=No default value.]

Provides the antenna beam width, in arcseconds.

String weightMode [INPUT, OPTIONAL, default="equal"]

specifies how to assign spectral weights;

every channel of every spectrum receives its own weight.

The weighting strategies are:

  • "equal": all channels of all spectra have the same weight.

  • "selection": takes the "weight" column of the spectra.

Please note that for each spectrum, each channel can have a different weight so the weighting is done channel-wise.

Int2d channels [INPUT, OPTIONAL, default=empty by default]

by default, in this case all channels are selected for each segment (subband)

This parameter can be used to "crop" a part of spectral range.

For each segment, this Int2d has a row with two elements, the first element the start channel, and the second element specifies the last channel, i.e. the start and the end of the range of channels to be read per segment

Double1d mapSize [INPUT, OPTIONAL, default=Int2d(2,0) i.e. autocompute optimal]

this parameter may be used to specify the size of the map to be generated; the size is given along the x and y axes, in arc seconds.

When both sizes are equal, a Double1d with a single element can be provided.

Otherwise, this parameter array must contain two elements:

  • width of the map, size along the x axis

  • height of the map, size along the y axis

By default, this parameter is set to zero, in order to let algorithm choose the optimal map dimensions.

Double1d refPixel [INPUT, OPTIONAL, default=Double1d(2, 0.), i.e. autocompute]

specifies which is the reference pixel (in both axes), whose offset with regards to the projection centre is given by the (additional) parameter refPixelOffset

By default, this parameter is set to zero, to let the algorithm find the pixel coordinates of the point to which the spectra offsets are referred.

If both x- and y-axis values of the reference pixel are equal, a Double1d array with a single element can be provided.

Otherwise, this parameter must have two elements:

  • first element of the Double1d array specifies the value of the reference pixel in the x axis,

  • second element of the Double1d array specifies the value of the reference pixel in the y axis

This reference pixel is referred to the bottom most, left most pixel of the regular grid that covers the whole area to be mapped.

Please note that the referencePixel and the offset value at the reference pixel (aka refPixelOffsetValue) are correlated, the user cannot specify an arbitrary value for each of them.

Wcs wcs [INPUT, OPTIONAL, default=no default value]

Provide a WCS to perform the projection. In principle this might be used also to rotate the result cube, by using an input WCS with certain rotation angle (wcs.crota2 different from 0)."

Double1d refPixelCoordinates [INPUT, OPTIONAL, default=Double1d(2, 0.), i.e. autocompute]

specifies the coordinates of the reference pixel, in the x and y axes.

By default, this parameter is set to zero to let algorithm compute a suitable reference pixel.

If provided, this parameter must have two elements:

  • first element: coordinate of the reference pixel in the x axis (e.g. longitude of the reference pixel),

  • second element: coordinate of the reference pixel in the y axis (e.g. latitude of the reference pixel)

Double1d pixelSize [INPUT, OPTIONAL, default=Double1d(2, 0.), i.e. autocompute]

defines the size of the pixels in the x and y axes, measured in arc seconds per pixel.

By default this parameter is set to zero to let algorithm compute the optimal size.

If both x- and y-axis values are equal, a Double1d array with a single parameter can be chosen.

Otherwise, this parameter must have two elements:

  • size along the x-axis in the first element,

  • size along the y-axis in the second one.

Double1d smoothFactor [INPUT, OPTIONAL, default=Double1d(2, 1.0), i.e. autocompute]

deprecated parameter (usage not recommended);

provides a smooth factor, increasing (broadening) the area of influence (kernel size) used to compute each pixel.

Integer filterType [INPUT, OPTIONAL, default=2]

specifies the type of convolution filter, by default an exponential (gaussian) function.

Allowed values:

  • BoxCar => 1

  • Exponential (Gaussian) => 2

Visit the herschel.hifi.dp.otf.filter package documentation for details about the available filters.

Double1d[] filterParams [INPUT, OPTIONAL, default=no default value]

provides the numeric parameters for that characterize the filter, such as width and position.

This input parameter is an array that contains two Double1d arrays.

  • The first element of this input array i.e. the first Double1d provides the parameters for the filter function along the x-axis,

  • The second element of this input array i.e. the second Double1d provides the parameters for the filter function along the y-axis

For example, if the filter type is gaussian, the filterparam[0].get(0) contains the kernel length (in pixels) along the x-axis , and the kernel beam width in x-axis(in pixels).

As a second example, if the filter type is box then filterparam[0] contains contains just a Double1d with a single-element, the kernel length (in pixels).

Cube cube [OUTPUT, OPTIONAL, default=no default value]

No default value.

First cube produced by this task, if several segments where processed, or the only cube produced if only one segment was specified

Cube[] cubes [OUTPUT, OPTIONAL, default=no default value]

No default value.

Array of cubes produced by this task, one per (specified) subband of the HifiTimelineProduct.

Double1d xPoints [OUTPUT, OPTIONAL, default=no default value]

No default value.

x-coordinates of points that define the regular grid.

Double1d yPoints [OUTPUT, OPTIONAL, default=no default value]

No default value.

y-coordinates of points that define the regular grid

See also

History

  • 2009-06-04 - ESS: First version. Based on DoCube.