TiledShapeStMan.h

Classes

TiledShapeStMan -- Tiled Data Storage Manager using the shape as id. (full description)

class TiledShapeStMan : public TiledStMan

Interface

Public Members
TiledShapeStMan (const String& hypercolumnName, const IPosition& defaultTileShape, uInt maximumCacheSize = 0)
TiledShapeStMan (const String& hypercolumnName, const Record& spec)
~TiledShapeStMan()
virtual DataManager* clone() const
virtual String dataManagerType() const
virtual Bool canAccessColumn (Bool& reask) const
virtual TSMCube* singleHypercube()
virtual void setShape (uInt rownr, TSMCube* hypercube, const IPosition& shape, const IPosition& tileShape)
static DataManager* makeObject (const String& dataManagerType, const Record& spec)
Private Members
TiledShapeStMan()
virtual IPosition defaultTileShape() const
void addRow (uInt nrrow)
Int findHypercube (const IPosition& shape)
void addHypercube (uInt rownr, const IPosition& cubeShape, const IPosition& tileShape)
void extendHypercube (uInt rownr, uInt cubeNr)
virtual TSMCube* getHypercube (uInt rownr)
virtual TSMCube* getHypercube (uInt rownr, IPosition& position)
virtual void setupCheck (const TableDesc& tableDesc, const Vector<String>& dataNames) const
virtual Bool flush (AipsIO&, Bool fsync)
virtual void create (uInt nrrow)
virtual void readHeader (uInt nrrow, Bool firstTime)
void updateRowMap (uInt cubeNr, uInt pos, uInt rownr)
void extendRowMap (uInt nrow)

Description

Prerequisite

Etymology

TiledShapeStMan is the Tiled Storage Manager where the shape is used as id to support variable shaped arrays.

Synopsis

TiledShapeStMan is a derivation from TiledStMan, the abstract tiled storage manager class. A description of the basics of tiled storage managers is given in the Tables module description.

TiledShapeStMan creates a hypercube for each different shape of the data arrays. For example, if a table contains line and continuum data of an observation, it results in 2 hypercubes. TiledShapeStMan does it all automatically, so it is much easier to use than class TiledDataStMan.
TiledShapeStMan is meant for columns with not too many different shapes, otherwise looking for a matching hypercube may take too long. When many different shapes are used, class TiledCellStMan should be used instead.

TiledShapeStMan has the following (extra) properties:

Motivation

TiledDataStMan proved to be very powerful, but also a bit cumbersome to use because a few special functions need to be called. TiledShapeStMan alleviates that problem.

Example

  // Define the table description and the columns in it.
  TableDesc td ("", "1", TableDesc::Scratch);
  td.addColumn (ArrayColumnDesc<float>  ("RA", 1));
  td.addColumn (ArrayColumnDesc<float>  ("Dec", 1));
  td.addColumn (ScalarColumnDesc<float> ("Velocity"));
  td.addColumn (ArrayColumnDesc<float>  ("Image", 2));
  // Define the 3-dim hypercolumn with its data and coordinate columns.
  // Note that its dimensionality must be one higher than the dimensionality
  // of the data cells.
  td.defineHypercolumn ("TSMExample",
			  3,
			  stringToVector ("Image"),
			  stringToVector ("RA,Dec,Velocity"));
  // Now create a new table from the description.
  SetupNewTable newtab("tTiledShapeStMan_tmp.data", td, Table::New);
  // Create a TiledShapeStMan storage manager for the hypercolumn
  // and bind the columns to it.
  // The (default) tile shape has to be specified for the storage manager.
  TiledShapeStMan sm1 ("TSMExample", IPosition(3,16,32,32));
  newtab.bindAll (sm1);
  // Create the table.
  Table table(newtab);
  // Define the values for the coordinates of the hypercube.
  Vector<float> raValues(512);
  Vector<float> DecValues(512);
  indgen (raValues);
  indgen (decValues, float(100));
  ArrayColumn<float> ra (table, "RA");
  ArrayColumn<float> dec (table, "Dec");
  ScalarColumn<float> velocity (table, "Velocity");
  ArrayColumn<float> image (table, "Image");
  Cube<float> imageValues(IPosition(2,512,512));
  indgen (imageValues);
  // Write some data into the data columns.
  uInt i;
  for (i=0; i<64; i++) {
      table.addRow();
      image.put (i, imageValues);
      ra.put (i, raValues);
      dec.put (i, decValues);
      velocity.put (i, float(i));
  }
Note that in this example the same shape is used for each row, but it could have been different.

Member Description

TiledShapeStMan (const String& hypercolumnName, const IPosition& defaultTileShape, uInt maximumCacheSize = 0)
TiledShapeStMan (const String& hypercolumnName, const Record& spec)

Create a TiledShapeStMan storage manager for the hypercolumn with the given name. The hypercolumn name is also the name of the storage manager. The given maximum cache size (default is unlimited) is persistent, thus will be reused when the table is read back. Note that the class ROTiledStManAccessor allows one to overwrite the maximum cache size temporarily.
The constructor taking a Record expects fields in the record with the name of the arguments in uppercase. If not defined, their default value is used.

~TiledShapeStMan()

virtual DataManager* clone() const

Clone this object. It does not clone TSMColumn objects possibly used.

virtual String dataManagerType() const

Get the type name of the data manager (i.e. TiledShapeStMan).

virtual Bool canAccessColumn (Bool& reask) const

TiledShapeStMan can access a column if there are 2 hypercubes and the first one is empty. reask is set to True (because next time things might be different).

virtual TSMCube* singleHypercube()

Test if only one hypercube is used by this storage manager. If not, throw an exception. Otherwise return the hypercube.

virtual void setShape (uInt rownr, TSMCube* hypercube, const IPosition& shape, const IPosition& tileShape)

Set the shape and tile shape of the given hypercube. It is used when the first row in a new hypercube is written. If needed it adds a dimension to the shape, which reflects the row dimension. The tile shape in that dimension is by default 1.

static DataManager* makeObject (const String& dataManagerType, const Record& spec)

Make the object from the type name string. This function gets registered in the DataManager "constructor" map.

TiledShapeStMan()

Create a TiledShapeStMan. This constructor is private, because it should only be used by makeObject.

virtual IPosition defaultTileShape() const

Get the default tile shape.

void addRow (uInt nrrow)

Add rows to the storage manager.

Int findHypercube (const IPosition& shape)

Find the hypercube for the given shape. It returns -1 when not found.

void addHypercube (uInt rownr, const IPosition& cubeShape, const IPosition& tileShape)

Add a hypercube. The number of rows in the table must be large enough to accommodate this hypercube. The possible id values must be given in the record, while coordinate values are optional. The field names in the record should match the coordinate and id column names. The last dimension in the cube shape can be zero, indicating that the hypercube is extensible.

void extendHypercube (uInt rownr, uInt cubeNr)

Extend the hypercube with the given number of elements in the last dimension. The record should contain the id values (to get the correct hypercube) and optionally coordinate values for the elements added.

virtual TSMCube* getHypercube (uInt rownr)

Get the hypercube in which the given row is stored.

virtual TSMCube* getHypercube (uInt rownr, IPosition& position)

Get the hypercube in which the given row is stored. It also returns the position of the row in that hypercube.

virtual void setupCheck (const TableDesc& tableDesc, const Vector<String>& dataNames) const

Check if the hypercolumn definition fits this storage manager.

virtual Bool flush (AipsIO&, Bool fsync)

Flush and optionally fsync the data. It returns a True status if it had to flush (i.e. if data have changed).

virtual void create (uInt nrrow)

Let the storage manager create files as needed for a new table. This allows a column with an indirect array to create its file.

virtual void readHeader (uInt nrrow, Bool firstTime)

Read the header info.

void updateRowMap (uInt cubeNr, uInt pos, uInt rownr)

Update the map of row numbers to cube number plus offset.

void extendRowMap (uInt nrow)

Extend the map of row numbers to cube number plus offset will new empty entries.