Skip to contents

Create a TTEPlan from a study specification

Source: R/tteplan_from_spec.R
tteplan_from_spec_and_registrystudy.Rd

Builds a TTEPlan with a full ETT grid (enrollments x outcomes x follow-up) from the parsed study specification and a pre-loaded RegistryStudy. Also stores each enrollment's treatment implementation details in the ETT data.table so they are available via plan[[i]]$treatment_impl.

Usage

tteplan_from_spec_and_registrystudy(
  study,
  candidate_dir_spec,
  candidate_dir_tteplan,
  candidate_dir_results,
  spec_version = NULL,
  project_id = NULL,
  n_skeleton_files = NULL,
  global_max_isoyearweek = NULL,
  period_width = 4L,
  check_skeletons = TRUE
)

Arguments

study

A RegistryStudy R6 object, typically loaded via registrystudy_load(). Owns the rawbatch and skeleton path candidates. A list MAY stand in for it, as the package tests do. The list MUST carry skeleton_files. Without a work_root, s1 reads data_meta_dir from it for its work directory. A list has no $assert_skeletons_consistent(), so pass check_skeletons = FALSE here and to $s1_generate_enrollments_and_ipw(). With global_max_isoyearweek = NULL and a first file named skeleton_<n>.qs2, the list also needs $load_skeleton().

candidate_dir_spec

Character vector of candidate directories that contain the spec YAML spec_vXXX.yaml. The first existing directory is used to locate the spec.

candidate_dir_tteplan

Character vector of candidate directories where tteplan.qs2 lives (or will be created by plan$save()).

candidate_dir_results

Character vector of candidate directories for the results BASE directory (without the version suffix – the plan appends spec_version internally).

spec_version

Optional character scalar like "v003" selecting the spec YAML. When NULL, read from spec$study$implementation$version.

project_id

Optional character scalar for display/logging. When NULL, read from spec$study$implementation$project_prefix.

n_skeleton_files

Optional integer: if not NULL, only the first n_skeleton_files files are used (for faster dev iterations). Stored on the plan as n_skeleton_files_limit so tteplan_load() can re-apply it after a host transfer.

global_max_isoyearweek

Administrative censoring boundary (isoyearweek string, e.g., "2023-52"). If NULL (default), auto-detected from max(isoyearweek) in the first skeleton file. Also runs tteplan_validate_spec() on that skeleton.

period_width

Integer, the width in weeks of the enrollment period (default: 4L). The same width sets each follow-up interval. Stored on the plan and passed through to TTEDesign.

check_skeletons

Logical (default TRUE). Run RegistryStudy$assert_skeletons_consistent() before reading any skeleton, so a half-rebuilt or stale skeleton store stops here rather than flowing into a TTE plan. It scans every sidecar in the skeleton directory, which on a large store is minutes over a network mount. Pass FALSE only for a dev iteration you do not intend to trust, typically alongside n_skeleton_files.

Value

A TTEPlan object with the full ETT grid, embedded registrystudy, and CandidatePath fields populated.

Details

It carries each enrollment's observation encoding and both arm tolerances from the spec into the ETT data.table. plan[[i]]$design reads them back onto a TTEDesign. See the observation contract section of tteplan_read_spec().

Directory-resolution fields (dir_tteplan_cp, dir_spec_cp, dir_results_cp) are stored on the plan as CandidatePath instances. Stage scripts (s1.R, s2.R, s3.R, s4_export.R) can then re-load the plan on any host with tteplan_locate_and_load() and call plan$save(), plan$s1_generate_enrollments_and_ipw(), etc. without re-specifying any paths.

See also

registrystudy_load(), tteplan_locate_and_load()

Other tte_spec: tteplan_apply_derived_confounders(), tteplan_apply_exclusions(), tteplan_excel_spec_summary(), tteplan_osf_text(), tteplan_read_spec(), tteplan_validate_spec()