Validator¶

Validation tools for HED data structures and annotations.

Core validator classes¶

HedValidator¶

class HedValidator(hed_schema, def_dicts=None, definitions_allowed=False)[source]¶

Bases: object

Top level validation of HED strings.

This module contains the HedValidator class which is used to validate the tags in a HED string or a file. The file types include .tsv, .txt, and .xlsx. To get the validation issues after creating a HedValidator class call the get_validation_issues() function.

check_tag_formatting(original_tag) → list[dict][source]¶

Report repeated or erroneous slashes.

Parameters:: original_tag (HedTag) – The original tag that is used to report the error.
Returns:: Validation issues. Each issue is a dictionary.
Return type:: list[dict]

pattern_doubleslash = re.compile('([ \\t/]{2,}|^/|/$)')¶

run_basic_checks(hed_string, allow_placeholders) → list[dict][source]¶

Run basic validation checks on a HED string.

Parameters:

hed_string (HedString) – The HED string to validate.
allow_placeholders (bool) – Whether placeholders are allowed in the HED string.

Returns:

A list of issues found during validation. Each issue is represented as a dictionary.

Return type:

list[dict]

Notes

This method performs initial validation checks on the HED string, including character validation and tag validation.
It checks for invalid characters, calculates canonical forms, and validates individual tags.
If any issues are found during these checks, the method stops and returns the issues immediately.
The method also validates definition tags if applicable.

run_full_string_checks(hed_string) → list[dict][source]¶

Run all full-string validation checks on a HED string.

Parameters:: hed_string (HedString) – The HED string to validate.
Returns:: A list of issues found during validation. Each issue is represented as a dictionary.
Return type:: list[dict]

Notes

This method iterates through a series of validation checks defined in the checks list.
Each check is a callable function that takes hed_string as input and returns a list of issues.
If any check returns issues, the method stops and returns those issues immediately.
If no issues are found, an empty list is returned.

validate(hed_string, allow_placeholders, error_handler=None) → list[dict][source]¶

Validate the HED string object using the schema.

Parameters:

hed_string (HedString) – the string to validate.
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:

list[dict]

validate_units(original_tag, validate_text=None, report_as=None, error_code=None, index_offset=0, allow_placeholders=True) → list[dict][source]¶

Validate units and value classes

Parameters:

original_tag (HedTag) – The source tag
validate_text (str) – the text we want to validate, if not the full extension.
report_as (HedTag) – Report the error tag as coming from a different one. Mostly for definitions that expand.
error_code (str) – The code to override the error as. Again mostly for def/def-expand tags.
index_offset (int) – Offset into the extension validate_text starts at
allow_placeholders (bool) – Whether placeholders are allowed (affects value class validation for “#”)

Returns:

Issues found from units

Return type:

list[dict]

Specialized validators¶

SidecarValidator¶

class SidecarValidator(hed_schema)[source]¶

Bases: object

reserved_category_values = ['n/a']¶

reserved_column_names = ['HED']¶

validate(sidecar, extra_def_dicts=None, name=None, error_handler=None) → list[dict][source]¶

Validate the input data using the schema

Parameters:

sidecar (Sidecar) – Input data to be validated.
extra_def_dicts (list or DefinitionDict) – extra def dicts in addition to sidecar
name (str) – The name to report this sidecar as
error_handler (ErrorHandler) – Error context to use. Creates a new one if None.

Returns:

A list of issues associated with each level in the HED string.

Return type:

list[dict]

validate_structure(sidecar, error_handler) → list[dict][source]¶

Validate the raw structure of this sidecar.

Parameters:

sidecar (Sidecar) – the sidecar to validate
error_handler (ErrorHandler) – The error handler to use for error context.

Returns:

A list of issues found with the structure.

Return type:

list[dict]

SpreadsheetValidator¶

class SpreadsheetValidator(hed_schema)[source]¶

Bases: object

ONSET_TOLERANCE = 3¶

TEMPORAL_ANCHORS = re.compile('onset|inset|offset|delay')¶

validate(data, def_dicts=None, name=None, error_handler=None) → list[dict][source]¶

Validate the input data using the schema

Parameters:

data (BaseInput) – Input data to be validated.
def_dicts (list of DefDict or DefDict) – all definitions to use for validation
name (str) – The name to report errors from this file as
error_handler (ErrorHandler) – Error context to use. Creates a new one if None.

Returns:

A list of issues for HED string

Return type:

list[dict]

DefValidator¶

class DefValidator(def_dicts=None, hed_schema=None)[source]¶

Bases: DefinitionDict

Validates Def/ and Def-expand/, as well as Temporal groups: Onset, Inset, and Offset

add_definitions(defs, hed_schema=None)¶

Add definitions from dict(s) or strings(s) to this dict.

Parameters:

defs (list, DefinitionDict, dict, or str) – DefinitionDict or list of DefinitionDicts/strings/dicts whose definitions should be added.
hed_schema (HedSchema or None) – Required if passing strings or lists of strings, unused otherwise.

Note - dict form expects DefinitionEntries in the same form as a DefinitionDict: Note - str or list of strings will parse the strings using the hed_schema. Note - You can mix and match types, eg [DefinitionDict, str, list of str] would be valid input.

Raises:: TypeError – Bad type passed as defs.

check_for_definitions(hed_string_obj, error_handler=None) → list[dict]¶

Check string for definition tags, adding them to self.

Parameters:

hed_string_obj (HedString) – A single HED string to gather definitions from.
error_handler (ErrorHandler or None) – Error context used to identify where definitions are found.

Returns:

List of issues encountered in checking for definitions. Each issue is a dictionary.

Return type:

list[dict]

get(def_name) → DefinitionEntry | None¶

Get the definition entry for the definition name.

Not case-sensitive

Parameters:: def_name (str) – Name of the definition to retrieve.
Returns:: Definition entry for the requested definition.
Return type:: Union[DefinitionEntry, None]

static get_as_strings(def_dict) → dict[str, str]¶

Convert the entries to strings of the contents

Parameters:: def_dict (dict) – A dict of definitions
Returns:: Definition name and contents
Return type:: dict[str,str]

get_definition_entry(def_tag)¶

Get the entry for a given def tag.

Does not validate at all.

Parameters:: def_tag (HedTag) – Source HED tag that may be a Def or Def-expand tag.
Returns:: The definition entry if it exists
Return type:: def_entry(DefinitionEntry or None)

property issues¶: Return issues about duplicate definitions.

items()¶

Return the dictionary of definitions.

Alias for .defs.items()

Returns:: DefinitionEntry}): A list of definitions.
Return type:: def_entries({str

validate_def_tags(hed_string_obj) → list[dict][source]¶

Validate Def/Def-Expand tags.

Parameters:

hed_string_obj (HedString) – The HED string to process.
hed_validator (HedValidator) – Used to validate the placeholder replacement.

Returns:

Issues found related to validating defs. Each issue is a dictionary.

Return type:

list[dict]

validate_def_value_units(def_tag, hed_validator, allow_placeholders=False) → list[dict][source]¶: Equivalent to HedValidator.validate_units for the special case of a Def or Def-expand tag

validate_onset_offset(hed_string_obj) → list[dict][source]¶

Validate onset/offset

Parameters:: hed_string_obj (HedString) – The HED string to check.
Returns:: A list of issues found in validating onsets (i.e., out of order onsets, unknown def names).
Return type:: list[dict]

OnsetValidator¶

class OnsetValidator[source]¶

Bases: object

Validates onset/offset pairs.

static check_for_banned_tags(hed_string) → list[dict][source]¶

Returns an issue for every tag found from the banned list (for files without onset column).

Parameters:: hed_string (HedString) – The string to check.
Returns:: The validation issues associated with the characters. Each issue is dictionary.
Return type:: list[dict]

validate_temporal_relations(hed_string_obj) → list[dict][source]¶

Validate onset/offset/inset tag relations

Parameters:: hed_string_obj (HedString) – The HED string to check.
Returns:: A list of issues found in validating onsets (i.e., out of order onsets, repeated def names).
Return type:: list[dict]

Validation utilities¶

ReservedChecker¶

class ReservedChecker[source]¶

Bases: object

check_reserved_compatibility(group, reserved_tags)[source]¶

Check to make sure that the reserved tags can be used together and no duplicates.

Parameters:

group (HedTagGroup) – A group to be checked.
reserved_tags (list of HedTag) – A list of reserved tags in this group.

check_tag_requirements(group, reserved_tags)[source]¶

Check the tag requirements within the group.

Parameters:

group (HedTagGroup) – A group to be checked.
reserved_tags (list of HedTag) – A list of reserved tags in this group.

Notes: This is only called when there are some reserved incompatible tags.

get_def_information(group, reserved_tags) → list[list][source]¶

Get definition information for reserved tags.

Parameters:

group (HedGroup) – The HED group to check.
reserved_tags (list of HedTag) – The reserved tags to process.

Returns:

A list containing [requires_defs, defs].

Return type:

list[list]

get_group_requirements(reserved_tags) → tuple[float, float][source]¶

Returns the maximum and minimum number of groups required for these reserved tags.

Parameters:: reserved_tags (list of HedTag) – The reserved tags to be checked.
Returns:: the maximum required and the minimum required.
Return type:: tuple[float, float]

get_incompatible(tag, reserved_tags) → list[source]¶

Return the list of tags that cannot be in the same group with tag.

Parameters:

tag (HedTag) – Reserved tag to be tested.
reserved_tags (list of HedTag) – Reserved tags (no duplicates).

Returns:

List of incompatible tags.

Return type:

list[HedTag]

static get_instance()[source]¶

get_reserved(group)[source]¶

reserved_reqs_path = '/home/runner/work/hed-resources/hed-resources/submodules/hed-python/hed/validator/data/reservedTags.json'¶