annotation_util

Utilities to facilitate annotation of events in BIDS.

Functions

check_df_columns(df[, required_cols])

Return a list of the specified columns that are missing from a dataframe.

df_to_hed(dataframe[, description_tag])

Create sidecar-like dictionary from a 4-column dataframe.

extract_tags(hed_string, search_tag)

Extract all instances of specified tag from a tag_string.

generate_sidecar_entry(column_name[, ...])

Create a sidecar column dictionary for column.

get_bids_dataset(data_root)

Return a BIDS dataset object given a path to a dataset root.

hed_to_df(sidecar_dict[, col_names])

Return a 4-column dataframe of HED portions of sidecar.

merge_hed_dict(sidecar_dict, hed_dict)

Update a JSON sidecar based on the hed_dict values.

series_to_factor(series)

Convert a series to an integer factor list.

str_to_tabular(tsv_str[, sidecar])

Return a TabularInput a tsv string.

strs_to_hed_objs(hed_strings, hed_schema)

Returns a list of HedString objects from a list of strings.

strs_to_sidecar(sidecar_strings)

Return a Sidecar from a sidecar as string or as a list of sidecars as strings.

to_factor(data[, column])

Convert data to an integer factor list.

to_strlist(obj_list)

Return a list with the objects converted to string except for None elements.
check_df_columns(df, required_cols=('column_name', 'column_value', 'description', 'HED'))[source]

Return a list of the specified columns that are missing from a dataframe.

Parameters:

  • df (DataFrame) – Spreadsheet to check the columns of.

  • required_cols (tuple) – List of column names that must be present.

Returns:

List of column names that are missing.

Return type:

list

df_to_hed(dataframe, description_tag=True)[source]

Create sidecar-like dictionary from a 4-column dataframe.

Parameters:

  • dataframe (DataFrame) – A four-column Pandas DataFrame with specific columns.

  • description_tag (bool) – If True description tag is included.

Returns:

A dictionary compatible with BIDS JSON tabular file that includes HED.

Return type:

dict

Notes

  • The DataFrame must have the columns with names: column_name, column_value, description, and HED.

extract_tags(hed_string, search_tag)[source]

Extract all instances of specified tag from a tag_string.

Parameters:

  • hed_string (str) – Tag string from which to extract tag.

  • search_tag (str) – HED tag to extract.

Returns:

  • str: Tag string without the tags.

  • list: A list of the tags that were extracted, for example descriptions.

Return type:

tuple

generate_sidecar_entry(column_name, column_values=None)[source]

Create a sidecar column dictionary for column.

Parameters:

  • column_name (str) – Name of the column.

  • column_values – List of column values.

get_bids_dataset(data_root)[source]

Return a BIDS dataset object given a path to a dataset root.

Parameters:

data_root (str) – Path to the BIDS dataset root.

Returns:

BidsDataset

hed_to_df(sidecar_dict, col_names=None)[source]

Return a 4-column dataframe of HED portions of sidecar.

Parameters:

  • sidecar_dict (dict) – A dictionary conforming to BIDS JSON events sidecar format.

  • col_names (list, None) – A list of the cols to include in the flattened sidecar.

Returns:

Four-column spreadsheet representing HED portion of sidecar.

Return type:

DataFrame

Notes

  • The returned DataFrame has columns: column_name, column_value, description, and HED.

merge_hed_dict(sidecar_dict, hed_dict)[source]

Update a JSON sidecar based on the hed_dict values.

Parameters:

  • sidecar_dict (dict) – Dictionary representation of a BIDS JSON sidecar.

  • hed_dict (dict) – Dictionary derived from a dataframe representation of HED in sidecar.

series_to_factor(series)[source]

Convert a series to an integer factor list.

Parameters:

series (Series) –

Returns:

list - contains 0’s and 1’s, empty, ‘n/a’ and np.nan are converted to 0.

str_to_tabular(tsv_str, sidecar=None)[source]

Return a TabularInput a tsv string.

Parameters:

  • tsv_str (str) – A string representing a tabular input.

  • sidecar – An optional Sidecar object.

strs_to_hed_objs(hed_strings, hed_schema)[source]

Returns a list of HedString objects from a list of strings.

Parameters:

  • hed_strings (string or list) – String or strings representing HED annotations.

  • hed_schema (HedSchema or HedSchemaGroup) – Schema version for the strings.

Returns:

list of HedString objects or None.

Return type:

list or None

strs_to_sidecar(sidecar_strings)[source]

Return a Sidecar from a sidecar as string or as a list of sidecars as strings.

Parameters:

sidecar_strings (string or list) – String or strings representing sidecars.

Returns:

the merged sidecar from the list.

Return type:

Sidecar or None

to_factor(data, column=None)[source]

Convert data to an integer factor list.

Parameters:

  • data (Series or DataFrame) –

  • column (str) – Optional column name if DataFrame (otherwise column 0).

Returns:

list - contains 0’s and 1’s, empty, ‘n/a’ and np.nan are converted to 0.

to_strlist(obj_list)[source]

Return a list with the objects converted to string except for None elements.

Parameters:

obj_list (list) – A list of objects that are None or have a str method.

Returns:

A list with the objects converted to strings – except None values are preserved.

Return type:

list