Table

class Table(path=None, object_id=None)

Table with data ordered into multiple columns.

A table contains data ordered in columns. Several different types of columns are supported, e.g. strings, integers, floats, PhysicalQuantity and a generic column of instances.

The table has two advantages over e.g. numpy arrays. Firstly, a Table can be immediately persisted to disk (if constructed with a path). Additionally a Table has the ability to also contain instances of any savable QuantumATK type, i.e. MoleculeConfiguration, Bandstructure, etc.

A table is constructed in the following way:

table = Table(path='my_filename.hdf5', object_id='MyTable')

Then columns are added. Here we add an index, a bandgap and a band structure:

table.addIntegerColumn(key='index')
table.addQuantityColumn(key='band_gap', unit=eV)
table.addInstanceColumn(key='bandstructure', types=Bandstructure)

Data can be added row by row:

table.append(0, 1.23 * meV, bandstructure=my_bandstructure)

Or the table can be extended with a list:

table.extend([
    [1, 2.34 * meV, bandstructure_1],
    [2, 3.45 * meV, bandstructure_2],
    [3, 4.56 * meV, bandstructure_3]
])

The table also supports normal array operations:

  • table[row-index, column-index], e.g. table[1, 2] or table[2, 'bandstructure']

  • table[row, column] = value, e.g. table[2, 1] = 12.34 * meV

  • len(table) returns number of rows.

Do note that the table (like numpy arrays) must be filled with values, before the cell can be addressed. This can be done using table.fill(number_of_rows).

Parameters:

  • path (str) – The optional path. No path means that table is in-memory.
    Default: None

  • object_id (str | None) – The optional object id.
    Default: None

add(data)

Add data as new columns.

Parameters:

data (Column, Table, list) – The data.

addColumn(column_type, key=None, title=None, **kwargs)

Add a column to this table.

However, prefer to use the specific methods like addIntegerColumn, addFloatColumn, addQuantityColumn, addStringColumn or addInstanceColumn.

Parameters:

  • column_type (Column type) – The column type.

  • key (str) – The key.

  • title (str) – The title.

  • **kwargs (anything) – The kwargs.

addFloatColumn(key=None, title=None)

Add a column of floats with specified key and title.

Parameters:

  • key (str) – The optional column key.

  • title (str) – The optional title for this column.

addInstanceColumn(key=None, title=None, types=None)

Add a column of instances with specified types.

Parameters:

  • key (str) – The optional column key.

  • title (str) – The optional title for this column.

  • types (type or tuple of type) – The types of the instances in the column.

addIntegerColumn(key=None, title=None)

Add a column of integers with specified key and title.

Parameters:

  • key (str) – The optional column key.

  • title (str) – The optional title for this column.

addQuantityColumn(key=None, title=None, unit=None)

Add a column of quantities with specified unit.

Parameters:

  • key (str) – The optional column key.

  • title (str) – The optional title for this column.

  • unit (PhysicalQuantity.Unit) – The unit of the column.

addStringColumn(key=None, title=None)

Add a column of strings with specified key and title.

Parameters:

  • key (str) – The optional column key.

  • title (str) – The optional title for this column.

append(*values, **named_values)

Append row of data to the table.

For a table with an integer column and a string column, one could do like this:

table.append(12, ‘my_string’)

Parameters:

  • *values (anything) – The row values.

  • **named_values (anything) – the named row values.

clone(path=None, object_id=None)

Clone the table (i.e. create a new table with the same columns as this table, but no data).

Parameters:

  • path (str) – The filename to save the new table to.

  • object_id (str) – The object id.

Returns:

The cloned table.

Return type:

Table

column(index)

Retrieve column at a given index.

Parameters:

index (int) – The index.

Returns:

The corresponding column.

Return type:

Column

columns()
Returns:

Retrieve all columns in the table.

Return type:

List of columns

consolidate()

Try to embed all links into table.

extend(data, link=False)

Append rows to table with data from other table or a list of lists.

Parameters:

  • data (Table | list | list of list) – The data to extend the table with.

  • link (bool) – True, if links in the data should be preserved.
    Default: False.

extract(types=<class 'object'>)

Extract all objects of a specific type within the table.

Parameters:

types (tuple of type) – The types.

Returns:

An iterator over all matches.

Return type:

ColumnsIterator

fill(length)

Fill the table with default values up to a total number of rows.

Parameters:

length (int) – The length to fill to.

findColumn(key=None, types=None)

Find column by force-matching types and selecting the closest key.

Parameters:

  • key (str) – The optional key (column name) to search for.

  • types (str) – The optional types to filter for.

Returns:

The best matched column.

Return type:

Column | None

findColumns(types)

Find columns that may contain any objects of the supplied types.

Parameters:

types (tuple of types) – The types to contain.

Returns:

All matching columns.

Return type:

list of Columns

classmethod fromList(data, path=None, object_id=None)

Create table from list.

Column types and names are automatically guessed from the contents of a list. A single list is turned into a single column table.

Passing in a list of list is interpreted as a list of rows.

Parameters:

  • data (list or list of lists) – The list.

  • path (str) – The path to store the Table to. None means an in-memory table.

  • object_id (str) – The optional object id.
    Default: None

Returns:

The constructed table.

Return type:

Table

metatext()
Returns:

The metatext of the object or None if no metatext is set.

Return type:

str | None

numberOfColumns()

Return the number of columns.

Returns:

The number of columns.

Return type:

str

numberOfRows()
Returns:

The number of rows.

Return type:

int

persist(path, object_id=None, hidden=False)

Persist the table to disk. If you later modify this table, all modifications are also persisted to disk.

This is a no-op if the table has already been saved to disk, even though the supplied filename or group_name may differ from the table’s actual filename and group_name.

If you wish to save a copy of the table, simply save the table.

Parameters:

  • path (str) – The path.

  • group_name (str | None | None) – The object id.
    Default: None

raw(*index)

Retrieve the raw data. If using links, this will return LinkedObjects instead of the corresponding instances.

Parameters:

index (int | slice | tuple) – The index.

Returns:

The corresponding values.

Return type:

Any

setMetatext(text)

Set a given metatext string on the object.

Parameters:

text (str | None) – The metatext string that should be set. A value of “None” can be given to remove the current metatext.

signature()

Return a tuple describing the column signatures in the table. This can be used to match if two tables contain comparable data.

Returns:

The signature of the table

Return type:

tuple