Undocumented behavior of smooth()?

Update: I submitted a support request for this issue, and it's been forwarded to the development and documentation teams.

Original: The documentation for smooth() states that for the 'lowess' and 'loess' smoothing methods, span is a percentage of the total number of data points, less than or equal to 1. However, I discovered that if I set span >= 1, it seemed to behave similarly to that for the 'moving' method (i.e. the input is interpreted as the number of points to smooth over).

I found this line in smooth() that performs the conversion (line 146 in R2016b, before any of the specific methods are called):

if span < 1, span = ceil(span*t); end % percent convention

So, conversely then, smooth() is more than happy to convert a fraction to a number of samples if you request 'moving'.

I don't see this behavior mentioned in the documentation, and I believe both the behavior and documentation has been the same at least back to R2014a. Am I missing something?

I actually prefer this behavior - I want to smooth different length vectors with exactly the same method, and it seems overcomplicated to have to calculate the fraction for each such that I could be absolutely sure that the number of points in the span were always the same. It seems like using the fraction is a great way to make errors, generally. However, I see two problems with this:

1. It is (apparently) undocumented, so I assume there's no guarantee that the behavior will stay the same in future versions, and it could change without warning.
2. If I wanted to smooth using 'lowess' with a span of 100% of the data points, I would use span = 1, according to the documentation. However, the actual behavior is no smoothing, as any numbers >= 1 are interpreted as a number of samples, rather than as a fraction of samples.

Side note:

Like moving, lowess forces span to be odd, but it adds one point (line 292):

span = 2*floor(span/2) + 1;

instead of subtracting one, as in moving (line 206):

width = span-1+mod(span,2); % force it to be odd

I don't see any reason why the behavior should be different between the two.

[Chad Greene]

Interesting question, and well communicated. I'll be interested to find out what you hear from the documentation team.

Answer 1

[Evan]

From Mathworks support:

I have submitted an enhancement request for this to be considered and officially documented in future releases. However, since this is still currently an undocumented behavior, we cannot guarantee that this behavior will be preserved in the future. Therefore, I suggest not to use this functionality until it is officially documented.