FlagManagement
Dataflags in Timba are 32-bit integers; each bit may represent a different "flag category". The bits may be manipulated independently via the use of flagmasks (below).
Dataflags are associated with a VellSet. They are completely optional, so a VellSet does not need to have any if none apply. Flags are represented by an integer Vells object, and are thus subject to all the rules of Vells math such as implicit axis expansion. For example, a VellSet may contain a time-frequency-variable value Vells, but only a time-variable flag Vells. The frequency axis is implicitly expanded when these flags are bitwise-ORed with, e.g., a freq-variable flag Vells.
Most node classes involved with flags in any way (such as all the nodes discussed here) recognize a flag_mask parameter in the state record. This should be a vector of integer bitmasks, one per each child node. (If only a single value is given, it is implicitly expanded into a vector.) When a node is working with flags, each child's flags are bitwise-ANDed with the corresponding flagmask. This operation is referred to as masking below. The purpose of the flagmask is to allow selective application of flags.
The default flagmask value is -1 (hex 0xFFFFFFFF), aka "full mask". A flagmask value of 0 causes all flags to be ignored.
The Function base class defines a virtual evaluateFlags method, which is responsible for computing the flags of the resulting VellSet.
Since the flags of a result should be some kind of a union of the flags of the children, the default evaluateFlags() behaviour is implemented as follows. The flags of each child vellset (remember that Function operates on a vellset-by-vellset basis) are masked with the corresponding flagmask, then bitwise-ORed together to produce the flags for the output VellSet. The exception are NullVellSets: the flags of these, if any, are ignored.
Certain Function-derived nodes redefine this behaviour: Unary reduction functions : (e.g. Sum, Mean, Max, Min) do not generate any flags in the output. The flags of the child result are masked, and the sum/mean/etc. is then computed over unflagged values only. (Note that MeqMin and MeqMax operate differently when there are >1 children: they become an element-by-element min/max operation. In this case the flagging behaviour falls back to the Function default.)
MeqMultiply : if any argument is a NullVellSet, then no flags are produced on the output. This is consistent with matrix multiplication (see below). To put it in abstract terms, multiplying any flagged value by a null produces an unflagged null.
The MeqMatrixMultiply node computes the matrix product of two tensors of size NxM and MxK (in fact the node can multiply more than two children, but the operation is performed as a series of such binary multiplications). Thus, each element (VellSet) of the output, Cij, is computed as the sum of M products AikBkj (k=1...M).
Flagging is consistent with Function and Multiply above. The flags of Cij are a bitwise-OR of the flags Aik and Bkj over k, masked by the flagmasks of A and B. As in Multiply, if for a given k Aik and/or Bkj is a NullVellSet, then the flags of both elements in product k are ignored.
Each element of the inverted matrix Bij is a function of the entire input matrix A. Thus, the output flags for each element are identical, and are the bitwise-OR of all flags Aij for all i and j, masked with the flagmask. As in Function, the flags of NullVellSet elements are ignored.
The result of this node is the result of its first child, with flags merged across all children. Flags are merged via a bitwise-OR operation, and flagmask is applied to all child results.
If it has only one child, the flags of all its tensor elements are masked and merged. All elements of the output result are then assigned the same set of flags. This is obviously most useful for tensor results, but can also be used with scalar results to simply apply a flagmask.
If it has two or more children, the flags of remaining children are masked and merged with those of the first child in the following way;
* a) If the second child returns a scalar result, its flags are merged with every tensor element of the first child. b) If both results are are commensurate tensors, flags are merged element-by-element (if not commensurate, a fail is returned). c) If first child's result is scalar but the second is a tensor, the flags of all elements in the tensor are merged into the first child.
MeqSpigot and MeqSink interface with data objects called VisTiles. Tiles are an abstract interface to a visibility stream; these are mapped to and from an AIPS++ MS elsewhere in the system.
A tile represents data for Ntime timeslots and a single IFR. Tile flags are 32-bit integers. Each tile has Ntime x Nfreq x Ncorr "data flags", and Ntime "row flags". Row flags are meant to apply to the entire timeslot.
AIPS++ MS flags are boolean. The current MS reader implementation sets flagbit 0 (flag value 1) to represent a MS flag, and a row flag of all ones (0xFFFFFFFF) to represent missing rows. The MS writer implementation sets a MS flag if any bit of a tile flag is set.
MeqSpigot defines a number of state record fields that determine how tile flags are mapped onto VellSet flags: flag_mask and row_flag_mask : these are bitmasks (default value -1 == 0xFFFFFFFF) that are applied (via a bitwise-AND) to the tile flags.
flag_bit : if this is 0 (default), tile flags are assigned directly to VellSet flags, i.e., all unmasked tile flagbits are directly mapped to VellSet flagbits. If non-0, then this value is assigned to a VellSet flag wherever a masked tile flag is not 0. This allows you to set a different flagbit to represent input data flags.
Rows flagged as missing are excluded from the output Cells completely. Other row flags are implicitly expanded to apply to the entire timeslot.
MeqSink performs the reverse mapping (VellSet flags to tile flags). The following state record fields control this: flag_mask : (default value -1 == 0xFFFFFFFF) this is a flagmask applied to the VisTile flags.
flag_bit : if 0 (default), the masked VellSet flags are assigned directly to tile flags. If non 0, then this value is assigned to a tile flag whereever a masked VellSet flag is not 0.
MeqSink does not set tile row flags. Note that a sink modifies its input tile "in place", thus any row flags in the input tile (including missing rows) are preserved.