Python configuration

Purpose

Gives access to methods from popular packages in Python. Applicable for PLS_Toolbox/Solo 9.0.

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.

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.

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. 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.

5. Finish installation.

Configuration step in MATLAB

If the user has PLS_Toolbox and has ran evriinstall, open a new MATLAB instance and execute config_pyenv in the Command Window. The output of this function should resemble closely to the screenshot below. The version of Python being used is 3.8, and there is a PLS_Toolbox insignia in most of the fields of pyenv

Configuration step in Solo

Open Solo and configure Python by going to Edit>Options>Python>Configure Python.

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 (this also deletes the PLS_Toolbox virtual environment). See below how to do either of these options.

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>Delete 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>Delete 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.