Skip to contents

The study's definition files: read them, compare them, write them back

Source: R/spec_source.R
reload_from_spec.Rd

A study's definition is its folder's files: spec/ (the table and report workbooks, the ARD definition, the listing and figure workbook, the figure designs) and study.yml. tflplanner keeps a copy of them in its home, with a fingerprint of each file; open_study() reads the files that changed since, so an edit made directly in them (in Excel, by a script) is what the study opens with. A file that does not read (a sheet tflspec does not know, a broken row) stops nothing: the study opens as last saved, and cannot be saved until one of these is done.

Usage

reload_from_spec(study, home = tflplanner_home())

write_spec(study, home = tflplanner_home())

spec_status(study, home = tflplanner_home())

Arguments

study

A registered study's id, or an rtfstudy.

home

tflplanner's home.

Value

reload_from_spec() and write_spec(): the study (its spec says what was read). spec_status(): a data frame, file, status (same, changed, added, removed), size_was, size_now.

Details

  • reload_from_spec() reads every definition file and takes them in (after fixing them, or to take in workbooks copied into spec/ by hand). It fails with class tflplanner_spec_invalid (its problems the file, sheet, row and message of each) when they do not read.

  • write_spec() writes the files again from the study as last saved; the files it replaces are copied to spec/.rejected/ first.

  • spec_status() says which files changed since tflplanner last wrote or read them, without reading them.

Examples

# a home in the temporary folder: used in this R session only, nothing
# is written to your settings
old <- options(tflplanner.home = NULL)
setup_tflplanner(home = tempfile("tflplanner-home"))
#> The home /tmp/RtmpT9WaTi/tflplanner-home18ba34c46c36 is in the temporary folder: it is used in this R session only, not remembered for later ones.
#> tflplanner home: /tmp/RtmpT9WaTi/tflplanner-home18ba34c46c36
#> new studies go to: /tmp/RtmpT9WaTi/tflplanner-home18ba34c46c36/studies
# \donttest{
# (a few seconds: it writes the study's spec workbooks)
s <- create_study("ABC-101", title = "A phase 2 study")
spec_status("ABC-101")               # nothing changed outside tflplanner
#>                file status size_was size_now
#> 1         study.yml   same      376      376
#> 2     spec/data.yml   same     1825     1825
#> 3 spec/defaults.yml   same     1163     1163
#> 4      spec/toc.yml   same       13       13
s <- reload_from_spec("ABC-101")
# }
options(old)