SystematicSampling: Systematic Sampling

Documented in distUnita distUnitk IB sb_vk systematicDesign

# Generated by using Rcpp::compileAttributes() -> do not edit by hand
# Generator token: 10BE3573-1514-4C36-9D1C-5A225CD40393

#' @encoding UTF-8
#' @title Spreading measure based on Moran's \eqn{I} index
#'
#' @description
#'
#' This function implements the spreading measure based on Moran's \eqn{I} index.
#'
#' @param W a stratification matrix inheriting from \code{\link[Matrix]{sparseMatrix}} that represents the spatial weights. See \code{\link{wpik}}.
#' @param s a vector of size \eqn{N} with elements equal to 0 or 1. The value 1 indicates that the unit is selected while the value 0 is for non-chosen units.
#'
#'
#' @details
#' 
#' This index is developped by Tillé et al. (2018) and measure the spreading of a sample drawn from a population.
#' It uses a corrected version of the traditional Moran's \eqn{I} index. Each row of the matrix \eqn{\bf W} should represents a stratum. Each 
#' stratum is defined by a particular unit and its neighbouring units. See \code{\link{wpik}}.
#' The spatial balance measure is equal to
#' 
#' \deqn{I_B =\frac{( \bf s- \bar{s}_w)^\top  W ( s- \bar{s}_w)}{\bf \sqrt{( s- \bar{s}_w)^\top  D ( s- \bar{s}_w) ( s- \bar{s}_w)^\top  B ( s- \bar{s}_w)}},}
#' 
#' where \eqn{\bf D} is the diagonal matrix containing the \eqn{w_i}, 
#' 
#' \deqn{ \bf \bar{s}_w =  1 \frac{ s^\top  W  1}{ 1^\top  W  1}}
#' 
#' and 
#' 
#' \deqn{ \bf B =  W^\top  D^{-1}  W - \frac{ W^\top  1 1^\top  W}{1^\top  W  1}.}
#' 
#' To specify the spatial weights uses the argument \code{W}.
#'
#' @return A numeric value that represents the spatial balance. It could be any real value between -1 (spread) and 1 (clustered). 
#' 
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#' 
#' @references
#' Tillé, Y., Dickson, M.M., Espa, G., and Guiliani, D. (2018). Measuring the spatial balance of a sample: A new measure based on Moran's I index.
#' \emph{Spatial Statistics}, 23, 182-192. \url{https://doi.org/10.1016/j.spasta.2018.02.001}
#' 
#' @seealso
#' \code{\link{wpik}}
#' 
#' @examples
#'   N <- 36
#'   n <- 12
#'   x <- seq(1,sqrt(N),1)
#'   X <- expand.grid(x,x)
#'   pik <- rep(n/N,N)
#'   W <- wpik(as.matrix(X),pik,bound = 1,tore = TRUE,shift = FALSE,toreBound = sqrt(N))
#'   W <- W - diag(diag(W))
#'   s <- wave(as.matrix(X),pik,tore = TRUE,shift = TRUE,comment = TRUE)
#'   IB(W,s)
#' 
#' @export
IB <- function(W, s) {
    .Call(`_SystematicSampling_IB`, W, s)
}

#' @title Squared Euclidean distances of the unit k.
#'
#' @description
#' Calculate the squared Euclidean distance from unit \eqn{k} to the other units.
#'
#'
#' @param X matrix representing the spatial coordinates.
#' @param k the unit index to be used.
#' @param tore an optional logical value, if we are considering the distance on a tore. See Details.
#' @param toreBound an optional numeric value that specify the length of the tore.
#'
#'
#' @details
#'
#' Let \eqn{\mathbf{x}_k,\mathbf{x}_l} be the spatial coordinates of the unit \eqn{k,l \in U}. The classical euclidean distance is given by
#'
#' \deqn{d^2(k,l) = (\mathbf{x}_k - \mathbf{x}_l)^\top (\mathbf{x}_k - \mathbf{x}_l). }
#'
#' When the points are distributed on a \eqn{N_1 \times N_2} regular grid of \eqn{R^2}.
#' It is possible to consider the units like they were placed on a tore. It can be illustrated by Pac-Man passing through the wall to get away from ghosts. Specifically,
#' we could consider two units on the same column (resp. row) that are on the opposite have a small distance,
#'
#' \deqn{ d^2_T(k,l) = min( (x_{k_1} - x_{l_1})^2,
#'                       (x_{k_1} + N_1 - x_{l_1})^2,
#'                       (x_{k_1} - N_1 - x_{l_1})^2) +}
#' \deqn{ min( (x_{k_2} - x_{l_2})^2,
#'                       (x_{k_2} + N_2 - x_{l_2})^2,
#'                       (x_{k_2} - N_2 - x_{l_2})^2).}
#'
#' The option \code{toreBound} specify the length of the tore in the case of \eqn{N_1 = N_2 = N}.
#' It is omitted if the \code{tore} option is equal to \code{FALSE}.
#'
#' @return a vector of length \eqn{N} that contains the distances from the unit \eqn{k} to all other units.
#'
#'
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#'
#'
#' @seealso
#' \code{\link{wpik}}, \code{\link{wave}} and \code{\link[stats]{dist}}.
#'
#' @examples
#'   N <- 5
#'   x <- seq(1,N,1)
#'   X <- as.matrix(expand.grid(x,x))
#'   distUnitk(X,k = 2,tore = TRUE,toreBound = 5)
#'   distUnitk(X,k = 2,tore = FALSE,toreBound = -1)
#' @export
distUnitk <- function(X, k, tore, toreBound) {
    .Call(`_SystematicSampling_distUnitk`, X, k, tore, toreBound)
}

#' @title Squared Euclidean distances of the unit k.
#'
#' @description
#' Calculate the squared Euclidean distance from unit \eqn{k} to the other units.
#'
#'
#' @param X matrix representing the spatial coordinates.
#' @param k the unit index to be used.
#' @param tore an optional logical value, if we are considering the distance on a tore. See Details.
#' @param toreBound an optional numeric value that specify the length of the tore.
#'
#'
#' @details
#'
#' Let \eqn{\mathbf{x}_k,\mathbf{x}_l} be the spatial coordinates of the unit \eqn{k,l \in U}. The classical euclidean distance is given by
#'
#' \deqn{d^2(k,l) = (\mathbf{x}_k - \mathbf{x}_l)^\top (\mathbf{x}_k - \mathbf{x}_l). }
#'
#' When the points are distributed on a \eqn{N_1 \times N_2} regular grid of \eqn{R^2}.
#' It is possible to consider the units like they were placed on a tore. It can be illustrated by Pac-Man passing through the wall to get away from ghosts. Specifically,
#' we could consider two units on the same column (resp. row) that are on the opposite have a small distance,
#'
#' \deqn{ d^2_T(k,l) = min( (x_{k_1} - x_{l_1})^2,
#'                       (x_{k_1} + N_1 - x_{l_1})^2,
#'                       (x_{k_1} - N_1 - x_{l_1})^2) +}
#' \deqn{ min( (x_{k_2} - x_{l_2})^2,
#'                       (x_{k_2} + N_2 - x_{l_2})^2,
#'                       (x_{k_2} - N_2 - x_{l_2})^2).}
#'
#' The option \code{toreBound} specify the length of the tore in the case of \eqn{N_1 = N_2 = N}.
#' It is omitted if the \code{tore} option is equal to \code{FALSE}.
#'
#' @return a vector of length \eqn{N} that contains the distances from the unit \eqn{k} to all other units.
#'
#'
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#'
#'
#' @seealso
#' \code{\link{wpik}}, \code{\link{wave}} and \code{\link[stats]{dist}}.
#'
#' @examples
#'   N <- 5
#'   x <- seq(1,N,1)
#'   X <- as.matrix(expand.grid(x,x))
#'   distUnitk(X,k = 2,tore = TRUE,toreBound = 5)
#'   distUnitk(X,k = 2,tore = FALSE,toreBound = -1)
#' @export
distUnita <- function(X, a, tore, toreBound) {
    .Call(`_SystematicSampling_distUnita`, X, a, tore, toreBound)
}

#' @encoding UTF-8
#' @title Projection operator
#'
#'
#' @description
#'
#' This operator projects the vector v orthogonally onto the line spanned by vector u.
#'
#' @param v vector projected.
#' @param u vector that define the line on which we project.
#' 
#' @details
#' 
#' The projection operator is defined by :
#' 
#' \deqn{proj_u(v) = \frac{\langle u , v \rangle}{\langle u, u \rangle} u}
#'  where \eqn{\langle . , . \rangle} is the inner product also written \eqn{u^\top v}.
#' 
#' @return The projection of the vector v onto the line spanned by the vector u.
#' 
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#' 
#' @references 
#' \url{https://en.wikipedia.org/wiki/Projection_(linear_algebra)}s
#' 
NULL

#' @title Column sums for sparseMatrix
#'
#' @description
#' Form column sums for sparseMatrix.
#'
#' @param x A sparse matrix, i.e., inheriting from \code{\link[Matrix]{sparseMatrix}}.
#'
#' @details
#' This function is designed to be used for internal \code{RcppArmadillo} functions. Nevertheless it could be applied in R.
#' It loops on the non-zero entries of the \code{\link[Matrix]{sparseMatrix}}. For general uses, the function
#' \code{\link[Matrix]{colSums}} should be prefered.
#'
#' @return column sums of x.
#' 
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#' 
#' @seealso
#' \code{\link[Matrix]{colSums}}, \code{\link[Matrix]{rowSums}}.
#'
NULL

#' @title Row sums on sparse matrix.
#'
#' @description
#' Form row sums for sparseMatrix.
#'
#' @param x A sparse matrix, i.e., inheriting from \code{\link[Matrix]{sparseMatrix}}.
#'
#' @details
#' This function is designed to be used for internal \code{RcppArmadillo} functions. Nevertheless it could be applied in R.
#' It loops on the non-zero entries of the \code{\link[Matrix]{sparseMatrix}}. For general uses, the function \code{\link[Matrix]{rowSums}} should
#' be prefered.
#'
#' @return row sums of x. 
#' 
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#' 
#' @seealso
#' \code{\link[Matrix]{colSums}}, \code{\link[Matrix]{rowSums}}.
#' 
#' 
NULL

#' @encoding UTF-8
#' @title Values \eqn{v_k} to compute the Spatial balance
#'
#' @description
#'
#' Calculates the \eqn{v_k} values of the spatial balance developped by Stevens and Olsen (2004) and suggested by Grafström et al. (2012).
#'
#' @param pik vector of the inclusion probabilities. The length should be equal to \eqn{N}.
#' @param X matrix representing the spatial coordinates.
#' @param s A vector of size \eqn{N} with elements equal 0 or 1. The value 1 indicates that the unit is selected while the value 0 is for non-chosen unit.
#'
#' @details
#'
#' The spatial balance measure based on the Voronoï polygons is defined by
#'
#' \deqn{B(S) = \frac{1}{n}\sum_{k\in S} (v_k -1)^2 .}
#'
#' The function return the \eqn{v_k} values and is mainly based on the function \code{\link[BalancedSampling:sb]{sb}} of the package \code{BalancedSampling} Grafström and Lisic (2019).
#'
#' @return A vector of size \eqn{N} with elements equal to the \eqn{v_k} values. If the unit is not selected then the value is equal to 0.
#'
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#'
#' @references
#'
#' Grafström, A., Lundström, N.L.P. and Schelin, L. (2012). Spatially balanced sampling through the Pivotal method.
#' \emph{Biometrics}, 68(2), 514-520
#'
#' Grafström, A., Lisic J. (2019). BalancedSampling: Balanced and Spatially Balanced Sampling. R package version 1.5.5.
#' https://CRAN.R-project.org/package=BalancedSampling
#'
#' Stevens, D. L. Jr. and Olsen, A. R. (2004). Spatially balanced sampling of natural resources.
#' \emph{Journal of the American Statistical Association 99, 262-278}
#'
#' @seealso
#' \code{\link[BalancedSampling:sb]{BalancedSampling::sb}}
#'
#'
#' @examples
#' N <- 50
#' n <- 10
#' X <- as.matrix(cbind(runif(N),runif(N)))
#' pik <- sampling::inclusionprobabilities(runif(N),n)
#' s <- wave(X,pik)
#' v <- sb_vk(pik,X,s)
#' 1/n*sum((v[which(v != 0)]-1)^2)
#' BalancedSampling::sb(pik,X,which(s == 1))
#'
#' @export
sb_vk <- function(pik, X, s, tore, toreBound) {
    .Call(`_SystematicSampling_sb_vk`, pik, X, s, tore, toreBound)
}

#' @encoding UTF-8
#' @title systematic desgin
#'
#' @description
#' 
#' Find all possible systematic sample from a vector of inclusion probabilities \code{pik}. 
#'
#' @param pik vector of inclusion probabilities..
#' 
#' @return A matrix of size at most N x N with elements equal to 0 or 1. The value 1 indicates that the uni is selected while the value 0 is for non-chosen unit.
#' 
#' @author Raphaël Jauslin \email{raphael.jauslin@@unine.ch}
#' 
#' @export
systematicDesign <- function(pik) {
    .Call(`_SystematicSampling_systematicDesign`, pik)
}