auto_basis: Automatic basis-function placement

Description Usage Arguments Details Examples

View source: R/basisfns.R


Generate automatically a set of local basis functions in the domain, and automatically prune in regions of sparse data.


auto_basis(manifold = plane(), data, regular = 1, nres = 3, prune = 0,
  max_basis = NULL, subsamp = 10000, type = c("bisquare", "Gaussian",
  "exp", "Matern32"), isea3h_lo = 2, bndary = NULL,
  scale_aperture = ifelse(is(manifold, "sphere"), 1, 1.25), verbose = 0L,



object of class manifold, for example, sphere or plane


object of class SpatialPointsDataFrame or SpatialPolygonsDataFrame containing the data on which basis-function placement is based, or a list of these; see details


an integer indicating the number of regularly-placed basis functions at the first resolution. In two dimensions, this dictates the smallest number of basis functions in a row or column at the coarsest resolution. If regular=0, an irregular grid is used, one that is based on the triangulation of the domain with increased mesh density in areas of high data density; see details


the number of basis-function resolutions to use


a threshold parameter that dictates when a basis function is considered irrelevent or unidentifiable, and thus removed; see details


maximum number of basis functions. This overrides the parameter nres


the maximum amount of data points to consider when carrying out basis-function placement: these data objects are randomly sampled from the full dataset. Keep this number fairly high (on the order of 10^5), otherwise fine-resolution basis functions may be spuriously removed


the type of basis functions to use; see details


if manifold = sphere(), this argument dictates which ISEA3H resolution is the coarsest one that should be used for the first resolution


a matrix containing points containing the boundary. If regular == 0 this can be used to define a boundary in which irregularly-spaced basis functions are placed


the aperture (in the case of the bisquare, but similar interpretation for other basis) width of the basis function is the minimum distance between all the basis function centroids multiplied by scale_aperture. Typically this ranges between 1 and 1.5 and is defaulted to 1 on the sphere and 1.25 on the other manifolds.


a logical variable indicating whether to output a summary of the basis functions created or not




This function automatically places basis functions within the domain of interest. If the domain is a plane or the real line, then the object data is used to establish the domain boundary.

The argument type can be either “Gaussian”, in which case

φ(u) = \exp≤ft(-\frac{\|u \|^2}{2σ^2}\right),

“bisquare”, in which case

φ(u) = ≤ft(1- ≤ft(\frac{\| u \|}{R}\right)^2\right)^2 I(\|u\| < R),

“exp”, in which case

φ(u) = \exp≤ft(-\frac{\|u\|}{ τ}\right),

or “Matern32”, in which case

φ(u) = ≤ft(1 + \frac{√{3}\|u\|}{κ}\right)\exp≤ft(-\frac{√{3}\| u \|}{κ}\right),

where the parameters σ, R, τ and κ are scale arguments.

If the manifold is the real line, the basis functions are placed regularly inside the domain, and the number of basis functions at the coarsest resolution is dictated by the integer parameter regular which has to be greater than zero. On the real line, each subsequent resolution has twice as many basis functions. The scale of the basis function is set based on the minimum distance between the centre locations following placement. The scale is equal to the minimum distance if the type of basis function is Gaussian, exponential, or Matern32, and is equal to 1.5 times this value if the function is bisquare.

If the manifold is a plane, and regular > 0, then basis functions are placed regularly within the bounding box of data, with the smallest number of basis functions in each row or column equal to the value of regular in the coarsest resolution (note, this is just the smallest number of basis functions). Subsequent resolutions have twice the number of basis functions in each row or column. If regular = 0, then the function INLA::inla.nonconvex.hull is used to construct a (non-convex) hull around the data. The buffer and smoothness of the hull is determined by the parameter convex. Once the domain boundary is found, INLA::inla.mesh.2d is used to construct a triangular mesh such that the node vertices coincide with data locations, subject to some minimum and maximum triangular-side-length constraints. The result is a mesh that is dense in regions of high data density and not dense in regions of sparse data. Even basis functions are irregularly placed, the scale is taken to be a function of the minimum distance between basis function centres, as detailed above. This may be changed in a future revision of the package.

If the manifold is the surface of a sphere, then basis functions are placed on the centroids of the discrete global grid (DGG), with the first basis resolution corresponding to the third resolution of the DGG (ISEA3H resolution 2, which yields 92 basis functions globally). It is not recommended to go above nres == 3 (ISEA3H resolutions 2–4) for the whole sphere; nres=3 yields a total of 1176 basis functions. Up to ISEA3H resolution 6 is available with FRK; for finer resolutions; please install dggrids from using devtools.

Basis functions that are not influenced by data points may hinder convergence of the EM algorithm when K_type = ``unstructured'', since the associated hidden states are, by and large, unidentifiable. We hence provide a means to automatically remove such basis functions through the parameter prune. The final set only contains basis functions for which the column sums in the associated matrix S (which, recall, is the value/average of the basis functions at/over the data points/polygons) is greater than prune. If prune == 0, no basis functions are removed from the original design.


## Not run: 

### Create a synthetic dataset
d <- data.frame(lon = runif(n=1000,min = -179, max = 179),
                lat = runif(n=1000,min = -90, max = 90),
                z = rnorm(5000))
coordinates(d) <- ~lon + lat
proj4string(d)=CRS("+proj=longlat +ellps=sphere")

### Now create basis functions over sphere
G <- auto_basis(manifold = sphere(),data=d,
                nres = 2,prune=15,
                type = "bisquare",
                subsamp = 20000)

### Plot

## End(Not run)

FRK documentation built on May 2, 2019, 8:11 a.m.