[Discussion/Notes] Provide Formula Interface

[humanfactors]

I've been doing some work on providing a simple formula interface to FIPS https://github.com/humanfactors/FIPS/tree/formula-proposal-interface. The logic of providing this interface is twofold:

1. Users can more readily adjust what the predicted latent variable is from the outset of model simulation (e.g. provided below);
2. It is more transparent to the users how our latent pred_vars are calculated, and what variable they should index

The prototype I've hacked together is far from complete or perfect. Currently the general interface is something like the following:

TPM.simulation.results = FIPS_simulate(
  FIPS_df = simulated.dataframe, # The FIPS_df
  modeltype = "TPM",         # three process model
  pvec = TPM_make_pvec(),      # parameter vector
  formula = alertness_with_w ~ s + c + u + w
  )

Like any big change I do want to minimize issues with legacy code. I envision that this formula argument will be optional, with the previous defaults being placed in when the user supplies no argument (that is how it currently works). However, in writing the basic logic for this feature, I have come across a few issues:

• Currently, the FIPS_Simulation class is assigned after the main loop of each of the models

  FIPS/R/simulation_threeprocessmodel.R

  Line 300 in ab1da48

  dat <- FIPS_simulation(dat, modeltype = "TPM", pvec = pvec, pred_stat = "alertness", pred_cols = TPM_cols)

  The issue with this approach is that attributes need to be continuously added to the object within the FIPS_Simulate function. This creates a lot of noise, and you end up changing object attributes in helper functions down the line:

  FIPS/R/formula_interface_rlang.R

  Lines 28 to 32 in 6e2ca5b

  	add_formula_vector <- function(.FIPS_sim, pred_vector, pred_name) {
  	.FIPS_sim[,pred_name] = pred_vector
  	attr(.FIPS_sim, "pred_cols") = c(attr(.FIPS_sim, "pred_cols"), pred_name)
  	return(.FIPS_sim)
  	}

• Ideally, we are setting all attributes like pred_stat at the time we create the object.
• What I'm thinking is that the main loops for the model functions should effectively do nothing but be similar to a model.frame whereby it returns only the essential elements for the model.
• We then will need constructor functions for each model type (e.g., FIPS_simulate_TPM) and these are called in the FIPS_simulate function. These functions will take in the arguments like formula all the data etc., and then produce the required object. The added benefit is that we simplify the role of the main loops.
• This will have side-effects for the plotting functions which will need to be examined, and likely also for validation.
• The only issue I have is how we might add in help for the formula, given it's model depdendent.

In any case, this is my notes from late on a Friday, so when I get round to implementing this Monday I can remember what the hell I was thinking!!! @lukestrickland

[humanfactors]

Currently we now have full formula support for TPM (d76aaf2) and Unified model (bc2fe36) with internal documentation (b57cd20).

You can see an internal use of the process_bmm_formula in simulation_unifiedfatiguemodel.R. This ensures backwards compatibility for when no model_formula is provided.

FIPS/R/simulation_unifiedfatiguemodel.R

Lines 179 to 181 in b57cd20

	if (is.null(model_formula)) {
	dat = process_bmm_formula(dat, fatigue ~ s + I(pvec["kappa"]) * c, pvec)
	}

Associated unit tests showing some usage can also be seen:

FIPS/tests/testthat/test-FIPS_formula_interface.R

Lines 4 to 9 in b57cd20

	tpmrun_sc = FIPS_simulate(simulation_df, "TPM", TPM_make_pvec(), model_formula = s_c_fatigue ~ s + c)
	expect_true(get_FIPS_pred_stat(tpmrun_sc) == "s_c_fatigue")
	expect_true(attr(tpmrun_sc, "simmed"))
	expect_equal(
	tpmrun_sc$s_c_fatigue, (tpmrun_sc$c + tpmrun_sc$s)
	)

I've manually checked and all plotting function seem to still work as intended. However, there is a chance of new bugs with 0.2.0 release.

I will merge this into Master along with website (to support #11).