Refine naming of "callbacks"

[m-mohr]

In the 3rd year planning concerns were raised that callback (inspired from JS) is not a well-known word in Python and R. We should either call it differently (in R and Python a function called from a function has no specific name, is just called "function") or add a glossary entry.

callback is not very well chosen anyway, because the function is not necessarily called once data is available, but immediately.

[mkadunc]

I believe there are two things to be named here:

1. the function itself as a type of referenceable entity, i.e. what do we call the executable component that can be repeatedly called/referenced from a process graph and that is itself represented by (part of) a process graph

   • this concept is very similar to what we call "process graph" elsewhere in openEO, e.g. in https://open-eo.github.io/openeo-api/draft/processreference/#run_process_graph ;
   • if you replace 'variables' with 'arguments', then the concept is very close to what we call "process" ;
   • i'm fine with using 'function' — that would be consistent with Javascript, R, Python etc.

2. the process parameter which expects a function as its value (callback in Javascript, f in R, function in Python). Here we either:

   1. decide to use the same name for all such parameters (seems to be what Javascript, Python and R do) — in this case I suggest using the name from 1; or
   2. choose the name for each process separately, based on the intent/role of the parameter within the process (what Java and .NET do) — our current processes already do that (we have reducer, overlap_resolver, process, expression ...)

[m-mohr]

1. Avoid exposing process graph to users: user-defined processes #161 is a very relevant issue. The question is whether we want users to know about process graphs or not. Currently, we expose our "code" as process graphs to users, but we may want to call it differently in the long run (e.g. process chain or algorithm or ...?). An issue with naming it function could be that it's not always just a single function, but could be a complex graph of processes again.
2. I'd go for 2ii as I like descriptive names. For most processes a single name would also fit, but for example the "overlap_resolver" is a case where it's not clear what the "callback" does in the context of the function.

So we need a solution for 1 (and #161).

[m-mohr]

It is relatively easy to replace callback in documentation, but it's still in the process graphs ("callback" property). Depending on the amount of changes we have for the API (looking especially at option 1 in #161 (comment)) we may replace it or not. Would prefer to not change it in the process graphs, but if we work heavily on the API anyway for consistency, then I'd probably also make the naming in the process graph consistent.

ToDos:

• Update documentation
• Replace "format": "callback" with "format": "xxx" (depends on Avoid exposing process graph to users: user-defined processes #161)
• Check whether the callback object should be renamed in process graphs

[aljacob]

Here again, I think it does not matter much, what it is called in the process graph, as this is not so relevant to the client user. The important thing is, that the client library user, can build graphs with callbacks in an easy manner (again building graphs, without necessarily being aware of the fact, that a graph is created in the background by the client implementation). What has to be clear is, that the user is aware of how the callback portion of the graph is evaluated and applied on the input data. Meaning he needs to know if a function is called e.g. on every pixel or collectively on the whole data-set or flattening/reducing along a specific dimension, e.g. temporal mean, kernel-function in spatial domain, minimum value of all values, or just a specific dimension...

For me again it is fine to call this concept differently in each client library/application as long as it something that a typical user of the specific client can relate to conceptually.

[m-mohr]

1. We are only speaking about the HTTP API description here. What the clients do is up to the clients.
2. The description how the callback is applied to the data is described in the processes. If the descriptions there are not sufficient, this is an issue for the processes repository. Currently, the processes are not completely consistent in this and probably need some work.

I'd conclude that in the API itself we just call it parametrized process graph (until we plan to go for #161). In the end it is really just a special type of process graph. For the API, that seems the best choice.

Clients can the call this however it fits best in their environment/community although the process descriptions will not adapt magically to use this term. Function or process seems to be the preferable options for the process descriptions. As we are always use processes, I guess I'll go with process in the descriptions.

Interestingly, we don't call UDFs UDPs ;-)