SpawAggregate: Create and describe spatially weighted survey estimates for...
In spacom: Spatially Weighted Context Data for Multilevel Modelling

Description Usage Arguments Details Value Author(s) Examples

This step-2 function should be used to create spatially weighted context data when contextual indicators are aggregate estimates derived from available micro-level survey data. Aggregation functions can be user-defined or chosen among predefined options, which include indicators of central tendency (e.g., spatially weighted mean), dispersion (e.g., spatially weighted standard deviation) and inter-group variability (e.g., spatially weighted Gini coefficient for group inequality). Point estimates can be adjusted by user-defined design weights. Descriptive confidence intervals are computed by way of an ad hoc bootstrap resampling procedure.

SpawAggregate(contextual.data,
 context.id,
 contextual.names,
 contextual.weight.matrices=NULL,
 nb.resamples = 1000,
 aggregation.functions = "weighted.mean",
 confidence.intervals = 0.95,
 design.weight.names = NULL,
 sample.seed = NULL,
 additional.args = NULL,
 verbose = TRUE)

`contextual.data`	A `data.frame` consisting of micro-level data to generate contextual indicators by aggregation and containing a column named `context.id` with the context ID variable. This is an individual level dataframe. The data must be numeric (`logical`, `integer`, or plain `numeric`). There must not be any missing values, `NaN`s, `NULL`s or `NA`s.
`context.id`	The name of the context ID variable. This variable allows matching contextual units from different data sets (`contextual.data`, `contexutal.weight.matrix`). Values can by of any type but need to be defined consitently across data sets.
`contextual.names`	A `list` of names of contextual variables to be aggregated.
`contextual.weight.matrices`	A `list` of weights to be applied to each variable specified in `contextual.names`. A weight may be a weights matrix as, for instance computed by `WeightMatrix`, or `NULL`, in which case the corresponding contextual variable is not weighted. If only one weight is defined (instead of a list) it is applied to all contextual variables. Defaults to `NULL`, which means that none of contextual indicators are weighted.
`nb.resamples`	A number of resamples to be evaluated. By default set to 1000.
`aggregation.functions`	A `list` of aggregation functions. Functions take either 1 argument in which case the corresponding individual design weight is `NULL`, 2 arguments in which case the second argument is taken from the corresponding individual design weight. Defaults to `"mean"`.
`confidence.intervals`	A `vector` of confidence intervals. Defaults to `0.95` which corresponds to 95 %.
`design.weight.names`	a `list` of optional design weights at the individual level used for aggregation (for example, for a weighted mean). List must have same length as contextual.names. May contain `NULL`s for variables which should not be weighted at the individual level. If only one design.weight is defined (instead of a list) it is applied to all contextual variables. By default set to `NULL`.
`sample.seed`	Is one of three things `NULL`, in which case whatever the current random seed is is used an `integer`, which will be used to set the random seed. This allows reproducible random samples a saved `.Random.seed` which allows reproducible random samples as well. The reason why both 2. and 3. are present is because `.Random.seed` can be saved a posteriori. Defaults to `NULL`.
`additional.args`	For aggregation functions which take additional arguments (that is in addition to the data to aggregate and design weights), they can be specified here. `additional.args` defaults to `NULL`
`verbose`	if `TRUE`, progress information and an estimate of the remaining computing time is shown at the screen. Defaults to `TRUE`

SpawAggregate can be used for two similar, yet distinct, purposes:

Aggregate contextual data and weight it spatially. For this, make sure to set nb.resamples=0
To resample thecontextual data repeatedly (bootstrap) and generate a series of aggregated and spatially weighted data.frames. For this, make sure to use a large number of resamples.

The function SpawAggregate works exactly the same way in either case, but the output changes. See return value for this

An object of class SpawAggregateOutput-class if nb.resamples is different than 0, a data.frame in the contrary case.

Till Junge, Sandra Penic, Mathieu Cossuta, Guy Elcheroth

## Creating spatially weighted aggregated contextual indicator - spatially weighted 
## risk of war victimization across TRACES areas.
## This is step-2 function

## Step 1: Load distance matrix and create weights
data(d_geo)
geow.50 <- WeightMatrix(d_geo, bandwidth=50)

## Step 2: Load dataframe with micro-level data for aggregation and create 
## spatially weighted contextual indicator (risk of war victimization weighted by geow.50)

data(traces_event)


wv.g50 <- SpawAggregate(contextual.data=traces_event,
                           context.id="area.name",
                           contextual.names="w_all",
                           contextual.weight.matrices=geow.50,
                           aggregation.functions="weighted.mean",
                           design.weight.names="weight",
                           nb.resamples=5)

## To create non-weighted and spatially weighted (by geow.50) risk of war victimization 

wv.nw.g50 <- SpawAggregate(contextual.data=traces_event,
                           context.id="area.name",
                           contextual.names=c("w_all","w_all"),
                           contextual.weight.matrices=list(NULL,geow.50),
                           aggregation.functions="weighted.mean",
                           design.weight.names="weight",
                           nb.resamples=5)