Validator¶

Validation tools for HED data structures and annotations.

Core Validator Classes¶

HedValidator¶

class hed.validator.hed_validator.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.

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

Constructor for the HedValidator class.

Parameters:

hed_schema (HedSchema or HedSchemaGroup) – HedSchema object to use for validation.
def_dicts (DefinitionDict or list or dict) – the def dicts to use for validation
definitions_allowed (bool) – If False, flag definitions found as errors

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]

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.

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

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]

validate_units(original_tag, validate_text=None, report_as=None, error_code=None, index_offset=0) → 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

Returns:

Issues found from units

Return type:

list[dict]

Specialized Validators¶

SidecarValidator¶

class hed.validator.sidecar_validator.SidecarValidator(hed_schema)[source]¶

Bases: object

reserved_column_names = ['HED']¶

reserved_category_values = ['n/a']¶

__init__(hed_schema)[source]¶

Constructor for the SidecarValidator class.

Parameters:: hed_schema (HedSchema) – HED schema object to use for validation.

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 hed.validator.spreadsheet_validator.SpreadsheetValidator(hed_schema)[source]¶

Bases: object

ONSET_TOLERANCE = 3¶

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

__init__(hed_schema)[source]¶

Constructor for the SpreadsheetValidator class.

Parameters:: hed_schema (HedSchema) – HED schema object to use for validation.

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 hed.validator.def_validator.DefValidator(def_dicts=None, hed_schema=None)[source]¶

Bases: DefinitionDict

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

__init__(def_dicts=None, hed_schema=None)[source]¶

Initialize for definitions in HED strings.

Parameters:

def_dicts (list or DefinitionDict or str) – DefinitionDicts containing the definitions to pass to baseclass
hed_schema (HedSchema or None) – Required if passing strings or lists of strings, unused otherwise.

validate_def_tags(hed_string_obj, hed_validator=None) → 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 hed.validator.onset_validator.OnsetValidator[source]¶

Bases: object

Validates onset/offset pairs.

__init__()[source]¶

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]

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]

Validation Utilities¶

ReservedChecker¶

class hed.validator.reserved_checker.ReservedChecker[source]¶

Bases: object

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

static get_instance()[source]¶

get_reserved(group)[source]¶

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_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_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_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]