Assign a study group to each file with an LLM — data_group

Classifies every file in a repository into a study group from its path (folder + name) context, so a multi-study repository can be split into study-<group>/ directories (used by psychds_check). Group codes follow datacheck's scheme: ex1, ex2a, pilot1, ... . Every file resolves to exactly one study – there is no "shared" group. The only files that stay collection-level (never grouped, group left NA) are the root README and the root ro-crate-metadata.json (see .data_doc_role()), which callers must exclude BEFORE calling this function (see data_check.R). Only meaningful with an LLM for the residual cases the deterministic passes leave unresolved; callers get a fully deterministic grouping when llm_use(FALSE).

Usage

data_group_llm(
  files,
  model = llm_model(),
  params = list(),
  batch_size = .data_check_llm_batch,
  paper = NULL
)

Arguments

files: a data.frame of files (needs file_path or file_name; an optional data_type column limits which files are sent to the model – see Details)
model: the LLM model name
params: a named list passed to llm()
batch_size: number of files per LLM call

Value

a data.frame with group and referenced_by columns (one row per input file, same order) and "model"/"roster"/"roster_check"/ "unresolved" attributes, or NULL only when files is empty/NULL. Every placeable file resolves to a real study group – there is no "shared" value and no partial-failure NULL return.

Details

Only files that will actually be analysed or placed (data, documentation, code, materials) are sent to the model; every one of them must end up with a real study code – a materials or documentation file reused across multiple studies is still assigned to exactly ONE owning study (whichever the deterministic passes or the model placed it in first); every other study that reuses it gets a reference recorded separately (see referenced_by in data_check.R), not a second group membership. Paths that name their study outright ("Experiment 1/", "study2a_data.csv") are grouped by a deterministic regex first and skip the model entirely; LLM-returned codes are normalized and validated against the scheme, so a malformed code can never become a study directory name. The sent files are batched (see .data_check_llm_batch) so large repositories do not exceed the model's request/output limits.

Examples

if (FALSE) { # \dontrun{
# needs an LLM (see llm_use())
files <- local_files(demofile("repo"), recursive = TRUE)
data_group_llm(files)
} # }