s2runif: Generate uniform random points on sphere

View source: R/s2random.R

s2runifR Documentation

Generate uniform random points on sphere

Description

Generate uniform random points on sphere.

Usage

s2runif(
  n,
  region = s2(...),
  giveup = 1000,
  warn = TRUE,
  ...,
  nsim = 1,
  drop = TRUE,
  ex = NULL
)

Arguments

n

Number of points. Can be a vector in which case nsim should be equal to length(n) (happens automatically if nsim is missing).

region

Region (of class "s2region") to simulate the pattern in. Defaults to the unit sphere.

giveup

Number of attempts in the rejection method after which the algorithm should stop trying to generate new points.

warn

Logical. Whether to issue a warning if 'n“ is very large. See Details.

...

Arguments passed on to s2

radius

Numeric. Defaults to 1. For convenience this can also be an object of class "s2region" from where the radius and unitname then will be extracted.

unitname

Optional. Name of unit of length. Either a single character string, or a vector of two character strings giving the singular and plural forms, respectively.

nsim

Number of simulated realisations to be generated.

drop

Logical. If nsim = 1`` and drop = TRUE' (the default), the result will be a point pattern, rather than a list containing a point pattern.

ex

Optional. A point pattern to use as the example. If ex is given and n and region are missing, then n and region will be calculated from the point pattern ex.

Details

This function generates n independent random points, uniformly distributed in the region region on the sphere. The algorithm depends on the type of region, as follows:

  • If region is a box in longitude and latitude coordinates ("s2lonlatbox") then n independent random points, uniformly distributed in the box, are generated by assigning uniform random values to their lon,lat coordinates using the appropriate acos transform for the latitude coordinates.

  • If region is a polygon or cap, the algorithm uses the rejection method. It finds a s2lonlatbox enclosing the region, generates points in this box, and tests whether they fall in the desired region. It gives up when giveup * n tests have been performed without yielding n successes.

If warn = TRUE, then a warning will be issued if n is very large. The threshold is [spatstat.options("huge.npoints")](spatstat::spatstat.options). This warning has no consequences, but it helps to trap a number of common errors.

Value

A point pattern on the sphere (an object of class "s2pp") if nsim = 1 and drop = TRUE, or a list of point patterns otherwise.

Examples

X <- s2runif(10)
loop <- cbind(lon = c(0, 60, 60, 0), lat = c(-40, -40, 40, 40))
poly <- s2polygon(loop)
s2runif(10, region = poly)
s2runif(c(10, 20), region = poly)

spatstat/spatstat.sphere documentation built on Jan. 27, 2023, 2:59 a.m.