Working with MATLAB

A graphical user interface (GUI) version of MATLAB can be used in the UK Biobank Research Analysis Platform (UKB-RAP). This article provides a method for accessing MATLAB either through the UKB-RAP GUI or via your local command line interface (CLI).

Please note that UK Biobank does not provide a MATLAB license, you must bring your own license to access MATLAB.

If you have further questions or concerns about accessing MATLAB within the UKB-RAP after reading this article, please post them here. 

Overview

• Start an instance of the ttyd app
• Select instance type with gpu capabilities
• Access the worker
• Download and extract the docker image
• Start a container with port forwarding
• Access the container via the specified port
• Provide your MATLAB license login details

Login

• If you are using the dx toolkit via the CLI -dx login

Select the instance

Start an instance of the ttyd app:

• available from the tool library
• CLI - dx run ttyd --instance-type <instance-type>

Select instance type with gpu capabilities:

• e.g., mem2_ssd1_gpu_x16
• CLI - dx run ttyd --instance-type mem2_ssd1_gpu_x16

Access the worker

• Finding and booting an available instance can often take 15 minutes before access can be established. 
  • The GUI will display the status Ready quickly after an available instance has been found. However, attempts to connect to the worker URL will fail until after the instance has fully installed and configured the required packages. 
  • The true readiness of the instance for access can be established through watching the job after dx run ttyd... on the CLI. The Ready instance will display Listening on port <port number from ttyd input> when ready for access.
• After booting, the default port of 443 should allow access to the worker url.
  • e.g., http://job-<job_id>.dnanexus.cloud
  • The above http address is linked by the "Worker URL" button on the monitor tab of the GUI.
  • If you are having trouble with the default port (you've waited sufficiently and the watched CLI describes "Listening on port..."), you may wish to try accessing through an alternative port. 
    • CLI - dx run ttyd --input port=8080 --instance-type mem2_ssd1_gpu_x16
    • GUI - change input port when going through the app start options.

Download and extract the docker image

• docker pull mathworks/matlab-deep-learning:r2022b

Starting a container

Start a container with port forwarding:

• docker run --gpus all -it -p 8080:8888 --shm-size=40gb mathworks/matlab-deep-learning:r2022b -browser
• The -p parameter of the above redirects any traffic from port 8080 to port 8888. The host port (8080 in this case) cannot be the same as the port used as input to the ttyd app (default is 443).
• --gpus all enables use of all GPU hardware on the worker
• --shm-size=40gb specifies memory allocation to the container
• The -browser flag opens a session within the browser window. See Additional - Run MATLAB as superuser for further options.

Access the container via the specified port

• Open a new browser (e.g., Google Chrome)
• Copy the Worker URL into the address bar
• Append :8080 to the end of the address.
  • e.g., http://job-<job_id>.dnanexus.cloud:8080

Provide your MATLAB license login details

• You will now need to login into Matlab using your academic or personal license.
• UK Biobank does not provide a license for researchers.

Additional - Mount a directory from your UKB RAP project space for the container

• From the ttyd CLI run - docker run -v "/mnt/project/Bulk/Brain MRI/":/home/dnax/ --gpus all -it -p 8080:8888 --shm-size=40gb mathworks/matlab-deep-learning:r2022b -browser
• This will provide MATLAB workspace access to the mounted directory. 

Run MATLAB as superuser

• Running MATLAB as a superuser allows the user to install additional software (e.g., MATLAB toolboxes). 
• This method provides the ability to install additional software and then commit updates to the docker image for use later.
  • It is important to only commit software updates.
  • Committing an image that with imported data will commit the embedded data. This is bad practise as the docker image will be unnecessarily large and data security could easily be compromised.
• Method - docker run --gpus all -it -p 8080:6080 --shm-size=40gb mathworks/matlab-deep-learning:r2022b -vnc
  • The 8080:6080 port forwarding here reflects the default port exposed by the -vnc parameter of the mathworks/matlab-deep-learning docker image.
• Open a new browser tab and append :8080 to the end of the address.
  • e.g., http://job-<job_id>.dnanexus.cloud:8080
  • This should bring up an ubuntu desktop user interface (shown in the screenshot below). 
  • To start up MATLAB with administrator privileges, you can open a terminal and type sudo matlab.
  • At this point, you will then be able to install MATLAB toolboxes. 

• After installing toolboxes, you may wish to commit the docker container changes to the docker image. To do this, you will need to:
  • Find the container_name and/or ID - docker ps -a
  • Type docker commit <container_name or container_ID> mathworks/matlab-deep-learning:<version_name (e.g, r2022b-medical)>
• Save the revised docker image
  • docker save mathworks/matlab-deep-learning:r2022b-medical | gzip > matlab_medical_image.tar.gz
• Upload the resultant docker image file to your project space
  • dx upload matlab_medical_image.tar.gz
• Please note that these commands may take some time to load. 

The next time you wish to use MATLAB:

• When you start a new instance, you will first need to fetch your saved docker image using dx download.
  • e.g. dx download matlab_medical_image.tar.gz
• Then run docker load < matlab_medical_image.tar.gz
• Once, the image is loaded, you can then execute the same docker run --gpus all -it -p 8080:6080 --shm-size=40gb mathworks/matlab-deep-learning:r2022b -vnc statement described above.
• Alternatively, if you don't have a docker image saved to your project, please repeat the instructions from step 1 to access MATLAB.