Dear Christoph

The Supermodel section of the documentation of the Model API makes things a
bit more confusing.
The first sentence says that a Supermodel is "A superservice for applying
complex models". A Superservice, however, is an algorithm (given that
Superservice is said to be an algorithm type in the documentation of the
algorithm API).

Maybe we could rename the "Superservice" algorithm type to "Superalgorithm".
Then, both Supermodel and Superalgorithm are Superservices belonging
together (where a Supermodel is created by a Superalgorithm).

Best regards,
Roman

On Mon, Jan 31, 2011 at 1:45 PM, Roman Affentranger <
roman at douglasconnect.com> wrote:

> Dear Christoph
>
> Few comments regarding the superservice documentation.
> 1) "Super service" is a part of "5. Algorithm Types", but the title has a
> different color than the other algorithm types.
> 2) Under the REST operations, there are links for Parameters, Result and
> Status Codes for GET ("as in Algorithm"). These links point to
> opentox.org/dev/Algorithm, which doesn't exist...
> 3) I find the "introduction" sentence a bit confusing:
>
> =====
> Super Service
> Allows to create models and specify descriptor calculation , feature
> selection and possibly other services, necessary to generate the data,
> required by the model building algorithm
> A superservice for creating models is a specific instance of an algorithm,
> with input parameters defined below. The result of a super algorithm is a
> super model (see Model API).
> =====
>
> I think this could be a bit more clear, e.g.
> =====
> Superservice
> A Superservice is a specific instance of an algorithm that, like a regular
> algorithm, creates a model, but additionally allows for specific definition
> of the individual services (descriptor calculation, feature selection, and
> possibly other services) necessary to generate the data required by the
> model building algorithm. The result of a Superservice is a Supermodel (see
> Model API)
> =====
>
> I don't know if the above sentences are even correct, but I think something
> like that would be more clear. In particular:
> - If you say "a superservice for creating models is a specific instance of
> an algorithm", this gives the impression that there are Superservices wih
> another purpose than creating models. Is that true? If so, it could be made
> more clear. If not, I'd suggest rephrasing as I suggested above.
> - The last sentence "The result of a super algorithm is a super model (see
> Model API)" should be rephrased. The term "super algorithm" appears out of
> nowhere. What's the difference between a Superservice and a Superalgorithm?
> - "(see Model API)" should be a link to the Model API.
>
> So, overall, I think it is fairly clear, however, could be made more clear
> ;)
> In particular, the terminology should be revisited (Superservice vs
> Superalgorithm. If both, both need to be defined). Also, the spelling should
> be unified (Super Service, super service, Superservice, etc.). That is: one
> word, two words? Capital letters/lower-case letters? Same for Supermodel,
> Superalgorithm (if we keep it).
>
> Since it clearly states that the output of a Superservice/Superalgorithm is
> a Supermodel, I'll look at that next....
>
> Best regards,
> Roman
>