If you're new to MATLAB or looking to get an idea for the type of workflow that might happen in the lab as well as good coding practices, here are some resources.
Check if your school offers MATLAB licenses
Getting Started With MATLAB (~1 hr, run code yourself)
MATLAB - Data Science Tutorial (~45 min)
MATLAB Central has useful things like Answers (how do I ...?) and File Exchange (has someone already written & packaged the piece of code you're trying to write?). Google searches with the keyword "matlab" will often pull up links to MATLAB Answers and the MATLAB File Exchange (abbreviated to FEX). Login to your MathWorks account and bookmark questions as you go.
There is a possibility that for whatever you're trying to do, a built-in MATLAB function or a function written by someone else already exists. Keep that in mind as you balance the time to search for existing code vs. writing your own.
I also recommend keeping a record of answers that you find on MATLAB Central or otherwise (I use OneNote, in which case I suggest having a separate section for each language or program, and a single page for each topic or title). Include both the link and a (preferably text) snippet of the relevant code that was useful. I both update and reference my personal record frequently (often daily) for MATLAB, Mathematica, git, python, bash, Excel, etc.
When you find good resources, make them "yours" in the sense that you can get back to them quickly. OneNote has good search capabilities (Ctrl+E) where you have granular control over the scope (e.g. "This Notebook", "All Notebooks", etc.)
New feature as of R2019b. Highly recommended: MATLAB - Function Argument Validation MATLAB - arguments
It is convenient and easier in the short-term to write code for a whole project in a single script, e.g. having 1000 lines of consecutive code. You can have every variable you assign accessible in a single workspace and you can send a single file instead of many via email, etc.
However, even with good documentation and comments, it becomes difficult for someone else to understand, modify, or debug the code (see Debugging section). It's likely that after a year or many years when you look back at the code, you will have forgotten the details of the workflow yourself.
While it takes more work initially, one effective coding methodology that pays off in the long-run involves:
- compartmentalizing code into functions with clear input/output behavior
- give every new function appropriate documentation & comments (see Code Preamble and Commenting sections)
- write a corresponding "test" function or use a test framework (see Test Functions section)
Some key benefits are as follows:
- Forces you to think about what you're trying to accomplish
- Helps to keep you organized
- Helps you get into the habit of frequent documentation (remember to paste a preamble template into new functions, see preamble template section)
- much easier to debug (see Debugging section, and use
Ctrl+Dshortcut!)
MATLAB excels in debugging features. This article claims the following about debugging:
- On average, a developer creates 70 bugs per 1000 lines of code (!)
- 15 bugs per 1,000 lines of code find their way to the customers
- Fixing a bug takes 30 times longer than writing a line of code
- 75% of a developer’s time is spent on debugging (1500 hours a year!)
- In the US alone, $113B is spent annually on identifying & fixing product defects
(accessed 2020-09-17)
In research, you are the developer. Your customers are your advisor, your labmates, and other researchers (when you publish or share your code). Take the time to be more effective at both debugging and avoiding bugs, and you'll save time and headaches down the road!
Here are two places to start:
MATLAB also has a suite of tools for running test cases. Whether or not you use one of these frameworks, I highly suggest you write and use test functions.
MATLAB - Testing Frameworks For a simple, effective approach, check out the Script-Based Unit Test Framework.
Something that isn't talked about in the above tutorials is that test functions can also be a really effective way to visualize and understand a piece of code without cluttering the function itself. For example, if your code involves operations on high-dimensional data, you can include plotting routines to visualize and understand what happens in lower dimensions. The visualization is also useful as a double check for debugging: Is this the output you would expect from a particular process?
- Input and output should be self-contained within a repository (this can be with nested submodules as well)
- I like to have one repo correspond to one (intended) paper. These can be split as needed and as the project progresses, but it allows for modular deployment of code
- By having at minimum a top-level "code", "data", and "results" folder, you can get the code ready for containerization/deployment via Code Ocean (super cool!). Best practice is generally to split these anyway
- If you use data that can't be posted publicly (due to copyright, licensing restrictions, etc.), but it is small/reasonable enough to fit inside a GitHub repo (i.e. files are all less than 100 MB and the repo isn't massive, i.e. < a few GiB), then you can make a submodule (i.e. repo) that contains that data but doesn't get made public when the rest of the code gets made public. However, there are generally better alternatives to hosting your data, such as figshare (first 100 GB free).
- Hosting code inside a GitHub organization (free to create, e.g. @BYU-Materials-Innovation or @sgbaird-5DOF) rather than a personal account (e.g. sgbaird) allows you to assign granular permissions (e.g. Read vs. Write vs. Admin) to people while keeping the repo private until launch. Haven't seen any downsides to this approach yet.
- GitHub repository (recommended)
- MATLAB packages (can be combined with GitHub repositories)
- GitHub Packages (I don't know a lot about these, but multiple packages can be contained within a single GitHub repository)
Add a date to the preamble (YYYY-MM-DD) and references to published papers or other resources (try copy as .. formatted citation in Mendeley). Cite other people's work! If e.g. a MATLAB answer goes beyond general knowledge or has a useful description of what's going on, include a link to that as well in the format: "https://www.mathworks.com/matlabcentral/answers/<####>" (e.g. https://www.mathworks.com/matlabcentral/answers/15345), which will be more permanent (if the question title changes, the URL doesn't change), or just use the URL from your browser which includes (at least part of) the question title.
MATLAB - Add Help for your Program
preamble-template.txt leverages built-in program help features, readability, lab-specific coding practices, as well as the ability to use Ctrl-J to reformat the preamble section. Copy this template or make your own and place it somewhere easily accessible while coding.
Condensed version from 8 Handy MATLAB Shortcuts That Will Save You a Ton of Time including other(s) that I've added.
| Function | Windows | Mac |
|---|---|---|
| Function Help | F1 |
F1 (?) |
| Comment | Ctrl+R |
⌘+/ |
| Un-comment | Ctrl+T |
⌘+T |
| Auto-Indent | Ctrl+I |
⌘+I |
| Abort | Ctrl+C |
⌘+C |
| Run all code | F5 |
⌘+return |
| Run highlighted code | F9 |
fnkey+F9 |
| Switch panes | Ctrl+tab |
Ctrl+1, 2, 3 etc. |
| Jump to cursor location | ALT + left arrow key or right arrow key |
N/A |
| New script | Ctrl+N |
⌘+N |
| Cancel current action | Esc |
Esc |
| Open function | Ctrl+D |
(?) |
| Image | Source |
|---|---|
| Simba Learns to Code | https://www.reddit.com/r/ProgrammerHumor/comments/a9dijb/legacy_code/ |
Primarily based on page from @BYU-Materials-Innovation/training private repo.