3.6

Table Workspaces

Overview

Table workspaces are general purpose workspaces for storing data of mixed types. A table workspace is organized in columns. Each column has a name and a type - the type of the data in that column.

Working with Table Workspaces in Python

For more details on interacting with Table Workspaces in Python, please see this page.

Accessing Workspaces

The methods for getting a variable to an Table Workspace is the same as shown in the Workspace help page.

If you want to check if a variable points to something that is an Table Workspace you can use this:

from mantid.api import ITableWorkspace

tableWS = CreateEmptyTableWorkspace()

if tableWS is ITableWorkspace:
    print tableWS.getName() + " is a " + tableWS.id()

Output:

tableWS is a TableWorkspace

Creating a Table Workspace in Python

Most of the time Table workspaces are the output of certain algorithms, but you can create them yourself should you wish.

from mantid.kernel import V3D

# Create PositionTable
tableWS = CreateEmptyTableWorkspace()

# Add some columns, Recognized types are: int,float,double,bool,str,V3D,long64
tableWS.addColumn(type="int",name="Detector ID")
tableWS.addColumn(type="str",name="Detector Name")
tableWS.addColumn(type="V3D",name="Detector Position")

# Populate the columns for three detectors
detIDList = range(1,4)
detPosList = [ V3D(9.0,0.0,0.0), V3D(10.0,3.0,0.0), V3D(12.0,3.0,6.0)]
for j in range(len(detIDList)):
    nextRow = { 'Detector ID': detIDList[j],
                'Detector Name': "Detector {0}".format(detIDList[j]),
                'Detector Position': detPosList[j] }
    tableWS.addRow ( nextRow )

Table Workspace Properties

#setup as above

# Rows
print "Row count:", tableWS.rowCount()
print tableWS.row(0) # row values as a dictionary
# Resize the table
tableWS.setRowCount(4)
# Add Rows
tableWS.addRow( [2, "new Detector 1", V3D(2,2,2)])
# or using a dictionary
nextRow = { 'Detector ID': 5,
                'Detector Name': "new Detector 2",
                'Detector Position':  V3D(5,5,5) }
tableWS.addRow ( nextRow )

# Columns
print "Column count:", tableWS.columnCount()
print "Column names:", tableWS.getColumnNames()
columnValuesList = tableWS.column(0)
# To remove a column
tableWS.removeColumn("Detector Name")

Working with Table Workspaces in C++

Table workspaces can be created using the workspace factory:

ITableWorkspace_sptr table = WorkspaceFactory::Instance().createTable("TableWorkspace");

Columns are added using the addColumn method:

table->addColumn("str","Parameter Name");
table->addColumn("double","Value");
table->addColumn("double","Error");
table->addColumn("int","Index");

Here the first argument is a symbolic name of the column’s data type and the second argument is the name of the column. The predefined types are:

Symbolic name C++ type
int int
float float
double double
bool bool
str std::string
V3D Mantid::Geometry::V3D
long64 int64_t

The data in the table can be accessed in a number of ways. The most simple way is to call templated method T& cell(row,col), where col is the index of the column in the workspace and row is the index of the cell in the column. Columns are indexed in the order they are created with addColumn. There are also specialized methods for four predefined data types: int& Int(row,col), double& Double(row,col), std::string& String(row,col), bool& Bool(row,col). Columns use std::vector to store the data. To get access to the vector use getVector(name). To get the column object use getColumn(name).

Only columns of type int, double and str can currently be saved to Nexus by SaveNexus or SaveNexusProcessed. Columns of other types will simply be omitted from the Nexus file without any error message.

Table rows

Cells with the same index form a row. TableRow class represents a row. Use getRow(int) or getFirstRow() to access existing rows. For example:

std::string key;
double value;
TableRow row = table->getFirstRow();
do
{
  row >> key >> value;
  std::cout << "key=" << key << " value=" << value << std::endl;
}
while(row.next());

TableRow can also be use for writing into a table:

for(int i=0; i < n; ++i)
{
  TableRow row = table->appendRow();
  row << keys[i] << values[i];
}

Defining new column types

Users can define new data types to be used in TableWorkspace. TableColumn.h defines macro DECLARE_TABLECOLUMN(c_plus_plus_type,symbolic_name). c_plus_plus_type must be a copyable type and operators << and >> must be defined. There is also DECLARE_TABLEPOINTERCOLUMN macro for declaring non-copyable types, but it has never been used.

Other Information on Workspaces

  • Workspace - Overview of workspaces, which include the following classes:
    • MatrixWorkspace - A base class that contains among others:
      • WorkspaceSingleValue - Holds a single number (and X & error value, if desired). Mainly used for workspace algebra, e.g. to divide all bins in a 2D workspace by a single value.
      • Workspace2D - A workspace for holding two dimensional data in memory, this is the most commonly used workspace.
      • EventWorkspace - A workspace that retains the individual neutron event data.
    • TableWorkspace - A workspace holding data in rows of columns having a particular type (e.g. text, integer, ...).
    • WorkspaceGroup - A container for a collection of workspaces. Algorithms given a group as input run sequentially on each member of the group.

Category: Concepts