HedString¶

class HedString(hed_string, hed_schema, def_dict=None, _contents=None)[source]: A HED string.

Methods

`hed.models.hed_string.HedString.__init__`(...)	Constructor for the HedString class.
`hed.models.hed_string.HedString.append`(...)	Add a tag or group to this group.
`hed.models.hed_string.HedString.check_if_in_original`(...)	Check if the tag or group in original string.
`hed.models.hed_string.HedString.copy`()	Return a deep copy of this string.
`hed.models.hed_string.HedString.expand_defs`()	Replace def tags with def-expand tags
`hed.models.hed_string.HedString.find_def_tags`([...])	Find def and def-expand tags
`hed.models.hed_string.HedString.find_exact_tags`(...)	Find the given tags.
`hed.models.hed_string.HedString.find_placeholder_tag`()	Return a placeholder tag, if present in this group.
`hed.models.hed_string.HedString.find_tags`(...)	Find the base tags and their containing groups.
`hed.models.hed_string.HedString.find_tags_with_term`(term)	Find any tags that contain the given term.
`hed.models.hed_string.HedString.find_top_level_tags`(...)	Find top level groups with an anchor tag.
`hed.models.hed_string.HedString.find_wildcard_tags`(...)	Find the tags and their containing groups.
`hed.models.hed_string.HedString.from_hed_strings`(...)	Factory for creating HedStrings via combination.
`hed.models.hed_string.HedString.get_all_groups`([...])	Return HedGroups, including descendants and self.
`hed.models.hed_string.HedString.get_all_tags`()	Return HedTags, including descendants.
`hed.models.hed_string.HedString.get_as_form`(...)	Get the string corresponding to the specified form.
`hed.models.hed_string.HedString.get_as_indented`([...])	Returns the string as a multiline indented format
`hed.models.hed_string.HedString.get_as_long`()	Return this HedGroup as a long tag string.
`hed.models.hed_string.HedString.get_as_original`()	Return the original form of this string.
`hed.models.hed_string.HedString.get_as_short`()	Return this HedGroup as a short tag string.
`hed.models.hed_string.HedString.get_first_group`()	Returns the first group in this hed string or group.
`hed.models.hed_string.HedString.get_original_hed_string`()	Get the original hed string.
`hed.models.hed_string.HedString.groups`()	Return the direct child groups of this group.
`hed.models.hed_string.HedString.lower`()	Convenience function, equivalent to str(self).lower()
`hed.models.hed_string.HedString.remove`(...)	Remove any tags/groups in items_to_remove.
`hed.models.hed_string.HedString.remove_definitions`()	Remove definition tags and groups from this string.
`hed.models.hed_string.HedString.remove_refs`()	This removes any refs(tags contained entirely inside curly braces) from the string.
`hed.models.hed_string.HedString.replace`(...)	Replace an existing tag or group.
`hed.models.hed_string.HedString.shrink_defs`()	Replace def-expand tags with def tags
`hed.models.hed_string.HedString.sort`()	Sort the tags and groups in this HedString in a consistent order.
`hed.models.hed_string.HedString.sorted`()	Returns a sorted copy of this hed group
`hed.models.hed_string.HedString.split_hed_string`(...)	Split a HED string into delimiters and tags.
`hed.models.hed_string.HedString.split_into_groups`(...)	Split the HED string into a parse tree.
`hed.models.hed_string.HedString.tags`()	Return the direct child tags of this group.
`hed.models.hed_string.HedString.validate`([...])	Validate the string using the schema

Attributes

`hed.models.hed_string.HedString.CLOSING_GROUP_CHARACTER`
`hed.models.hed_string.HedString.OPENING_GROUP_CHARACTER`
`hed.models.hed_string.HedString.is_group`	Always False since the underlying string is not a group with parentheses.
`hed.models.hed_string.HedString.span`	Return the source span.

HedString.__init__(hed_string, hed_schema, def_dict=None, _contents=None)[source]¶

Constructor for the HedString class.

Parameters:

hed_string (str) – A HED string consisting of tags and tag groups.
hed_schema (HedSchema) – The schema to use to identify tags.
def_dict (DefinitionDict or None) – The def dict to use to identify def/def expand tags.
_contents ([HedGroup and/or HedTag] or None) – Create a HedString from this exact list of children. Does not make a copy.

Notes

The HedString object parses its component tags and groups into a tree-like structure.

HedString.append(tag_or_group)¶

Add a tag or group to this group.

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

HedString.check_if_in_original(tag_or_group)¶

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

HedString.copy()[source]¶

Return a deep copy of this string.

Returns:: The copied group.
Return type:: HedString

HedString.expand_defs()[source]¶

Replace def tags with def-expand tags

This does very minimal validation

Returns:: self

HedString.find_def_tags(recursive=False, include_groups=3)¶

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

HedString.find_exact_tags(exact_tags, recursive=False, include_groups=1)¶

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

HedString.find_placeholder_tag()¶

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.

HedString.find_tags(search_tags, recursive=False, include_groups=2)¶

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

HedString.find_tags_with_term(term, recursive=False, include_groups=2)¶

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

HedString.find_top_level_tags(anchor_tags, include_groups=2)[source]¶

Find top level groups with an anchor tag.

A max of 1 tag located per top level group.

Parameters:

anchor_tags (container) – A list/set/etc of short_base_tags to find groups by.
include_groups (0, 1 or 2) – Parameter indicating what return values to include. If 0: return only tags. If 1: return only groups. If 2 or any other value: return both.

Returns:

The returned result depends on include_groups:

Return type:

list or tuple

HedString.find_wildcard_tags(search_tags, recursive=False, include_groups=2)¶

Find the tags and their containing groups.

This searches tag.short_tag, 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

classmethod HedString.from_hed_strings(hed_strings)[source]¶

Factory for creating HedStrings via combination.

Parameters:: hed_strings (list or None) – A list of HedString objects to combine. This takes ownership of their children.
Returns:: The newly combined HedString
Return type:: new_string(HedString)

HedString.get_all_groups(also_return_depth=False)¶

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

HedString.get_all_tags()¶

Return HedTags, including descendants.

Returns:: A list of all the tags in this group including descendants.
Return type:: list

HedString.get_as_form(tag_attribute)¶

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

HedString.get_as_indented(tag_attribute='short_tag')¶

Returns 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)

HedString.get_as_long()¶

Return this HedGroup as a long tag string.

Returns:: The group as a string with all tags as long tags.
Return type:: str

HedString.get_as_original()[source]¶

Return the original form of this string.

Returns:: The string with all the tags in their original form.
Return type:: str

Notes

Potentially with some extraneous spaces removed on returned string.

HedString.get_as_short()¶

Return this HedGroup as a short tag string.

Returns:: The group as a string with all tags as short tags.
Return type:: str

HedString.get_first_group()¶

Returns 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

HedString.get_original_hed_string()¶

Get the original hed string.

Returns:: The original string with no modification.
Return type:: str

HedString.groups()¶

Return the direct child groups of this group.

Returns:: All groups directly in this group, filtering out HedTag children.
Return type:: list

HedString.lower()¶: Convenience function, equivalent to str(self).lower()

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

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.

HedString.remove_definitions()[source]¶

Remove definition tags and groups from this string.

This does not validate definitions and will blindly removing invalid ones as well.

HedString.remove_refs()[source]¶

This removes any refs(tags contained entirely inside curly braces) from the string.

This does NOT validate the contents of the curly braces. This is only relevant when directly editing sidecar strings. Tools will naturally ignore these.

static HedString.replace(item_to_replace, new_contents)¶

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

HedString.shrink_defs()[source]¶

Replace def-expand tags with def tags

This does not validate them and will blindly shrink invalid ones as well.

Returns:: self

HedString.sort()¶: Sort the tags and groups in this HedString in a consistent order.

HedString.sorted()¶

Returns a sorted copy of this hed group

Returns:: The sorted copy
Return type:: sorted_copy (HedGroup)

static HedString.split_hed_string(hed_string)[source]¶

Split a HED string into delimiters and tags.

Parameters:: hed_string (str) – The HED string to split.
Returns:: A list of tuples where each tuple is (is_hed_tag, (start_pos, end_pos)).
Return type:: list

Notes

The tuple format is as follows
- is_hed_tag (bool): A (possible) hed tag if true, delimiter if not.
- start_pos (int): Index of start of string in hed_string.
- end_pos (int): Index of end of string in hed_string
This function does not validate tags or delimiters in any form.

static HedString.split_into_groups(hed_string, hed_schema, def_dict=None)[source]¶

Split the HED string into a parse tree.

Parameters:

hed_string (str) – A hed string consisting of tags and tag groups to be processed.
hed_schema (HedSchema) – HED schema to use to identify tags.
def_dict (DefinitionDict) – The definitions to identify

Returns:

A list of HedTag and/or HedGroup.

Return type:

list

Raises:

ValueError –

The string is significantly malformed, such as mismatched parentheses.

Notes

The parse tree consists of tag groups, tags, and delimiters.

HedString.tags()¶

Return the direct child tags of this group.

Returns:: All tags directly in this group, filtering out HedGroup children.
Return type:: list

HedString.validate(allow_placeholders=True, error_handler=None)[source]¶

Validate the string using the schema

Parameters:

allow_placeholders (bool) – allow placeholders in the string
error_handler (ErrorHandler or None) – the error handler to use, creates a default one if none passed

Returns:

A list of issues for hed string

Return type:

issues (list of dict)

HedString.CLOSING_GROUP_CHARACTER = ')'¶

HedString.OPENING_GROUP_CHARACTER = '('¶

HedString.is_group¶: Always False since the underlying string is not a group with parentheses.

HedString.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