Factor HED tags¶

The factor_hed_tags operation is similar to the factor_column operation in that it produces factor vectors containing 0’s and 1, which are appended to the returned DataFrame. However, rather than basing these vectors on values in a specified column, the factors are computed by determining whether the assembled HED annotations for each row satisfies a specified search query.

An example search query is whether the assembled HED annotation contains a particular HED tag. For more information on HED search queries, see the HED search documentation.

Purpose¶

Use this operation to:

Create factor vectors based on semantic content in HED annotations
Extract experimental conditions encoded in HED tags
Generate design matrices from richly annotated datasets
Query for specific event types using HED tag combinations

Parameters¶

Parameters for the factor_hed_tags operation.

Parameter	Type	Description
queries	list	A list of HED query strings.
query_names	list	(Optional) A list of names for the factor columns generated by the queries.
remove_types	list	(Optional) Structural HED tags to be removed (usually `Condition-variable` and `Task`).
expand_context	bool	(Optional: default True) Expand the context and remove `Onset` and`Offset` tags before the query.

The query_names list, which must be empty or the same length as queries, contains the names of the factor columns produced by the search. If the query_names list is empty, the result columns are titled “query_1”, “query_2”, etc.

Most of the time the remove_types should be set to ["Condition-variable", "Task"] and the effects of the experimental design captured using the factor_hed_types_op. If expand_context is set to false, the additional context provided by Onset, Offset, and Duration is ignored.

Example¶

The factor_hed-tags operation in the following example produce two factor columns with 1’s where the HED string for a row contains the Correct-action and Incorrect-action, respectively. The resulting factor columns are named correct and incorrect, respectively.

A sample JSON file with a single factor_hed_tags transformation operation.

[{ 
    "operation": "factor_hed_tags",
    "description": "Create factors based on whether the event represented a correct or incorrect action.",
    "parameters": {
        "queries": ["correct-action", "incorrect-action"],
        "query_names": ["correct", "incorrect"],
        "remove_types": ["Condition-variable", "Task"],
        "expand_context": false
    }
}]

Results¶

The results of executing this factor_hed-tags operation on the sample remodel event file using the sample remodel sidecar file for HED annotations is:

Results of factor_hed_tags.

onset	duration	trial_type	stop_signal_delay	response_time	response_accuracy	response_hand	sex	correct	incorrect
0.0776	0.5083	go	n/a	0.565	correct	right	female	0	0
5.5774	0.5083	unsuccesful_stop	0.2	0.49	correct	right	female	0	1
9.5856	0.5084	go	n/a	0.45	correct	right	female	0	0
13.5939	0.5083	succesful_stop	0.2	n/a	n/a	n/a	female	1	0
17.1021	0.5083	unsuccesful_stop	0.25	0.633	correct	left	male	0	1
21.6103	0.5083	go	n/a	0.443	correct	left	male	0	0

Notes¶

Requires HED schema: You must specify a HED schema version when creating the Dispatcher
Requires sidecar: Most datasets need a JSON sidecar file with HED annotations
Query syntax follows HED search conventions (see HED documentation)
Use expand_context to include temporal context from Onset/Offset markers
The remove_types parameter helps separate experimental design from event-level queries