Making MATLAB projects reproducible and shareable
♻️

Dr David Wilby (he/him)
RSE Team, The University of Sheffield
rse.shef.ac.uk | davidwilby.dev

OpenFest Thurs 15th September 2022

Who am I?

And why should I be talking about this?

Wilby & Roberts (2017) J. Exp. Bio.

• Previously researcher in biology/physics
• Research Software Engineer
• Software Sustainability Institute Fellow

What is reproducibility?

How the Turing Way defines reproducible research

Image: The Turing Way

Why is reproducibility important for research?

Image: The Turing Way

• Verification ✔️
• Share learning 🧑‍🎓
• Re-use ♻️
• Longevity ⏳
• Efficiency ⌚
• Make code accessible 📖

What is software?

• laden with confirmation bias
• software means the same as code as far as this talk goes at least
• software or code, is good for research reproducibility
• but it is not without its challenges

The Challenge of Software Reproducibility

• Document required software, data and where to get them
• Document steps to reproduce analysis
• Create a well-defined computational “environment”
• Make it easy!

(some) Principles of Reproducible Code

• Organise your project 📑

Instead of ❌

first_try.m
pretty.fig
stuff/
how%20torun.docx
data.csv
data_(01).csv
data.txt

Try ✔️

data/
docs/
figs/
output/
src/
    01_download_data.m
    02_clean_data.m
    03_fit_model.m
    04_plot_figs.m
README.md

Via BES Guide to Reproducible Research

(some) Principles of Reproducible Code

• Share the code 🔬 (use a license!)
• Share the data 📊 (license here too!)
• Define dependencies & environment 🤓
• Use version control 🐙
• Document how to use the code 📋
• Get colleagues to try it out! 🧑‍🤝‍🧑
• Just try your best! 👍

MATLAB can be … challenging

• 📦 ❌ No package manager (à la python, R, node etc.)
• 🖥️ ❌ No virtual envrironments (sort of)
• 🤓 ❌ Limited dependency discovery/management
• ⛔ Proprietary source code
• 💸 MathWorks get most of their income from industry - so aren’t largely motivated to develop open source tools and guidance
• 🙃 Lots of weird binary file formats
• 🧑‍💻❌ Doesn’t get a lot of attention from (research) software engineers
• 😣 sigh…

So why bother?

Lots of researchers use MATLAB.

12,000 active MATLAB licenses at The University of Sheffield

Data from: Web of Science

What’s the solution?

Case study

• Paper in review
• Uses MATLAB (& R) code to run some plotting and statistical analysis
• Hosted on GitHub at github.com/davidwilby/HermitCrabPolarizationVision2022

Environment: MATLAB ‘Projects’

• projects are an effort to make matlab more portable
• almost like a virtual environment
• loads files onto the MATLAB path
• the path is a list of filesystem locations where matlab ‘looks’ for code
• projects load specific files onto the path when loaded and take them off when closed

Aside: Jargon Blast 💥

MATLAB Projects

A tool for defining files, paths and dependencies within a project, helping to improve portability.

MATLAB Toolboxes

A way of packaging up code as tools which will be used across your MATLAB installation. Kind of like ‘packages’ in other languages.

MATLAB Packages

Not really like packages in any other language.

A way of protecting namespaces, e.g. import MyPackage.MyClass.

In folders starting with + e.g. +MyPackage/

Dependency management

Dependency analyzer

Now what? 🤷

Either:

• document how to obtain and install the dependencies

or

• provide dependencies with the code, if small and if permitted

• as I said, there’s no package manager
• or built in programmatic way of installing dependencies
• yet
• so what’s the solution here?

Documentation - readme files

• In this readme you can see that I’ve illustrated the structure and contents of the repository

• regarding the dependencies, all I’ve been able to do is to detail the dependencies

bit.ly/3L7WM9Z

• but one thing that can be even better than this is to use a literate programming tool
• the matlab version of this is called a live script
• it’s similar to rmarkdown or jupyter notebooks

🥡 MATLAB projects can be reproducible

Image: Jarekt via Wikimedia

Reproducibility Checklist

• ☑️ organise project
• ☑️ share your code and data
• ☑️ document/capture dependencies
• ☑️ write examples (documentation!)
• ☑️ tutorials (also documentation!!)
• ☑️ explain how to use the code! (documentation!!!)

Acknowledgements

• Software Sustainability Institute
• Research Software Engineering Team
• in2Track Team (Civil Engineering) - Ehsan Kazemi, Yiqi Wu, Andy Nichols
• TeleRegain Team (ACSE) - Josh Giles, Salem Mansour, Jake Toth, Mahnaz Arvaneh

Resources

• The Turing Way
• BES Guide to Reproducible Research
• repliMAT (Coming soon!)
• Blog: a concise guide
• Code Clinics