Loading...
Searching...
No Matches
casacore::TableQuantumDesc Class Reference
measures package (libcasa_measures) » TableMeasures_module

More...

`#include <TableQuantumDesc.h>`

## Public Member Functions

| TableQuantumDesc (const TableDesc &td, const String &column)
| Constructs a Quantum column descriptor with null units (Unit == "").
| TableQuantumDesc (const TableDesc &td, const String &column, const Unit &)
| Constructs a Quantum column descriptor with the specified Quantum unit.
| TableQuantumDesc (const TableDesc &td, const String &column, const Vector< String > &unitNames)
| Constructs a Quantum column descriptor with the specified Quantum units.
| TableQuantumDesc (const TableDesc &td, const String &column, const Vector< Unit > &)
| TableQuantumDesc (const TableDesc &td, const String &column, const String &unitCol)
| Constructs a Quantum column descriptor with variable units stored in unitCol.
| TableQuantumDesc (const TableDesc &td, const String &column, const Char *unitCol)
| TableQuantumDesc (const TableQuantumDesc &that)
| Copy constructor (copy semantics).
| ~TableQuantumDesc ()
TableQuantumDesc & | operator= (const TableQuantumDesc &that)
| Assignment.
const Vector< String > & | getUnits () const
| Returns the Quantum column descriptor's units.
Bool | isUnitVariable () const
| Returns True if descriptor set for variable units (one per row).
const String & | columnName () const
| Returns the name of the quantum column.
const String & | unitColumnName () const
| Returns the name of the units column (an empty String is returned if the units are not variable).
void | write (TableDesc &)
| Makes the TableQuantumDesc persistent (updates the Table Descriptor).
void | write (Table &)

## Static Public Member Functions

static TableQuantumDesc * | reconstruct (const TableDesc &td, const String &column)
| Reconstructs a previously constructed TableQuantumDesc.
static Bool | hasQuanta (const TableColumn &column)
| Does this column contain table quanta?

## Private Member Functions

void | writeKeys (TableRecord &columnKeyset)
| Write the actual keywords.
void | checkColumn (const TableDesc &td) const
| Throw an exception if the quantum column doesn't exist.
void | checkUnitsColumn (const TableDesc &td) const
| Throw an exception if the variable units column isn't a string column.

## Private Attributes

String | itsColName
| Name of column which stores the Quantum's values.
Vector< String > | itsUnitsName
| The Quantum's unit as a string.
String | itsUnitsColName
| Name of units column if units are variable.

## Detailed Description

A class for defining Quantum columns in Tables.

### Intended use:

Public interface

### Review Status

Reviewed By:
  Bob Garwood
Date Reviewed:
  1999/12/23
Test programs:
  tTableQuantum

### Prerequisite

- Table
- Quantum

### Synopsis

A TableQuantumDesc object is used to define a Quantum column in a Table. The use of this object and the associated Scalar- and ArrayQuantColumn objects make it possible to store (and retrieve) Quanta in Tables.

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.

Caution: A good understanding of the Table system is essential before attempting to use this class;

Defining a Quantum column requires the following steps:

1. Use a normal Scalar- or ArrayColumnDesc to define a column to use for the Quanta.
2. If needed (see below) define a column for the Quantum Units.
3. Add the columns to the Table Descriptor.
4. Declare a TableQuantumDesc to associate the column defined in step 1 and the Unit column from step 2 and update the Table Descriptor.
5. Setup and create the Table.

It is also possible to define a Quantum column after the table is created. which is useful when columns (to be used for quanta) are added to an already existing table.

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"));
casacore::ScalarColumnDesc
Definition ScaColDesc.h:162
casacore::TableQuantumDesc::TableQuantumDesc
TableQuantumDesc(const TableDesc &td, const String &column)
Constructs a Quantum column descriptor with null units (Unit == "").
casacore::Unit
Definition Unit.h:187

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");
casacore::ArrayColumnDesc
Templated class for description of table array columns.
Definition ArrColDesc.h:235

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.

### Example

// 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..\.
casacore::SetupNewTable
Create a new table - define shapes, data managers, etc.
Definition SetupNewTab.h:337
casacore::TableDesc
Definition TableDesc.h:189
casacore::TableDesc::New
@ New
Definition TableDesc.h:193
casacore::Table
Definition Table.h:157
casacore::Table::New
@ New
create table
Definition Table.h:175

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);

### Motivation

This class assists in the definition of a Quantum Table Column.

### Thrown Exceptions

- AipsError during construction if the column doesn't exist.
- AipsError during construction if the unit's column doesn't exist (when variable units).
- AipsError during construction if the type of the variable unit's column is not String.
- AipsError during a reconstruct if the column doesn't have a Unit.

Definition at line 263 of file TableQuantumDesc.h.

## Constructor & Destructor Documentation

## TableQuantumDesc() [1/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column )

Constructs a Quantum column descriptor with null units (Unit == "").

The column should have already been added to the TableDesc. An exception is thrown if the column doesn't exist.

Referenced by operator=(), reconstruct(), and TableQuantumDesc().

## TableQuantumDesc() [2/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column,
|  | const Unit & | )

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.

## TableQuantumDesc() [3/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column,
|  | const Vector< String > & | unitNames )

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.

## TableQuantumDesc() [4/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column,
|  | const Vector< Unit > & | )

## TableQuantumDesc() [5/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column,
|  | const String & | unitCol )

Constructs a Quantum column descriptor with variable units stored in unitCol.

Both the quantum and unit column should exist in the TableDesc.

## TableQuantumDesc() [6/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableDesc & | td,
|  | const String & | column,
|  | const Char * | unitCol )

## TableQuantumDesc() [7/7]

casacore::TableQuantumDesc::TableQuantumDesc | ( | const TableQuantumDesc & | that | ) |

Copy constructor (copy semantics).

References TableQuantumDesc().

## ~TableQuantumDesc()

casacore::TableQuantumDesc::~TableQuantumDesc | ( |  | ) |

## Member Function Documentation

## checkColumn()

void casacore::TableQuantumDesc::checkColumn | ( | const TableDesc & | td | ) | const

private

Throw an exception if the quantum column doesn't exist.

## checkUnitsColumn()

void casacore::TableQuantumDesc::checkUnitsColumn | ( | const TableDesc & | td | ) | const

private

Throw an exception if the variable units column isn't a string column.

## columnName()

const String & casacore::TableQuantumDesc::columnName | ( |  | ) | const

inline

Returns the name of the quantum column.

Definition at line 321 of file TableQuantumDesc.h.

References itsColName.

## getUnits()

const Vector< String > & casacore::TableQuantumDesc::getUnits | ( |  | ) | const

inline

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.

Definition at line 313 of file TableQuantumDesc.h.

References itsUnitsName.

## hasQuanta()

Bool casacore::TableQuantumDesc::hasQuanta | ( | const TableColumn & | column | ) |

static

Does this column contain table quanta?

## isUnitVariable()

Bool casacore::TableQuantumDesc::isUnitVariable | ( |  | ) | const

inline

Returns True if descriptor set for variable units (one per row).

Definition at line 317 of file TableQuantumDesc.h.

References itsUnitsColName.

## operator=()

TableQuantumDesc & casacore::TableQuantumDesc::operator= | ( | const TableQuantumDesc & | that | ) |

Assignment.

References TableQuantumDesc().

## reconstruct()

TableQuantumDesc * casacore::TableQuantumDesc::reconstruct | ( | const TableDesc & | td,
|  | const String & | column )

static

Reconstructs a previously constructed TableQuantumDesc.

References TableQuantumDesc().

## unitColumnName()

const String & casacore::TableQuantumDesc::unitColumnName | ( |  | ) | const

inline

Returns the name of the units column (an empty String is returned if the units are not variable).

Definition at line 326 of file TableQuantumDesc.h.

References itsUnitsColName.

## write() [1/2]

void casacore::TableQuantumDesc::write | ( | Table & |  | ) |

## write() [2/2]

void casacore::TableQuantumDesc::write | ( | TableDesc & |  | ) |

Makes the TableQuantumDesc persistent (updates the Table Descriptor).

## writeKeys()

void casacore::TableQuantumDesc::writeKeys | ( | TableRecord & | columnKeyset | ) |

private

Write the actual keywords.

## Member Data Documentation

## itsColName

String casacore::TableQuantumDesc::itsColName

private

Name of column which stores the Quantum's values.

Definition at line 340 of file TableQuantumDesc.h.

Referenced by columnName().

## itsUnitsColName

String casacore::TableQuantumDesc::itsUnitsColName

private

Name of units column if units are variable.

Definition at line 344 of file TableQuantumDesc.h.

Referenced by isUnitVariable(), and unitColumnName().

## itsUnitsName

Vector<String> casacore::TableQuantumDesc::itsUnitsName

private

The Quantum's unit as a string.

Definition at line 342 of file TableQuantumDesc.h.

Referenced by getUnits().

The documentation for this class was generated from the following file:

- measures/TableMeasures/TableQuantumDesc.h