+[**Step 1: Find Python**](step-1-find-python-anchor). If a version >= Python 3.8 is found, skip to Step 3. +
[**Step 2: Install Python if needed**](step-2-install-python-if-needed-anchor) . @@ -61,7 +90,7 @@ If already connected, skip to Step 4. (step-1-find-python-anchor)= #### Step 1: Find Python -Follow these steps until you find a Python executable that is version 3.7 or greater. +Follow these steps until you find a Python executable that is version 3.8 or greater. If you can't locate one, you will need to install it. ````{Admonition} Does MATLAB already have a good version of Python you can use? @@ -69,18 +98,18 @@ If you can't locate one, you will need to install it. In your MATLAB command window execute the following function: ```matlab -pyenv +>> pyenv ``` The following example response shows that MATLAB is using Python version 3.9 -with executable located at `C:\Program Files\Python39\pythonw.exe`. +with executable located at `C:\Program Files\Python\Python39\python.EXE`. ```matlab PythonEnvironment with properties: Version: "3.9" - Executable: "C:\Program Files\Python39\pythonw.exe" - Library: "C:\Program Files\Python39\python39.dll" - Home: "C:\Program Files\Python39" + Executable: "C:\Program Files\Python\Python39\python.EXE" + Library: "C:\Program Files\Python\Python39\python39.dll" + Home: "C:\Program Files\Python\Python39" Status: NotLoaded ExecutionMode: InProcess ``` @@ -97,20 +126,16 @@ There are several likely places to look for Python on your system. **For Linux users**: ->Likely places for system-space installation are `/bin`, `/local/bin`, `/usr/bin`, `/usr/local/bin`, or `/opt/bin`. User-space installations are usually your home directory in a subdirectory such as `~/bin` -or `~/.local/bin`. +>Likely places for system-space installation are `/bin`, `/local/bin`, `/usr/bin`, `/usr/local/bin`, or `/opt/bin`. User-space installations are usually your home directory in a subdirectory such as `~/bin` or `~/.local/bin`. The `which python` command will list the Python executable that is first found in your path. **For Windows users**: -> Likely places for system-space installation are `C:\`, `C:\Python`, or `C:\Program Files`. -User-space installations default to your personal account -in `C:\Users\yourname\AppData\Local\Programs\Python\python39` where `yourname` is your Windows account name -and `python39` will be the particular version (in this case Python 3.9). +> Likely places for system-space installation are `C:\`, `C:\Python`, `C:\Program Files` or `C:\Program Files\Python`. User-space installations default to your personal account in `C:\Users\yourname\AppData\Local\Programs\Python\python39` where `yourname` is your Windows account name and `python39` will be the particular version (in this case Python 3.9). If you don't have any success finding a Python executable, you will need to install Python as described in [**Step 2: Install Python if needed**](step-2-install-python-if-needed-anchor). -Otherwise, you can skip to [**Step 3:Connect Python to MATLAB**](step-3-connect-python-to-matlab-anchor). +Otherwise, you can skip to [**Step 3: Connect Python to MATLAB**](step-3-connect-python-to-matlab-anchor). ```{warning} **You need to keep track of the path to your Python executable for Step 3.** @@ -126,17 +151,16 @@ for your operating system and version. Depending on your OS and the installer options you selected, Python may be installed in your user space or in system space for all users. - You should keep track of the directory that Python was installed in. -- You may want to add the location of the Python executable to your PATH. - (Most installers give you that option as part of the installation.) +- You may want to add the location of the Python executable to your system or user PATH. -#### Installing in a virtual environment +```{warning} +MATLAB installs add-ons such as the HEDTools in a specific user directory as described below. +This makes user-installed Python modules available to all MATLAB projects. +**For this reason, we do not recommend trying to set up a virtual environment.** +``` -https://www.mathworks.com/support/search.html/answers/1750425-python-virtual-environments-with-python-interface.html?fq%5B%5D=asset_type_name:answer&page=1 (step-3-connect-python-to-matlab-anchor)= -#### Step 3: Connect Python to Matlab - - -C:\Users\username\AppData\Local\Programs\Python\python -m venv C:\Users\username\py38 +#### Step 3: Connect Python to MATLAB Setting the Python version uses the MATLAB `pyenv` function with the `'Version'` argument as illustrated by the following example. @@ -144,30 +168,14 @@ as illustrated by the following example. ````{admonition} Example MATLAB function call connect MATLAB to Python. ```matlab ->> pyenv('Version', 'C:\Program Files\Python39\python.exe') +>> pyenv('Version', 'C:\Program Files\Python\Python39\python.exe') ``` ```` Be sure to substitute the path of the Python that you have found. -Notice that the executable listed in Step 1 was `pythonw.exe`, but we have used `python.exe` here -to indicate the command line version. Use the MATLAB `pyenv` function again without arguments to check that your installation is as expected. -````{Admonition} Example response for pyenv all with no arguments after setting environment. - -```matlab - PythonEnvironment with properties: - - Version: "3.9" - Executable: "C:\Program Files\Python39\python.exe" - Library: "C:\Program Files\Python39\python39.dll" - Home: "C:\Program Files\Python39" - Status: NotLoaded - ExecutionMode: InProcess -``` -```` - (step-4-install-hedtools-anchor)= #### Step 4: Install HEDTools @@ -175,14 +183,15 @@ The general-purpose package manager for Python is called `pip`. By default, `pip` retrieves packages to be installed from the [**PyPI**](https://pypi.org) package repository. You will need to use the version of `pip` that corresponds to the version of Python that is connected to MATLAB. -This may not be the default `pip` used from the command line. +The right version of `pip` is found in the `Scripts` subdirectory of your Python installation. + ````{admonition} Command to install hedtools in MATLAB. To install the latest released version of `hedtools` type a pip command such as the following in your MATLAB command window. ```matlab -system('"C:\Program Files\Python39\Scripts\pip" install hedtools') +system('"C:\Program Files\Python\Python39\Scripts\pip" install hedtools') ``` Use the full path of the pip associated with the Python that you are using with MATLAB @@ -224,6 +233,38 @@ Similarly, the `pip` package manager might be named `pip3` instead of `pip`. ``` +You can also install the Python HEDtools from GitHub if you want the version that is under development. + +````{admonition} Command to install hedtools in MATLAB. +To install the latest released version of `hedtools` type a pip command such as the +following in your MATLAB command window. + +```matlab +system('"C:\Program Files\Python\Python39\Scripts\pip" install hedtools') +``` +Use the full path of the pip associated +with the Python that you are using with MATLAB +```` +If you want the newest features of the Python HEDTools, you will need to install directly from the GitHub repository. + +````{admonition} Command to install hedtools from the GitHub repository. + +```matlab +system('"C:\Program Files\Python\Python39\Scripts\pip" install git+https://github.com/hed-standard/hed-python/@develop') +``` +Be sure to replace the path to pip, with the one for your Python installation. +```` + +````{warning} +If you have an existing version of HEDTools installed and you want to install a new version, +**you must uninstall the hedtools first**. + +```matlab +system('"C:\Program Files\Python\Python39\Scripts\pip" uninstall hedtools') +``` +Be sure to replace the path to pip, with the one for your Python installation. +```` + The following MATLAB statement can be used to test that everything was installed correctly. ````{Admonition} Test that everything is installed. @@ -238,16 +279,9 @@ Using HEDTOOLS version: {'date': '2022-06-20T14:40:24-0500', 'dirty': False, 'er ``` ```` +### Calling HEDTools from MATLAB -(matlab-wrappers-for-HED-tools-anchor)= -### MATLAB wrappers for HEDTools - -The [**hedtools_wrappers**](https://github.com/hed-standard/hed-examples/tree/main/hedcode/matlab_scripts/hedtools_wrappers) directory in the -[**hed-examples**](https://github.com/hed-standard/hed-examples) GitHub repository -contains MATLAB wrapper functions for calling various commonly used HED tools. - -#### Direct calls to HEDTools - +The wrapper functions provide the basic functionality for the common operations Wrapper functions are provided to some of the more commonly used functions in the HEDTools suite. @@ -343,10 +377,10 @@ supported for your version of MATLAB. The MATLAB `matlab.exception.PyException` captures error information generated during Python execution. -(hed-web-services-in-matlab-anchor)= -## HED web services in MATLAB +(web-services-for-hedtools-anchor)= +## Web services for HEDTools -HED web services allow MATLAB programs to request the same services that are available +MATLAB HED web services allow MATLAB programs to request the same services that are available through the online tools. These services are available through the [**https://hedtools.org/hed**](https://hedtools.org/hed) server. Alternatively, these services can be accessed through a locally-deployed docker module. diff --git a/docs/source/HedValidationGuide.md b/docs/source/HedValidationGuide.md index 36351dc..558a546 100644 --- a/docs/source/HedValidationGuide.md +++ b/docs/source/HedValidationGuide.md @@ -171,9 +171,9 @@ Use the [**HED online development server**](https://hedtools.ucsd.edu/hed_dev) t HED validation in MATLAB is currently done by accessing the HED online tools as web services. #### Direct access to services -Users can access these services directly by calling using the HED MATLAB web services +Users can access these services directly by calling wrapper functions or by using the HED MATLAB web services functions as explained in -[**HED web services in MATLAB**](./HedMatlabTools.md#hed-web-services-in-matlab). +[**HED MATLAB tools**](./HedMatlabTools.md#hed-matlab-tools-anchor). Download the [**web_services**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/web_services) directory from GitHub and include this directory in your MATLAB path. The [**runAllDemos.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/runAllDemos.m) diff --git a/docs/source/HowCanYouUseHed.md b/docs/source/HowCanYouUseHed.md index 3938b85..ebe45b7 100644 --- a/docs/source/HowCanYouUseHed.md +++ b/docs/source/HowCanYouUseHed.md @@ -616,9 +616,12 @@ for more information on installation and use. The project source code is located in the [**CTagger**](https://github.com/hed-standard/ctagger) GitHub repository. -[**HED services in MATLAB**](https://www.hed-resources.org/en/latest/HedMatlabTools.html#hed-services-in-matlab) explains how the [**HED online services**](https://hedtools.ucsd.edu/hed) -can be called programmatically in MATLAB. The HED services are deployed online through a docker container -as described in [**Web tools and rest services**](web-tools-and-rest-services-anchor). +[**HED MATLAB tools**](https://www.hed-resources.org/en/latest/HedMatlabTools.html#hed-matlab-tools) explains how the +users can use the HEDTools in MATLAB using one of three approaches: using MATLAB wrappers for the HED Python tools, +using MATLAB wrappers for the HED web services, or by calling HED tools through EEGLAB. + +The [**HED online services**](https://hedtools.ucsd.edu/hed) can be called programmatically in MATLAB. The HED services are deployed online through a docker container +as described in [**Web tools and rest services**](web-tools-and-rest-services-anchor). [**Python HEDTools in MATLAB**](./HedMatlabTools.md#python-hedtools-in-matlab) From bc9ba32e7c904364e9a9cf3003895e8721b08fcf Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Wed, 8 May 2024 21:18:49 -0500 Subject: [PATCH 2/9] Continued update of the HED-matlab --- docs/source/HedMatlabTools.md | 45 +++++++++++++++++------------------ 1 file changed, 22 insertions(+), 23 deletions(-) diff --git a/docs/source/HedMatlabTools.md b/docs/source/HedMatlabTools.md index e328463..4f03ad4 100644 --- a/docs/source/HedMatlabTools.md +++ b/docs/source/HedMatlabTools.md @@ -187,26 +187,23 @@ The right version of `pip` is found in the `Scripts` subdirectory of your Python ````{admonition} Command to install hedtools in MATLAB. -To install the latest released version of `hedtools` type a pip command such as the +To install the latest released version of `hedtools` type a `pip` command such as the following in your MATLAB command window. ```matlab system('"C:\Program Files\Python\Python39\Scripts\pip" install hedtools') ``` -Use the full path of the pip associated -with the Python that you are using with MATLAB +Use the full path of the `pip` associated with the Python that your MATLAB is using. ```` -Giving the full path to `pip` corresponding to the Python installation that MATLAB -is using ensures that MATLAB knows about `HEDtools`. -(The version of MATLAB that Python is using may not be the same as the Python in the system PATH.) +Giving the full path to correct version of `pip` +ensures that MATLAB knows about `HEDtools`. +(The version of Python that MATLAB is using may not be the same as the Python in the system PATH.) -Also watch the resulting messages in the command window to make sure that HEDtools +Also watch the resulting messages in the MATLAB command window to make sure that HEDtools was successfully installed. -In the case of the above example, the Python being used is in system space, -which requires administrator privileges. - -The first line of the output was: +In the above example, the Python being used is in system space, +which requires administrator privileges. The first line of the output from installation was: ```matlab Defaulting to user installation because normal site-packages is not writeable @@ -215,7 +212,7 @@ The first line of the output was: On Windows these packages will be found in a `site-packages` directory such as: ```text -`C:\Users\username\AppData\Roaming\Python\Python39\site-packages` +C:\Users\username\AppData\Roaming\Python\Python39\site-packages ``` On Linux these packages might be found in directory such as: @@ -233,36 +230,38 @@ Similarly, the `pip` package manager might be named `pip3` instead of `pip`. ``` -You can also install the Python HEDtools from GitHub if you want the version that is under development. +You will need to install the Python HEDTools. -````{admonition} Command to install hedtools in MATLAB. -To install the latest released version of `hedtools` type a pip command such as the -following in your MATLAB command window. +````{admonition} Command to install HEDTools in MATLAB. +To install the latest released version of `hedtools` type a `pip` command such as the +following in your MATLAB command window: ```matlab system('"C:\Program Files\Python\Python39\Scripts\pip" install hedtools') ``` -Use the full path of the pip associated -with the Python that you are using with MATLAB + ```` -If you want the newest features of the Python HEDTools, you will need to install directly from the GitHub repository. +The above command retrieves the latest version of HEDTools from the PyPI archive. +If you want the newest features of the Python HEDTools, you will need to install directly from the GitHub repository +as shown in the following example. -````{admonition} Command to install hedtools from the GitHub repository. +````{admonition} Command to install HEDTools from the GitHub repository. ```matlab system('"C:\Program Files\Python\Python39\Scripts\pip" install git+https://github.com/hed-standard/hed-python/@develop') ``` -Be sure to replace the path to pip, with the one for your Python installation. +This installs the version of HEDTools on the `develop` branch. +Be sure to replace the path to `pip`, with the one for your Python installation. ```` ````{warning} If you have an existing version of HEDTools installed and you want to install a new version, -**you must uninstall the hedtools first**. +**you must uninstall the HEDTools first**: ```matlab system('"C:\Program Files\Python\Python39\Scripts\pip" uninstall hedtools') ``` -Be sure to replace the path to pip, with the one for your Python installation. +Be sure to replace the path to `pip`, with the one for your Python installation. ```` The following MATLAB statement can be used to test that everything was installed correctly. From 4a76be7ed9502b2c66ddc82d41275cd838bda5aa Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Fri, 10 May 2024 06:46:43 -0500 Subject: [PATCH 3/9] Continued updating instructions for setup --- docs/source/HedMatlabTools.md | 148 +++++++++++++++++++++------------- 1 file changed, 92 insertions(+), 56 deletions(-) diff --git a/docs/source/HedMatlabTools.md b/docs/source/HedMatlabTools.md index 9227742..51d67e7 100644 --- a/docs/source/HedMatlabTools.md +++ b/docs/source/HedMatlabTools.md @@ -1,67 +1,80 @@ # HED MATLAB tools +HED's primary code base is maintained in Python, but much of the HED tool functionality can also be accessed in MATLAB. There are currently three types of support available for HED (Hierarchical Event Descriptors) in MATLAB: -* [**Python HEDTools in MATLAB**](python-hedtools-in-matlab-anchor) - calling HED python tools from within MATLAB. -* [**HED web services in MATLAB**](hed-web-services-in-matlab-anchor) - web services called from MATLAB scripts. -* [**EEGLAB plug-in integration**](eeglab-integration-anchor) - EEGLAB plugins and other native MATLAB. +* [**HEDTools in MATLAB**](hedtools-in-matlab-anchor) - calling HED python tools from within MATLAB through MATLAB wrapper functions. +* [**HED web services in MATLAB**](hed-web-services-in-matlab-anchor) - calling web services from MATLAB scripts. +* [**EEGLAB integration**](eeglab-integration-anchor) - calling HED tools through the EEGLAB menus. -Python support in MATLAB +The HED MATLAB wrapper functions allow you to incorporate validation, summary, search, factorization, +and other HED processing directly into your MATLAB scripts without +reimplementing these operations in MATLAB or knowing Python. +These tools require a one-time setup connecting your MATLAB to Python. -(python-hedtools-in-matlab-anchor)= -## Python HEDTools in MATLAB +A second option is to call the HED python tools through MATLAB functions that call HED's online services. +This method accesses the Internet to perform the main actions and requires no setup. +This method is not designed for iteratively processing large collections of recordings, +but is usually fine for processing individual recordings. -Although MATLAB began python support of python in 2014, you must be using -MATLAB version 2020b or later with the HEDTools because the -current version of the HEDTools requires Python 3.8 or later. -With these tools you can incorporate validation, summary, search, factorization, -and other HED processing directly into your MATLAB processing scripts without -reimplementing these operations in MATLAB. +Many of HED's functions are also available through EEGLAB's GUI, but EEGLAB must be installed. +EEGLAB uses one of the first two methods to access HED's functionality. -**Note:** For your reference, the source for `hedtools` is the +(hedtools-in-matlab-anchor)= +## HEDTools in MATLAB + +After an initial one-time setup, you can use the MATLAB HEDTools without knowing Python. +The `hedtools` library requires a Python version >= 3.8. +In order to call functions from this library in MATLAB, +you must be running MATLAB version >= R2019a and have a +[**compatible version of Python**](https://www.mathworks.com/support/requirements/python-compatibility.html) installed on your machine. + +**Note:** For your reference, the source for the Python `hedtools` is the [**hed-python**](https://github.com/hed-standard/hed-python) GitHub repository. The code is fully open-source with an MIT license. The actual API documentation is available [**here**](https://hed-python.readthedocs.io/en/latest/api2.html), but the tutorials and tool documentation for `hedtools` on [**HED Resources**](https://www.hed-resources.org/en/latest/index.html) provides more -examples of use. - +examples of use. +[**MATLAB HEDTools**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/hedtools_wrappers) +can be downloaded from... ### Getting started -The `hedtools` library requires a Python version >= 3.8. -In order to call functions from this library in MATLAB, -you must be running MATLAB version >= R2019a and have a -[**compatible version of Python**](https://www.mathworks.com/support/requirements/python-compatibility.html) -installed on your machine. - The most difficult part of the process for users who are unfamiliar with Python is getting Python connected to MATLAB. -Once that is done, many of the standard `hedtools` functions have -[**MATLAB HED tool wrapper functions**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/hedtools_wrappers), -which take MATLAB variables as arguments and return MATLAB variables. -Thus, once the setup is done, you don't have to learn any additional Python syntax to use the tools. -You should only have to do this setup once, since MATLAB retains the setup information -from session to session. +Once the setup is done, you don't have to learn any additional Python syntax to use the tools. +The MATLAB wrapper functions take MATLAB variables as arguments and return MATLAB variables +or opaque objects which are passed on to other functions. + -````{admonition} Steps for setting up Python HEDtools for MATLAB. +````{admonition} Steps for setting up Python HEDtools for MATLAB (done once). -[**Step 1: Find Python**](step-1-find-python-anchor). If yes, skip to Step 3. +[**Step 1: Find Python**](step-1-find-python-anchor). +- If no Python, go to **Step 2**. +- If Python is present, but MATLAB doesn't know about it, go to **Step 3**. +- If Python is on your system and it is connected to MATLAB, skip to **Step 4**.-[**Step 2: Install Python if needed**](step-2-install-python-if-needed-anchor) . +[**Step 2: Install Python if needed**](step-2-install-python-if-needed-anchor). +- Be sure to pick the latest version of Python that is +[**compatible**](https://www.mathworks.com/support/requirements/python-compatibility.html) with your version of MATLAB. +- REMEMBER the installation path of the Python.
[**Step 3: Connect Python to MATLAB**](step-3-connect-python-to-matlab-anchor). -If already connected, skip to Step 4. +- If your Python is already connected to MATLAB (as checked in **Step 1**), go to **Step 4**. + + +[**Step 4: Install Python HEDtools**](step-4-install-python-hedtools-anchor) -[**Step 4: Install HEDtools**](step-4-install-hedtools-anchor) +[**Step 5: Install MATLAB HEDtools**](step-5-install-matlab-hedtools-anchor) ```` (step-1-find-python-anchor)= #### Step 1: Find Python -Follow these steps until you find a Python executable that is version 3.7 or greater. +Follow these steps until you find a Python executable that is version 3.8 or greater. If you can't locate one, you will need to install it. ````{Admonition} Does MATLAB already have a good version of Python you can use? @@ -72,21 +85,21 @@ In your MATLAB command window execute the following function: pyenv ``` The following example response shows that MATLAB is using Python version 3.9 -with executable located at `C:\Program Files\Python39\pythonw.exe`. +with executable located at `C:\Program Files\Python\Python39\python.exe`. ```matlab PythonEnvironment with properties: Version: "3.9" - Executable: "C:\Program Files\Python39\pythonw.exe" - Library: "C:\Program Files\Python39\python39.dll" - Home: "C:\Program Files\Python39" + Executable: "C:\Program Files\Python\Python39\python.exe" + Library: "C:\Program Files\Python\Python39\python39.dll" + Home: "C:\Program Files\Python\Python39" Status: NotLoaded ExecutionMode: InProcess ``` ```` -If MATLAB has already knows about a suitable Python version that is at least 3.7, +If MATLAB has already knows about a suitable Python version that is at least 3.8, you are ready to go to [**Step 4: Install HEDTools**](step-4-install-hedtools-anchor). Keep track of the location of the Python executable. @@ -101,9 +114,9 @@ There are several likely places to look for Python on your system. or `~/.local/bin`. **For Windows users**: -> Likely places for system-space installation are `C:\`, `C:\Python`, or `C:\Program Files`. +> Likely places for system-space installation are `C:\`, `C:\Python`, `C:\Program Files`, or `C:\Program Files\Python`. User-space installations default to your personal account -in `C:\Users\yourname\AppData\Local\Programs\Python\python39` where `yourname` is your Windows account name +in a location such as `C:\Users\yourname\AppData\Local\Programs\Python\python39` where `yourname` is your Windows account name and `python39` will be the particular version (in this case Python 3.9). If you don't have any success finding a Python executable, @@ -117,7 +130,7 @@ Otherwise, you can skip to [**Step 3:Connect Python to MATLAB**](step-3-connect- ``` (step-2-install-python-if-needed-anchor)= -#### Step 2: Install Python if needed +#### Step 2: Install Python if needed. (Remember where it is.) If you don't have Python on your system, you will need to install it. Go to [**Python downloads**](https://www.python.org/downloads/) and pick the correct installer @@ -129,13 +142,13 @@ Python may be installed in your user space or in system space for all users. - You may want to add the location of the Python executable to your PATH. (Most installers give you that option as part of the installation.) -#### Installing in a virtual environment +We do not recommend using a Python virtual environment. If you are not running in administrative mode, +MATLAB installs add-on Python packages in a specific place in your user space, and these packages are then +available to all your MATLAB applications. -https://www.mathworks.com/support/search.html/answers/1750425-python-virtual-environments-with-python-interface.html?fq%5B%5D=asset_type_name:answer&page=1 (step-3-connect-python-to-matlab-anchor)= #### Step 3: Connect Python to Matlab - C:\Users\username\AppData\Local\Programs\Python\python -m venv C:\Users\username\py38 Setting the Python version uses the MATLAB `pyenv` function with the `'Version'` argument @@ -144,13 +157,11 @@ as illustrated by the following example. ````{admonition} Example MATLAB function call connect MATLAB to Python. ```matlab ->> pyenv('Version', 'C:\Program Files\Python39\python.exe') +>> pyenv('Version', 'C:\Program Files\Python\Python39\python.exe') ``` ```` Be sure to substitute the path of the Python that you have found. -Notice that the executable listed in Step 1 was `pythonw.exe`, but we have used `python.exe` here -to indicate the command line version. Use the MATLAB `pyenv` function again without arguments to check that your installation is as expected. @@ -160,16 +171,16 @@ Use the MATLAB `pyenv` function again without arguments to check that your insta PythonEnvironment with properties: Version: "3.9" - Executable: "C:\Program Files\Python39\python.exe" - Library: "C:\Program Files\Python39\python39.dll" - Home: "C:\Program Files\Python39" + Executable: "C:\Program Files\Python\Python39\python.exe" + Library: "C:\Program Files\Python\Python39\python39.dll" + Home: "C:\Program Files\Python\Python39" Status: NotLoaded ExecutionMode: InProcess ``` ```` -(step-4-install-hedtools-anchor)= -#### Step 4: Install HEDTools +(step-4-install-python-hedtools-anchor)= +#### Step 4: Install Python HEDTools The general-purpose package manager for Python is called `pip`. By default, `pip` retrieves packages to be installed from the [**PyPI**](https://pypi.org) @@ -177,12 +188,12 @@ package repository. You will need to use the version of `pip` that corresponds to the version of Python that is connected to MATLAB. This may not be the default `pip` used from the command line. -````{admonition} Command to install hedtools in MATLAB. +````{admonition} Command to install Python HEDtools in MATLAB. To install the latest released version of `hedtools` type a pip command such as the following in your MATLAB command window. ```matlab -system('"C:\Program Files\Python39\Scripts\pip" install hedtools') +system('"C:\Program Files\Python\Python39\Scripts\pip" install hedtools') ``` Use the full path of the pip associated with the Python that you are using with MATLAB @@ -238,9 +249,34 @@ Using HEDTOOLS version: {'date': '2022-06-20T14:40:24-0500', 'dirty': False, 'er ``` ```` +If you want to install a newer version of the Python HEDTools, you must first uninstall the current version. + +````{Admonition} Uninstalling the current version of Python HEDTools. + +```matlab +system('"C:\Program Files\Python\Python39\Scripts\pip" uninstall hedtools') +``` +```` +If you want to install the latest unreleased version of the Python HEDTools, you should first uninstall your +current HEDtools as above. You can install from GitHub instead of the `pip` defaults by +using the appropriate web address as shown in the following example. + +````{Admonition} Installing Python HEDTools from the GitHub develop branch. + +```matlab +system('"C:\Program Files\Python\Python39\Scripts\pip" install git+https://github.com/hed-standard/hed-python/@develop') +``` +```` + +(step-5-install-matlab-hedtools-anchor)= +#### Step 5: Install MATLAB HEDtools + +The final step in the setup is to download the MATLAB HEDTools and put in your MATLAB path. +***Path to release zip to be added soon....*** + -(matlab-wrappers-for-HED-tools-anchor)= -### MATLAB wrappers for HEDTools +(running-matlab-hedtools-anchor)= +### Running MATLAB HEDTools The [**hedtools_wrappers**](https://github.com/hed-standard/hed-examples/tree/main/hedcode/matlab_scripts/hedtools_wrappers) directory in the [**hed-examples**](https://github.com/hed-standard/hed-examples) GitHub repository From dc261a7558619915808f626732d8c59386bd4b8c Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Thu, 30 May 2024 08:49:30 -0500 Subject: [PATCH 4/9] Minor type corrections started MATLAB section rewrite --- docs/source/HedMatlabTools.md | 4 +-- docs/source/HedSchemas.md | 42 +++++++++++++++---------------- docs/source/HedValidationGuide.md | 2 +- docs/source/HowCanYouUseHed.md | 5 +--- 4 files changed, 25 insertions(+), 28 deletions(-) diff --git a/docs/source/HedMatlabTools.md b/docs/source/HedMatlabTools.md index 4f03ad4..d1dbb6f 100644 --- a/docs/source/HedMatlabTools.md +++ b/docs/source/HedMatlabTools.md @@ -1,5 +1,5 @@ -(hed-matlab-tools-anchor)= -# HED MATLAB tools +(matlab-hedtools-anchor)= +# MATLAB HedTools The goal of the HED MATLAB tools is to provide access to HED tools from MATLAB without knowledge of Python. The HED tools allow validation, summary, search, factorization, data epoching diff --git a/docs/source/HedSchemas.md b/docs/source/HedSchemas.md index a63bb3a..c93d59f 100644 --- a/docs/source/HedSchemas.md +++ b/docs/source/HedSchemas.md @@ -82,13 +82,13 @@ The HED standard schema source is located in the [**standard_schema**](https://github.com/hed-standard/hed-schemas/tree/main/standard_schema) directory of the [**hed-schemas**](https://github.com/hed-standard/hed-schemas) GitHub repository. -| Format | Type | Use | -| ------ | ---- | ---- | -| XML | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HED8.2.0.xml) | Accessed by tools for validation and analysis. | -| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml) | Readable display. | -| Mediawiki | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedwiki/HED8.1.0.mediawiki) | Edited to create a new schema. | -| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedwiki/HED8.1.0.mediawiki) | Readable display for editing. | -| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/score/prerelease) | Working directory for developing the prerelease. | +| Format | Type | Use | +|------------| ---- | ---- | +| XML | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedxml/HED8.2.0.xml) | Accessed by tools for validation and analysis. | +| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedxml/HED8.2.0.xml) | Readable display. | +| MediaWiki | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/standard_schema/hedwiki/HED8.1.0.mediawiki) | Edited to create a new schema. | +| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/standard_schema/hedwiki/HED8.1.0.mediawiki) | Readable display for editing. | +| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/score/prerelease) | Working directory for developing the prerelease. | ### The SCORE library @@ -96,13 +96,13 @@ The HED SCORE library is an implementation of the [**SCORE**](https://hed-schema For more information and the latest references see [**HED SCORE schema**](https://hed-schemas.readthedocs.io/en/latest/hed_score_schema.html). -| Format | Type | Use | -| ------ | ---- | ---- | -| XML | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedxml/HED_score_1.0.0.xml) | Accessed by tools for validation and analysis. | -| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedxml/HED_score_1.0.0.xml) | Readable display. | -| Mediawiki | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki) | Edited to create a new schema. | -| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki) | Readable display for editing. | -| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/score/prerelease) | Working directory for developing the prerelease. | +| Format | Type | Use | +|------------| ---- | ---- | +| XML | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedxml/HED_score_1.0.0.xml) | Accessed by tools for validation and analysis. | +| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedxml/HED_score_1.0.0.xml) | Readable display. | +| MediaWiki | [**Raw**](https://raw.githubusercontent.com/hed-standard/hed-schemas/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki) | Edited to create a new schema. | +| | [**Formatted**](https://github.com/hed-standard/hed-schemas/blob/main/library_schemas/score/hedwiki/HED_score_1.0.0.mediawiki) | Readable display for editing. | +| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/score/prerelease) | Working directory for developing the prerelease. | ### The LISA library @@ -112,11 +112,11 @@ For more information and the latest references see [**HED LISA schema**](https://hed-schemas.readthedocs.io/en/latest/hed_lisa_schema.html). The LISA library is under development and is only available in prerelease format. -| Format | Type | Use | -| ------ | ---- | ---- | -| XML | **Raw** | Accessed by tools for validation and analysis. | -| | [**Formatted**] | Readable display. | -| Mediawiki | [**Raw**] | Edited to create a new schema. | -| | [**Formatted**] | Readable display for editing. | -| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/lisa/prerelease) | Working directory for developing the prerelease. | +| Format | Type | Use | +|------------| ---- | ---- | +| XML | **Raw** | Accessed by tools for validation and analysis. | +| | [**Formatted**] | Readable display. | +| MediaWiki | [**Raw**] | Edited to create a new schema. | +| | [**Formatted**] | Readable display for editing. | +| Prerelease | [**Directory**](https://github.com/hed-standard/hed-schemas/tree/main/library_schemas/lisa/prerelease) | Working directory for developing the prerelease. | diff --git a/docs/source/HedValidationGuide.md b/docs/source/HedValidationGuide.md index 558a546..057696f 100644 --- a/docs/source/HedValidationGuide.md +++ b/docs/source/HedValidationGuide.md @@ -173,7 +173,7 @@ HED validation in MATLAB is currently done by accessing the HED online tools as #### Direct access to services Users can access these services directly by calling wrapper functions or by using the HED MATLAB web services functions as explained in -[**HED MATLAB tools**](./HedMatlabTools.md#hed-matlab-tools-anchor). +[**MATLAB HedTools**](./HedMatlabTools.md). Download the [**web_services**](https://github.com/hed-standard/hed-matlab/tree/main/hedmat/web_services) directory from GitHub and include this directory in your MATLAB path. The [**runAllDemos.m**](https://raw.githubusercontent.com/hed-standard/hed-matlab/main/hedmat/web_services/runAllDemos.m) diff --git a/docs/source/HowCanYouUseHed.md b/docs/source/HowCanYouUseHed.md index ebe45b7..37adc37 100644 --- a/docs/source/HowCanYouUseHed.md +++ b/docs/source/HowCanYouUseHed.md @@ -616,7 +616,7 @@ for more information on installation and use. The project source code is located in the [**CTagger**](https://github.com/hed-standard/ctagger) GitHub repository. -[**HED MATLAB tools**](https://www.hed-resources.org/en/latest/HedMatlabTools.html#hed-matlab-tools) explains how the +[*MATLAB HedTools**](https://www.hed-resources.org/en/latest/MatlabHedTools.md) explains how the users can use the HEDTools in MATLAB using one of three approaches: using MATLAB wrappers for the HED Python tools, using MATLAB wrappers for the HED web services, or by calling HED tools through EEGLAB. @@ -624,9 +624,6 @@ The [**HED online services**](https://hedtools.ucsd.edu/hed) can be called progr as described in [**Web tools and rest services**](web-tools-and-rest-services-anchor). -[**Python HEDTools in MATLAB**](./HedMatlabTools.md#python-hedtools-in-matlab) -explains how to install and call various Python tools from MATLAB. - (web-tools-and-rest-services-anchor)= #### Web tools and REST services From b2a829b85e879352fdf3b983a88dbe422df5b294 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Fri, 31 May 2024 16:20:39 -0500 Subject: [PATCH 5/9] Minor typo corrections --- docs/source/FileRemodelingTools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/FileRemodelingTools.md b/docs/source/FileRemodelingTools.md index 7719dce..7cf59aa 100644 --- a/docs/source/FileRemodelingTools.md +++ b/docs/source/FileRemodelingTools.md @@ -877,7 +877,7 @@ The resulting columns are called *stopped* and *stop_failed*, respectively. The results of executing this *factor_column* operation on the [**sample remodel event file**](sample-remodel-event-file-anchor) are: -````{admonition} Results of the factor_column operation on the sampe data. +````{admonition} Results of the factor_column operation on the sample data. | onset | duration | trial_type | stop_signal_delay | response_time | response_accuracy | response_hand | sex | stopped | stop_failed | | ----- | -------- | ---------- | ----------------- | ------------- | ----------------- | ------------- | --- | ---------- | ---------- | From 623e3e61bfed1072caa97267b9500975165e8a41 Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Sat, 1 Jun 2024 14:26:54 -0500 Subject: [PATCH 6/9] Minor update to onlne tools description --- docs/source/HedOnlineTools.md | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/source/HedOnlineTools.md b/docs/source/HedOnlineTools.md index 540c56e..d5d2184 100644 --- a/docs/source/HedOnlineTools.md +++ b/docs/source/HedOnlineTools.md @@ -19,13 +19,13 @@ about download and deployment information. The HED browser-based tools are organized into the following pages, each focused on a particular type of file. -| Operates on | URL | Description | -|-----------------| ----- | ------- | -| [**Events**](events-online-tools-anchor) | [**link**](https://hedtools.org/hed/events) | validation, summary, and generation tools. | +| Operates on | URL | Description | +|-----------------| ----- |------------------------------------------------------------| +| [**Events**](events-online-tools-anchor) | [**link**](https://hedtools.org/hed/events) | validation, summary, search, and generation tools. | | [**Sidecars**](sidecars-online-tools-anchor) | [**link**](https://hedtools.org/hed/sidecars) | validation, transformation, extraction, and merging tools. | -| [**Spreadsheets**](spreadsheets-online-tools-anchor) | [**link**](https://hedtools.org/hed/spreadsheets) | validation and transformation tools. | -| [**Strings**](strings-online-tools-anchor) | [**link**](https://hedtools.org/hed/spreadsheets) | validation and transformation tools. | -| [**Schemas**](schemas-online-tools-anchor) | [**link**](https://hedtools.org/hed/schemas) | validation, conversion, and comparison tools. | +| [**Spreadsheets**](spreadsheets-online-tools-anchor) | [**link**](https://hedtools.org/hed/spreadsheets) | validation and transformation tools. | +| [**Strings**](strings-online-tools-anchor) | [**link**](https://hedtools.org/hed/spreadsheets) | validation and transformation tools. | +| [**Schemas**](schemas-online-tools-anchor) | [**link**](https://hedtools.org/hed/schemas) | validation, conversion, and comparison tools. | Many of the tools require that you provide a HED schema. Usually, you can do this by selecting one of the standard HED versions using a pull-down menu, @@ -116,6 +116,8 @@ otherwise the tool returns the assembled `.tsv` events file. The online tools do not allow the option of retaining other columns in the returned file. A more general alternative is to use the remodeling tools through the interface. +#### Search annotations + #### Generate sidecar template Generating a sidecar template file from the information in a single events file From 04ef82f1fcd2b8505dc95c3468aeb13caa0f712a Mon Sep 17 00:00:00 2001 From: Kay Robbins <1189050+VisLab@users.noreply.github.com> Date: Thu, 6 Jun 2024 14:40:36 -0500 Subject: [PATCH 7/9] Updated the graphics --- docs/_static/images/HedToolsSchematic.png | Bin 0 -> 58087 bytes docs/source/HedAndEEGLAB.md | 198 ++++++++++++++ docs/source/HedMatlabTools.md | 243 +++--------------- docs/source/HedValidationGuide.md | 2 +- docs/source/HowCanYouUseHed.md | 2 +- docs/source/_static/images/MatlabHedTools.png | Bin 0 -> 56302 bytes docs/source/index.rst | 1 + 7 files changed, 230 insertions(+), 216 deletions(-) create mode 100644 docs/_static/images/HedToolsSchematic.png create mode 100644 docs/source/HedAndEEGLAB.md create mode 100644 docs/source/_static/images/MatlabHedTools.png diff --git a/docs/_static/images/HedToolsSchematic.png b/docs/_static/images/HedToolsSchematic.png new file mode 100644 index 0000000000000000000000000000000000000000..74b961a048dbea901d16a239fa71c7ee5c2cc80a GIT binary patch literal 58087 zcmeFZbyU<{7d8wCC?(x0-Q6nPB}mNBEg%ij-6$m>skAghcMRPjD4jz{C^dw1zQ6JI zexB!k-uUNR>s#+1?^?QCjB{e|bM1ZhzV<#usHw{1U{YWrAtB)?D#&OcA)!(uA)&l~ zfC7Btzxe(s@DH+!hP)I~`RJo9;0M&#k}8r&NL8^|*QRK|&lpY$x-Lja54#b6k^3Es z%#o13`zp#vf;^3OZ+vROQ=c|t1MaLO!U8)kv{=XT#s#8tvOAv9c%q(AJA+mf4wxgE znICw{FbAXaKg6Ezt1T!E&3R-5DY1T6Rz*;^YbBQhCRVX4De9^9S24>mtY;j{ib!EJ zk)@W}INSZD%9!9`csjq+HshUnNRB<){6%2KU_bSj-)ZxWctAFDWX|tDN{aksM6&9? z|Ku}LVE_3zM}rUt{m;kh#S!Qse|