When is the renamevars function introduced?

I use MATLAB Version: 9.7.0.1190202 (R2019b) and got "error using eval. unrecognized function or variable 'renamevars'. Can it be that renamevar function was introduced after 2019b?

Answer 1

[Image Analyst]

R2020a

[alpedhuez]

Yes. Is there any command that will allow me to check on Matlab?

[Image Analyst]

I think if you used the online documentation (not your local documentation) and scrolled all the way down to the bottom, it should tell you.

[alpedhuez]

True.

>Introduced in R2020

But thought it could be useful if this point was checked in an error message.

[alpedhuez]

I ran 'renamevars' on Matlab 2019b installed on a server.

[alpedhuez]

Thus would have been ideally helpful if there is a check to see if a function is compatible with the release.

[alpedhuez]

What I meant is that R2019b could have said "such function is not included in R2019b release."

[alpedhuez]

One can check with the list of default functions in R2019b.

[alpedhuez]

As you noted, the message says

• the function did not exist in the current version MATLAB

or

• could not be found on your MATLAB path or in your current folder

But does not say which one that can be potentially be confusing.

[alpedhuez]

>Yes. Is there any command that will allow me to check on Matlab?

I was asking whether there is a simpler way to figure it out without going through online documentation.

[DGM]

For what it's worth, there is a tool on the File Exchange called when(). In theory, it does what you want, looking up the release version a given function was introduced. The theory isn't quite the same as reality though. There are three problems with it.

1: When() relies on the web docs to get the date. It expects a particular structure to the page which has changed since the function was last updated. I've already notified the author with a fix, but have yet to see a fixed version.

2: When() will only look up things that it determines are Matlab functions. This means that it simply doesn't even try to look up functions which don't exist in the version you're using, even if the webdocs do exist.

3: The assumptions that when() uses to determine the webdocs URL aren't always correct. It assumes that the url is

url = ['https://mathworks.com/help/matlab/ref/' fname '.html'];

or

url = ['https://mathworks.com/help/simulink/slref/' fname '.html'];

It happens that renamevars() is one of the exceptions to this rule.

https://www.mathworks.com/help/matlab/ref/table.renamevars.html

I've attached a modified version of when() which should have fixes for issues 1 and 2. The latter issue just requires foreknowledge of how the URL is structured.

when table.renamevars

## [table.renamevars] does not exist (Introduced in R2020a).

Note that even though renamevars() exists in R2021a, the mismatch between the URL and function name causes when() to confusingly say it doesn't exist.

when renamevars

Connection error or no online documentation found for [renamevars].

If you use the expected filename, it acknowledges that it exists, but then it can't find the webdocs.

The impression now is probably that this is a huge waste of time, and that's a bit unfair. You just happened to have asked about something that's an exception to the rules. For most things, this modified version of when() should at least suffice to get a version. If you're stuck on a slow connection, or if you don't have enough system resources to squander rendering needlessly heavy web pages, when() is much faster than trying to look up web docs.

EDIT: read my comment below about a more robust version of when().

[Walter Roberson]

I do not recall which release it started, but IIRC by R2019b, MATLAB had already implemented noticing (many) functions as being known but not installed, and telling you which toolbox was needed. For example, just tested in R2019b:

>> random(3)

'random' requires Statistics and Machine Learning Toolbox.

It was not complete; for example in R2019b it could not tell me where newff() is from.

[Cris LaPierre]

However, both of these only work if the function exists in the current version of MATLAB, right?

[DGM]

@Cris LaPierre If you're referring to when(), then with the modifications I made, yes it does work even when the function doesn't exist.

In R2015b:

>> which tiledlayout

'tiledlayout' not found.

>> when tiledlayout

## [tiledlayout] does not exist (Introduced in R2019b).

... so long as it can correctly guess the URL. As I mentioned, the number of URLs which it can't correctly predict seems signficant though. I'm sure it could be improved for robustness, but bear in mind that I didn't write this. I just slapped on a field-expedient repair.

[Walter Roberson]

Cris, are you referring to the situation where a function has been removed from MATLAB?

I would expect that the Mathworks code about suggesting a toolbox only knows the names for functions in the same release, rather than checking online for a current repository... so I would not expect that the issue of removed functions in a later release would arise. On the other hand I have misplaced my expectations that a current version of MATLAB would be able to say "Oh, that used to be function in toolbox Z but it was removed"... which would be a useful enhancement.

[DGM]

For what it's worth, I took this opportunity to improve on the existing version of when(). It's not perfect, but it turns out there are a lot of problems trying to make it so.

https://www.mathworks.com/matlabcentral/fileexchange/97272-a-slightly-more-robust-version-of-when

This version addresses all three caveats I mentioned above. It will return results for functions not in the current installation -- whether due to the version or due to a missing toolbox. It will correctly return results even for cases like renamevars() or createMask() which have an unpredictable URL structure.

Regarding the case where a function has been removed from MATLAB, there really isn't much that can be done. When() just concludes that no webdocs exist, which is at least accurate.

[DGM]

@Cris LaPierre I guess I keep misinterpreting "current version" as "installed version". You're right, since that's what webdocs cover. I had considered scraping the totality of release notes and building a table, but as far as I can tell, that wouldn't be complete either.

[Walter Roberson]

renamevars() is a method of a class, rather than a function itself. Guessing the formal documentation URL for methods of a class can be tricky even assuming you know what class is being used. But the MATLAB class resolution algorithm is not as simple as "first parameter determines the class to look at", so even if you made this when() operate similar to which() in the ability to pass in the text of a calling expression, it would be easy to get the type wrong...

Some methods do not have separate documentation, and are only documented in the class description.

Some methods do not have separate documentation just for the method and are not documented in the main class description either, and you have to look on other pages...

... and why is the documentation page table.renamevars and not tabular.renamevars ?

which -all renamevars

/MATLAB/toolbox/matlab/datatypes/tabular/@tabular/renamevars.m  % tabular method
/MATLAB/toolbox/matlab/bigdata/@tall/renamevars.m               % Shadowed tall method
/MATLAB/toolbox/parallel/parallel/@distributed/renamevars.m     % Shadowed distributed method
/MATLAB/toolbox/parallel/parallel/@codistributed/renamevars.m   % Shadowed codistributed method

Then there is the problem that it is not uncommon for methods to not be known to MATLAB, not available for being found using which, until the class has been invoked (so that MATLAB brings the classdef and related routines into memory.)

[DGM]

Considering these sorts of complications and the unsolvable problem of efficiently getting comprehensive picture of function removal versions, I'm inclined to think that TMW is the only party in any position to make a complete and robust version of when() or the resources upon which such a tool must rely.

I just resorted to using a websearch to deal with urls that can't be blindly guessed. It has its own problems, but I don't know what would be better. The docs search tool on-site needs JS to work (things like release notes and function lists do too).

Relying on any information present in the local installation (e.g. toolbox names) will make the tool dependent on the existence of the query subject in the local installation. Half the times I call when() is specifically because a function doesn't exist and I'm trying to see why, so I think said functionality is critically important.

[Walter Roberson]

I have access to ISOs, and those contain all toolboxes. I do not, however, have licenses for all the toolboxes, so I cannot install everything (I think.)

It is possible to parse the manifests to find all the file names, but I have not figured out how the names of the manifest files relate to product names.

And just knowing the file names is not enough, since methods can be completely enclosed within their classes. And I have never found the way to figure out the complete list of built-in functions.

So, as users we can do more than "nothing" to create an appropriate database, but I'm not sure if we could get it right.

[DGM]

If one had a comprehensive set of the installation material, that might at least have the potential to be significantly more complete than other approaches. I mean, squeezing harder won't get legacy or toolbox-related information out of release notes if it's simply not there.

As far as I can see, the available options are all significant challenges in terms of effort and time, and they all lead to a result that is not only likely incomplete to an unknowable degree, but thereafter requires biannual maintenance as well. As I think Star Strider mentioned, you may also have to (programmatically) identify and deal with cases where functions changed name or moved from their original toolbox to the base toolbox. Whether that degree of rigor is warranted for an incomplete database probably depends on how incomplete it's assumed to be.