HED API reference

class HedTools

base

Method Summary

static formatEvents(eventsIn)

Convert eventsIn to a char array if necessary.

Parameters:

eventsIn - events as a char, string, or struct

Returns:

events converted to a char.

static formatSidecar(sidecarIn)

Convert the sidecar to a char array if necessary.

Parameters:

sidecarIn - a sidecar as a char, string, or struct

Returns:

sidecar converted to a char.

class HedToolsPython

Concrete class using direct calls to Python for HedTools interface.

Constructor Summary

HedToolsPython(version)

Construct a HedToolsPython object for calling HedTools.

Parameters:

version - string or char array or cellstr

representing a valid HED version.

Method Summary

generateSidecar(eventsIn, valueColumns, skipColumns)

Return a sidecar string based on an events data.py.hed

Parameters:

eventsIn - char, string or rectified struct. valueColumns - cell array of char giving names of

columns to be treated as value columns.

skipColumns - cell array of char giving names of

columns to be skipped.

Returns:

sidecar - char array with sidecar.

getHedAnnotations(events, sidecar, varargin)

Return a cell array of HED annotations of same length as events.

Parameters:

events - char, string or rectified struct. sidecar - char, string or struct representing sidecar

Optional name-value:

‘includeContext’ - boolean true->expand context (usually true). ‘removeTypesOn’ - boolean true-> remove Condition-variable and Task ‘replaceDefs’ - boolean true->replace def with definition (usually true).

Returns:

annotations - cell array with the HED annotations.

Note: The annotations do not have a header line, while events in char or string form is assumed to have a header line.

static getHedFromAnnotations(annotations, schema)

Cell array of char or string convert to py.list of HedString

static getHedQueryHandler(query)

Return a HED query handler.

Parameters:

query - a string query

Returns;

queryHandler - the query handler object.

static getHedSchemaObj(schema)

Get a HedSchema or HedSchemaGroup object based on hedVersion

Parameters:

schema - a single string or a cell array of strings representing

the HED schema version or a schema object.

Returns:

hedSchemaObj - A hedSchema object

static getHedStringObjs(tabular, schema, removeTypesOn, includeContext, replaceDefs)

Return a Python list of HedString objects – used as input for search.

Parameters:

tabular - a TabularInput obj schema - a hedSchema or hedVersion removeTypesOn - boolean true-> remove Condition-variable and Task. includeContext - boolean true->expand context (usually true). replaceDefs - boolean true->replace def with definition (usually true).

Returns:

hedStringObjs (py.list of HedString objects)

Note this is used as the basis for HED queries or for assembled HED. To manipulate directly in MATLAB – convert to a cell array of char using string(cell(hedObjs))

static getSidecarObj(sidecar)

Returns a HEDTools Sidecar object extracted from input.

Parameters:

sidecar - Sidecar object, string, struct or char

Returns:

sidecar_obj - a HEDTools Sidecar object.

static getTabularObj(events, sidecar)

Returns a HED TabularInput object representing events or other columnar item.

Parameters:

events - string, struct, or TabularInput for tabular data. sidecar - Sidecar object, string, or struct or py.None

Returns:

tabularObj - HEDTools TabularInput object representing tabular data.

static getTabularSummary(valueColumns, skipColumns)

Returns a HED TabularSummary object.

Parameters:

valueColumns - cell array with value column names. skipColumns - cell array with skip column names

Returns:

tabularSum - TabularSummary object.

Throws: HedFileError if valueColumns and skipColumns

overlap.

resetHedVersion(version)

Change the HED Version used.

Parameters:

version - cell array or char array or string with HED

version specification.

searchHed(annotations, queries)

Return an array of 0’s and 1’s indicating query truth

Parameters:

annotations - cell array of char or string of length n queries = cell array HED queries of length m

Returns:

factors - n x m array of 1’s and 0’s.

setHedSchema(schema)

Set a HedSchema or HedSchemaGroup object based on hedVersion

Parameters:

schema - a single string or a cell array of strings representing

the HED schema version or a schema object.

validateEvents(events, sidecar, varargin)

Validate HED in events or other tabular-type input.

Parameters:

events - char array, string, struct (or tabularInput) sidecar - char, string or struct representing sidecar

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

Returns:

issues - A string with the validation issues suitable for

printing (has newlines).

validateSidecar(sidecar, varargin)

Validate a sidecar containing HED tags.

Parameters:

sidecar - a char, string, struct, or SidecarObj

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

Returns:

issues - Char array with the validation issues suitable

for printing (has newlines).

validateTags(hedTags, varargin)

Validate a string containing HED tags.

Parameters:

hedTags - A MATLAB string or character array.

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

Returns:

issues - A string with the validation issues suitable for

printing (has newlines).

class HedToolsService

Creates a connection object for the HED web online services.

Constructor Summary

HedToolsService(hedVersion, host)

Construct a HedConnection that can be used for web services.

Parameters:

hedversion - valid version specification host - string or char array with the host name of service

Note, the version could be an array.

Method Summary

generateSidecar(eventsIn, valueColumns, skipColumns)

Return a sidecar string based on an events data.

Parameters:

eventsIn - char, string or rectified struct. valueColumns - cell array of char giving names of

columns to be treated as value columns.

skipColumns - cell array of char giving names of

columns to be skipped.

Returns:

sidecar - char array with sidecar.

getHedAnnotations(eventsIn, sidecar, varargin)

Return a cell array of HED annotations of same length as events.

Parameters:

eventsIn - char, string or rectified struct. sidecar - char, string or struct representing sidecar

Optional name-value:

‘includeContext’ - boolean true->expand context (usually true). ‘removeTypesOn’ - boolean true-> remove Condition-variable and Task ‘replaceDefs’ - boolean true->replace def with definition (usually true).

Returns:

annotations - cell array with the HED annotations.

Note: The annotations do not have a header line, while events in char or string form is assumed to have a header line.

static getRequestTemplate()

Create a parameter template for HEDTools web service request.

resetSessionInfo(host)

Reset the session for accessing the HED webservices

Parameters:

host = URL for the services

Notes: sets obj.Cookie, obj.CRSFToken and obj.Options.

searchHed(annotations, queries)

Return an array of 0’s and 1’s indicating query truth

Parameters:

annotations - cell array of char or string of length n queries = cell array HED queries of length m

Returns:

factors - n x m array of 1’s and 0’s.

validateEvents(events, sidecar, varargin)

Validate HED in events or other tabular-type input.

Parameters:

events - char, string or rectified struct. sidecar - char, string or struct representing sidecar

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

Returns:

issues - A string with the validation issues suitable for

printing (has newlines).

validateSidecar(sidecar, varargin)

Validate a sidecar

Parameters:

sidecar - a string, struct, or char array representing

a sidecar

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

Returns:

issues - printable issue string or empty

validateTags(hedtags, varargin)

Validate a single string of HED tags.

Parameters:

hedtags - a string or char array with a hed tag string.

Optional name-value:

‘checkWarnings’ - boolean (optional, default false)

indicates whether to include warnings.

issues - printable string with issues or an empty

string if no issues.

getHedTools(hedVersion, host)

Factory method that returns either HedToolsService or HedToolsPython

Parameters:

hedVersion - char or cell array with HED version to be used. host - web address of service if HedToolsService is to be used.

remodel(remodel_args)

Run the remodeling tools.

Parameters:

remodel_args - A cell array of command line parameters for remodeling.

remodelRestore(restore_args)

Restore the specified remodeling backup.

Parameters:

restore_args - cell array with restore arguments.

remodelBackup(backup_args)

Create a remodeling backup.

Parameters:

backup_args - cell array with backup arguments.

runRemodelDemos

A test script for a wrapper functions for HED remodeling tools

separateFiles(dirPath)

Separate the files in a directory into lists of directories and files.

Parameters:

dirPath (str) Full path of a directory whose contents are separated.

Returns:

sep_files Cell array of full paths of the files in dirPath sep_dirs Cell array of the full paths of the subdirectories in dirPath

rectify_events(event_struct, sampling_rate)

Makes sure that an EEG.event structure has onset and duration fields.

Parameters:

event_struct - (Input/Output) EEG.event structure adjusted. sampling_rate - Sampling rate needed to convert latency to onset.

events2string(events)

Returns string representing a rectified EEG.event structure

Parameters:

events - the EEGLAB EEG.event struct or similar srate - the EEG sampling rate in Hz (needed if no onset column)

Returns:

event_string - a string representation suitable to write to .tsv

Note 1: The conversion converts NaN to n/a.

Note 2: This assumes that the events structure has been rectified by adding onset and duration fields as required by BIDS.

getFileList(rootPath, namePrefix, nameSuffix, extensions, excludeDirs)

Return a full path list of specified files in rootPath directory tree.

Parameters:

rootPath (char) full path of root of directory tree to search namePrefix (char) prefix of the filename or any if empty string nameSuffix (char) suffix of the filename or any if empty string extensions (cell array) names of extensions (with . included) excludeDirs (cell array) names of subdirectories to exclude

Returns:

selectedList (cell array) list of full paths of the files

str2lines(inString)

Splits a string based on n into cell entries.

Parameters:

inString -

filterDirectories(dirs, excludeDirs)

Returns a filtered list of fullpaths of directories not in excludeDirs

Parameters:

dirs (cell array): List of fullpaths of directories to check. excludeDirs (cell array): List of fullpaths of directories to exclude.

Returns:

cell array: list of fullpaths of directories not excluded.

filterFiles(fileList, namePrefix, nameSuffix, extensions)

Return a list whose filenames satisfy the specified criteria

Parameters:

fileList (cell array) paths of the files to be filtered. namePrefix (char) prefix of the filename or any if empty string nameSuffix (char) suffix of the filename or any if empty string extensions (cell array) names of extensions (with . included)

Returns:

filteredList (cell array) paths of files satisfying criteria.

demoStringServices(host)

Shows how to call hed-services to process a list of hedstrings.

Example 1: Validate valid list of strings using HED version.

Example 2: Validate invalid list of strings using HED URL.

Example 3: Validate invalid list of strings uploading HED schema.

Example 4: Convert valid strings to long using HED version.

runAllDemos

host = ‘https://hedtools.org/hed_dev’; host = ‘http://127.0.0.1:5000’;

getDemoData()

Return the demo data in a struct for running the services.

demoGetServices(host)

Get the options and data

exampleGenerateSidecar

Setup the options

demoLibraryServices(host)

Shows how to call hed-services using libraries.

Example 1: Validate valid events file using HED version list. Example 2: Validate valid events file using HED version list needed libraries. Example 3: Validate events file invalid because of missing library.

getRequestTemplate()

Create a parameter template for HEDTools web service request.

demoEventServices(host)

Shows how to call hed-services to process a BIDS events file.

Example 1: Validate valid events file using HED version.

Example 2: Validate invalid events file using a HED URL.

Example 3: Assemble valid event HED strings uploading HED schema.

Example 4: Assemble valid event HED strings (def expand) using HED version.

Example 5: Generate a JSON sidecar template from an events file.

getHostOptions(host)

Set the options associated with the services for host.

demoSpreadsheetServices(host)

Shows how to call hed-services to process a spreadsheet of event tags.

Example 1: Validate valid spreadsheet file using schema version.

Example 2: Validate invalid spreadsheet file using HED URL.

Example 3: Convert valid spreadsheet file to long uploading HED schema.

Example 4: Convert valid spreadsheet file to short using HED version.

Get the options and data

runDemo

Use this script to run an individual type of service. host = ‘https://hedtools.org/hed’;

demoEventRemodelingServices(host)

Shows how to call hed-services to remodel an events file.

Example 1: Remodeling an change events file by removing column

Example 2: Summarize the column values from an event file.

Example 3: Summarize the HED type tags from an event file

Example 4: Factor HED columns

demoSidecarServices(host)

Shows how to call hed-services to process a BIDS JSON sidecar.

Example 1: Validate valid JSON sidecar using a HED version.

Example 2: Validate invalid JSON sidecar using HED URL.

Example 3: Convert valid JSON sidecar to long uploading HED schema.

Example 4: Convert valid JSON sidecar to short using a HED version.

Example 5: Extract a 4-column spreadsheet from a valid JSON sidecar.

Example 6: Merge a 4-column spreadsheet with a JSON sidecar.

demoEventSearchServices(host)

Shows how to call hed-services to search a BIDS events file.

Example 1: Search an events file for HED using a valid query.

Example 2: Search an events file for HED and return additional columns.

getSessionInfo(csrf_url)

Setup the session for accessing the HED webservices

Parameters:

csrf_url - URL for the services.

Returns:

cookie - A string cookie value. csrftoken - A string csrf token for the session.