Structuring your MATLAB code base

When your MATLAB project gets large, or when you have a lot of projects, it’s time to consider restructuring your code and libraries so you can focus on what matters the most instead of plowing through the mess you just created.

For my projects, I usually create a file called ‘managedPathAndFiles_{myProjectName}.m’ at the top-level folder. The comments in the demo code below highlight the techniques used:

function [file, folder] = managedPathAndFile_myProject(isRegenerated)
% isRegenerated: set to 'false' to skip addpath() (which is slow)

 % Optional default input arguments by name instead of couting nargin
 if( ~exist('isRegenerated', 'var') )
   isRegenerated = true;
 end

 % Note the use of nested structures (like replacing _ with .)
 % You can use the hierarchy to group folders/files in a way you can 
 % operate on them in one-shot

 % Use the location of this file as anchor 
 % 'pwd' is unreliable because you can call this from other folders if
 % it's in MATLAB's path
 folder.root = fileparts( mfilename('fullpath') );
 
 % Include your project specific subroutines in the MATLAB path
 % Use fullfile() to generate platform independent folder structures
 folder.core.root = fullfile(folder.root, 'core');
 folder.core.helper = fullfile(folder.core.root, 'helper'); 
 % Add all the paths under the folder in one shot
 if( isRegenerated )
   % '-end' avoids name conflict by yielding to the incumbent paths 
   addpath( genpath(folder.core.root), '-end' );
 end
 
 % Automatically create data storage folder
 folder.data.root = fullfile(folder.root, 'data');
 folder.data.cache = fullfile(folder.data.cache, 'data');
 if( isRegenerated )
   % Outputting something will absorb the error if the path alreayd
   % exist. I made a mkdir_silent() in my libraries, but used the
   % native call here for demo.
   [~, ~] = structfun(@mkdir, folder.data);
 end
 
 % Sometimes you might have config or external files to load
 file.data.statistics = fullfile(folder.data.root, 'statistics.mat');
 
end

Many people don’t know about the function genpath() so they ended up lumping all their dependencies in one folder which makes my eyes bleed. Organize your files into a tree that makes sense now!

I’d recommend any serious MATLAB developer build their own library folder with a consistent naming and a sensible tree hierarchy. After looking into FEX and what’s natively available in MATLAB and you still need to roll out your own code, you’re likely to rediscover what you’ve already built just by establishing a new .m file/function you are about to write in the folder you’d most naturally put it in (like people with like mind: self, tend to pick the same names).

Sometimes you have to whip up some ‘crappy’ code that doesn’t generalize (or can be reused) in other contexts. Consider putting them in a /private folder under the caller so it won’t be visible to everybody else. Of course, I encourage people spend a little more time to write the code properly so it can be put in your own MATLAB library.

170 total views, no views today

How I learned MATLAB inside out

Back when I was in struggling graduate student working 3 university jobs to stay afloat, one of the job was to build a multi-center data collection system that take cares of remote data upload, store it in a database and visualize the waveforms and records.

I surveyed other platforms and languages for a couple of months and finally settled on MATLAB because at the time MATLAB had the most convenient data types (cells), data loading/saving (‘.mat’ files so I don’t have to manage the datatypes/format), external interfaces, and most importantly MATLAB FileExchange (FEX) pretty much cover every generic idea I can think of. With MATLAB, my work is pretty much down to coding the high level ‘business’ logic.

And no, I wasn’t biased towards MATLAB at the time because I have a signal processing background. I didn’t know much about MATLAB’s programming support back then other than number crunching (just like the 90% of the public who misundestood the power of the language), so I wouldn’t choose it for a software project at that level of complexity without much research.

Learning the guts of MATLAB, architecturing and coding the entire system took me only 3 months (well, it included a 1 month non-stop 16 hours a day, 7-days a week shut-in programming). Not a shabby platform for a project that is supposed to take 4 years. In fact, the rest of the time was spent

  1. reading the last owners *#@&ed up perl code and fighting to get the fragile linux setup to work on other machines, then reverse the entire project requirements from the source code because there wasn’t any documentation and the previous owners graduated.
  2. reconstruct Guidant’s half-finished (done by a 3rd party then abandoned) binary data reader by finishing the hardest part of the incomplete XSLT code.

The rest that has to do with MATLAB was relatively easy once I learned the main ideas through their documentation, newsgroups, Loren’s blog and the official support.

To understand and appreciate the beauty of MATLAB and use it effectively, you have to get past the following hurdles:

  1. Basic data structures: cell, struct and language features.
  2. Vectorization: use for-loops only in limited cases
  3. Anonymous function (Lambdas), cellfun(), arrayfun(), bsxfun(), structfun()
  4. Overloading and OOP
  5. Tables (Heterogeneous data structures) and Categorical objects (Nominal, Ordinal)

or else you are coding it like a C programmer: a complete waste of MATLAB’s license fees. If you know these 5 aspects of MATLAB well and would say there are strictly superior options out there, please let me know in the comments section and I’ll look into it.

 

177 total views, no views today

MATLAB Quirks: cellfun() high-performance trap

cellfun() is a powerful function in MATLAB which mirrors the idea of applying a ‘map’ operation (as in functional programming) to monads (cells: a datatype that holds any arbitrary data type, including itself).

One common use is to identify which cells are empty so you can ignore them. Typically, you can do

index.emptyCells = cellfun(@isempty, C);

According to the help (H1) page, there is a limited set of strings that you can use in place of the function handle (functor) for backward compatibility:

 
A = CELLFUN('fun', C), where 'fun' is one of the following strings,
returns a logical or double array A the elements of which are computed 
from those of C as follows:
 
   'isreal'     -- true for cells containing a real array, false
                   otherwise 
   'isempty'    -- true for cells containing an empty array, false 
                   otherwise 
   'islogical'  -- true for cells containing a logical array, false 
                   otherwise 
   'length'     -- the length of the contents of each cell 
   'ndims'      -- the number of dimensions of the contents of each cell
   'prodofsize' -- the number of elements of the contents of each cell
 
A = CELLFUN('size', C, K) returns the size along the K-th dimension of
the contents of each cell of C.
 
A = CELLFUN('isclass', C, CLASSNAME) returns true for each cell of C
that contains an array of class CLASSNAME.  Unlike the ISA function, 
'isclass' of a subclass of CLASSNAME returns false.

Turns out these functions have their native implementation and runs super-fast. But I got burned once when I tried to use this on cells containing table() objects:

index.emptyCells = cellfun('isempty', cellsOfTables);

I meant to find out if I have zero-row or zero-column (empty) table objects with that. It gave me all false even when my cells have these 0-by-0 tables. What a Terrible Failure?! Turns out these ‘backward compatibility’ native implementations (I guess they already have cellfun() before having function handles) looks at the raw data stream like PODs (Plain Old Datatypes) as a C program would do.

A table() object has lots of stuff stored in it like variable (column) names, so there’s no way a program looking at an arbitrary binary stream without accounting for such data type will consider that object empty. It’s up to the overloaded isempty() or numel() of the class to tell what is empty and what’s not, but it needs to be called by the function handle to establish which method to call.

Lesson learned: don’t use those special string based functor in cellfun() unless you know for sure it’s a POD. Otherwise it will get you the wrong answer at the speed of light.

543 total views, 1 views today

Make your MATLAB code work everywhere

MATLAB is used in many different setups that it’s hard to expect every line of your code you write generalizes to all other versions, platform and deployments. The following code examples helps you identify what envirnoment you are in and so you can branch accordingly:

% 32 bit vs 64 bit MATLAB
% This exploits the fact that mex is on the same platform as your MATLAB
is64bit = strcmpi( mexext(), 'mexw64');

% Handling different MATLAB versions
if( verLessThan('matlab', yourVersionString) )
  error('This code requires %s or above to run!', yourVersionString);
end

% Headless (Parallel) workers
% This exploits the fact that JVM is not loaded for parallel workers. 
% Starting MATLAB with '/nojvm' will be considered headless
isHeadless = ~usejava('desktop');

% DCOM / ActiveX /Automation Server
isDCOM = enableservice('AutomationServer');

% Test for compiled MATLAB:
isdeployed()

138 total views, no views today

Auto Mouse Mover / Clicker

At work I came across a piece of fine software (fine as the ‘F’ in RTFM) to access the data from an open-source project that decided to throw a warning dialog box every time when it come across some minor data integrity issues while going through tens of thousands of entries.

Upon inspecting the C code, they failed to provide a mechanism to suppress the warning dialog box for Windows (it can be done a function that uses with signals in linux though). Since this is a one-shot gig anyway and I don’t have the time to figure out the dependencies and recompile their code chain, I came up with something ghetto: automated mouse clicker.

It’s the kind of solution that is not too natural to come by for people with finer control over computers (aka, software engineers), but immediately obvious to middle-school level script kiddies.

I have to admit I almost lost the ‘street’ knack as it took me an hour digging through the documentation and code base to find a ‘proper’ way to do it before I even gave the ghetto patch a thought. That’s how seasoned engineers can get pwned by noobs who ‘don’t know a damn thing’ but ‘gets the job done’. Luckily, I remembered to switch hats early enough this time.

A ghetto trick or two can be used ONLY when we are really sure that it’s a one-time gig that won’t be reused. Any attempts to extend the one-time-wonder can only attribute to pain and misery for everybody, as a recurring theme in software and product development projects.

Sounds like a familiar situation at work? It’s always that one small thing your client asked you for. If you hack something up quick-‘n’-dirty and it worked, they are going to say, ‘by the way, one more one small thing…’. Lather, rinse, and repeat and soon you’re buried in brown, sticky foam.

This can be explained by the life lesson I learned in my first summer internship during high school: people in general don’t know what they really wanted and they don’t communicate well. Me included. The soft-skills coaching received at Stanford helped quite a bit, but I still consider myself ‘not there yet’.

Typically, your client is going to ask you for something specific (which is not what they really wanted because they haven’t figured it out yet) and keep revising and making sharp turns at your expense to make up for the ‘errors’ as in ‘trial-and-error’.

This is not a win-win scenario. It’s a tug of war between you and your client: you want your client to do their homework to figure out what they wanted and your client want to crap-shoot at your expense. It creates tension between you and your client. A work contract (or a specification agreed upon) might protect you from blame, but a client that doesn’t get what he/she wanted (regardless of who is at fault) is not going to be happy about your work.

One way out of it is to ask your client to start with a vague, underlying theme of what they are trying to accomplish. This way they won’t be overwhelmed by the pressure to get all the detailed specs right. If you have a long term relationship with the client, it pays to learn what are their general ‘interests’ are so you can piece the fragments together quicker. Gradually, you can ease them into thinking through their underlying goals aloud and you can take the opportunity to explore how you can help them accomplish it.

Guide them through their thought process, and maybe show a little prototype or design to help them visualize how they can accomplish their goals (through you). With the big picture in mind, you can make educated judgement, fill in details, and decide what intermediate/iterative steps are needed instead of letting the client unwittingly micromanage you based off his/her solution approach by saying ‘I need one small thing quick…’ one at a time. You are now in control over the project and in a very good position to help your client meet his/her true agenda.

It seemed like more upfront work to meet your client halfway and do part (or half) of their homework, but for anything other than a short hit-and-run, it’s less total work for you and a happier outcome for both. Using this approach, I was able to deliver a last minute change in ‘1 minute’ because the software architecture I designed was tailored towards the client’s underlying goal, so the feature he forgot to ask for was naturally built in and only requires one line of code to turn it on despite I hadn’t explicitly planned for it.

The bottom line is that humans are clueless (at various levels) and they want to further their interests (by doing something). If we take both parties’ interest into account and spot inefficiencies that we can correct, there’s at least an approach where everybody wins. Game-theoretic approach and market equilibrium is ‘optimal’ only when ‘technology’ is held unimproved and there is no on-going relationship between parties. Life doesn’t always have to be a war or struggle 🙂

156 total views, no views today

“Copy as path” option in Microsoft Windows

Very often I want to copy the full path of a file to my MATLAB environment for quick testing. Before my coworker showed me the trick, I tried to staple the filename I copied from the Explorer window to the address bar then re-copy the whole. That was dumb.

For some reason, Windows stowed away a slick feature called ‘Copy as Path’. You have to hold “SHIFT” key while right-clicking to get the good stuff displayed (same as “Open Command Window Here”).  What a crime!

This website shows you a way to have the menu option activated by default:
http://www.askvg.com/registry-tweak-to-add-copy-as-path-option-in-files-and-folders-context-menu-in-windows/

95 total views, no views today