Skip to content

Commit 9e11a81

Browse files
VisLabVisLab
authored
Merge pull request #354 from VisLab/develop
Updated docs and removed matlab code from this repo
2 parents c9a7eb6 + 6ad4114 commit 9e11a81

File tree

8 files changed

+234
-157
lines changed

8 files changed

+234
-157
lines changed

‎README.md

Lines changed: 6 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -14,38 +14,14 @@ Most of these datasets have complete versions available on
1414
[**openNeuro**](https://openneuro.org/).
1515
See [**datasets/README.md**](./datasets/README.md) for details.
1616

17-
The [**hedcode**](https://github.com/hed-standard/hed-examples/tree/main/hedcode)
18-
subdirectory contains MATLAB scripts, Python Jupyter Notebooks,
19-
and Python scripts with direct calls to HedTools.
20-
The repository also contains example code in python and matlab.
21-
See [**hedcode/README.md**](src/README.md) for details.
22-
The Python scripts and notebooks require the installation of
23-
`hedtools` whose [**installation**](./README.md#installation-of-hedtools)
24-
is described below.
17+
The [**src**](https://github.com/hed-standard/hed-examples/tree/main/hedcode)
18+
subdirectory contains Python Jupyter notebooks demonstrating calls to HedTools.
19+
For MATLAB support for HED see the [**hed-matlab**](https://github.com/hed-standard/hed-matlab)
20+
GitHub repository.
2521

2622
The [**docs**](https://github.com/hed-standard/hed-examples/tree/main/docs)
27-
subdirectory contains the main documentation for this and other HED resources.
28-
The [**HED GitHub organization repository**](https://github.com/hed-standard/)
23+
subdirectory contains the source documentation for this and other HED resources.
24+
The [**HED GitHub organization**](https://github.com/hed-standard/)
2925
gathers the HED supporting resources, all of which are open source.
3026

3127

32-
### Installation of hedtools
33-
34-
The most of the Python-related resources in this repository
35-
require the installation of the HEDTools Python module, which can be
36-
installed using `pip` or directly from its GitHub repository as follows:
37-
38-
To use `pip` to install `hedtools` from PyPI:
39-
40-
```
41-
pip install hedtools
42-
```
43-
44-
To install directly from the
45-
[GitHub](https://github.com/hed-standard/hed-python) repository:
46-
47-
```
48-
pip install git+https://github.com/hed-standard/hed-python/@master
49-
```
50-
51-
HEDTools require python 3.7 or greater.

‎docs/requirements.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
11
Sphinx>=5.2.2
22
myst-parser>=0.18.1
3-
sphinx_rtd_theme>=1.0.0
3+
sphinx-rtd-theme>=1.0.0

‎docs/source/FileRemodelingQuickstart.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -309,7 +309,7 @@ because *remove_parent_event* is false.
309309
rows in the data file no longer represent trials, but individual events within the trial.)
310310

311311
Next we specify how the new events are generated in the *new_events* dictionary.
312-
Each new event has a name, which is a key in the *new_events* dictionary.
312+
Each type of new event has a name, which is a key in the *new_events* dictionary.
313313
Each key is associated with a dictionary
314314
specifying the values of the following parameters.
315315

@@ -338,7 +338,8 @@ The AOMIC data report indicates that the stop signal lasted 500 ms.
338338
The copy columns indicate which columns from the parent event should be copied to the
339339
newly-created event.
340340
We would like to transfer the *response_accuracy* and the *response_hand* information to the response event.
341-
*Note:* Copy columns is an optional key in the new events dictionary. If you do not want to carry over any column values from the parent event to the new events you can omit this key.
341+
*Note:* Copy columns is an optional key in the *new_events* dictionary.
342+
If you do not want to carry over any column values from the parent event to the new events you can omit this key.
342343

343344

344345
The final remodeling file can be found at:

‎docs/source/FileRemodelingTools.md

Lines changed: 117 additions & 49 deletions
Large diffs are not rendered by default.

‎docs/source/HedMatlabTools.md

Lines changed: 75 additions & 67 deletions
Original file line numberDiff line numberDiff line change
@@ -1,70 +1,71 @@
11
# HED MATLAB tools
22

3-
There are currently three types of support available for HED (Hierarchical Event Descriptors) supports in MATLAB:
4-
5-
* [**HED services in MATLAB**](hed-services-matlab-anchor) - web services called from MATLAB scripts
6-
* [**EEGLAB plug-in integration**](eeglab-integration-anchor) - EEGLAB plugins and other HED support
7-
* [**Python HEDTools in MATLAB**](python-hedtools-in-matlab-anchor) - explains how to call the HED python tools from within MATLAB.
8-
9-
HED services allow MATLAB programs to request the same services that are available
10-
through the browser at [https://hedtools.edu/hed](https://hedtools.edu/hed).
11-
12-
(hed-services-matlab-anchor)=
13-
## HED services in MATLAB
14-
15-
HED RESTful services allow programs to make requests directly to the
16-
HED online tools available at
17-
[https://hedtools.edu/hed](https://hedtools.edu/hed) or
18-
in a locally-deployed docker module.
19-
See [**HED-web**](https://hed-web.readthedocs.io/en/latest/index.html)
20-
for additional information on the deployment.
21-
22-
The [**runAllTests.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/runAllTests.m)
23-
is a main script that runs all the example code and reports whether
24-
the code runs successfully.
25-
You should start by running this script to make sure everything is working on your system,
3+
There are currently three types of support available for HED (Hierarchical Event Descriptors) in MATLAB:
4+
5+
* [**HED web services in MATLAB**](hed-web-services-in-matlab-anchor) - web services called from MATLAB scripts.
6+
* [**EEGLAB plug-in integration**](eeglab-integration-anchor) - EEGLAB plugins and other native MATLAB.
7+
* [**Python HEDTools in MATLAB**](python-hedtools-in-matlab-anchor) - calling HED python tools from within MATLAB.
8+
9+
10+
(hed-web-services-in-matlab-anchor)=
11+
## HED web services in MATLAB
12+
13+
HED web services allow MATLAB programs to request the same services that are available
14+
through the online tools.
15+
These services are available through the [**https://hedtools.org/hed**](https://hedtools.org/hed) server.
16+
Alternatively, these services can be accessed through a locally-deployed docker module.
17+
See the [**hed-web**](https://hed-web.readthedocs.io/en/latest/index.html)
18+
GitHub repository documentation for additional information on the docker deployment.
19+
The MATLAB code to run demos of these services is available on the
20+
[**hed-matlab**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/web_services)
21+
GitHub repository.
22+
23+
The following MATLAB code demos are available to show how to access HED web services.
24+
25+
| Target | MATLAB source | Purpose |
26+
| ------ |-----------------|-----------|
27+
| Overall | [**runAllDemos.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/runAllDemos.m) | Harness for running all demos. |
28+
| Overall | [**demoGetServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoGetServices.m) | List available services. |
29+
| Events | [**demoEventServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testEventServices.m) | Validation, conversion, sidecar generation. |
30+
| Events | [**demoEventSearchServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoEventSearchServices.m) | Search, assembly. |
31+
| Schema | *in progress* | For schema library developers. |
32+
| Sidecars | [**demoSidecarServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoSidecarServices.m) | Validation, conversion, extraction, merging. |
33+
| Spreadsheets | [**demoSpreadsheetServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoSpreadsheetServices.m) | Validation, conversion. |
34+
| Strings | [**demoStringServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoStringServices.m) | Validation, conversion. |
35+
36+
37+
The [**runAllDemos.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/runAllDemos.m)
38+
script runs all the demo code and reports whether
39+
the demos run successfully.
40+
Before using the HED web services from MATLAB,
41+
you should run this script to make sure everything is working on your system,
2642
that you have Internet access, and that the HED services are available.
2743

28-
This script also demonstrates how to call the individual test functions.
29-
Each test function takes a host URL as a parameter and returns a list of errors.
30-
The individual test scripts illustrate how to call each type of available web service.
31-
32-
33-
| Target | MATLAB source| Purpose |
34-
| ------ | ------------- | ------- |
35-
| Overall | [**runAllTests.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/runAllTests.m) | Harness for running all tests. |
36-
| Overall | [**testGetServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testGetServices.m) | List available services. |
37-
| Events | [**testEventServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testEventServices.m) | Validation, conversion, sidecar generation. |
38-
| Events | [**testEventSearchServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testEventSearchServices.m) | Search, assembly.|
39-
| Schema | *in progress* | For schema library developers. |
40-
| Sidecars | [**testSidecarServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testSidecarServices.m) | Validation, conversion, extraction, merging. |
41-
| Spreadsheets | [**testSpreadsheetServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testSpreadsheetServices.m) | Validation, conversion.|
42-
| Strings | [**testStringServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testStringServices.m) | Validation, conversion. |
43-
44+
This script also demonstrates how to call the individual demo functions.
45+
Each demo function takes a host URL as a parameter and returns a list of errors.
46+
The demos all use demo data read by the
47+
[**getDemoData**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/getDemoData.m)
48+
function, which returns a MATLAB `struct` containing all needed test data.
49+
The individual demo scripts illustrate how to call each type of available web service.
4450

51+
(overview-of-service-requests-anchor)=
4552
### Overview of service requests
4653

4754
Calling HED services from MATLAB requires the following steps:
4855

49-
1. **Set up a session**:
50-
1. Establish a session by requesting a CSRF token and a cookie.
51-
2. Construct a header array using the token and the cookie.
52-
2. **Create a request structure**.
53-
3. **Make a request** using the MATLAB `webwrite`.
54-
4. **Decode the response** returned from `webwrite`.
56+
1. [**Set up a session**](setting-up-a-session-from-matlab-anchor).
57+
2. [**Create a request structure**](creating-a-request-structure-anchor).
58+
3. [**Make a request**](making-a-service-request-anchor).
59+
4. [**Decode the response**](decoding-a-service-response-anchor).
5560

5661
Usually, you will do the first step (the session setup) once at the beginning of your script
5762
to construct a fixed session header that can be used in subsequent requests in your script.
5863

64+
(setting-up-a-session-from-matlab-anchor)=
5965
### Setting up a session from MATLAB
6066

6167
The goal of the session setup is to construct a header that can be used in subsequent web requests.
62-
The first step is to call the [**getHostOptions.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/getHostOptions.m).
63-
This function constructs the services URL from the host URL.
64-
The function also makes a service request to obtain a CSRF token and a cookie.
65-
The function then constructs a header and calls the MATLAB `weboptions` function
66-
to get an options object suitable for use with the MATLAB `webwrite` function
67-
use in all of our examples.
68+
The first step is to call the [**getHostOptions.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/getHostOptions.m).
6869

6970
(setting)=
7071
`````{admonition} Establish a session.
@@ -80,20 +81,19 @@ The `host` should be set to the URL of the webserver that you are using.
8081
The call to `getHostOptions`, only needs to be done once at the beginning of your session.
8182
The `servicesURL` and the `options` can be used for all of your subsequent requests.
8283

84+
This function constructs the services URL from the host URL.
85+
The function also makes a service request to obtain a CSRF token and a cookie using
86+
[**getSessionInfo**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/getSessionInfo.m).
87+
The function then constructs a header and calls the MATLAB `weboptions` function
88+
to get an options object suitable for use with the MATLAB `webwrite` function
89+
use in all of our examples.
8390

8491
The `getHostOptions` does all the setup for using the services.
8592
As indicated by the code below, all communication is done in JSON.
8693
However, as demonstrated below, the MATLAB `webwrite` function
8794
takes a MATLAB `struct` as its `request` parameter and internally
8895
converts to the format specified in the header before making the request.
8996

90-
The `Timeout` parameter indicates how many seconds MATLAB will wait for a response
91-
before returning as a failed operation.
92-
The `timeout` value of 120 seconds is sufficient for most situations.
93-
However, but this can be adjusted upward or downward to suit the user.
94-
The `HeaderFields` sets the parameters of HTTP request.
95-
96-
9797
(gethostoptions-source-anchor)=
9898
`````{admonition} Source for getHostOptions.
9999
:class: tip
@@ -111,17 +111,24 @@ function [servicesUrl, options] = getHostOptions(host)
111111
```
112112
`````
113113

114-
In the following examples, we assume that `getHostOptions` has been called to retrieve
115-
`servicesUrl` and `options` for use in the session.
114+
The `Timeout` parameter indicates how many seconds MATLAB will wait for a response
115+
before returning as a failed operation.
116+
The `timeout` value of 120 seconds is sufficient for most situations.
117+
However, this can be adjusted upward or downward to suit the user.
118+
The `HeaderFields` sets the parameters of HTTP request.
116119

120+
(creating-a-request-structure-anchor)=
117121
### Creating a request structure
118122

119123
The request structure is a MATLAB `struct` which must have a `service` field and can have an
120124
arbitrary number of fields depending on which service is being requested.
121125

122126
The simplest service is `get_services`,
123127
which returns a string containing information about the available services.
124-
This service requires no additional parameters.
128+
This service requires no additional parameters.
129+
In this and other examples, we assume that `getHostOptions` has been called to retrieve
130+
`servicesUrl` and `options` for use in the session.
131+
125132

126133
`````{admonition} Request a list of available HED web services.
127134
:class: tip
@@ -169,28 +176,29 @@ Another possibility is to provide a URL for the schema.
169176
The most-commonly used option is to use `schema_version` to indicate one of the supported
170177
versions available in the
171178
[**hedxml**](https://github.com/hed-standard/hed-specification/tree/master/hedxml) directory of the
172-
[**hed-specification**](https://github.com/hed-standard/hed-specification) repository on GitHub.
179+
[**hed-schemas**](https://github.com/hed-standard/hed-schemas) repository on GitHub.
173180

174181
(create-request-sidecar-validate-anchor)=
175182
`````{admonition} Create a request for the sidecar_validate web service.
176183
:class: tip
177184
```matlab
178-
jsonText = fileread('../../../datasets/eeg_ds003645s_hed/task-FacePerception_events.json');
185+
jsonText = fileread('../../datasets/eeg_ds003645s_hed_demo/task-FacePerception_events.json');
179186
request = struct('service', 'sidecar_validate', ...
180-
'schema_version', '8.0.0', ...
187+
'schema_version', '8.2.0', ...
181188
'json_string', jsonText, ...
182189
'check_for_warnings', 'on');
183190
```
184191
`````
185192
This example reads the JSON sidecar to be validated as a character array into the variable `jsonText`
186-
and makes a request for validation using HED8.0.0.xml.
193+
and makes a request for validation using `HED8.2.0.xml`.
187194

188195
The request indicates that validation warnings as well as errors should be included in the response.
189196
If you wish to exclude warnings, use `off` instead of `on` as the `check_for_warnings` field value.
190197

191-
The [**testSidecarServices.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/testSidecarServices.m)
198+
The [**demoSidecarServices.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/demoSidecarServices.m)
192199
function shows complete examples of the various HED services for JSON sidecars.
193200

201+
(making-a-service-request-anchor)=
194202
### Making a service request
195203

196204
The HED services all use the MATLAB `webwrite` to make HED web service requests.
@@ -207,7 +215,7 @@ outputReport(response, 'Example: validate a JSON sidecar');
207215
```
208216
`````
209217

210-
The [**<code>outputReport.m</code>**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/outputReport.m)
218+
The [**<code>outputReport.m</code>**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/outputReport.m)
211219
MATLAB script outputs the response in readable form with a user-provided table.
212220

213221
If the web server is down or times out during a request,

‎docs/source/HedValidationGuide.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -173,10 +173,10 @@ HED validation in MATLAB is currently done by accessing the HED online tools as
173173
#### Direct access to services
174174
Users can access these services directly by calling using the HED MATLAB web services
175175
functions as explained in
176-
[**HED services in MATLAB**](./HedMatlabTools.md#hed-services-in-matlab).
177-
Download the [**web_services**](https://github.com/hed-standard/hed-examples/tree/main/hedcode/matlab_scripts/web_services)
176+
[**HED web services in MATLAB**](./HedMatlabTools.md#hed-web-services-in-matlab).
177+
Download the [**web_services**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/web_services)
178178
directory from GitHub and include this directory in your MATLAB path.
179-
The [**runAllTests.m**](https://raw.githubusercontent.com/hed-standard/hed-examples/main/hedcode/matlab_scripts/web_services/runAllTests.m)
179+
The [**runAllDemos.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/runAllDemos.m)
180180
script calls all the services on test data.
181181

182182
#### Access through EEGLAB

‎src/README.md

Lines changed: 28 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,17 +9,41 @@ gathers the HED supporting resources, all of which are open source.
99

1010
The main documentation for this and other HED resources
1111
is available through the
12-
[**HED-examples**](https://hed-examples.readthedocs.io/en/latest/index.html) documentation,
12+
[**HED-resources**](https://www.hed-resources.org) documentation,
1313
whose source is contained in the
1414
[**docs**](https://github.com/hed-standard/hed-examples/tree/main/docs)
1515
subdirectory of this repository.
1616

17-
The [**hedcode**](https://github.com/hed-standard/hed-examples/tree/main/hedcode)
18-
subdirectory contains MATLAB scripts, Python Jupyter Notebooks,
19-
and Python scripts with direct calls to HedTools.
17+
The [**src**](https://github.com/hed-standard/hed-examples/tree/main/src)
18+
subdirectory of the [**hed-examples**] GitHub repository contains Python Jupyter
19+
notebooks with examples of how to call the HEDTools.
20+
21+
For MATLAB support for HED see the [**hed-matlab**](https://github.com/hed-standard/hed-matlab)
22+
GitHub repository.
2023

2124
The [**datasets**](https://github.com/hed-standard/hed-examples/tree/main/datasets)
2225
subdirectory contains datasets for testing various aspects of HED.
2326
These datasets have stubs for actual imaging data in order to reduce their size.
2427
Most of these datasets have complete versions available on
2528
[**openNeuro**](https://openneuro.org/).
29+
30+
### Installation of hedtools
31+
32+
The most of the Python-related resources in this repository
33+
require the installation of the HEDTools Python module, which can be
34+
installed using `pip` or directly from its GitHub repository as follows:
35+
36+
To use `pip` to install `hedtools` from PyPI:
37+
38+
```
39+
pip install hedtools
40+
```
41+
42+
To install directly from the
43+
[GitHub](https://github.com/hed-standard/hed-python) repository:
44+
45+
```
46+
pip install git+https://github.com/hed-standard/hed-python/@master
47+
```
48+
49+
HEDTools require python 3.7 or greater.

0 commit comments

Comments
 (0)