read_events: hidden method args make session filtering look harder than it is

[bbuchsbaum]

Summary

bidser::read_events dispatches via UseMethod(), so the public signature surfaced by autocomplete, ?read_events, and tooling like rpeek sig is just function(x, ...). The actual filtering arguments — subid, task, run, session — only appear on the read_events.bids_project method body, and users typically don't read method source.

The visible effect: callers write defensive post-filtering instead of passing the args that are already there. For example, I wrote this in a script today:

tabs <- bidser::read_events(proj, subid = subject_id, task = TASK)
if (".session" %in% names(tabs))
  tabs <- tabs[as.character(tabs$.session) == SESSION, ]

…when the right call is simply:

tabs <- bidser::read_events(proj, subid = subject_id, task = TASK, session = SESSION)

The same point applies to read_confounds, read_func_scans, read_preproc_scans — all generics with function(x, ...) signatures whose useful filtering args live on the method.

Suggestion

The minimal, non-breaking fix is to document the dispatched args on the generic's roxygen. Concretely:

1. Add @param subid, @param task, @param run, @param session (and @param ...) to the generic's roxygen block, so the help page and IDE autocomplete surface them.
2. Optionally, lift the args onto the generic itself:

   read_events <- function(x, subid = ".*", task = ".*", run = ".*",
                           session = ".*", ...) UseMethod("read_events")

   This is purely additive — existing methods continue to receive them via ....

A nice-to-have, but breaking: renaming the metadata columns .session / .run / .subid / .task / .file to plain session / run / etc. The . prefix forces backtick-quoted column references in dplyr and trips up names()-based membership checks. If a 1.0 release is on the horizon, worth bundling there.

Repro

?bidser::read_events       # only `x` and `...` documented
formals(bidser::read_events)  # function (x, ...)

vs. the actual method:

formals(bidser:::read_events.bids_project)
# $x ; $subid = ".*" ; $task = ".*" ; $run = ".*" ; $session = ".*" ; $... 

Happy to send a PR for the documentation-only fix if useful.

[bbuchsbaum]

Adding a second, sharper example from the same script: read_confounds and read_events disagree on metadata-column naming.

• read_events.bids_project returns .subid, .task, .run, .session, .file (dot-prefixed)
• read_confounds.bids_project returns participant_id, task, run, session (bare)

Both are "list one row per (subject, task, run, session) with a nested data tibble" generics — they should agree. The practical consequence is exactly the kind of defensive code that signals API friction:

# I wrote this because I remembered .run from read_events and wasn't sure
# whether read_confounds used the same convention. It turns out it doesn't.
run_id <- if ("run" %in% names(confounds)) confounds$run else confounds$.run
nuisance <- lapply(confounds$data[order(as.integer(run_id))], ...)

The right call is just confounds$run — but a user can't know that without reading both method bodies.

Suggestion

Pick one convention across all the read_* nesters (read_events, read_confounds, anything similar) and align them. Bare names (run, session, …) are friendlier for downstream dplyr code; dot-prefixed (.run, .session, …) marks them as bidser-injected metadata at the cost of needing backticks.

I'd vote bare for new code + a deprecation cycle on read_events that returns both run and .run for one release, then drops the dotted form. Happy to PR if you want it done that way.

(Folding this into the same issue rather than opening a new one — both observations are the same underlying theme: cross-reader API consistency.)