nancumprod

Compute the cumulative product of matrices, specifying the treatment of NaNs.

Description

nancumprod: Cumulative product of a matrix, with user-specified treatment of NaNs.

Computes the cumulative product of matrix A along dimension DIM, allowing the user to replace NaNs with ones, or to maintain NaNs as placeholders.
  
USAGE: B = nancumprod(A, DIM, NMODE)
 
ARGUMENTS:
 
A: Input matrix.
 
B: Output cumulative product matrix, treating NaNs as determined by nmode.
 
DIM: B = nancumprod(A, DIM) returns the nan-cumulative product of the elements along the dimension of A specified by scalar DIM. For example, nancumprod(A,1) works down the columns, nancumprod(A,2) works across the rows. If DIM is not specified, it defaults to the first non-singleton dimension of A.
 
NMODE: specifies how NaNs should be treated. Acceptable values are:
1: REPLACE NaNs with ones (default).
2: MAINTAIN NaNs as position holders in B. (Skip NaNs without reset.)
3: RESET product to 1 on NaNs, replacing NaNs with ones.
4: RESET product to 1 on NaNs, maintaining NaNs as position holders.
   
See also: cumprod, nancumprod, nansum, nanmean, nanmedian, ...
(nancumsum is available from the FEX; other nan* functions may require Toolboxes)

• MATLAB release: MATLAB 7.4 (R2007a)

[Urs (us) Schwarz]

a trouvaille of paramount importance to this community - offered by former CSSM senior brett shoelson; a function that should have been in ML stock for a long time.
needless to say that his clean coding fulfills all the criteria to be a five-star contender: concise h1, help text with meticulous examples, proper input and options error checking, and an interesting, vectorized engine.
us

[Urs (us) Schwarz]

a trouvaille of paramount importance to this community - offered by former CSSM senior brett shoelson; a function that should have been in ML stock for a long time.
needless to say that his clean coding fulfills all the criteria to be a five-star contender: concise h1, help text with meticulous examples, proper input and options error checking, and an interesting, vectorized engine.
us

[Rick Patterson]

I hope the author will not mind if I suggest what may be a better implementation of NMODE case 2 in the circumstances I mention above:

    case 2
        % DO NOT INCREMENT, BUT USE NaNs AS PLACEHOLDERS.
        B = A;
        B(B~=B) = 1;
        B = cumprod(B, dim);
        B(A~=A) = NaN;
    otherwise % case 3
...

[Rick Patterson]

ie In the case where cumulative product of a matrix in the column dimension is required
eg in example 2) above, b=nancumprod(a,1,2)

[Brett Shoelson]

Rick,
Thanks for the comment, though I'm not really sure I understand it. Are you suggesting that I do away with option 2 and force it to be treated like option 1?
 

[Rick Patterson]

Brett,

Sorry for the garbled initial comment, my very first comment on the matter was lost to the ether. I'll attempt to explain further...

So using the setup of example 2:

a =

     8 NaN 6
     3 5 7
     4 9 2

and attempting to get a cumprod down columns with NaNs retained, via:

b=nancumprod(a,1,2)

yields:

b =

           8 NaN 25920
          24 480 181440
          96 4320 362880

ie the column products do not reset at the start of each column.

With the 'case 2' clause adjusted as per my post above, the result is instead:

b =

     8 NaN 6
    24 5 42
    96 45 84

which was a more reasonable treatment for the problem I had at hand.

[Brett Shoelson]

Rick, I see now what you mean. I will circle back around to fix this case and re-post--as soon as I can get to it! :)
Thanks for the comments!
Brett