Skip to contents

Generate data based on a ellipsoidal niche

Source: R/virtual_data.R
virtual_data.Rd

Simulates n random points from a multivariate normal distribution defined by the centroid and covariance matrix of a nicheR_ellipsoid object.

Usage

virtual_data(object, n = 100, truncate = FALSE, effect = "direct", seed = 1)

Arguments

object

A nicheR_ellipsoid object containing at least centroid and cov_matrix.

n

Integer. The number of virtual points to generate. Default = 100.

truncate

Logical. If TRUE (default), points are constrained within the confidence limit (cl) defined in the object.

effect

Character. The distribution pattern of points. "direct" (default) creates a concentration near the centroid. "inverse" creates higher density towards the edges. "uniform" distributes points evenly throughout the ellipsoid volume. Note: "inverse" and "uniform" require truncate = TRUE.

seed

Integer. Random seed for reproducibility. Default = 1. Set to NULL for no seeding.

Value

A matrix with n rows and columns corresponding to the environmental variables (dimensions) of the input object.

Details

When truncate = FALSE, the function generates points from a standard multivariate normal distribution defined by the ellipsoid's centroid and covariance matrix, without any constraints on their location. The function uses eigen-decomposition to transform standard normal variables into the coordinate system defined by the ellipsoid's covariance structure.

When truncate = TRUE, the function generates candidate points uniformly distributed within a bounding box (hyper-cube) defined by the ellipsoid's axes_coordinates. Points falling outside the ellipsoid (where Mahalanobis distance \(Md >\) chi2_cutoff) are removed.

From this filtered pool, n points are selected using weighted random sampling without replacement. The weights are determined by the effect argument:

  • "direct": Weights are proportional to the multivariate normal density (\(\exp(-0.5 \times Md)\)), clustering points near the centroid.

  • "inverse": Weights are proportional to the complement of the normal density (\(1 - \exp(-0.5 \times Md)\)), pushing points toward the edges.

  • "uniform": All points within the ellipsoid have equal weight, resulting in a uniform spatial distribution.

Examples

# Loading data
## Reference niche
data("ref_ellipse", package = "nicheR")

# Generate virtual data from the reference niche
vdata_direct <- virtual_data(ref_ellipse, n = 100, effect = "direct")
vdata_inverse <- virtual_data(ref_ellipse, n = 100,
                              effect = "inverse", truncate = TRUE)

# Check a sample of the generated data
head(vdata_direct)
#>         bio_1   bio_12
#> [1,] 24.43048 1593.388
#> [2,] 23.38038 1795.911
#> [3,] 24.83258 1541.094
#> [4,] 22.68868 2148.820
#> [5,] 24.08559 1832.378
#> [6,] 21.89134 1544.880
head(vdata_inverse)
#>         bio_1   bio_12
#> [1,] 25.29501 1600.449
#> [2,] 22.98510 1564.597
#> [3,] 22.22315 1578.350
#> [4,] 26.29732 1385.688
#> [5,] 26.45626 1258.054
#> [6,] 26.72507 1737.921