SDRecord

The SDRecord is the fundamental data atom of SDCalc.

Unless otherwise stated, the units of all values in an SDRecord are SI units. Angles are expressed in degrees. Until Measures and coordinates are fully supported in Glish, temporary fields in an SDRecord will be used to hold sufficient information to indicate the coordinate system and reference frame where appropriate. All of the fields described below are required unless stated otherwise.

The value of a field is undefined in the following circumstances:

• The Glish function is_nan(x) returns T for a floating point value.
• The value is < 0 for an integer field.
• The string is empty.

For boolean fields, all values are considered valid. In addition, all values in the data array should be considered valid. The data array flag field should be used to indicate invalid values in the data array.

Certain operations on SDRecords lead to ambiguities in some fields in the resulting SDRecord. In averaging two SDRecords taken at different times, it is not clear what value should be given to the time field and the fields that contain values at the given time (e.g. azimuth). What value should be given to the direction when data from different directions are combined? Rather than simply mark these fields as undefined (which would loose all of this information), one of the input records will be chosen as a template for use during that operation. Typically this will be the first record used in that operation. All values in the resulting record except those directly affected by the operation (e.g. tsys and exposure in an average) will be unchanged from the values in the template record. The documentation for each operation should describe when this occurs. The hist field will show the history of operations.

An SDRecord is a Glish record having the following structure:

data

A Glish record which contains the data array and a description of the data array (axis type, values, increments, and units).

arr

The data array. The dimensionality of the data array is (nchan, nstokes) where nchan is the number of channels and nstokes is the number of different stokes types found in this data. nstokes is either 1, 2 or 4.

desc

A Glish record which describes the data array.

ctype, crval, crpix, and cdelt

Follow standard FITS usage. They describe the first axis of the data array. An SDRecord can therefore only contain data where the first axis is linear in some coordinate system.

units

A string describing the units of the data array.

stokes

A vector of strings describing the stokes type of each element of the second axis of the data array. The possible stokes types are:

I, Q, U, V, RR, RL, LR, LL, XX, XY, YX, YY, RX, RY, LX, LY, XR, XL YR, YL, PP, PQ, QP, QQ

For a typical single dish telescope, raw data will have stokes = ("XX", "YY") or ("RR", "LL").

flag

A boolean matrix with the shape as arr. When true, the corresponding value in arr has been flagged as bad and should not be used. When false, the corresponding value in arr is good.

weight

A floating point matrix having the same shape as arr.

header

A Glish record with the following fixed structure. The bulleted items are mearly separators to make this list easier to read, they are not members of header. The type of each field is indicated at the end of each description. Vector fields are indicated by giving the length of the vector in parenthesis after the field type.

• Identity

  time

  The mid-point of the observation (UT). Double.

  scan_number

  The scan ID. Integer.

  object

  The name of the thing being observed. String.

  direction

  Where the telescope was pointed. Double(2).

  direction_rate

  Any slew rate during the observation. Double(2).

• Times

  ut_date

  The UT date corresponding to time. String.

  ut

  The UT on ut_date corresponding to time. Double.

  lst

  The LST corresponding to time. Double.

  exposure

  The total amount of time actually spent collecting photons (e.g excludes blanking time, etc).

  duration

  The elapsed (clock) time. Float.

• Observer

  observer

  String

  project

  String

• Backend

  rest_frequency

  Double.

  resolution

  The frequency resolution. This need not be the same as the channel spacing.

  bandwidth

  The total bandwidth. Double.

  obs_frequency

  The sky frequency at the reference channel. Double.

  tcal

  The cal temperature. Float(nstokes).

  trx

  The receiver temperature. Float(nstokes).

  tsys

  The system temperature. Float(nstokes).

  sigma

  The theoretical noise per channel. Float(nstokes).

• References

  reference_position

  A reference position on the sky for position switched data. Double(2).

  reference_frequency

  The frequency reference for frequency switched data. Double.

• Telescope

  telescope

  A string identifying the telescope. String.

  telescope_position

  The (x, y, z) position of the telescope in the ITRF (VLBI) coordinate system. Double(3).

  telescope_diameter

  The diameter of the dish. More detailed telescope models will no doubt be useful but the parameters to describe these models are beyond the scope of the header record. If standard components could be identified, they would eventually be placed in the header. Until then, additional parameters to describe the shape of the telescope surface should be placed in ns_header. Float.

  telescope_mount

  The mount type. Chosen from the following values: ``alt-az'', ``equatorial'', ``X-Y'', ``orbiting'', ``bizarre''.

  azel

  The azimuth and elevation at time. Double(2).

  vcorr

  The velocity of the telescope with respect to the velocity reference frame at time using the given velocity definition.

• Weather

  pressure

  The atmopheric pressure. Float.

  dewpoint

  The dew point. Float.

  tambient

  The ambient temperature. Float.

  wind_dir

  The wind direction. Float.

  wind_speed

  The wind speed. Float.

• Coordinate system kludges

  direction_coord

  A Glish Record describing the coordinate system for the direction field. It has the following structure.

  name

  The coordinate name. String.

  equinox

  The equinox for the coordinate. Double.

  reference_coord

  A Glish Record describing the reference_position field. It has the following structure.

  name

  The coordinate name. String.

  equinox

  The equinox for the coordinate. Double.

  is_offset

  True if this is an offset position, else this is an absolute position. If this is an offset position then it is offset from the reference_position. Bool.

  veldef

  The velocity definition (e.g. ``radio'', ``optical''). String.

  velref

  The velocity reference frame (e.g. ``LSR'', ``HEL'', ,etc.). String.

hist

This vector of strings contains a history of the operations which resulted in this SDRecord. Each element is a valid Glish command. Taken as a while, the hist field should be sufficient to regenerate the SDRecord from the original data source.

In addition to the fixed structure described above. An SDRecord may contain an optional ns_header field. This is a Glish record which can contain any additional information not found in the fixed portion of an SDRecord. This field will typicall be used for telescope-dependent information.

The x-axis can be easily constructed from the data field by the following simple Glish function:

	make_xaxis := function(ref data)
	{
	   x := data.crval;
	   x +:= ([1:data::Shape[1]] - data.desc.crpix)*data.desc.cdelt;
	   return x;
	}

To summarize, in pseudo-Glish an SDRecord looks like this:

	sdrecord := [data=[=], header=[=], hist=[=], ns_header=[=]];
	sdrecord.data := [arr=[...], flag=[...], desc=[=], weight=[...]];
	sdrecord.data.desc := [units=,stokes=,ctype=,crpix=,crval=,cdelt=];
        sdrecord.header := [time=,scan_number=,object=,etc.];
	sdrecord.hist := ["# useful history","# as a vector","# etc. etc."];
        sdrecord.ns_header := [non-standard fields]

ns_header is optional

 
• Issues