hdmf.common.alignedtable module

Collection of Container classes for interacting with aligned and hierarchical dynamic tables

class hdmf.common.alignedtable.AlignedDynamicTable(name, description, id=None, columns=None, colnames=None, target_tables=None, category_tables=None, categories=None)

Bases: DynamicTable

DynamicTable container that supports storing a collection of subtables. Each sub-table is a DynamicTable itself that is aligned with the main table by row index. I.e., all DynamicTables stored in this group MUST have the same number of rows. This type effectively defines a 2-level table in which the main data is stored in the main table implemented by this type and additional columns of the table are grouped into categories, with each category being’ represented by a separate DynamicTable stored within the group.

NOTE: To remain compatible with DynamicTable, the attribute colnames represents only the

columns of the main table (not including the category tables). To get the full list of column names, use the get_colnames() function instead.

Parameters:
property category_tables

List of DynamicTables to be added to the container. NOTE - Only regular DynamicTables are allowed. Using AlignedDynamicTable as a category for AlignedDynamicTable is currently not supported.

property categories

Get the list of names the categories

Short-hand for list(self.category_tables.keys())

Raises:

KeyError if the given name is not in self.category_tables

add_category(category)

Add a new DynamicTable to the AlignedDynamicTable to create a new category in the table.

NOTE: The table must align with (i.e, have the same number of rows as) the main data table (and other category tables). I.e., if the AlignedDynamicTable is already populated with data then we have to populate the new category with the corresponding data before adding it.

raises:

ValueError is raised if the input table does not have the same number of rows as the main table. ValueError is raised if the table is an AlignedDynamicTable instead of regular DynamicTable.

Parameters:

category (DynamicTable) – Add a new DynamicTable category

get_category(name=None)
Parameters:

name (str) – Name of the category we want to retrieve

add_column(name, description, data=[], table=False, index=False, enum=False, col_cls=<class 'hdmf.common.table.VectorData'>, check_ragged=True, category=None)

Add a column to the table

raises:

KeyError if the category does not exist

Parameters:

  • name (str) – the name of this VectorData

  • description (str) – a description for this column

  • data (ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or DataIO) – a dataset where the first dimension is a concatenation of multiple vectors

  • table (bool or DynamicTable) – whether or not this is a table region or the table the region applies to

  • index (bool or VectorIndex or ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator or int) –

    • False (default): do not generate a VectorIndex

    • True: generate one empty VectorIndex

    • VectorIndex: Use the supplied VectorIndex

    • array-like of ints: Create a VectorIndex and use these values as the data

    • int: Recursively create n VectorIndex objects for a multi-ragged array

  • enum (bool or ndarray or list or tuple or Dataset or Array or StrDataset or HDMFDataset or AbstractDataChunkIterator) – whether or not this column contains data from a fixed set of elements

  • col_cls (type) – class to use to represent the column data. If table=True, this field is ignored and a DynamicTableRegion object is used. If enum=True, this field is ignored and a EnumData object is used.

  • check_ragged (bool) – whether or not to check for ragged arrays when adding data to the table. Set to False to avoid checking every element if performance issues occur.

  • category (str) – The category the column should be added to

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

We can either provide the row data as a single dict or by specifying a dict for each category

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

get_colnames(include_category_tables=False, ignore_category_ids=False)

Get the full list of names of columns for this table

returns:

List of tuples (str, str) where the first string is the name of the DynamicTable that contains the column and the second string is the name of the column. If include_category_tables is False, then a list of column names is returned.

Parameters:

  • include_category_tables (bool) – Ignore sub-category tables and just look at the main table

  • ignore_category_ids (bool) – Ignore id columns of sub-category tables

to_dataframe(ignore_category_ids=False)

Convert the collection of tables to a single pandas DataFrame

Parameters:

ignore_category_ids (bool) – Ignore id columns of sub-category tables

__getitem__(item)

Called to implement standard array slicing syntax.

Same as self.get(item). See get for details.

get(item, **kwargs)

Access elements (rows, columns, category tables etc.) from the table. Instead of calling this function directly, the class also implements standard array slicing syntax via __getitem__ (which calls this function). For example, instead of calling self.get(item=slice(2,5)) we may use the often more convenient form of self[2:5] instead.

Parameters:

item – Selection defining the items of interest. This may be either a:

  • int, list, array, sliceReturn one or multiple row of the table as a pandas.DataFrame. For example:

    • self[0] : Select the first row of the table

    • self[[0,3]] : Select the first and fourth row of the table

    • self[1:4] : Select the rows with index 1,2,3 from the table

  • stringReturn a column from the main table or a category table. For example:

    • self['column'] : Return the column from the main table.

    • self['my_category'] : Returns a DataFrame of the my_category category table. This is a shorthand for self.get_category('my_category').to_dataframe().

  • tuple: Get a column, row, or cell from a particular category table. The tuple is expected to consist of the following elements:

    • category: string with the name of the category. To select from the main table use self.name or None.

    • column: string with the name of the column, and

    • row: integer index of the row.

    The tuple itself then may take the following forms:

    • Select a single column from a table via:

      • self[category, column]

    • Select a single full row of a given category table via:

      • self[row, category] (recommended, for consistency with DynamicTable)

      • self[category, row]

    • Select a single cell via:

      • self[row, (category, column)] (recommended, for consistency with DynamicTable)

      • self[row, category, column]

      • self[category, column, row]

Returns:

Depending on the type of selection the function returns a:

  • pandas.DataFrame: when retrieving a row or category table

  • array : when retrieving a single column

  • single value : when retrieving a single cell. The data type and shape will depend on the data type and shape of the cell/column.

has_foreign_columns(ignore_category_tables=False)

Does the table contain DynamicTableRegion columns

returns:

True if the table or any of the category tables contains a DynamicTableRegion column, else False

Parameters:

ignore_category_tables (bool) – Ignore the category tables and only check in the main table columns

get_foreign_columns(ignore_category_tables=False)
Determine the names of all columns that link to another DynamicTable, i.e.,

find all DynamicTableRegion type columns. Similar to a foreign key in a database, a DynamicTableRegion column references elements in another table.

returns:

List of tuples (str, str) where the first string is the name of the category table (or None if the column is in the main table) and the second string is the column name.

Parameters:

ignore_category_tables (bool) – Ignore the category tables and only check in the main table columns

get_linked_tables(other_tables=None, ignore_category_tables=False)
Get a list of the full list of all tables that are being linked to directly or indirectly

from this table via foreign DynamicTableColumns included in this table or in any table that can be reached through DynamicTableRegion columns

Returns: List of dicts with the following keys:

  • ‘source_table’ : The source table containing the DynamicTableRegion column

  • ‘source_column’ : The relevant DynamicTableRegion column in the ‘source_table’

  • ‘target_table’ : The target DynamicTable; same as source_column.table.

Parameters:

  • other_tables (list or tuple or set) – List of additional tables to consider in the search. Usually this parameter is used for internal purposes, e.g., when we need to consider AlignedDynamicTable

  • ignore_category_tables (bool) – Ignore the category tables and only check in the main table columns

data_type = 'AlignedDynamicTable'
namespace = 'hdmf-common'