fn_gpsmart: Run GP-SMART for an input crime and input suspects
In Sophie-c-h/gpsmartr: Geographic Profiling - Suspect Mapping And Ranking Technique (GP-SMART) in R

View source: R/fn_gpsmart.R

fn_gpsmart

R Documentation

Run GP-SMART for an input crime and input suspects

Description

Calculates suspect variables relative to the input crime, calculates probability of crime per suspect activity location (node) within the user's input search radius, ranks suspects according to their highest probability activity node, and returns ranked suspects and (optionally) their activity nodes for mapping.

Usage

fn_gpsmart(
  input_crime,
  input_suspects,
  search_radius = 10,
  weights = NULL,
  return_node_predictions = FALSE
)

Arguments

`input_crime`	A data frame with 1 row and 16 columns, created by `fn_prepare_input_crime()`.
`input_suspects`	A data frame with 1 row per suspect activity node and 21 columns, created by `fn_prepare_suspect_data()`.
`search_radius`	The distance (in kilometres) around the input crime to search for suspect nodes. Suspects with nodes within this distance are shortlisted. The default is 10km.
`weights`	A list of 8 data frames, one per weighting variable (node attribute), specifying the weight to use for each value of each attribute for each input crime type. If `NULL`, the default, built-in weights will be used (see Details).
`return_node_predictions`	Logical. Whether to return per-node predictions for the shortlisted suspects, required as input for `fn_map_gpsmart_output()`.

Details

In calculating the probability of crime per suspect activity node, the function weights the node (adjusts the probability) based on its values across 7 attributes (weighting variables). The weighting variables are: frequency, recency, duration, behaviour similarity, location type similarity, daypart similarity, weekpart similarity and season similarity. The default (built in) weights were estimated using a New Zealand sample of offenders and activity locations as described in Curtis-Ham et al (2022). To create your own weights, use the built in list of data frames as a template, replacing only the weight values. (use gpsmartr.private:::node_weights_lookups to access the built in weights).
The function will return an error if there are no suspect nodes within the search radius.
Season variables are based on Southern Hemisphere.

Value

A list with four elements:

suspects_ranked: A data frame with n rows = n suspects with nodes within the search_radius of the input crime, ranked by their maximum predicted crime probability.
node_predictions: If return_node_predictions = TRUE, a data frame with n rows = n suspect nodes within search radius, including all node attributes and predicted crime probability per node; if return_node_predictions = FALSE, a character string "no node predictions".
input_crime: The data frame entered as input for fn_gpsmart(). It is included in the output for use in the fn_map_gpsmart_output() function.
search_radius: The search radius (in kilometres), entered as input for fn_gpsmart(). It is included in the output for use in the fn_map_gpsmart_output() function.

Author(s)

Sophie Curtis-Ham

References

Curtis-Ham S., Bernasco, W., Medvedev, O. N., & Polaschek, D. L. L (2022). 'A new geographic profiling method for mapping and ranking suspects in crime investigations: GP-SMART'. Journal of Investigative Psychology and Offender Profiling. https://doi.org/10.1002/jip.1585

Examples

## Not run: 
data(example_input_crime_raw)
data(example_input_suspects_raw)
fn_gpsmart(
  input_crime = fn_prepare_input_crime(example_input_crime_raw),
  input_suspects = fn_prepare_suspect_data(example_input_suspects_raw),
  search_radius = 10,
  return_node_predictions = FALSE
)

## End(Not run)

Sophie-c-h/gpsmartr documentation built on April 13, 2022, 5:51 p.m.