# Compute distance or surround values for a cluster randomized trial

`compute_distance.Rd`

`compute_distance`

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

## 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) `"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"`

## 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`

.

## 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 = "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).

## Examples

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