HED services

HED tools are available as web services. HED uses JSON format for both the request parameters and the response return values. The tools are also available to run locally using a deployer Docker module. (See the GitHub hed-python repository for code and additional information.) Examples of calling the services in MATLAB can be found at: https://github.com/hed-standard/hed-python/blob/master/webtools/examples/matlab.

The HED services are currently hosted on https://hedtools.ucsd.edu/hed.

To perform a request:

  1. Send an initial request to: https://hedtools.ucsd.edu/hed/services to get cookie information and a csrf token. The getSessionInfo function gives an example of how to perform this initial request in MATLAB.
  2. Use the cookie and csrf token from Step 1 in all subsequent requests for this session. The URL for making actual service requests is: https://hedtools.ucsd.edu/hed/services_submit.
  3. The form of parameters for the request is a two-entry JSON dictionary with keys "service" and "service_parameters".
    • The value associated with "service" is a string giving the name of the service.
    • The value associated with "service_parameters" is a dictionary of the names of the required parameters as keys.
    • All parameter values are sent as strings. Files are sent as strings.
    • The HED services interface currently only supports tab-separated-value (tsv) files and JSON files.

HED services and their parameters

ServiceService parameters
get_services
dictionary_to_longjson_string
schema_string or schema_url or schema_version
dictionary_to_shortjson_string
schema_string or schema_url or schema_version
dictionary_validatejson_string
schema_string or schema_url or schema_version
check_for_warnings
events_assemble events_string
json_string
schema_string or schema_url or schema_version
expand_defs
check_for_warnings
events_validate events_string
json_string
schema_string or schema_url or schema_version
check_for_warnings
spreadsheet_to_longspreadsheet_string
schema_string or schema_url or schema_version
spreadsheet_to_shortspreadsheet_string
schema_string or schema_url or schema_version
spreadsheet_validatespreadsheet_string
schema_string or schema_url or schema_version
check_for_warnings
strings_to_longstring_list
schema_string or schema_url or schema_version
strings_to_shortstring_list
schema_string or schema_url or schema_version
strings_validatestring_list
schema_string or schema_url or schema_version
check_for_warnings

HED service response format

All HED services requests have the same response format. The response consists of a JSON dictionary with four keys (shown in the following table). If the service successfully executed the error_type and error_msg are empty. In case of failure, the error_type and error_msg have an explanation of why the service failed --- for example there was a connection timeout.

Response fieldMeaning
serviceName of the requested service.
resultsDictionary with results of service.
error_typeType of error if the service failed.
error_msgExplanation of the message if the service failed.

Format of the results dictionary returned in the response

Results dictionaryKey meaning
commandThe command that was executed in response to the service request.
dataThe data returned by the service.
msg_categorySuccess, warning, or failure depending on the result of service request
msgExplanation of the result of service processing.

Meaning of different HED service request parameters

Service parameterMeaning
check_for_warningsIf true, check for warnings when validating.
column_x_checkIf present with value 'on' indicates that column number x has HED tags.
column_x_inputContains the prefix appended to column x if x has HED tags.
defs_expandIf true, assembly expands definitions and replaces def/XXX with def-expand/XXX.
events_stringA BIDS events file as a string.
has_column_namesIf true, the first row of the spreadsheet or events file is interpreted as column names.
hed_columnsA list of column numbers (starting with 1) of columns containing HED strings. If empty, all columns are used.
hed_stringsList of HED strings to be processed.
json_stringIf true, check for warnings when validating.
schema_stringHED XML schema as a string.
schema_urlA URL from which a HED schema can be downloaded.
schema_versionVersion of HED to used in processing.
spreadsheet_stringA spreadsheet tsv as a string.