This function generates demand points to characterize a distribution of points.

make.DemandPoints(
  points,
  n = 100L,
  quantile = 0.5,
  kernel.method = c("ks", "hypervolume")[1],
  ...
)

Arguments

points

base::matrix() object containing points.

n

integer number of demand points to use for each attribute space for each species. Defaults to 100L.

quantile

numeric quantile to generate demand points within. If 0 then demand points are generated across the full range of values the points intersect. Defaults to 0.5.

kernel.method

character name of kernel method to use to generate demand points. Defaults to 'ks'.

...

arguments passed to kernel density estimating functions

Value

A new DemandPoints() object.

Details

Broadly speaking, demand points are generated by fitting a kernal to the input points. A shape is then fit to the extent of the kernal, and then points are randomly generated inside the shape. The demand points are generated as random points inside the shape. The weights for each demand point are calculated the estimated density of input points at the demand point. By supplying 'ks' as an argument to method in kernel.method, the shape is defined using a minimum convex polygon adehabitatHR::mcp() and ks::kde() is used to fit the kernel. Note this can only be used when the data is low-dimensional (d < 3). By supplying "hypervolume" as an argument to method, the hypervolume::hypervolume() function is used to create the demand points. This method can be used for hyper-dimensional data (\(d << 3\)).

Examples

# \dontrun{
# set random number generator seed
set.seed(500)

# load data
cs_spp <- terra::rast(
  system.file("extdata", "cs_spp.tif", package = "raptr")
)
cs_space <- terra::rast(
  system.file("extdata", "cs_space.tif", package = "raptr")
)

# generate species points
species.points <- randomPoints(cs_spp[[1]], n = 100, prob = TRUE)
env.points <- as.matrix(terra::extract(cs_space, species.points))

# generate demand points for a 1d space using ks
dps1 <- make.DemandPoints(points = env.points[, 1], kernel.method = "ks")

# print object
print(dps1)
#> An object of class "DemandPoints"
#> Slot "coords":
#>                 [,1]
#>   [1,]  0.0808103968
#>   [2,] -0.0046110217
#>   [3,]  0.0668303875
#>   [4,] -0.0041704369
#>   [5,]  0.0967735150
#>   [6,]  0.0861980942
#>   [7,]  0.0132235375
#>   [8,]  0.0310942534
#>   [9,]  0.0825810503
#>  [10,] -0.0060209781
#>  [11,]  0.0564411167
#>  [12,]  0.0481650728
#>  [13,]  0.0344428697
#>  [14,]  0.0926038714
#>  [15,] -0.0147107136
#>  [16,]  0.0756575651
#>  [17,]  0.0369092066
#>  [18,]  0.0799855542
#>  [19,] -0.0117221538
#>  [20,]  0.0577459378
#>  [21,]  0.0920794481
#>  [22,]  0.0952088937
#>  [23,] -0.0037990799
#>  [24,]  0.0305098021
#>  [25,]  0.0693633656
#>  [26,]  0.0298491907
#>  [27,] -0.0151671059
#>  [28,]  0.0661814401
#>  [29,]  0.0964706922
#>  [30,]  0.0960502613
#>  [31,]  0.0230169782
#>  [32,] -0.0062315864
#>  [33,]  0.0466713175
#>  [34,]  0.0430020565
#>  [35,] -0.0034828312
#>  [36,]  0.0139532333
#>  [37,]  0.0610430389
#>  [38,]  0.0638028611
#>  [39,]  0.0141869350
#>  [40,]  0.0614487432
#>  [41,]  0.0174622280
#>  [42,]  0.0569979270
#>  [43,]  0.0758035879
#>  [44,]  0.0911338272
#>  [45,]  0.0613651955
#>  [46,]  0.0712111254
#>  [47,] -0.0153747189
#>  [48,]  0.0053567871
#>  [49,]  0.0001290644
#>  [50,]  0.0748831153
#>  [51,]  0.0913817001
#>  [52,]  0.0696987096
#>  [53,]  0.0081708493
#>  [54,] -0.0165420542
#>  [55,]  0.0685402105
#>  [56,]  0.0458259359
#>  [57,]  0.0473664533
#>  [58,]  0.0598048639
#>  [59,]  0.0029895718
#>  [60,]  0.0134756202
#>  [61,]  0.0898856666
#>  [62,]  0.0962462811
#>  [63,]  0.0379707447
#>  [64,]  0.0634802596
#>  [65,]  0.0808849066
#>  [66,]  0.0236644935
#>  [67,]  0.0044193709
#>  [68,]  0.0343277191
#>  [69,]  0.0193473454
#>  [70,]  0.0633850623
#>  [71,] -0.0002382385
#>  [72,]  0.0894711456
#>  [73,]  0.0148280825
#>  [74,]  0.0381031308
#>  [75,] -0.0069926637
#>  [76,]  0.0202786373
#>  [77,]  0.0664897506
#>  [78,] -0.0106829763
#>  [79,]  0.0283130898
#>  [80,]  0.0461905189
#>  [81,]  0.0069314662
#>  [82,]  0.0376396250
#>  [83,]  0.0641600912
#>  [84,]  0.0807674021
#>  [85,]  0.0180828544
#>  [86,] -0.0002938116
#>  [87,]  0.0006463106
#>  [88,]  0.0537719357
#>  [89,]  0.0851661388
#>  [90,]  0.0983258660
#>  [91,]  0.0782045450
#>  [92,]  0.0684126648
#>  [93,]  0.0848222984
#>  [94,] -0.0010883919
#>  [95,] -0.0058721562
#>  [96,]  0.0018729640
#>  [97,]  0.0066104840
#>  [98,]  0.0284932298
#>  [99,] -0.0145268791
#> [100,]  0.0098583591
#> 
#> Slot "weights":
#>   [1] 0.3010606 0.3850167 0.3296584 0.3854821 0.2703865 0.2904376 0.3967625
#>   [8] 0.3896309 0.2975354 0.3834467 0.3506640 0.3660383 0.3861334 0.2781870
#>  [15] 0.3723192 0.3114736 0.3831519 0.3027107 0.3764002 0.3480990 0.2791764
#>  [22] 0.2733036 0.3858744 0.3901590 0.3244229 0.3907559 0.3716687 0.3309954
#>  [29] 0.2709490 0.2717331 0.3953379 0.3832109 0.3686019 0.3745554 0.3862084
#>  [36] 0.3968460 0.3414976 0.3358828 0.3968727 0.3406761 0.3968743 0.3495757
#>  [43] 0.3111759 0.2809656 0.3408453 0.3206091 0.3713728 0.3936252 0.3896931
#>  [50] 0.3130564 0.2804945 0.3237301 0.3951657 0.3696947 0.3261238 0.3700298
#>  [57] 0.3674278 0.3439926 0.3920070 0.3967913 0.2833381 0.2713672 0.3817864
#>  [64] 0.3365415 0.3009116 0.3950104 0.3930144 0.3862627 0.3965723 0.3367357
#>  [71] 0.3893554 0.2841316 0.3969455 0.3816087 0.3823203 0.3963328 0.3303602
#>  [78] 0.3777600 0.3920285 0.3694140 0.3945385 0.3822290 0.3351498 0.3011465
#>  [85] 0.3968180 0.3893043 0.3901301 0.3558121 0.2924465 0.2675059 0.3062967
#>  [92] 0.3263876 0.2931186 0.3885737 0.3836134 0.3911560 0.3943711 0.3918831
#>  [99] 0.3725805 0.3958686
#> 

# generate demand points for a 2d space using hypervolume
dps2 <- make.DemandPoints(
  points = env.points,
  kernel.method = "hypervolume",
  samples.per.point = 50,
  verbose = FALSE
)
#> Note that the formula used for the Silverman estimator differs in version 3 compared to prior versions of this package.
#> Use method='silverman-1d' to replicate prior behavior.

# print object
print(dps2)
#> An object of class "DemandPoints"
#> Slot "coords":
#>              layer.1      layer.2
#>   [1,]  0.0561863616 -0.176043262
#>   [2,] -0.0562105989 -0.078724182
#>   [3,]  0.0566218600 -0.257811199
#>   [4,]  0.0090094413 -0.031027407
#>   [5,] -0.0082527495 -0.012413512
#>   [6,]  0.0092269705 -0.189655476
#>   [7,]  0.0634401689 -0.155924547
#>   [8,]  0.0645489532 -0.292470895
#>   [9,] -0.0841342265 -0.076687189
#>  [10,] -0.0061934003 -0.079008968
#>  [11,] -0.0674163761 -0.028676337
#>  [12,]  0.0773054285 -0.314839728
#>  [13,]  0.0072017316 -0.010155631
#>  [14,]  0.0546176297 -0.067258607
#>  [15,]  0.0292475820 -0.039698040
#>  [16,] -0.0489445224 -0.173109603
#>  [17,] -0.0404079224 -0.201308241
#>  [18,] -0.0633638208 -0.094263086
#>  [19,]  0.1090447591 -0.287599522
#>  [20,] -0.0350030556 -0.081417086
#>  [21,] -0.0335981827 -0.070885894
#>  [22,]  0.0247284541 -0.212438923
#>  [23,]  0.0225502385 -0.076830049
#>  [24,]  0.1003037110 -0.259912194
#>  [25,]  0.0899788969 -0.341731019
#>  [26,] -0.0219742773 -0.110948581
#>  [27,] -0.0293678248 -0.069409570
#>  [28,]  0.1109055546 -0.327037300
#>  [29,]  0.0268947709 -0.200413485
#>  [30,]  0.0091227958 -0.188303884
#>  [31,]  0.0425206780 -0.097837802
#>  [32,]  0.0204776828 -0.144379469
#>  [33,]  0.0357274942 -0.294195435
#>  [34,] -0.0466550908 -0.091145248
#>  [35,] -0.0217474936 -0.078603950
#>  [36,] -0.0320076786 -0.063311522
#>  [37,] -0.0401312675 -0.131562443
#>  [38,] -0.0122093623 -0.235093536
#>  [39,] -0.0474874477 -0.196343938
#>  [40,]  0.0592729741 -0.251280275
#>  [41,]  0.0315154861 -0.074308757
#>  [42,] -0.0376145055 -0.206462643
#>  [43,]  0.0299480705 -0.054657300
#>  [44,] -0.0156856535 -0.096612177
#>  [45,] -0.0368399764 -0.054054221
#>  [46,] -0.0148925791 -0.075593949
#>  [47,]  0.0101719788 -0.096078687
#>  [48,]  0.0524951317 -0.164594086
#>  [49,]  0.0702362559 -0.231293348
#>  [50,] -0.0019166160 -0.198270927
#>  [51,] -0.0119973356 -0.168959428
#>  [52,]  0.0304751900 -0.219820476
#>  [53,] -0.0030810190 -0.116882505
#>  [54,] -0.0813645575 -0.041134230
#>  [55,]  0.0393641761 -0.185280131
#>  [56,] -0.0383135749 -0.123865264
#>  [57,] -0.0037346760 -0.084747835
#>  [58,]  0.0938385090 -0.344215363
#>  [59,]  0.0201019606 -0.075350940
#>  [60,]  0.0575729997 -0.096891549
#>  [61,]  0.0277173388 -0.260892030
#>  [62,] -0.0290729711 -0.152987467
#>  [63,]  0.1132623121 -0.315947125
#>  [64,]  0.0400443068 -0.192813345
#>  [65,] -0.0395244791 -0.154758373
#>  [66,]  0.0631226622 -0.116265077
#>  [67,]  0.0361650480 -0.267542656
#>  [68,]  0.0972460224 -0.243745108
#>  [69,] -0.0171085114 -0.238457844
#>  [70,]  0.0178219019 -0.093644470
#>  [71,]  0.0065127571 -0.106851379
#>  [72,]  0.0199644609 -0.068747288
#>  [73,] -0.0073302097 -0.195060557
#>  [74,] -0.0243832960 -0.004595343
#>  [75,]  0.0542357305 -0.081347583
#>  [76,]  0.0050446241 -0.028458925
#>  [77,] -0.0466440173 -0.125659336
#>  [78,]  0.0319489519 -0.280789981
#>  [79,]  0.0048062417 -0.068727292
#>  [80,]  0.0415413703 -0.078259581
#>  [81,]  0.0574335681 -0.169415786
#>  [82,]  0.0571364240 -0.307939138
#>  [83,] -0.0031118159 -0.246522374
#>  [84,]  0.0580419896 -0.226504609
#>  [85,] -0.0534154791 -0.179055950
#>  [86,] -0.0217875410 -0.014767334
#>  [87,]  0.1108233528 -0.286069379
#>  [88,]  0.0897716951 -0.313756867
#>  [89,]  0.0336452425 -0.303461812
#>  [90,] -0.0057302045 -0.237321006
#>  [91,] -0.0874295970 -0.023752724
#>  [92,] -0.0439573775 -0.030899501
#>  [93,]  0.0621440955 -0.257788961
#>  [94,] -0.0845545340 -0.105432917
#>  [95,]  0.0004214444 -0.097796489
#>  [96,]  0.0478558916 -0.229698994
#>  [97,] -0.0596944859  0.012741367
#>  [98,] -0.0418503888 -0.110908638
#>  [99,] -0.0652293435  0.013968401
#> [100,] -0.0163040168 -0.139622603
#> 
#> Slot "weights":
#>   [1] 0.0011035379 0.0012400900 0.0012413036 0.0009209698 0.0008946157
#>   [6] 0.0015456889 0.0009495143 0.0010996052 0.0009106753 0.0011882000
#>  [11] 0.0010727270 0.0009784436 0.0008032946 0.0007734166 0.0008463295
#>  [16] 0.0009942093 0.0009930892 0.0011382373 0.0008947341 0.0013027252
#>  [21] 0.0012897836 0.0015040433 0.0010105343 0.0008993235 0.0008101575
#>  [26] 0.0013124895 0.0012763381 0.0008647388 0.0014894937 0.0015438284
#>  [31] 0.0009412861 0.0013001092 0.0009759555 0.0012776623 0.0012655290
#>  [36] 0.0012711300 0.0012408549 0.0011753535 0.0008965159 0.0012342890
#>  [41] 0.0009474223 0.0010089415 0.0008976637 0.0012745744 0.0012572162
#>  [46] 0.0012271577 0.0011446252 0.0011010426 0.0011116394 0.0015175142
#>  [51] 0.0014565406 0.0014652124 0.0012850191 0.0009688583 0.0013339816
#>  [56] 0.0012672636 0.0011895475 0.0007991656 0.0010211697 0.0008280643
#>  [61] 0.0012500957 0.0013152509 0.0008744544 0.0013530024 0.0011991971
#>  [66] 0.0008343745 0.0012210552 0.0008715166 0.0010696107 0.0010908997
#>  [71] 0.0012031148 0.0010025170 0.0014875786 0.0009054960 0.0008131295
#>  [76] 0.0009290152 0.0011968760 0.0010852899 0.0010939596 0.0008930561
#>  [81] 0.0010638913 0.0009725522 0.0011671849 0.0012311020 0.0008885727
#>  [86] 0.0009780506 0.0008764328 0.0009792408 0.0008630531 0.0012354213
#>  [91] 0.0008472724 0.0011611704 0.0012111331 0.0007903583 0.0012044374
#>  [96] 0.0013310071 0.0008049924 0.0012675725 0.0007824858 0.0013724906
#> 
# }