[Rivet] New projection method names without "projection"

[Andy Buckley]

On 24/05/16 07:59, Frank Siegert wrote:
>>>> As some of you at the MCnet Computing School last week (which was
>>>> excellent,
>>>> by the way) know, I think we made a mistake when we used the word
>>>> "projection" to name a concept in Rivet.
>>>
>>> For those of us who were not at the school last week, could you
>>> explain why Projection is a misnomer? I always liked it, as it is a
>>> concise wording which still captures exactly the functionality.
>>
>> I quite like the picture, but a) the algebraic mapping is not exact because
>> you can't actually do P(P(Event)),
>
> I see, though I would consider this nitpicking.

It is! But that's the problem with metaphors, they help users enormously 
when they are faithful, but hurt disproportionately when there are 
deviations that need to be explicitly flagged, explained, worked-around, 
etc..

>> b) the caching feature should not be
>> something users typically need to think about,
>
> This is not related to the (re)naming, is it?

I thought this was one of the points you were including in "projection 
is a good name"! It's a fairly small step from "running a projection 
twice doesn't change the result" (algebraic metaphor) to "projections 
cache their results". But no, not strictly related unless you read that 
behaviour into the name.

>> and c) my experience is that
>> users really do not get it... it's certainly not intuitive until someone
>> explains the relevant mental picture. "Calculator" or "Observable" might
>> have been better choices from the user point-of-view.
>
> Ah, that's a valid point.

Glad I've got one ;-)

>>>> We're too far down the rabbit-hole to completely reverse that now, but we
>>>> can reduce the number of times that normal users have to encounter the
>>>> word
>>>> "projection".
>>>
>>> I'll admit to being a boring conservative here, who has been scolded
>>> too often for user-facing changes (though I think we have been pretty
>>> good over the last months or even year(s)). While I'm not strictly
>>> against such changes, I'd prefer to limit them to really good reasons.
>>
>> We intend to keep Rivet alive for another 10 years or more, I think. That
>> means that change is inevitable as requirements change -- it's how we manage
>> it that matters. I don't think this is a critical thing, but I think a great
>> deal of our success so far is due to interface intuitiveness: users find
>> Rivet "natural" and easy to get from zero to something useful. If we want to
>> keep expanding that collection of coding users -- and I do, especially into
>> the BSM realms of the experiments -- then I think it's worth polishing this
>> last, unintuitive corner of the API.
>>
>>>> For addProjection, the "Projection" part of the name is redundant because
>>>> the argument type is an object derived from Projection. But I don't think
>>>> "add" is a very clear name anyway, so maybe something like
>>>> register(myproj,
>>>> "MyObs") would be better? We could have "add" as another alias to ease
>>>> the
>>>> transition from addProjection.
>>>
>>>
>>> Would the plan be to leave all three  (addProjection, register, add)
>>> functioning forever, or would one or two be obsoleted at some point?
>>
>>
>> I don't know about super-long-term, but in the short-term I would regard my
>> proposal as being for co-exiting synonyms. Arguably the ones with the
>> "projection" in the name are more suitable for internal Projection
>> implementation where the author needs to know what's going on under the
>> hood, while the "projection"-less variants are syntactic sugar for the
>> "casual" user who just wants to implement their analysis as quickly & easily
>> as possible.
>
> If we do not intend to keep the intermediate "add" around for
> super-long-term then I would suggest to not introduce it at all but go
> for "addProjection" and "register" only.

Ok, thanks! I was just thinking aloud... good feedback.

> Maybe we should also consider the context of booking/registering
> histograms, counters, etc., which will become more relevant once we
> have re-entrant histogramming. This uses a similar concept, not
> storing something as a member variable but registering it with a
> string instead. Are we happy with the parallel usage of
> bookHisto1D("name", ...) and register(myproj, "MyObs"), or should this
> be somewhat streamlined?

I had wondered this, but pushed it to the back of my mind. There is a 
bit of syntactic difference for what seem to be similar operations, but 
there are also a lot of operational differences in how members etc. are 
handled, so I don't really mind them being syntactically distinct. Using 
exactly the same "register()" function name for histograms might just be 
confusing, because it looks like they are being registered via exactly 
the same internal mechanism -- which would not be true. But my opinion 
is very malleable on this.

Thinking a bit further, since e.g. arrays of histograms are a useful 
thing in a way that arrays of projections are (usually) not, I don't see 
us eliminating histogram member pointers in the way that we did for 
projections. Unless David and Chris think this would be an elegant way 
to implement the sleight of hand needed on the multi-weight 
histogramming dev branch? You guys have a much better view of how the 
future of Rivet's histogramming interface will behave, so I hope you 
have an idea of what it would look like in an ideal world ;-)

Since I do think that good syntax, i.e. short, clear & natural, is an 
important way to attract and keep fickle users, this "cosmetic" stuff 
shouldn't be ignored. But very probably we can't see all the angles 
right now, so again we'll need to iterate and have a plan for backward 
compatibility and very gradual deprecation.

Andy

-- 
Dr Andy Buckley, Lecturer / Royal Society University Research Fellow
Particle Physics Expt Group, University of Glasgow