tonyfast/matlab_syntax.md

## matlab_syntax.md

      
    Raw
  

              matlab_syntax.md
            
          
    Matlab

Love it (I do!) or hate it (You're using it for the wrong thing); Matlab is a numerical computing engine.  Similarly, Matlab is an incredible medium to learn how to numerically program.  Their documentation is fantastic because it is not only filled with syntax, but theory and equations.  I think it is possible to learn a lot while learning Matlab.  Matlab is the Kool-Aid man equivalent of numerical computing; it can smash through most walls and make an enormous mess doing it.  OH YEA!
This document discusses one of the ideas I use to write better documentation for vectorized Matlab code.
Publishing Matlab Code

Matlab has a publish function that uses formatted comments and a few special functions to provide several presentation layers on executed code (e.g. PDF, HTML).  This is all well and good, but for vectorized matlab code it just doesn't matter.
Avoiding for loops with the *fun family

cellfun, arrayfun, and structfun are fantastic functions to beat the time suck of Matlab for loops.  These functions tend to run faster, but at the cost of code complexity, hygeine, and readability.
A vectorized function I might write during my testing phase could look like this.
Stats.out = cellfun( @(x,m) SpatialStatsFFT( x, [], 'Mask', m, 'shift', true, ... 
            'cutoff',[100 100], 'display', false ) , Spart.phase, Spart.mask, 'UniformOutput',false ); 
It becomes easy to write lines of code that do a lot at once with the *fun family.
The Ellipsis

Matlab needs to be told when commands extend to the next line.  The ellipsis ... does this job.  Moreover, everything after the ellipsis is a comment.  So what does the ugly code above look like it I use the ellipsis + comments.
Answer: "It looks uglier, but it has context and thats crucial."
Stats.out =  cellfun( ... Iterate over a cell array argument provide as an input
            @(x,m) SpatialStatsFFT(... A function I built to compute Spatially Resolved Vector Statistics
                         x, [], ... x is both the head and tail of the vector in the statistics : [] indicates a autocorrelation
                        'Mask', m, ... Normalize the statistics using a masking function to ignore some information
                        'shift', true, ... Fourier shift the output statistics
                        'cutoff',[100 100],... Cutoff of the vector distance of the statistics
                        'display', false ) ,... end SpatialStats : Do not automatically visualize the statistics : native to SpatialStatsFFT 
            Spart.phase, ... The numerator of the spatial statistics : Materials dependent parameters
            Spart.mask, ...  The denominator of the spatial statistics : Sampling dependent parameters
            'UniformOutput',false ... This statement is required if if the output of the anonymous function is non-singleton.
            ); % Loop of all the spatial regions
A Practical Application to Structure Arrays

Structure Arrays are a useful way to group like variables.  A structure array may contain many fields whose names may partially describe the contains of the variable.  Ellipsis commenting allows the meaning of the structure fields to augmented thereby making the code more readable.
S = struct( 'name', 'Some Name', ... Sample name of experiment
            't', timevector, ... The unit of time each dependent variable is sampled at.
            'value',vals ... The values were exported by some experimental setup at each time t
            );
A few notes


Lines of code are split canonically into pairs of arguments that work together.
Each line contains of description of its role.
The code can be nicely indented for better legibility.
For a much simpler example, we might be able to figure out what the function is doing.

Wrap Up

When your lines wrap around; Use an Ellipsis; Add a Comment; Share code with your colleagues.