define more user-friendly interface

[goldingn]

currently the main model-fitting function is movement. This requires many pieces of data from the user:

movement(locations, coords, population, movement_matrix, model,  model.params = NULL, ...)

with required arguments:

• a vector locations (unclear what this needs to be)
• a data.frame coords of coordinates
• a vector population of populations
• a matrix movement_matrix of observed movements between locations
• a string model naming a model to use

And optional arguments:

• numeric vector model.params giving parameters corresponding to model.
• unspecified additional parameters ...

A simpler interface would be:

movement(movement_matrix, location_dataframe, model = gravity(), optim_options = list())

possibly with glm-like function interface:

movement(movement_matrix ~ location_dataframe)

with required arguments:

• movement_matrix being an object of class movement_matrix containing the observed movement between some or all locations in location_dataframe
• location_dataframe being an object of class location_dataframe containing all of the information in locations, coords and population as dataframe columns, each row being a different location.

and optional parameters

• model being a function to initialise a model of the named type. E.g. gravity() would return a list giving the name of the flux function (in this case gravity.flux) and default arguments such as starting parameters as a named numeric vector (in this case c(alpha = 1, beta1 = 0.6, beta2 = 0.3, gamma = 3)). This model initialiser and could take different arguments, e.g. gravity(params = c(0.5, 0.2, 0.1, 5)).
• optim_options being a named list of options to pass to optim

Existing functions could be modified to help users create the location_dataframe and movement_matrix objects, the *.flux functions could be unexported and their docs replaced with more model- (rather than code-) centric docs for these initialisation functions.

Finally, we could write generic print, plot, and summary methods for the objects returned by the initialisation functions (flux objects?) and the same models with optimised parameters. e.g.:

flux <- gravity(c(0.5, 0.2, 0.1, 5))
plot(flux)

and

m <- movement(obs ~ locs)
plot(m$flux)

Thoughts on this proposed interface?

[goldingn]

Sorry to shift the goalposts - could we please change the interface to the flux functions so that each parameter is a separate named argument?

I.e.:

flux <- gravity(theta = 0.5, alpha = 0.2, beta = 0.1, gamma = 5)

this would enable users to change only one of the arguments from its defaults, without having to write out the lot:

flux <- gravity(theta = 0.1)

This could work internally like this:

gravity  <- function(theta=0.01, alpha=0.06, beta=0.03, gamma=0.01) {
  params <- c(theta=theta, alpha=alpha, beta=beta, gamma=gamma)
  ans  <- list(params = params, flux = gravity.flux)
  class(ans)  <- 'flux'
  return(ans)
}

and if we need to pass these automatically we can do this:

params <- c(theta = 0.01, alpha = 0.06, beta = 0.03, gamma = 0.01)
fl <- do.call('gravity', params)

[KathrinTessella]

Just a quick summary what has been done so far: 1) combine the args 'locations, coords, population' into a single data frame object: see https://github.com/SEEG-Oxford/movement/pull/49 2) define the various flux models: see https://github.com/SEEG-Oxford/movement/pull/50 3) update the flux model interfaces: see https://github.com/SEEG-Oxford/movement/pull/56 4) adjust the code to incorporate the newly created flux models: see https://github.com/SEEG-Oxford/movement/pull/58

[KathrinTessella]

@goldingn : any further comments what do you want for the generic methods 'print', 'plot', and 'summary' for the flux objects (e.g. flux <- gravity(); print(flux); summary(flux) and plot(flux))?

[goldingn]

Looks great!

For now, could you please not define plot, define summary to give the same output as print, and define print to print the flux type and named parameters. E.g. something along the lines of:

print(flux)

  flux object for a gravity model with parameters:

      theta = 0.01
      alpha = 0.06
      beta  = 0.03
      gamma = 0.01

  see ?gravity for the model formulation and explanation of parameters

[KathrinTessella]

Defined the generic methods for print() and summary() on the flux objects as suggested above (see https://github.com/SEEG-Oxford/movement/pull/62)

[KathrinTessella]

@goldingn I believe the final task on this issue is to further adjust the interface to be called like: movement(movement_matrix ~ location_dataframe) Is that still wanted ?

[goldingn]

yes please!

[KathrinTessella]

The final tasks to update the interface using the formula 'movement_matrix ~ location_dataframe' has been addressed in pull request https://github.com/SEEG-Oxford/movement/pull/64.