move `api` argument to a package wide option, replace by enum. Envion: `source` argument for switching to parquet as a datasource.

[PietrH]

Currently, all functions in v2.3-beta and upwards have an api argument that you can use to select the source of the data, either a local database connection (on Rstudio: api = FALSE) or the web api via OpenCPU (api = TRUE).

There is the future plan of supporting a third source, which will allow unauthenticated access to open data. This is the first reason to change this argument over before a large scale public release. This data will be published as a static parquet file that will be refreshed on a stable interval (hourly? daily?) via a dump.

We should switch this source selecting argument to an enum, either retaining the argument name api = c(NULL,"opencpu"), or switching to something else like source = c("local","opencpu","parquet")

consider switching it to a option wide option, setting the api argument is contextually distant from the other arguments in most functions. And you'd generally only switch it on a per session basis, not on a by function basis: if you have access to a local database connection, that connection would be preferred.

---

Update 20250822

Had a discussion with Peter.

There is two variables:

• source: where does the data come from, currently only the etn database, in the future, parquet open data, ...
• protocol: how did I get it : either a local database connection, or via the opencpu api

Protocol

protocol: currently to use the opencpu api or not, most users don't need to bother with this. So the package can detect if the local database is available .onLoad and decide that way for all functions going forward. If a poweruser wants to change this anyway, they can change a system environemental variable to force it: ETN_PROTOCOL

.onLoad <- function(libname, pkgname) {
  # Package options
  op <- options()
  op.etn <- list(
    etn.protocol = "opencpu",
    etn.opencpu_url = "https://opencpu.lifewatch.be/library/etnservice/R"
  )
  toset <- !(names(op.etn) %in% names(op))
  if (any(toset)) options(op.etn[toset])

There is also the options package: https://dgkf.github.io/options/

Source

source is different in that it's closer to users, and will have different options for different functions. The first will be detections: get_acoustic_detections(protocol = c("parquet", "database")) to switch between parquet (or opendata) and the database to get detections from. The first option should always be the one where the users needs the least permissions for.

If there is ever an open rest api, this would become a source, since it'll return different things than opencpu. If opencpu is ever replaced by a different api that connects to the database directly, that would be a different protocol.

[PietrH]

Is opencpu descriptive enough? Maybe api will do just fine? Users don't need to know the underlying technology, and if we change over to a different restful api it can be placed behind the same argument making any future transitions more seamless.

[PietrH]

Relevant tidy design principle: https://design.tidyverse.org/enumerate-options.html

[peterdesmet]

Personally, I prefer the value of opencpu over api, since it is more descriptive for debugging and communication. E.g. imagine if we change the behaviour of the value api from OpenCPU to a rest API, but users still have the old version of the etn package. Then using source = "api" would suddenly fail. At least if the value was source = "opencpu" we would immediately know why it fails (i.e. opencpu not being supported).

But it's a minor benefit and there might be advantages to using the value api.

[PietrH]

I think you are right that we should avoid using api since we plan to support multiple. However, I think we should pick terms that will cause the least confusion for users. And once a an enum is used for a certain source, it really shouldn't ever be used for a different source.

I think opencpu will be unfamiliar to most users. Which I why I didn't propose it. I also foresee parquet becoming an option.

I haven't come up with a solution on how to name the data sources in a way that is easy to comprehend if you are unfamiliar with the ETN data structure.. local-db, remote-db, open-data ?

[peterdesmet]

I think we might have to call it protocol rather than source. For users, any proposed values will be new to them, so I especially want to make sure that the INBO/VLIZ group that maintains ETN can understand the values. They are already familiar with terms such as parquet, opencpu, odbc.

[PietrH]

Still I'd like it to be as intuitive as possible.

In the current design these enums occur in all functions, I wonder if we wouldn't be better off placing it in a package wide option instead. By placing the enum further away from users, especially beginners, they will cause less confusion at the cost of lower discoverability.

I like source because there is no guarantee that the different protocols will return exactly the same values, as not all of the protocols pull from the same datasource (some use dumps).

[peterdesmet]

Package-wide makes sense to me, though it might make it a bit harder to test/switch.