Python configuration

Purpose

Creates a Python virtual environment for PLS_Toolbox, giving access to evrimodel objects that use Python. Applicable for PLS_Toolbox/Solo 9.0 and newer.

Methods Required for Configuration

Below shows a table of the PLS_Toolbox methods that use Python. The table also shows the corresponding Python package used to run each method. Without the proper configuration, access is denied to all of these methods.

PLS_Toolbox Method	Python Package
TSNE	Scikit-Learn
UMAP	Umap-Learn
ANNDL	Scikit-Learn & Tensorflow
ANNDLDA	Scikit-Learn & Tensorflow

What's needed

• Miniconda3
  • This is a Python virtual environment management software. The management software is what's used to help build and maintain the PLS_Toolbox virtual environment. This software is free and take up less than 1 GB of space. Instructions to download and install are located below.
• MATLAB R2020b or higher/ Solo 9.0
  • This requirement allows the use of recent versions of Python and its packages.
• Internet connection for Miniconda3 download and Python configuration

Note: The configuration can take a couple of minutes to complete. The PLS_Toolbox virtual environment can take between 1-2 GB of space.

A Python virtual environment is a setup denoting the version of Python being used as well as the packages and their versions. Virtual environments are created to organize these setups, and usually are created on a project-to-project basis. This PLS_Toolbox virtual environment is tailored for the user to use the Python methods in the toolbox. It is advised to not modify, add, or delete packages from this environment. We cannot guarantee that the software will work after modifications.

How to configure

Configuration requires that Miniconda3 be properly downloaded and installed following these instructions. Deviation from these instructions can lead to issues when running the configuration or running the Python methods.

Python configuration video

1. Using MATLAB: https://eigenvector.com/aiovg_videos/python-configuration-for-pls_toolbox/

Download Miniconda3

1. Open a browser and navigate to Minconda's site: https://docs.conda.io/en/latest/miniconda.html
2. Pick a link pertaining to your machine that explicitly states Miniconda3 in the hyperlink. The particular version associated with each of the installers is not important, any of these should work fine. If running macOS, select the .pkg installer. Run the installer.
3. You may be asked to install for just the user, select this option.

• Here is what this step looks like on Windows:

• Here is what this step looks like on macOS. Click on the 'Change Install Button' like below:

And select 'Install for me only'

4. If asked to add to the System Path, do so. Ignore the message saying that doing this is not recommended.

5. Finish installation.

Configuration step in MATLAB

Once PLS_Toolbox has been installed in MATLAB, launch MATLAB and execute config_pyenv in the Command Window. Successful configuration results in the message Your pyenv was configured successfully! on the command line, and subsequent execution of pyenv on the MATLAB command line produces output which should closely resemble what is displayed below

Configuration step in Solo

Open Solo and configure Python by going to Edit>Options>Python>Configure Python, like in the screenshot below.

Testing configuration

It's important to see that the configuration worked and that there is no unexpected behavior from Python. Follow the testing protocols below.

Test in MATLAB

To make sure that PLS_Toolbox and Python are working correctly, run one of the demo scripts that uses Python:

1. tsnedemo
2. umapdemo
3. anndldemo (change line 35 to options.algorithm = 'tensorflow' to use Tensorflow)
4. anndldademo (change line 70 to options.algorithm = 'tensorflow' to use Tensorflow)

If there are issues doing this, see the Troubleshooting section.

Test in Solo

Open one the Analysis Windows that uses Python and build a model to make sure that PLS_Toolbox and Python are working correctly.

If there are issues doing this, see the Troubleshooting section.

Undo configuration

If there comes a time that a user wants to undo this configuration, the user has two options: delete the PLS_Toolbox virtual environment or delete Miniconda3. See below how to do either of these options. Note: Deleting Miniconda3 will remove the PLS_Toolbox virtual environment, as well as any other virtual environments you may have created. Please use with caution.

Undo in MATLAB

• If the user would like to remove just the PLS_Toolbox virtual environment (and keep Miniconda3), run the following in the Command Window in MATLAB: undo_config_pyenv.
• If the user would like to remove Miniconda3 (as well as the PLS_Toolbox virtual environment), run the following in the Command Window in MATLAB: undo_config_pyenv('all').

Undo in Solo

• If the user would like to remove just the PLS_Toolbox virtual environment (and keep Miniconda3)
  • Open Solo and go to Edit>Options>Python>Remove PLS_Toolbox Python Environment.
• If the user would like to remove Miniconda3 (as well as the PLS_Toolbox virtual environment)
  • Open Solo and go to Edit>Options>Python>Remove Miniconda3.

Troubleshooting

• If MATLAB/Solo crashes when trying to run one of these methods:
  • From MATLAB
    • If the PLS_Toolbox virtual environment is in fact being used, then from MATLAB run check_pyenv. If there are warnings, rerun config_pyenv
  • From Solo
    • Click Edit>Options>Python>Check Environment Status. If there are warnings, click Configure Python.
• If there is an error along the lines of Unable to resolve py.anything_can_be_here
  • From MATLAB
    • Type pyenv in the Command Window and ensure the PLS_Toolbox is being used.
    • If running macOS or Linux, start up a new session of MATLAB and type py.sys.setdlopenflags(py.int(10)); in the Command Window, then rerun the method that caused the crash. If the crashing persists, contact our helpdesk at helpdesk@eigenvector.com.
    • If the PLS_Toolbox virtual environment is in fact being used, then from MATLAB run check_pyenv. If there are warnings, rerun config_pyenv
  • From Solo
    • Click Edit>Options>Python>Check Environment Status. If there are warnings, click Configure Python.

See Also

anndl, anndlda, tsne, umap, python