HedGroup

class HedGroup(hed_string='', startpos=None, endpos=None, contents=None)[source]

A single parenthesized HED string.

Methods

HedGroup.__init__([hed_string, startpos, ...])

Return an empty HedGroup object.

HedGroup.append(tag_or_group)

Add a tag or group to this group.

HedGroup.casefold()

Convenience function, equivalent to str(self).casefold().

HedGroup.check_if_in_original(tag_or_group)

Check if the tag or group in original string.

HedGroup.copy()

Return a deep copy of this group.

HedGroup.find_def_tags([recursive, ...])

Find def and def-expand tags.

HedGroup.find_exact_tags(exact_tags[, ...])

Find the given tags.

HedGroup.find_placeholder_tag()

Return a placeholder tag, if present in this group.

HedGroup.find_tags(search_tags[, recursive, ...])

Find the base tags and their containing groups.

HedGroup.find_tags_with_term(term[, ...])

Find any tags that contain the given term.

HedGroup.find_wildcard_tags(search_tags[, ...])

Find the tags and their containing groups.

HedGroup.get_all_groups([also_return_depth])

Return HedGroups, including descendants and self.

HedGroup.get_all_tags()

Return HedTags, including descendants.

HedGroup.get_as_form(tag_attribute)

Get the string corresponding to the specified form.

HedGroup.get_as_indented([tag_attribute])

Return the string as a multiline indented format.

HedGroup.get_as_long()

Return this HedGroup as a long tag string.

HedGroup.get_as_short()

Return this HedGroup as a short tag string.

HedGroup.get_first_group()

Return the first group in this HED string or group.

HedGroup.get_original_hed_string()

Get the original HED string.

HedGroup.groups()

Return the direct child groups of this group.

HedGroup.lower()

Convenience function, equivalent to str(self).lower().

HedGroup.remove(items_to_remove)

Remove any tags/groups in items_to_remove.

HedGroup.replace(item_to_replace, new_contents)

Replace an existing tag or group.

HedGroup.sort()

Sort the tags and groups in this HedString in a consistent order.

HedGroup.sorted()

Return a sorted copy of this HED group

HedGroup.tags()

Return the direct child tags of this group.

Attributes

HedGroup.is_group

True if this is a parenthesized group.

HedGroup.span

Return the source span.

HedGroup.__init__(hed_string='', startpos=None, endpos=None, contents=None)[source]

Return an empty HedGroup object.

Parameters:
  • hed_string (str or None) – Source HED string for this group.

  • startpos (int or None) – Starting index of group(including parentheses) in hed_string.

  • endpos (int or None) – Position after the end (including parentheses) in hed_string.

  • contents (list or None) – A list of HedTags and/or HedGroups that will be set as the contents of this group. Mostly used during definition expansion.

HedGroup.append(tag_or_group)[source]

Add a tag or group to this group.

Parameters:

tag_or_group (HedTag or HedGroup) – The new object to add to this group.

HedGroup.casefold()[source]

Convenience function, equivalent to str(self).casefold().

HedGroup.check_if_in_original(tag_or_group)[source]

Check if the tag or group in original string.

Parameters:

tag_or_group (HedTag or HedGroup) – The HedTag or HedGroup to be looked for in this group.

Returns:

True if in this group.

Return type:

bool

HedGroup.copy()[source]

Return a deep copy of this group.

Returns:

The copied group.

Return type:

HedGroup

HedGroup.find_def_tags(recursive=False, include_groups=3)[source]

Find def and def-expand tags.

Parameters:
  • recursive (bool) – If true, also check subgroups.

  • include_groups (int, 0, 1, 2, 3) – Options for return values. If 0: Return only def and def expand tags/. If 1: Return only def tags and def-expand groups. If 2: Return only groups containing defs, or def-expand groups. If 3 or any other value: Return all 3 as a tuple.

Returns:

A list of tuples. The contents depend on the values of the include_group.

Return type:

list

HedGroup.find_exact_tags(exact_tags, recursive=False, include_groups=1)[source]

Find the given tags. This will only find complete matches, any extension or value must also match.

Parameters:
  • exact_tags (list of HedTag) – A container of tags to locate.

  • recursive (bool) – If true, also check subgroups.

  • include_groups (bool) – 0, 1 or 2. If 0: Return only tags If 1: Return only groups If 2 or any other value: Return both

Returns:

A list of tuples. The contents depend on the values of the include_group.

Return type:

list

HedGroup.find_placeholder_tag()[source]

Return a placeholder tag, if present in this group.

Returns:

The placeholder tag if found.

Return type:

HedTag or None

Notes

  • Assumes a valid HedString with no erroneous “#” characters.

HedGroup.find_tags(search_tags, recursive=False, include_groups=2)[source]

Find the base tags and their containing groups. This searches by short_base_tag, ignoring any ancestors or extensions/values.

Parameters:
  • search_tags (container) – A container of short_base_tags to locate.

  • recursive (bool) – If true, also check subgroups.

  • include_groups (0, 1 or 2) – Specify return values. If 0: return a list of the HedTags. If 1: return a list of the HedGroups containing the HedTags. If 2: return a list of tuples (HedTag, HedGroup) for the found tags.

Returns:

The contents of the list depends on the value of include_groups.

Return type:

list

HedGroup.find_tags_with_term(term, recursive=False, include_groups=2)[source]

Find any tags that contain the given term.

Note: This can only find identified tags.

Parameters:
  • term (str) – A single term to search for.

  • recursive (bool) – If true, recursively check subgroups.

  • include_groups (0, 1 or 2) – Controls return values If 0: Return only tags. If 1: Return only groups. If 2 or any other value: Return both.

Return type:

list

HedGroup.find_wildcard_tags(search_tags, recursive=False, include_groups=2)[source]

Find the tags and their containing groups.

This searches tag.short_tag.casefold(), with an implicit wildcard on the end.

e.g. “Eve” will find Event, but not Sensory-event.

Parameters:
  • search_tags (container) – A container of the starts of short tags to search.

  • recursive (bool) – If True, also check subgroups.

  • include_groups (0, 1 or 2) – Specify return values. If 0: return a list of the HedTags. If 1: return a list of the HedGroups containing the HedTags. If 2: return a list of tuples (HedTag, HedGroup) for the found tags.

Returns:

The contents of the list depends on the value of include_groups.

Return type:

list

HedGroup.get_all_groups(also_return_depth=False)[source]

Return HedGroups, including descendants and self.

Parameters:

also_return_depth (bool) – If True, yield tuples (group, depth) rather than just groups.

Returns:

The list of all HedGroups in this group, including descendants and self.

Return type:

list

HedGroup.get_all_tags()[source]

Return HedTags, including descendants.

Returns:

A list of all the tags in this group including descendants.

Return type:

list

HedGroup.get_as_form(tag_attribute)[source]

Get the string corresponding to the specified form.

Parameters:

tag_attribute (str) – The hed_tag property to use to construct the string (usually short_tag or long_tag).

Returns:

The constructed string after transformation.

Return type:

str

HedGroup.get_as_indented(tag_attribute='short_tag')[source]

Return the string as a multiline indented format.

Parameters:

tag_attribute (str) – The hed_tag property to use to construct the string (usually short_tag or long_tag).

Returns:

The indented string.

Return type:

formatted_hed (str)

HedGroup.get_as_long()[source]

Return this HedGroup as a long tag string.

Returns:

The group as a string with all tags as long tags.

Return type:

str

HedGroup.get_as_short()[source]

Return this HedGroup as a short tag string.

Returns:

The group as a string with all tags as short tags.

Return type:

str

HedGroup.get_first_group()[source]

Return the first group in this HED string or group.

Useful for things like Def-expand where they only have a single group.

Raises a ValueError if there are no groups.

Returns:

The first group.

Return type:

HedGroup

HedGroup.get_original_hed_string()[source]

Get the original HED string.

Returns:

The original string with no modification.

Return type:

str

HedGroup.groups()[source]

Return the direct child groups of this group.

Returns:

All groups directly in this group, filtering out HedTag children.

Return type:

list

HedGroup.lower()[source]

Convenience function, equivalent to str(self).lower().

HedGroup.remove(items_to_remove: Iterable[Union[HedTag, HedGroup]])[source]

Remove any tags/groups in items_to_remove.

Parameters:

items_to_remove (list) – List of HedGroups and/or HedTags to remove by identity.

Notes

  • Any groups that become empty will also be pruned.

  • If you pass a child and parent group, the child will also be removed from the parent.

static HedGroup.replace(item_to_replace, new_contents)[source]

Replace an existing tag or group.

Note: This is a static method that relies on the parent attribute of item_to_replace.

Parameters:
  • item_to_replace (HedTag or HedGroup) – The item to replace must exist or this will raise an error.

  • new_contents (HedTag or HedGroup) – Replacement contents.

Raises:
  • KeyError

    • item_to_replace does not exist.

  • AttributeError

    • item_to_replace has no parent set.

HedGroup.sort()[source]

Sort the tags and groups in this HedString in a consistent order.

HedGroup.sorted()[source]

Return a sorted copy of this HED group

Returns:

The sorted copy.

Return type:

sorted_copy (HedGroup)

HedGroup.tags()[source]

Return the direct child tags of this group.

Returns:

All tags directly in this group, filtering out HedGroup children.

Return type:

list

HedGroup.is_group

True if this is a parenthesized group.

HedGroup.span

Return the source span.

Returns:

start index of the group (including parentheses) from the source string. int: end index of the group (including parentheses) from the source string.

Return type:

int