dealing with variable options (varargin) in matlab

Summary

There are various ways to handle variable input arguments (varargin) in Matlab. I present the standard method i use that is relatively flexible and allows for readable code.

Matlab doesn't adopt R, python, or various other language's syntax for passing optional arguments, namely, you can't specify the name-value pair in the list of inputs to the function. While this might initially seem to be a weakness, it can allow for cleaner, more flexible code with the right planning.

The main goal is to have a set of inputs that have default states within the function—often magic numbers or other hard-coded constants are placed here so they are easily edited and their impact understood. One way to deal with Matlab's method of passing optional parameters is to just pass an options structure as the sole name-value pair, with fieldnames containing the options used by the function.

download optionsStructExample.m

Matlab M
  1. % get an options structure from varargin, search for fields
  2. options=[];
  3. foo=0;
  4. bar = 'hello world';
  5.  
  6. if ~isempty(varargin)
  7.     options=varargin{1};
  8.     if isfield(options, 'foo')
  9.         foo=options.foo;
  10.     else
  11.         foo=0;
  12.     end
  13.     if isfield(options, 'bar')
  14.         bar=options.bar;
  15.     end
  16. end

However, this is not very flexible and the feature cannot be easily enhanced across all functions in a project. Further, it is not the most readable or consistent code and the same sequence of actions is repeated in the actual source code instead of dynamically/filter grabbing options set in the input. Another method is to then loop over name-value pair inputs.

download vararginForLoop.m

Matlab M
  1. for i = 1:2:length(varargin)
  2.     val = lower(varargin{i});
  3.     switch val
  4.         case 'foo'
  5.             foo = varargin{i+1};
  6.         case 'bar'
  7.             bar = varargin{i+1};
  8.         otherwise
  9.             disp('option not available!');
  10.     end
  11. end

This method isn't necessarily better, but solves the problem in a slightly different manner that in essence keeps the same problems: it still relies on a hard-coded enumeration of all acceptable variable input parameters. As more options are added, this can grow to consume a good chunk of the introductory code in a function and is not super friendly to someone skimming the code.

An alternative method is presented below (see getOptions.m). The idea is to take advantage of the repeated nature of how variable input arguments are dealt with along with dynamic filtering to ensure that the user cannot input invalid parameters. The solution is to always put all available options into a structure, called options, at the beginning of each function. This structure contains fieldnames that a user can input via classic name-value pairs, e.g. foobar('electionYear', 1992), or via a special options name-value pair wherein an options structure is created with fieldnames to be modified (see exampleScript.m below). In either case, a single function then deals with looping over all variable inputs and replaces the default values that match a valid fieldname. This is done dynamically, which means that if additional options are added, no new code is needed to help filter and add the new options name-value pairs to the functions settings.

While this introduces some restrictions on how a function responds to a given input, e.g. you cannot immediately call a new function based on user input before parsing all variable arguments (perhaps for the better), it forces a consistent format to how options are dealt with and allows for added functionality to be implemented across all functions in a project quickly.

For example, the special options name-value input argument was added later and instantly allowed me to reduce super-long code-lines with a ton of name-value pairs to several lines each with a single fieldname and input value, allowing for easier readability and (in the future) more dynamic parameter passing. This would have been much harder to implement across every script in my current project using the two previous methods.

More small code snippets to come in the future, for now, enjoy the example below!

download exampleScript.m

Matlab M
  1. % pass option via a name-value pair
  2. [output] = exampleFxn('foo',1,'bar','Call me Ishmael');
  3.  
  4. % or pass option via options structure
  5. inputOptions.foo = 1;
  6. inputOptions.bar = 'Call me Ishmael';
  7. [output] = exampleFxn('options',inputOptions);
download exampleFxn.m

Matlab M
  1. function [output] = exampleFxn(varargin)
  2.         % example function with outline for necessary components
  3.         % biafra ahanonu
  4.         % updated: 2014.02.17
  5.  
  6.         %========================
  7.         options.foo = 0;
  8.         options.bar = 'hello world';
  9.         % get options
  10.         options = getOptions(options,varargin);
  11.         % display(options)
  12.         % unpack options into current workspace
  13.         % fn=fieldnames(options);
  14.         % for i=1:length(fn)
  15.         %       eval([fn{i} '=options.' fn{i} ';']);
  16.         % end
  17.         %========================
  18.  
  19.         try
  20.                 if options.foobar==1
  21.                         display(options.bar);
  22.                         % do something
  23.                 else
  24.                         % do something else
  25.                 end
  26.         catch err
  27.                 display(repmat('@',1,7))
  28.                 disp(getReport(err,'extended','hyperlinks','on'));
  29.                 display(repmat('@',1,7))
  30.         end
download getOptions.m

Matlab M
  1. function [options] = getOptions(options,inputArgs,varargin)
  2.     % gets default options for a function, replaces with inputArgs inputs if they are present
  3.     % biafra ahanonu
  4.     % 2014.02.17 [22:21:49]
  5.     %
  6.     % inputs
  7.     %   options - structure with options as fieldnames
  8.     %   inputArgs - varargin containing name-value pairs passed from parent function.
  9.  
  10.     % list of valid options to accept, simple way to deal with illegal user input
  11.     validOptions = fieldnames(options);
  12.  
  13.     % loop over each input name-value pair, check whether name is valid and overwrite fieldname in options structure.
  14.     for i = 1:2:length(inputArgs)
  15.         val = inputArgs{i};
  16.         if ischar(val)
  17.             % allow input of an options structure that overwrites existing fieldnames with its own, for increased flexibility
  18.             if strcmp('options',val)
  19.                 inputOptions = inputArgs{i+1};
  20.                 [options] = mirrorRightStruct(inputOptions,options);
  21.             elseif ~isempty(strmatch(val,validOptions))
  22.                 options.(val) = inputArgs{i+1};
  23.             end
  24.         else
  25.             continue;
  26.         end
  27.     end
  28.  
  29. function [pullStruct] = mirrorRightStruct(pushStruct,pullStruct)
  30.     % overwrites fields in pullStruct with those in pushStruct, other pullStruct fields rename intact
  31.     % more generally, copies fields in pushStruct into pullStruct, if there is an overlap in field names, pushStruct overwrites.
  32.     pushNames = fieldnames(pushStruct);
  33.     for name = 1:length(pushNames)
  34.         iName = pushNames{name};
  35.         pullStruct.(iName) = pushStruct.(iName);
  36.     end

-biafra
bahanonu [at] alum.mit.edu

additional articles to journey through:

automatic python playlist creator
16 november 2012 | programming

Now that I've gotten back in the python groove somewhat, wanted to make a playlist script that recursively went through a folder, found all[...] files in a sub-folder and create a playlist from them. Implementation described and link to github repository.

sochi olympic stats: medal count
19 february 2014 | america

There have been several articles that re-order the medal count ranking by comparing medals to population or GDP, which then show small coun[...]tries topping the charts. This analysis ignores some obvious facts: small countries are over-represented in the number of athletes they send and the relationship between athletes sent and medals is linear. I present a brief analysis to support and expand on these claims.

filugori reboot
15 may 2012 | filugori

Several months ago I took a hard look at Filugori: The Long Tale, the story I started in grade school that was meant to be a mash-[...]up of my favorite books and fictional universes. However, it lacked a certain vision. The story was fun, frantic and fanciful, but there was no heart. It lacked cohesion and the universe did not appear to justify its own existence. Why should someone care to read this tale? What would they gain from it? While fleshing out the background of the universe, providing details on the four major epochs that define the story, I came to realize that I wanted to tell a very different tale than originally planned.

global history of architecture
08 june 2013 | architecture

One of my favorite classes at MIT was 4.605 (Global History of Architecture), which explored various styles and themes found throughout dif[...]ferent buildings and other types of architecture from the beginning of civilization to the present. In the spirit of sharing my enthusiasm for the course i'll discuss some takeaways from, and have included a couple papers i wrote for, the class.

©2006-2017 | biafra ahanonu | updated 12 december 2017
biafra ahanonu