In raubreywhite/fhi: FHI Convenience Functions

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)

Bounded context for the dashboards project

The fhi package contains a number of functions that span the dashboards project.

As mentioned in the umbrella documentation, we expect that for the automated analysis ANALYSIS, there is an R package called ANALYSIS and the following folder structure exists on the system:

/MASTERFOLDER/data_raw/
  |-- ANALYSIS/
/MASTERFOLDER/data_clean/
  |-- ANALYSIS/
/MASTERFOLDER/data_app/
  |-- ANALYSIS/
/MASTERFOLDER/results/
  |-- ANALYSIS/

It is important to note that we generally do not use MASTERFOLDER in production settings.

fhi::DashboardInitialiseOpinionated

fhi::DashboardInitialiseOpinionated is always the first function called in a RunProcess.R file. Its main purpose is to properly initialise the environment fhi::PROJ.

for(i in names(fhi::PROJ)){
  print(sprintf("%s=%s",i,fhi::PROJ[[i]]))
}

fhi::PROJ$PRODUCTION_NAME contains a list of all the computer names that are consided to be production machines.

fhi::PROJ$COMPUTER_NAME is this current computer's name. It is obtained from the file /tmp/computer.

fhi::PROJ$IS_PRODUCTION is used in the getter function fhi::DashboardIsProduction. This is primarily used to choose the appropriate mailing lists (i.e. production computer sends emails to the customers, test/development computers send emails to the developers).

fhi::DashboardIsProduction()

fhi::PROJ$IS_DEV is used in the getter function fhi::DashboardIsDev. It is flagged to TRUE if the script is called from within RStudio (i.e. a development environment). All automated analyses check for existing results before running (and exit if existing results are found). This getter function is generally used decide if we should delete existing results (i.e. if we are developing code then we don't care if there are existing results, we just want to see what the new version of the results looks like).

fhi::DashboardIsDev()

fhi::PROJ$IS_INITIALISED is used in the getter function fhi::DashboardIsInitialised. If the project is initialised, then you know that you are working in the integrated umbrella dashboards environment. This function is not used very often.

fhi::DashboardIsInitialised()

Here we now create the necessary file structure:

# Create an empty package
pkg <- file.path(tempdir(check=TRUE),"ANALYSIS")
usethis::create_package(pkg,open=F)

# Create the data/results/src folders
tmpdir <- tempdir(check=TRUE)
dir.create(file.path(tmpdir,"data_raw"))
dir.create(file.path(tmpdir,"data_clean"))
dir.create(file.path(tmpdir,"data_app"))
dir.create(file.path(tmpdir,"results"))

# Create the `ANALYSIS` specific folders inside
dir.create(file.path(tmpdir,"data_raw","ANALYSIS"))
dir.create(file.path(tmpdir,"data_clean","ANALYSIS"))
dir.create(file.path(tmpdir,"data_app","ANALYSIS"))
dir.create(file.path(tmpdir,"results","ANALYSIS"))

# Initialise
fhi::DashboardInitialiseOpinionated("ANALYSIS",
                                    STUB=tmpdir, 
                                    PACKAGE_DIR=pkg, 
                                    FORCE_DEV_PACKAGE_LOAD=TRUE
                                    )

# Lets see how `fhi::PROJ` has changed:
for(i in names(fhi::PROJ)){
  print(sprintf("%s=%s",i,fhi::PROJ[[i]]))
}

We can see that we have a few new extra variables:

fhi::PROJ$NAME is the name of the automated analysis.

fhi::PROJ$STUB is the master folder containing all of the data folders.

We can also see how the getter functions have changed:

# Hopefully not!
fhi::DashboardIsProduction()

# This one is a little special, because we used the flag `FORCE_DEV_PACKAGE_LOAD=TRUE`
fhi::DashboardIsDev()

# Obvious
fhi::DashboardIsInitialised()

fhi::DashboardFolder

Now that we have initialised our project, we need to access folder and datafiles. fhi::DashboardFolder is our function for this.

fhi::DashboardFolder("data_raw")
fhi::DashboardFolder("data_raw","myfile.txt")

fhi::DashboardMsg

According to the code style guidelines we do not use print. We instead use message, warning, and stop.

fhi::DashboardMsg is a stylised version of message, warning, and stop. It prints the requested message with a timestamp, computer name, analysis name, and a traceback of system calls. This is useful in log files.

MyFirstFunction <- function(d){ fhi::DashboardMsg("Important message!")}
MySecondFunction <- function(a=2){ MyFirstFunction(d=4) }
MyThirdFunction <- function(){ MySecondFunction() }
MyThirdFunction()