dist_mat {conleyreg} | R Documentation |
Distance matrix estimation
Description
This function estimates the distance matrix separately from Conley standard errors. Such step can be helpful when running multiple Conley standard error estimations
based on the same distance matrix. A pre-requisite of using this function is that the data must not be modified between applying this function and inserting the
results into conleyreg
.
Usage
dist_mat(
data,
unit = NULL,
time = NULL,
lat = NULL,
lon = NULL,
dist_comp = NULL,
dist_cutoff = NULL,
crs = NULL,
verbose = TRUE,
ncores = NULL,
par_dim = c("cross-section", "time", "r", "cpp"),
sparse = FALSE,
batch = TRUE,
batch_ram_opt = NULL,
dist_round = FALSE,
st_distance = FALSE,
dist_which = NULL
)
Arguments
data |
input data. Either (i) in non-spatial data frame format (includes tibbles and data tables) with columns denoting coordinates or (ii) in sf format. In
case of an sf object, all non-point geometry types are converted to spatial points, based on the feature's centroid. When using a non-spatial data frame format
the with projected, i.e. non-longlat, coordinates, |
unit |
the variable identifying the cross-sectional dimension. Only needs to be specified, if data is not cross-sectional. Assumes that units do not change their location over time. |
time |
the variable identifying the time dimension. Only needs to be specified, if data is not cross-sectional. |
lat |
the variable specifying the latitude |
lon |
the variable specifying the longitude |
dist_comp |
choice between |
dist_cutoff |
the distance cutoff in km. If not specified, the distances matrices contain all bilateral distances. If specified, the cutoff most be as least
as large as the largest distance cutoff in the Conley standard error corrections in which you use the resulting matrix. If you e.g. specify distance cutoffs of
100, 200, and 500 km in the subsequent |
crs |
the coordinate reference system, if the data is projected. Object of class crs or input string to |
verbose |
logical specifying whether to print messages on intermediate estimation steps. Defaults to |
ncores |
the number of CPU cores to use in the estimations. Defaults to the machine's number of CPUs. |
par_dim |
the dimension along which the function parallelizes in unbalanced panel applications. Can be set to |
sparse |
logical specifying whether to use sparse rather than dense (regular) matrices in distance computations. Defaults to |
batch |
logical specifying whether distances are inserted into a sparse matrix element by element ( |
batch_ram_opt |
the degree to which batch insertion should be optimized for RAM usage. Can be set to one out of the three levels: |
dist_round |
logical specifying whether to round distances to full kilometers. This further reduces memory consumption and can be a solution when even sparse matrices cannot accomodate the data. Note, though, that this rounding introduces a bias. |
st_distance |
logical specifying whether distances should be computed via |
dist_which |
the type of distance to use when |
Details
This function runs the distance matrix estimations separately from the Conley standard error correction. You can pass the resulting object to the
dist_mat
argument in conleyreg
, skipping the distance matrix computations and various checks in that function. Pre-computing the distance matrix
is only more efficient than deriving it via conleyreg
when estimating various models that use the same distance matrices. The input data must not be
modified between calling this function and inserting the results into conleyreg
. Do not reorder the observations, add or delete variables, or undertake
any other operation on the data.
Value
Returns an object of S3 class conley_dist
. It contains modified distance matrices, the used dist_cutoff
, a sparse matrix identifier, and
information on the potential panel structure. In the cross-sectional case and the balanced panel case, the distances are stored in one matrix, while in unbalanced
panel applications, distances come as a list of matrices. The function optimizes the distance matrices with respect to computational performance, setting
distances beyond dist_cutoff
to zero and actual off-diagonal zeros to NaN. Hence, these objects are only to be used in conleyreg
.
Examples
## Not run:
# Generate cross-sectional example data
data <- rnd_locations(100, output_type = "data.frame")
data$y <- sample(c(0, 1), 100, replace = TRUE)
data$x1 <- stats::runif(100, -50, 50)
# Compute distance matrix in cross-sectional case
dm <- dist_mat(data, lat = "lat", lon = "lon")
# Compute distance matrix in panel case
data$time <- rep(1:10, each = 10)
data$unit <- rep(1:10, times = 10)
dm <- dist_mat(data, unit = "unit", time = "time", lat = "lat", lon = "lon")
# Use distance matrix in conleyreg function
conleyreg(y ~ x1, data, 1000, dist_mat = dm)
## End(Not run)