MLPRegressor & MLPClassifier RSTs & SC example Code

[tedmoore]

@weefuzzy, this also contains a fix for the docs repo. The species 'data' wasn't at all checking if enums existed, so now it does do that so they will render. I abstracted the enum code into a new file since it needs to exist in two files.

[tremblap]

fantastic review!

maybe the learning rate entry is too verbose - I would remove after the 2nd sentence (i.e. Without context ->end) as you point at the online reference that says exactly that.
hidden is now hiddenLayers

[jamesb93]

A few small things including what I think are mix ups of discussion/discussion. These will render poorly in Max and be confusing to read in the reference.

Overall, I feel like it's quite a long help file. In Max this will span 5-7 tabs as we don't have the benefit of infinitely long documents to work through. I may break this apart and break "parity" in that sense to keep it legible.

[tedmoore]

Overall, I feel like it's quite a long help file.

By this do you mean the example code or the prose in the RST?

[jamesb93]

Apologies, the code.

[tedmoore]

It is quite long however I'm disinclined to delete things. Some of these could be examples, but even then I know that in this location they'll get much more attention and I think they're all relevant to using the object. I don't think there's redundancy.

[jamesb93]

It is quite long however I'm disinclined to delete things. Some of these could be examples, but even then I know that in this location they'll get much more attention and I think they're all relevant to using the object. I don't think there's redundancy.

Not redundancy as such. Towards the start of our tenure on the project I made an MLPClassifier and MLPRegressor help file that was essentially this file in Max format. It was criticised for being too long and not the right place for that kind of content. I suppose I am just raising the point that we have come full circle.

[tedmoore]

I see. Was it I that said it was too long? Is there a specific part that you think should not be included? I'm happy to leave it all in unless someone has a compelling reason for something to be taken out. It seems to me having many examples in the example code is a good thing as long as each example is demonstrating a different aspect of use.

[weefuzzy]

It was probably me. I don't think my thoughts have changed greatly. That code is great for a completely worked through tutorial on doing some meaty and cool. What goes into a help file should IMO be about making clear the usage of a particular object with as little distraction as possible. In the case of the MLPs I think that involves toy problems on already extant datasets / labelsets so that the interface for training and inference are very clear (because there's very little else).

That sort of terseness is useful for people who already know how to work with an object of this species, but want to see quickly what the interface is in this particular library (or people who have learnt our object but want to remind themselves quickly). The complete work-through is useful for people still getting to grips with the concepts and steps involved, or who might need inspiration. In both Max and SC I think 'tutorials' are a better place for examples of that depth.

I think I've probably often gone too far the other way in first drafts of help for a lot of these objects, to the point where it wouldn't be clear to someone browsing what possible use some given object might have. I think, besides finding an elusive middle ground in how suggestive the help file examples can be, some of that can be addressed by explicitly linking through to tutorials that present concrete applications in details.

[jamesb93]

I see. Was it I that said it was too long? Is there a specific part that you think should not be included? I'm happy to leave it all in unless someone has a compelling reason for something to be taken out. It seems to me having many examples in the example code is a good thing as long as each example is demonstrating a different aspect of use.

Taking the classifier as an example, my feeling is that the immediate SC/Max code would show how to add some points, train and then classify a whole dataset with predict and a point with predictPoint. It wouldn't have anything to do with synthesis or audio features at this point.

There would then be a link to an example/guide (not sure of the nomenclature in SC land) which deals with audio matching and also links to the learn article.

[tedmoore]

Moving some of this to guides in SC is find by me. However, I do think that a lot of SCers don't look at the guides. I know I don't and I've had conversations with others that say the same thing. We can put them them there, I just don't think they'll get as much attention. Long helpfiles in SC are not uncommon. As an SC user, I prefer to have it all there.

It wouldn't have anything to do with synthesis or audio features at this point.

Regarding this, we've talked a lot about having the materials be sound-creativity forward, so I've tried to generally avoid using dummy data sets (unless it really needs to be clear like KMeans perhaps is a good example of this), and I've always tried to have the example code make some sound. When we started the revamp of the help files this was one of the critiques that we offered on the previous iteration.