hdmf.common.table module

Collection of Container classes for interacting with data types related to the storage and use of dynamic data tables as part of the hdmf-common schema

class hdmf.common.table.VectorData(name, description, data=[])

Bases: hdmf.container.Data

A n-dimensional dataset representing a column of a DynamicTable. If used without an accompanying VectorIndex, first dimension is along the rows of the DynamicTable and each step along the first dimension is a cell of the larger table. VectorData can also be used to represent a ragged array if paired with a VectorIndex. This allows for storing arrays of varying length in a single cell of the DynamicTable by indexing into this VectorData. The first vector is at VectorData[0:VectorIndex(0)+1]. The second vector is at VectorData[VectorIndex(0)+1:VectorIndex(1)+1], and so on.

Parameters:
description

a description for this column

add_row(val)

Append a data value to this VectorData column

Parameters:val (None) – the value to add to this column
data_type = 'VectorData'
namespace = 'hdmf-common'
class hdmf.common.table.VectorIndex(name, data, target)

Bases: hdmf.common.table.VectorData

When paired with a VectorData, this allows for storing arrays of varying length in a single cell of the DynamicTable by indexing into this VectorData. The first vector is at VectorData[0:VectorIndex(0)+1]. The second vector is at VectorData[VectorIndex(0)+1:VectorIndex(1)+1], and so on.

Parameters:
target

the target dataset that this index applies to

add_vector(arg)

Add the given data value to the target VectorData and append the corresponding index to this VectorIndex :param arg: The data value to be added to self.target

add_row(arg)

Convenience function. Same as add_vector

__getitem__(arg)

Select elements in this VectorIndex and retrieve the corrsponding data from the self.target VectorData

Parameters:arg – slice or integer index indicating the elements we want to select in this VectorIndex
Returns:Scalar or list of values retrieved
get(arg, **kwargs)

Select elements in this VectorIndex and retrieve the corrsponding data from the self.target VectorData

Parameters:
  • arg – slice or integer index indicating the elements we want to select in this VectorIndex
  • kwargs – keyword arguments to pass into target.get
Returns:

Scalar or list of values retrieved

data_type = 'VectorIndex'
namespace = 'hdmf-common'
class hdmf.common.table.ElementIdentifiers(name, data=[])

Bases: hdmf.container.Data

Data container with a list of unique identifiers for values within a dataset, e.g. rows of a DynamicTable.

Parameters:
data_type = 'ElementIdentifiers'
namespace = 'hdmf-common'
class hdmf.common.table.DynamicTable(name, description, id=None, columns=None, colnames=None)

Bases: hdmf.container.Container

A column-based table. Columns are defined by the argument columns. This argument must be a list/tuple of VectorData and VectorIndex objects or a list/tuple of dicts containing the keys name and description that provide the name and description of each column in the table. Additionally, the keys index, table, vocab can be used for specifying additional structure to the table columns. Setting the key index to True can be used to indicate that the VectorData column will store a ragged array (i.e. will be accompanied with a VectorIndex). Setting the key table to True can be used to indicate that the column will store regions to another DynamicTable. Setting the key vocab to True can be used to indicate that the column data will come from a controlled vocabulary.

Columns in DynamicTable subclasses can be statically defined by specifying the class attribute __columns__, rather than specifying them at runtime at the instance level. This is useful for defining a table structure that will get reused. The requirements for __columns__ are the same as the requirements described above for specifying table columns with the columns argument to the DynamicTable constructor.

Parameters:
description

a description of what is in this table

id

the identifiers for this table

colnames

the ordered names of the columns in this table. columns must also be provided.

columns

the columns in this table

add_row(data=None, id=None, enforce_unique_id=False)

Add a row to the table. If id is not provided, it will auto-increment.

Parameters:
  • data (dict) – the data to put in this row
  • id (int) – the ID for the row
  • enforce_unique_id (bool) – enforce that the id in the table must be unique
add_column(name, description, data=[], table=False, index=False, vocab=False)

Add a column to this table.

If data is provided, it must contain the same number of rows as the current state of the table.

raises ValueError:
 if the column has already been added to the table
Parameters:
create_region(name, region, description)

Create a DynamicTableRegion selecting a region (i.e., rows) in this DynamicTable.

raises:IndexError if the provided region contains invalid indices
Parameters:
  • name (str) – the name of the DynamicTableRegion object
  • region (slice or list or tuple) – the indices of the table
  • description (str) – a brief description of what the region is
__getitem__(key)
get(key, default=None, df=True, **kwargs)

Select a subset from the table

Parameters:key

Key defining which elements of the table to select. This may be one of the following:

  1. string with the name of the column to select
  2. a tuple consisting of (str, int) where the string identifies the column to select by name and the int selects the row
  3. int, list of ints, or slice selecting a set of full rows in the table
Returns:
  1. If key is a string, then return array with the data of the selected column
  2. If key is a tuple of (int, str), then return the scalar value of the selected cell
  3. If key is an int, list or slice, then return pandas.DataFrame consisting of one or more rows
Raises:KeyError
to_dataframe(exclude=None)

Produce a pandas DataFrame containing this table’s data.

Parameters:exclude (set) – Set of columns to exclude from the dataframe
classmethod from_dataframe(df, name, index_column=None, table_description='', columns=None)

Construct an instance of DynamicTable (or a subclass) from a pandas DataFrame.

The columns of the resulting table are defined by the columns of the dataframe and the index by the dataframe’s index (make sure it has a name!) or by a column whose name is supplied to the index_column parameter. We recommend that you supply columns - a list/tuple of dictionaries containing the name and description of the column- to help others understand the contents of your table. See DynamicTable for more details on columns.
Parameters:
  • df (DataFrame) – source DataFrame
  • name (str) – the name of this table
  • index_column (str) – if provided, this column will become the table’s index
  • table_description (str) – a description of what is in the resulting table
  • columns (list or tuple) – a list/tuple of dictionaries specifying columns in the table
copy()

Return a copy of this DynamicTable. This is useful for linking.

data_type = 'DynamicTable'
namespace = 'hdmf-common'
class hdmf.common.table.DynamicTableRegion(name, data, description, table=None)

Bases: hdmf.common.table.VectorData

DynamicTableRegion provides a link from one table to an index or region of another. The table attribute is another DynamicTable, indicating which table is referenced. The data is int(s) indicating the row(s) (0-indexed) of the target array. DynamicTableRegion`s can be used to associate multiple rows with the same meta-data without data duplication. They can also be used to create hierarchical relationships between multiple `DynamicTable`s. `DynamicTableRegion objects may be paired with a VectorIndex object to create ragged references, so a single cell of a DynamicTable can reference many rows of another DynamicTable.

Parameters:
table

The DynamicTable this DynamicTableRegion is pointing to

__getitem__(arg)
get(arg, index=False)

Subset the DynamicTableRegion

Parameters:arg – 1) tuple consisting of (str, int) where the string defines the column to select and the int selects the row, 2) int or slice to select a subset of rows
Returns:Result from self.table[….] with the appropritate selection based on the rows selected by this DynamicTableRegion
to_dataframe(**kwargs)

Convert the whole DynamicTableRegion to a pandas dataframe.

Keyword arguments are passed through to the to_dataframe method of DynamicTable that is being referenced (i.e., self.table). This allows specification of the ‘exclude’ parameter and any other parameters of DynamicTable.to_dataframe.

shape

Define the shape, i.e., (num_rows, num_columns) of the selected table region :return: Shape tuple with two integers indicating the number of rows and number of columns

data_type = 'DynamicTableRegion'
namespace = 'hdmf-common'
class hdmf.common.table.VocabData(name, description, data=[], vocabulary=[])

Bases: hdmf.common.table.VectorData

A n-dimensional dataset that can contain elements from a controlled vocabulary.

Parameters:
data_type = 'VocabData'
namespace = 'hdmf-common'
vocabulary

the items in this vocabulary

__getitem__(arg)
get(arg, index=False, join=False)

Return vocabulary elements for the given argument.

Parameters:
  • index (bool) – Return indices, do not return CV elements
  • join (bool) – Concatenate elements together into a single string
Returns:

CV elements if join is False or a concatenation of all selected elements if join is True.

add_row(val, index=False)

Append a data value to this VocabData column

If a controlled-vocabulary is provided for val (i.e. index is False), the correct index value will be determined. Otherwise, val will be added as provided.
Parameters:
  • val (None) – the value to add to this column
  • index (bool) – whether or not the value being added is an index