compute_distance {CRTspat}

Compute distance or surround values for a cluster randomized trial

Description

compute_distance computes distance or surround values for a cluster randomized trial (CRT)

Usage

compute_distance(
  trial,
  distance = "nearestDiscord",
  scale_par = NULL,
  auxiliary = NULL
)

Arguments

trial

an object of class "CRTsp" or a data frame containing locations in (x,y) coordinates, cluster assignments (factor cluster), and arm assignments (factor arm).

distance

the quantity(s) to be computed. Options are:

"nearestDiscord"	distance to nearest discordant location (km)
"distanceAssigned"	distance to the nearest pixel in the assigned cluster (km)
"disc"	disc
"kern"	kernel-based measure
"hdep"	Tukey half space depth
"sdep"	simplicial depth

scale_par

scale parameter equal to the disc radius in km if distance = "disc" or to the standard deviance of the kernels if distance = "kern"

auxiliary

"CRTsp" object containing external cluster and or arm assignments.

Details

For each selected distance measure, the function first checks whether the variable is already present, and carries out the calculations only if the corresponding field is absent from the trial data frame.

If distance = "nearestDiscord" is selected the computed values are Euclidean distances assigned a positive sign for the intervention arm of the trial, and a negative sign for the control arm.

If distance = "distanceAssigned" is selected the computed values are Euclidean distances to the nearest pixel in the auxiliary "CRTsp" object.

If distance = "disc" is specified, the disc statistic is computed for each location as the number of locations within the specified radius that are in the intervention arm (Anaya-Izquierdo & Alexander(2020)). The input value of scale_par is stored in the design list of the output "CRTsp" object. Recalculation is carried out if the input value of scale_par differs from the one in the input design list. The value of the the surround calculated based on intervened locations is divided by the value of the surround calculated on the basis of all locations, so the value returned is a proportion.

If distance = "kern" is specified, the Normal curve with standard deviation scale_par is used to simulate diffusion of the intervention effect by Euclidean distance. For each location in the trial, the contributions of all intervened locations are summed. As with distance = "disc", when distance = "kern" the surround calculated based on intervened locations is divided by the value of the surround calculated on the basis of all locations, so the value returned is a proportion.

If either distance = "hdep" or distance = "sdep" is specified then both the simplicial depth and Tukey half space depth are calculated using the algorithm of Rousseeuw & Ruts(1996). The half-depth probability within the intervention cloud (di) is computed with respect to other locations in the intervention arm (Anaya-Izquierdo & Alexander(2020)). The half-depth within the half-depth within the control cloud (dc) is also computed. CRTspat returns the proportion di/(dc + di).

If an auxiliary auxiliary "CRTsp" object is specified then either distanceAssigned or nearestDiscord (the default) is computed with respect to the assignments in the auxiliary. If the auxiliary is a grid with design$geometry set to 'triangle', 'square' or 'hexagon' then the distance is computed to the edge of the nearest grid pixel in the discordant arm (using a circular approximation for the perimeter) rather than to the point location itself.

Value

The input "CRTsp" object with additional column(s) added to the trial data frame with variable name corresponding to the input value of distance.

Examples

{
# Calculate the disc with a radius of 0.5 km
exampletrial <- compute_distance(trial = readdata('exampleCRT.txt'),
distance = 'disc', scale_par = 0.5)
}