Current status of API is unclear

[Datseris]

@kahaaga I've merged main (which is #168 ) into my branch that defines the encoding API and also implements it for histograms. Things remain unclear to me, mainly because discussions were spread across many different issues and PRs and I no longer remember where the information is supposed to be.

Is it correct that all main API functions start with the estimator types? This means that we have:

• entropy(e::Entropy, p::ProbEst, x, ...)
• probabilities(p::ProbEst, x, ...)
• probabilities_and_outcomes(p::ProbEst, x, ...)

But as far as I can tell, these are the only two functions that follow this appraoch of having first the type. The following functions have the different approach of having first input x, and then the probabilities type:

• outcome_space
• total_outcomes
• missing_outcomes
• outcomes

Can you please explain what is the overall plan? Should we make all functions follow the first or the second version in the order of arguments?

[kahaaga]

My opinion: we make all functions follow the first order. That is: type first, then the argument.

[Datseris]

ok I do this in a new PR

[Datseris]

@kahaaga and what do we do about the encode and decode functions? They were encode(χ, e::Encoding) before. Should the order be changed?

I have to admit I find it more natural to have encoding(element, encoding). Because it reads "encode this value using that encoding." The other way around it doesn't read naturally: encode, using this encoding, this value.

Which also makes me think, why did we change the probabilities interface to have the type first? For the entropies I got your argument: it made extending entropies to joint entropies natural. But does this argument carry over to probabilities? Notice that the Julia style guide says "put type first", but this is a bit missleading: this is for the cases that the type decides the return type, such as in rand(Int, x). In our case the estimator doesn't decide the return type, only the return value.

On the other hand, it would be good to have an idea of how in general the broader Julia community does this. Is the "algorithm deciding argument" before or after the input data? In JuliaDynamics overall it is first input data and then algorithm deciding argument. Eg. that's how it is done in RecurrenceAnalysis.jl or TimeseriesSurrogates.jl: surrogate(x, method). I could be in the wrong though, and everywhere else it is done the other way around. Let's try to collect at least a couple of examples from other repos?

[Datseris]

I've opened this: https://discourse.julialang.org/t/design-q-order-of-arguments-input-data-and-algorithm-type/91768

[kahaaga]

Good idea on consulting with the community!

I have to admit I find it more natural to have encoding(element, encoding). Because it reads "encode this value using that encoding." The other way around it doesn't read naturally: encode, using this encoding, this value.

Well, it depends on how you phrase it. Take encode(x, method::A). There's "encode x using method of type A", and there's "A-encode x". Both feels pretty natural to me.

I don't feel strongly about either option beyond the vararg-argument, but the vargarg-argument weights pretty strongly in my opinion. I've gone through several rounds of design proposal for the CausalityTools methods without coming up with anything reasonably developer-friendly, because without it, we're back to writing a bunch of specialized methods for all input argument combinations. This is a pain, is error-prone, hard to document and hard to debug.

A third option is to have the types as the first argument to methods that will never accept vargargs as the last argument. But how do we know if a method won't be extended with varargs later? In some cases it is obvious that it will never happen, but in other cases it is not so clear.

Which also makes me think, why did we change the probabilities interface to have the type first?

I think the reasoning was just "follow the same style everywhere". But since there is no established guidelines on the topic, we could also just decide on a style guide ourselves.

Anyways, we should see what the community thinks too.

I'll try to find some examples from well-established packages in the meanwhile.

[kahaaga]

Some examples from other packages with functionality for estimating some statistic from data (I'll fill this out as I investigate more)

StatsBase.jl

Implements different algorithms as a different function, and parameters as keyword arguments. They do knuths_sample and fisher_yates_sample, where we'd do sample!(Knuths(), args...) and sample(FisherYates(), args...).

Distributions.jl

Uses a similar type-based approach, where each distributions is its own type. They dispatch on type-first, then input. For example, fit_mle(dist::D, x), where D <: Distribution. However, here the return type is also of type D, so this again is not really comparable to our situation.

Distances.jl

Perhaps the best example of using the same approach as us: distance type first, then input data, and return type is not the same as the distance type. For example, pairwise(d::Distance, args...) returns a vector.