Create or update a "CRTsp" object

CRTsp coerces data frames containing co-ordinates and location attributes into objects of class "CRTsp" or creates a new "CRTsp" object by simulating a set of Cartesian co-ordinates for use as the locations in a simulated trial site

Usage

CRTsp(
  x = NULL,
  design = NULL,
  geoscale = NULL,
  locations = NULL,
  kappa = NULL,
  mu = NULL,
  geometry = "point"
)

Arguments

x

an object of class "CRTsp" or a data frame containing locations in (x,y) coordinates, cluster assignments (factor cluster), and arm assignments (factor arm). Optionally specification of a buffer zone (logical buffer); any other variables required for subsequent analysis.

design

list: an optional list containing the requirements for the power of the trial

geoscale

numeric: standard deviation of random displacement from each settlement cluster center (for new objects)

locations

integer: number of locations in population (for new objects)

kappa

numeric: intensity of Poisson process of settlement cluster centers (for new objects)

mu

numeric: mean number of points per settlement cluster (for new objects)

geometry

with valid values 'point' (the default, corresponding to point locations), 'triangle', 'square' and 'hexagon' corresponding to grids constructed from pixels of regular polygons.

Value

A list of class "CRTsp" containing the following components:

design	list:	parameters required for power calculations
geom_full	list:	summary statistics describing the site
geom_core	list:	summary statistics describing the core area (when a buffer is specified)
trial	data frame:	rows correspond to geolocated points, as follows:
	x	numeric vector: x-coordinates of locations
	y	numeric vector: y-coordinates of locations
	cluster	factor: assignments to cluster of each location
	arm	factor: assignments to "control" or "intervention" for each location
	nearestDiscord	numeric vector: Euclidean distance to nearest discordant location (km)
	buffer	logical: indicator of whether the point is within the buffer
	...	other objects included in the input "CRTsp" object or data frame

Details

If a data frame or "CRTsp" object is input then the output "CRTsp" object is validated, a description of the geography is computed and power calculations are carried out.

If geoscale, locations, kappa and mu are specified then a new trial dataframe is constructed corresponding to a novel simulated human settlement pattern. This is generated using the Thomas algorithm (rThomas) in spatstat.random allowing the user to defined the density of locations and degree of spatial clustering. The resulting trial data frame comprises a set of Cartesian coordinates centred at the origin.

Examples

{# Generate a simulated area with 10,000 locations
example_area = CRTsp(geoscale = 1, locations=10000, kappa=3, mu=40)
summary(example_area)
}
#> ===============================CLUSTER RANDOMISED TRIAL ===========================
#> 
#> Summary of coordinates
#> ----------------------
#>         Min.   : 1st Qu.: Median : Mean   : 3rd Qu.: Max.   :
#>       x -4.85    -2.62    -0.02     0.00     2.52     5.15   
#>       y -4.88    -2.44    -0.02     0.00     2.37     5.12   
#> 
#> Total area (within  0.2 km of a location) :  106 sq.km
#> Total area (convex hull) :  99.7 sq.km
#> 
#> Locations and Clusters
#> ----------------------                                          -                        
#> Coordinate system                      (x, y)                        
#> Locations:                                                      10000                        
#> Available clusters (across both arms)                           Not assigned                        
#> No randomization          -                        
#> No power calculations to report          -