# System configuration

# 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] "/tmp/RtmpmVNWMt/Rinst24627673cd7a/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.