feat: support multiple source datasets in one meta_adam (#174)

[yihui]

Summary

Closes #174 (scenario 3: one metadata object driving analyses that read from different source datasets — e.g. an AE summary from adae plus a lab box plot from adlb).

Previously meta_adam() held a single observation dataset, so multiple named observations were only ever subsets of one source. Multiple distinct source datasets were impossible.

API

meta_adam()'s observation/population arguments now accept datasets in the package's usual ";"-separated style (matching the semicolon-list convention used throughout). Each argument takes one of:

• a data frame — unchanged, backward compatible;
• a ";"-separated string of dataset names (e.g. "adae;adlb"), each retrieved with get();
• a named list of data frames.

When more than one dataset is supplied, the first is the primary dataset (kept in its own slot as the single source of truth) and the rest are registered in data_source.

define_population(from = ...) / define_observation(from = ...) select which registered dataset a term reads from. Defaults "population" / "observation" (resolve to the primary slots). The primary dataset's own name also resolves to the live slot, so it stays in sync with in-place edits (meta_add_total(), meta_split()).

Usage

adsl <- forestly_adsl
adae <- forestly_adae
adlb <- boxly_adlb

meta <- meta_adam(population = "adsl", observation = "adae;adlb") |>
  define_plan(plan) |>
  define_observation(name = "apat", group = "TRTA", subset = SAFFL == "Y", var = "AEDECOD") |>
  define_observation(name = "lb", group = "TRTA", subset = SAFFL == "Y", var = "AVAL", from = "adlb") |>
  ...
  meta_build()

meta |> collect_observation_record("apat", "apat", "rel")  # reads adae
meta |> collect_observation_record("apat", "lb", "alt")    # reads adlb

Backward compatibility

Data-frame observation/population and no from behave exactly as before. Full existing suite passes; the print() snapshot was updated for the new from column (with pinned console width) and _snaps was un-ignored so the reference ships in the package build.

Tests

test-independent-testing-multi-source.R covers the ";"-string and named-list forms, from routing to distinct datasets, primary-name resolution, unregistered-from / non-data-frame / unnamed-list errors, and the single-source backward-compat path.

🤖 Generated with Claude Code

[elong0527]

I am wondering about the motivation for introducing more than one dataset into a single metalite object, as this starts to expand the scope of metalite and may introduce additional questions.

Originally, a metalite object was designed to group similar analyses together, assuming they shared the same subject-level and observation-level data.

If analyses required separate observation data, the recommendation was to create multiple metalite objects to separate them (e.g., one metalite object for safety analysis and another for LB analysis).

The full CSR could then be compiled using a collection of metalite objects.

[LittleBeannie]

I am wondering about the motivation for introducing more than one dataset into a single metalite object, as this starts to expand the scope of metalite and may introduce additional questions.

Originally, a metalite object was designed to group similar analyses together, assuming they shared the same subject-level and observation-level data.

If analyses required separate observation data, the recommendation was to create multiple metalite objects to separate them (e.g., one metalite object for safety analysis and another for LB analysis).

The full CSR could then be compiled using a collection of metalite objects.

Thanks for sharing your insights! I agree with you that a list of multiple metalite objects serves our needs. However, using multiple metalite objects may require duplicate definitions. For example, the AE analysis and LAB analysis may share the same population_where. If we have one metadata object for AE and another for LAB, we would need to define the same population twice, which violates the "single-entry" principle.