System dependency specification file

rfacts has strict system dependencies.

  • FACTS Linux engines (>= 6.2.4)
  • FLFLL (>= 6.2.4)
  • Mono (>= 5.20.1.19)

Before you can use rfacts to simulate trials in R, you must specify the paths to all these executable files in a CSV file. You can see an example CSV file at inst/example_paths.csv in the rfacts package source.

path <- system.file("example_paths.csv", package = "rfacts")
writeLines(readLines(path))
#> executable_type,facts_version,path,engine_name,param_set,param_type
#> mono,6.2.4,/PATH/TO/mono/mono-5.20.1.19/bin/mono,NA,NA,NA
#> mono,6.2.5,/PATH/TO/mono/mono-5.20.1.19/bin/mono,NA,NA,NA
#> flfll,6.2.4,/PATH/TO/flfll/prd/prior_versions/version_6.2.5/FLFLL.exe,NA,NA,NA
#> flfll,6.2.5,/PATH/TO/flfll/prd/prior_versions/version_6.2.5/FLFLL.exe,NA,NA,NA
#> engine,6.0.0.1,/PATH/TO/facts/engines/contin/6.0.0.1/contin.x,contin,NucleusParameterSet,1
#> engine,6.0.0.1,/PATH/TO/facts/engines/dichot/6.0.0.1/dichot.x,dichot,NucleusParameterSet,2
#> engine,6.0.0.1,/PATH/TO/facts/engines/multep/6.0.0.1/multep.x,multep,MultipleEndpointParameterSet,1
#> engine,6.0.0.1,/PATH/TO/facts/engines/tte/6.0.0.1/tte.x,tte,TTEDesignParameterSet,3
#> engine,6.0.0.1,/PATH/TO/facts/engines/aipf_contin/5.0.0.7/aipf_contin.x,aipf_contin,AIPFParameterSet,1
#> engine,6.0.0.1,/PATH/TO/facts/engines/aipf_dichot/5.0.0.7/aipf_dichot.x,aipf_dichot,AIPFParameterSet,2
#> engine,6.0.0.1,/PATH/TO/facts/engines/aipf_tte/5.0.0.9/aipf_tte.x,aipf_tte,AIPFParameterSet,3
#> engine,6.0.0.1,/PATH/TO/facts/engines/CRM/0.3.8.2/CRM.x,crm,CRMDesignParamSet,0
#> engine,6.2.5,/PATH/TO/facts/engines/contin/6.0.0.4/contin.x,contin,NucleusParameterSet,1
#> engine,6.2.5,/PATH/TO/facts/engines/dichot/6.0.0.4/dichot.x,dichot,NucleusParameterSet,2
#> engine,6.2.5,/PATH/TO/facts/engines/multep/6.0.0.4/multep.x,multep,MultipleEndpointParameterSet,1
#> engine,6.2.5,/PATH/TO/facts/engines/tte/6.0.0.4/tte.x,tte,TTEDesignParameterSet,3
#> engine,6.2.5,/PATH/TO/facts/engines/aipf_contin/6.0.0.4/aipf_contin.x,aipf_contin,AIPFParameterSet,1
#> engine,6.2.5,/PATH/TO/facts/engines/aipf_dichot/6.0.0.4/aipf_dichot.x,aipf_dichot,AIPFParameterSet,2
#> engine,6.2.5,/PATH/TO/facts/engines/aipf_tte/6.0.0.4/aipf_tte.x,aipf_tte,AIPFParameterSet,3
#> engine,6.2.5,/PATH/TO/facts/engines/CRM/6.0.0.4/CRM.x,crm,CRMDesignParamSet,0
#> engine,6.2.5,/PATH/TO/facts/engines/contin/6.0.0.4/contin.x,contin,SDBaseParameterSet,1
#> engine,6.2.5,/PATH/TO/facts/engines/dichot/6.0.0.4/dichot.x,dichot,SDBaseParameterSet,2

Required columns

  • executable_type: Must be “mono”, “flfll”, or “engine” to denote the general type of the executable.
  • facts_version: The version of FACTS with which this executable is compatible.
  • path: File path to the executable.
  • engine_name: For engines only. Name of the engine. Must be one of the engine types in the example CSV file at system.file("example_paths.csv", package = "rfacts").
  • param_set: For engines only. Parameter set designation listed in the XML code of FACTS files for that engine.
  • param_type: For engines only. Parameter type designation listed in the XML code of FACTS files for that engine.

Connecting rfacts to the system dependencies

To allow rfacts to find the CSV file above, you must set the RFACTS_PATHS environment variable. For a single R session, you can do this with Sys.setenv(RFACTS_PATHS = "path/to/file.csv"). To set RFACTS_PATHS permanently for all future sessions, open your .Renviron file with usethis::edit_r_environ() and add a line with RFACTS_PATHS=path/to/file.csv. Then, restart R so the changes take effect. Verify that you did this correctly by checking the value of the environment variable.

Sys.getenv("RFACTS_PATHS")
#> [1] "/Users/runner/work/_temp/Library/rfacts/example_paths.csv"

Check the system dependency information with rfacts_paths().

library(rfacts)
rfacts_paths()
#> # A tibble: 22 × 6
#>    executable_type facts_version path                    engin…¹ param…² param…³
#>    <chr>           <chr>         <chr>                   <chr>   <chr>   <chr>  
#>  1 mono            6.2.4         /PATH/TO/mono/mono-5.2… NA      NA      NA     
#>  2 mono            6.2.5         /PATH/TO/mono/mono-5.2… NA      NA      NA     
#>  3 flfll           6.2.4         /PATH/TO/flfll/prd/pri… NA      NA      NA     
#>  4 flfll           6.2.5         /PATH/TO/flfll/prd/pri… NA      NA      NA     
#>  5 engine          6.0.0.1       /PATH/TO/facts/engines… contin  Nucleu… 1      
#>  6 engine          6.0.0.1       /PATH/TO/facts/engines… dichot  Nucleu… 2      
#>  7 engine          6.0.0.1       /PATH/TO/facts/engines… multep  Multip… 1      
#>  8 engine          6.0.0.1       /PATH/TO/facts/engines… tte     TTEDes… 3      
#>  9 engine          6.0.0.1       /PATH/TO/facts/engines… aipf_c… AIPFPa… 1      
#> 10 engine          6.0.0.1       /PATH/TO/facts/engines… aipf_d… AIPFPa… 2      
#> # … with 12 more rows, and abbreviated variable names ¹​engine_name, ²​param_set,
#> #   ³​param_type

Use rfacts_sitrep() to verify that all the executables exist and are indeed executable. This vignette uses toy paths that do not actually exist. In your setup, if exists and is_executable are all TRUE, then your setup is configured correctly.

rfacts_sitrep()
#> # A tibble: 22 × 5
#>    executable_type facts_version exists is_executable path                      
#>    <chr>           <chr>         <lgl>  <lgl>         <chr>                     
#>  1 mono            6.2.4         FALSE  FALSE         /PATH/TO/mono/mono-5.20.1…
#>  2 mono            6.2.5         FALSE  FALSE         /PATH/TO/mono/mono-5.20.1…
#>  3 flfll           6.2.4         FALSE  FALSE         /PATH/TO/flfll/prd/prior_…
#>  4 flfll           6.2.5         FALSE  FALSE         /PATH/TO/flfll/prd/prior_…
#>  5 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/co…
#>  6 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/di…
#>  7 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/mu…
#>  8 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/tt…
#>  9 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/ai…
#> 10 engine          6.0.0.1       FALSE  FALSE         /PATH/TO/facts/engines/ai…
#> # … with 12 more rows

If you change RFACTS_PATHS, you need to call reset_rfacts_paths() or restart R in order for the changes to take effect.