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.
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.
trim_back(tag_string)	Return a trimmed copy of tag_string.
trim_front(tag_string)	Return a copy of tag_string with leading blanks and commas removed.

check_df_columns(df, required_cols=('column_name', 'column_value', 'description', 'HED'))

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)

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)

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)

Create a sidecar column dictionary for column.

Parameters:

• column_name (str) – Name of the column.

• column_values – List of column values.

hed_to_df(sidecar_dict, col_names=None)

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 side car.

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)

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.

trim_back(tag_string)

Return a trimmed copy of tag_string.

Parameters:

tag_string (str) – A tag string to be trimmed.

Returns:

A copy of tag_string that has been trimmed.

Return type:

str

Notes

• The trailing blanks and commas are removed from the copy.

trim_front(tag_string)

Return a copy of tag_string with leading blanks and commas removed.

Parameters:

tag_string (str) – A tag string to be trimmed.

Returns:

A copy of tag_string that has been trimmed.

Return type:

str