A good understanding of the Table system is essential
before attempting to use this class.
TableQuantumDesc objects are analogous to ColumnDesc objects in that they
add information, describing the characteristics of a column, to the Table
Descriptor before the Table is created. However, rather than
replacing the use of a ColumnDesc object, a TableQuantumDesc is
used in conjunction with a ColumnDesc in the definition of
Quantum columns.
Defining a Quantum column requires the following steps:
The type of the quantum columns must match the type of the underlying
Quanta that are to be stored in the column. Hence, for a column of
Quantum<Complex> a ScalarColumnDesc<Complex> must be used.
As with standard Table Columns Quanta can be stored in Scalar and Array
columns. This must be specified in advance by using either a
Scalar- or ArrayColumnDesc.
After the Table has be created a Quantum column can be accessed for writing and reading of Quanta via the (RO)ScalarQuantColumn<T> and (RO)ArrayQuantColumn<T> objects.
Quantum Units
The treatment of the Unit component of a Quantum in the TableQuantumDesc
class varies depending on your needs. The main consideration
is whether the Quanta to be stored in a specific column are to have the
same Unit or whether their Units could differ. In the simple case,
where the
Quanta have the same unit, a TableQuantumDesc is declared with the
Unit value specified as a parameter. The following defines a Quantum
column with units "deg":
ScalarColumnDesc<Double> scd("QuantumCol");
...
// defines QuantumCol as a Quantum column with fix Units "deg"
TableQuantumDesc tqd(td, "QuantumCol", Unit("deg"));
This constructor stores the value for the Unit as a column keyword. In situations, however, where it is necessary to store a distinct Unit with each Quantum, it is necessary to define an additional column for storing the Unit component of each Quantum. The TableQuantumDesc constructor for this takes the name of the Unit column as a parameter. Hence an additional column must be defined for storing the Units and its type must be string. The following example shows how to set up a Quantum column with support for Quantum unit variability:
// the quanta values stored here
ScalarColumnDesc<Double> scd("QuantumCol");
// a String column for the Units
ScalarColumnDesc<String> scd("QuantumUnitCol");
...
TableQuantumDesc tqd(td, "QuantumCol", "QuantumUnitCol");
One further consideration is that for Array Quantum Columns it is necessary to decide on a level of granularity for the Unit storage you would like. In Array Quantum columns it is possible to store a distinct Unit per row or per array element per row. This distinction is established when the Unit column is declared. Defining a ScalarColumn for Units specifies per row variability, that is, each row in an array column of Quanta will have the same unit. Alternatively, use of an ArrayColumn for the Unit column specifies that every Quantum stored will have its unit stored as well. In both cases the Unit column's type must be String. The following defines an Array Quantum Column with per row Unit storage:
// for the Quanta values
ArrayColumnDesc<Double> scd("ArrayQuantumCol");
// per row storage of units
ScalarColumnDesc<String> scd("QuantumUnitCol");
...
TableQuantumDesc tqd(td, "ArrayQuantumCol", "QuantumUnitCol");
And finally, an array Quantum Column with an Array Unit Column:
// for Quanta values
ArrayColumnDesc<Double> scd("ArrayQuantumCol");
// per element storage of Units
ArrayColumnDesc<String> scd("ArrayUnitCol");
...
TableQuantumDesc tqd(td, "ArrayQuantumCol", "ArrayUnitCol");
After constructing an TableQuantumDesc object use of the write() member updates the Table Descriptor or Table object. (RO)ScalarQuantColumn<T> and (RO)ArrayQuantColumn<T> are subsequently used to read-only and read/write access the Quantum Columns.
// create a table descriptor as normal
TableDesc td("measTD", "1", TableDesc::New);
td.comment() = "A table containing measures and quantums";
// This example sets up a Quantum<Complex> column but any valid Quantum
// type can be specified. However, the type of the Quantums to be
// stored must match the type of the underlying table column.
ScalarColumnDesc<Complex> tcdQCplx("Quant", "A quantum complex column");
// For a Quantum array column an ArrayColumnDesc is first defined
ArrayColumnDesc<Double> tcdQDoub("QuantArray", "A quantum array col");
// The QuantumArray column has variable units. A string is needed
// for these. This could be done in two ways depending on what is
// wanted. Units can vary per element of array per row or
// just per row. In the first instance an ArrayColumn<String> would be
// require. Here we want to vary units only per row.
ScalarColumnDesc<String> tcdUnits("VarQuantUnits", "Quantum units");
// Add the columns to the Table Descriptor
td.addColumn(tcdQplx);
td.addColumn(tcdQDoub);
td.addColumn(tcdUnits);
// Create the TableQuantumDesc with units "deg" and an Array Quantum
// Column with per row Unit granularity
TableQuantumDesc tqdS(td, "Quant", unit("deg"));
TableQuantumDesc tqdA(td, "QuantArray", "VarQuantUnits");
// Update the Table Descriptor
tqdA.write(td);
tqdS.write(td);
// Setup and create the new table as usual.
SetupNewTable newtab("mtab", td, Table::New);
Table qtab(newtab);
// Now ScalarQuantColumn and ArrayQuantColumn objects could be
// constructed to access the columns...
Note that writing the Quantum description could also be done
after the table is created. It is meaningless in this case, but
it is useful when columns (to be used for quanta) are added to
an already existing table.
be used as
// Setup and create the new table as usual.
SetupNewTable newtab("mtab", td, Table::New);
Table qtab(newtab);
// Update the Table Descriptor
tqdA.write(qtab);
tqdS.write(qtab);
Constructs a Quantum column descriptor with the specified Quantum unit. The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.
Constructs a Quantum column descriptor with the specified Quantum units. The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.
Constructs a Quantum column descriptor with variable units stored in unitCol. Both the quantum and unit column should exist in the TableDesc.
Copy constructor (copy semantics).
Reconstructs a previously constructed TableQuantumDesc.
Assignment.
Returns the Quantum column descriptor's units. A empty vector is returned if units have not been specified. This could be because the null unit constructor was used or because the units are variable.
Returns True if descriptor set for variable units (one per row)
Returns the name of the quantum column.
Returns the name of the units column (an empty String is returned if the units are not variable).
Makes the TableQuantumDesc persistent (updates the Table Descriptor).
Does this column contain table quanta?
Write the actual keywords.
Throw an exception if the quantum column doesn't exist.
Throw an exception if the variable units column isn't a string column.