The output of the movement() should be of class 'movement_model'

[KathrinTessella]

The output of movement (essentially an optimised ‘flux' object) should be of class ‘movement_model’.

[KathrinTessella]

@goldingn : going through my emails, I found this note you mentioned once. Do you still want this to be the case? This would imply to rename the 'optimisedmodel' -> 'movement_model'. Is that correct?

Similar, the predict.optimisedmodel() function is renamed to 'predict.movement_model()?

[goldingn]

Yes, that would be good. I think it would be a more intuitive name to users than optimisedmodel. Please go ahead and change all of these.

It would also be helpful to write a few sentences for the package helpfile, and the readme, outlining the classes and how the relate. If you could draft something and post here, I can edit it for you too put it in the docs?

[KathrinTessella]

@goldingn We are still using internally (unexported) the 'movementmodel' object. For the code maintenance, the two objects 'movementmodel' and the 'movement_model' as result from the movement() function can be quite confusing. Do we want to rename the unexported 'movementmodel' to sth different?

[goldingn]

Yes, please rename the old one.

Where is is used? Perhaps we can get rid of it altogether

[KathrinTessella]

I don't think we can delete it easily without much rework. It is the 'predictionModel' (called in line 76)

  # create the prediction model which is a movementmodel object
  predictionModel <- movementmodel(dataset=NULL, min_network_pop=50000, flux_model = flux_model, symmetric=FALSE)

which is passed throughout the code numerous times.

@goldingn Would 'prediction_model' be a suitable new name?

[goldingn]

Sure, sounds good to me.

I've just had a look through and I agree - renaming the class (and function to create it) to something sensible will be fine. I hadn't realised it was more than a wrapper.

I suppose in the line you mentioned it would be clearer and more consistent to have something like:

 # create the prediction model which is a movementmodel object
prediction_model <- makePredictionModel(dataset = NULL, min_network_pop = 50000, flux_model = flux_model, symmetric = FALSE)

where:

class(prediction_model)

[1] "prediction_model"

[KathrinTessella]

Sounds sensible.

[KathrinTessella]

@goldingn A first quick draft to update the "Usage" section of the readme for the new package

Usage

The most common use of the package is to parameterize a movement model based on observed population movements, and then use this model to predict de novo population movements.

m <- movement(location_data ~ observed_movement, model = radiationWithSelection())

Where location_data is a location_dataframe object containing location, population, x and y columns corresponding to location ids, coordinates (x and y) and populations, respectively. observed_movement, a movement_matrix objects, is a square matrix of observed population movements between the location_ids. The model is a flux object which represents a specific movement model. Current supported movement models are radiation with selection, original radiation, gravity, gravity with distance, intervening opportunities and uniform selection.

This returns an movement_model object which can be used by predict() to predict population movements from a RasterLayer, or a dataframe formatted as location_dataframe above.

prediction <- predict(m, raster)
prediction <- predict(m, location_data)

[goldingn]

Great, thanks! Here's an edited version to stick up:

Usage

The most common use of the package is to parameterize a movement model based on observed population movements, and then use this model to predict de novo population movements.

Code to fit such a model might look like this:

m <- movement(observed_movement ~ location_data, model = radiationWithSelection())

where observed_movement is a movement_matrix object containing observations about movements between pairs of locations, location_data is a location_dataframe object containing the coordinates and populations of those locations, and radiationWithSelection() creates a flux object, representing the type of movement model to by fitted. Current supported movement models are: radiation with selection, original radiation, gravity, gravity with distance cutoff, intervening opportunities and uniform selection.

The movement model fits the parameters of the specified movement model, and returns a movement_model object. This object can be plotted, or used to predict to populations movements to new location_dataframe object, or even a RasterLayer object giving populations in each cell:

plot(m)
prediction <- predict(m, location_data)
prediction <- predict(m, raster)

[KathrinTessella]

@goldingn For the package helpfile I copied your edit version of the 'usage' readme section as a '@note' statement

#' @title Modelling and Analysing Movement Data for Epidemiology
#'
#' @description Movement of humans and animals has a crucial role in the epidemiology of a
#' number of diseases. Movement data is increasingly available to
#' epidemiologists and its incorporation in models and maps of disease is
#' increasingly popular. This package is a collaborative effort to improve our
#' ability to analyses movement data and to build and apply epidemiological
#' movement models.
#'
#' @docType package
#' @name movement-package
#' 
#' @note
#' The most common use of the package is to parameterize a movement model based on observed 
#' population movements, and then use this model to predict _de novo_ population movements.
#' Code to fit such a model might look like this:
#' 
#' \code{m <- movement(observed_movement ~ location_data, model = radiationWithSelection())}
#' 
#' where \code{observed_movement} is a \code{movement_matrix} object containing observations 
#' about movements between pairs of locations, \code{location_data} is a \code{location_dataframe} 
#' object containing the coordinates and populations of those locations, and \code{radiationWithSelection()}
#' creates a \code{flux} object, representing the type of movement model to by fitted. Current supported 
#' movement models are: \code{\link{radiationWithSelection}}, \code{\link{originalRadiation}}, 
#' \code{\link{gravity}}, \code{\link{gravityWithDistance}}, \code{\link{interveningOpportunities}} and
#' \code{\link{uniform selection}}.
#' 

#' The \code{\link{movement}} model fits the parameters of the specified movement model, and returns a 
#' \code{movement_model} object. This object can be plotted, or used to predict to populations movements 
#' to new \code{location_dataframe} object, or even a \code{RasterLayer} object giving populations in 
#' each cell.
#' 
#' @examples
#' plot(m)
#' prediction <- predict(m, location_data)
#' prediction <- predict(m, raster)

[goldingn]

Cool!

I expect the example will fail though, it'll need all the objects to be created and then the movement() call added, no?

[KathrinTessella]

true! The example is still an open issue (see https://github.com/SEEG-Oxford/movement/issues/69). Best to remove the '@example' for now and we could add it back later if wanted.

[goldingn]

Yup, so long as there is an example in the function docs (eventually) I don't think we need one in the package doc. The note should be sufficient, particularly with those links in place.

[KathrinTessella]

renaming has been completed and documentation has been updated.