What is the best practice to understand the source code of MATLAB's built function ?

I want to learn the basic theory of wavelet synchrosqueezed transform, and find that there is a built-in function wsst in the Wavelet Toolbox. I open the wsst file using the dbtype wsst command so that the source code of the wsst is illustrated in the Command Window. However, I find that there are many complex function callls in the calculation process of wsst, it is difficult to get insight into the detailed calculation procedure of wsst. I would like to receive some useful advice from the mathworks community on how to better understand Matlab's built-in complex functions, such as the aforementioned wsst function.

[Chuguang Pan]

I find there are duplicate attribute validations in the wsstImpl function which is the local function of wsst. There are two vcoMustBeEven(namedargs.VoicesPerOctave) validation function.

function [Tx,freq,analysisParam,params] = wsstImpl(x,fsOrTs,namedargs)
arguments
    x       {mustBeVector,mustBeFloat,mustBeReal,mustBeFinite}
    fsOrTs  {mustBeScalarOrEmpty} = []
    namedargs.Name {mustBeTextScalar} = 'amor'
    namedargs.VoicesPerOctave (1,1) {mustBeNumeric,mustBeInteger,vcoMustBeEven(namedargs.VoicesPerOctave),mustBeInRange(namedargs.VoicesPerOctave,10,48,"inclusive"),vcoMustBeEven(namedargs.VoicesPerOctave)} = 32
    namedargs.ExtendSignal (1,1) logical = false
    namedargs.WaveletParameters  {mustBeNumeric,mustBePositive}
end

Answer 1

[dpb]

Let's first reformat the code to be more legible...

function [Tx,freq,analysisParam,params] = wsstImpl(x,fsOrTs,namedargs)
arguments
    x       {mustBeVector,mustBeFloat,mustBeReal,mustBeFinite}
    fsOrTs  {mustBeScalarOrEmpty} = []
    namedargs.Name {mustBeTextScalar} = 'amor'
    namedargs.VoicesPerOctave (1,1) {mustBeNumeric, ...
                                     mustBeInteger, ...
                                     vcoMustBeEven(namedargs.VoicesPerOctave), ...
                                     mustBeInRange(namedargs.VoicesPerOctave,10,48,"inclusive"), ...
                                     vcoMustBeEven(namedargs.VoicesPerOctave)} = 32
    namedargs.ExtendSignal (1,1) logical = false
    namedargs.WaveletParameters  {mustBeNumeric,mustBePositive}
end

Now looking at the validation, it is saying that first VoicesPerOctave --

If passed, must be

1. a single element of a numeric class, then
2. integer-valued, then
3. even-valued, and
4. within the range of 10 to 48, inclusive.

Finally, if not passed, the default value of 32 is set.

These are relatively easy to figure out what are doing, but the only way to really understand in depth is to learn the syntax and behavior of the MATLAB validation functions. Start with the <Function Argument Validation> page to get an overview of the forest instead of trying at the tip of the smallest branch of a single tree.

As outlined in the details of argument validation you'll get to if you read the above reference, validation is a sequential process; the most generic must be verified first such that later checking can assume certain things are true. For example, the very first steps above wouldn't work if were reversed; "even" isn't defined unless the argument is numeric.

As far as the original question regarding how to understand the implementation of a computational algorithm, you can almost completely ignore the argument validation code; it has no direct bearing on the actual calculation; it just ensures that the code will have the types and ranges of values expected up front so the actual working code sections don't have to worry about whether an assumption has been violated.

The thing to do is to start with the "Algorithms" and "Reference" sections to see what bread crumbs Mathworks has left for you in the documentation and then obtain and read the references to understand the general concepts being applied. Once you understand that theory, then walking through the code will be at least somewhat simpler; just how difficult to follow will depend a lot upon just how clever the person who implemented it was in utilizing internals or specific features of MATLAB syntax for performance reasons.

[Chuguang Pan]

@dpb. Thanks a lot for your helpful answer. I should learn the calculation processes of wsst based on the reference first.

[dpb]

If you aren't familiar with the field, then to do more than use the toolbox functions as black (or dark gray) boxes is about all one can do; trying to ferret out the principles behind an algorithmic implementation is generally a difficult task unless the code is very well commented; implementation details tend to obfuscate the big picture very quickly. Even a calculation of something as trivial as a mean may look very complex and hard to determine that is what a code function does if it is implemented in such a manner as to maximize the numerical precision rather than as simply a brute force sum. The general principle simply gets lost in the details.