Generate expDesign objects that mainly consist on a sequence of functions to apply to
scanList objects. expDesign object generation relies on purrr's
compose() function.
design_exp(..., .dir = c("forward", "backward"))
| ... | functions of |
|---|---|
| .dir | character scalar, either |
an expDesign objects, a list consisting in the following elements:
FUN.seq: function sequence created by purrr's compose() function
WIP: more to come, notably to include more descriptive function names.
It is best practice to use a combination of:
provided "building blocks": functions included in the SimuNet package, such as
design_sampling(), add_scans(),
remove_mostPeripheral(), or sum_scans()
user-defined functions: designed to take a scanList object as a first argument, which is is
in essence a 3 dimensional array with adjacency matrices on the first 2 dimensions, and the
successive scan numbers as the 3rd dimension. User-defined function should returned a modified
scanList object, therefore allowing for function chaining in a fashion similar to
tidy functions (see also the notion of grammar of data
manipulation with the dplyr package).
expDesign objects are used to store sequences of manipulations to apply to a theoretical
scanList, in order to obtain a (simulated) empirical scanList. Such manipulations can
represent empirical sampling (e.g. group-scan sampling, focal sampling, biased sampling),
observation error, node removal, etc.
expDesign objects can be applied to scanList objects via the function
perform_exp(), or directly as simunet() exp.design argument
for simunet() to automatically generate a theoretical scanList and apply the inputted
expDesign to it.
Providing more than one expDesign object to either perform_exp() or
simunet() functions (i.e. effectively passing them as their ... argument) will
make them output a list of scanList objects - i.e. a sLlist object - which are convenient
ways to apply different experimental manipulation sequences to a given theoretical scanList and
allow for comparison (e.g. of the impact of sampling regime).
set.seed(42) n <- 5L samp.effort <- 100L # Adjacency matrix import ## random directed adjacency matrix Adj <- sample(1:samp.effort,n * n) |> matrix(nrow = 5,dimnames = list(letters[1:n],letters[1:n])) Adj[lower.tri(Adj,diag = TRUE)] <- 0L Adj#> a b c d e #> a 0 100 37 27 58 #> b 0 0 20 36 42 #> c 0 0 0 5 93 #> d 0 0 0 0 30 #> e 0 0 0 0 0# Designing the experiments: ## setting a constant probability of not observing edges group.scan <- design_sampling(method = "group",sampling = 0.8) ## setting a biased focal sampling favoring central individual (node strength) focal.scan <- design_sampling( method = "focal", sampling = function(Adj) Adj |> igraph::graph.adjacency("upper",weighted = TRUE) |> igraph::strength() ) ## Adding more scans, removing the most peripheral individual, before performing an even focal ## sampling focal.periRemoved <- design_exp( function(Adj) add_scans(Adj,42), # users can use anonymous function to specify arguments remove_mostPeripheral, # ... or pass functions as arguments directly design_sampling(method = "focal",sampling = "even") # design_sampling: special case # that returns sampling functions ) # Apply the experimental design ## on previously obtained theoretical scans sL <- simunet(Adj = Adj,samp.effort = samp.effort,mode = "upper",n.scans = 120L) perform_exp(sL,group.scan)#> #> scan: 1 #> a . 1 NA . 1 #> b . . . . . #> c . . . . 1 #> d . . . . . #> e . . . . . #> #> scan: 2 #> a . 1 . . . #> b . . . . 1 #> c . . . . 1 #> d . . . . . #> e . . . . . #> #> ... ( 117 more scans) #> #> scan: 120 #> a . 1 . . 1 #> b . . 1 1 . #> c . . . . 1 #> d . . . . NA #> e . . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - obs.P - theoretical.scanList#> #> Weighted adjacency matrix #> a . 65 20 36 #> b . . 20 25 #> c . . . 58 #> e . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - focalList - theoretical.scanList - summed.scanList - sampled## on newly simulated scanList within the simunet() wrapper simunet(Adj = Adj,samp.effort = samp.effort,mode = "upper",n.scans = 120L, focal.scan )#> #> scan: 1 #> a . NA NA . NA #> b . . NA . NA #> c . . . . NA #> d . . . . 1 #> e . . . . . #> #> scan: 2 #> a . NA . NA NA #> b . . . NA NA #> c . . . . 1 #> d . . . . NA #> e . . . . . #> #> ... ( 117 more scans) #> #> scan: 120 #> a . 1 NA NA NA #> b . . . . 1 #> c . . . NA NA #> d . . . . NA #> e . . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - focalList - theoretical.scanList#> [[1]] #> #> scan: 1 #> a . 1 1 NA 1 #> b . . . NA . #> c . . . . 1 #> d . . . . . #> e . . . . . #> #> scan: 2 #> a . 1 . NA . #> b . . . . 1 #> c . . . . NA #> d . . . . . #> e . . . . . #> #> ... ( 117 more scans) #> #> scan: 120 #> a . 1 . . 1 #> b . . 1 1 . #> c . . . . 1 #> d . . . . 1 #> e . . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - obs.P - theoretical.scanList #> #> [[2]] #> #> scan: 1 #> a . 1 NA NA NA #> b . . . . . #> c . . . NA NA #> d . . . . NA #> e . . . . . #> #> scan: 2 #> a . NA NA NA . #> b . . NA NA 1 #> c . . . NA 1 #> d . . . . . #> e . . . . . #> #> ... ( 117 more scans) #> #> scan: 120 #> a . NA . NA NA #> b . . 1 NA NA #> c . . . . 1 #> d . . . . NA #> e . . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - focalList - theoretical.scanList #> #> attr(,"class") #> [1] "sLlist"simunet(Adj = Adj,samp.effort = samp.effort,mode = "upper",n.scans = 120L, focal.scan,focal.periRemoved )#> [[1]] #> #> scan: 1 #> a . 1 NA NA NA #> b . . . . . #> c . . . NA NA #> d . . . . NA #> e . . . . . #> #> scan: 2 #> a . 1 NA NA NA #> b . . . . . #> c . . . NA NA #> d . . . . NA #> e . . . . . #> #> ... ( 117 more scans) #> #> scan: 120 #> a . 1 NA NA NA #> b . . . 1 1 #> c . . . NA NA #> d . . . . NA #> e . . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - focalList - theoretical.scanList #> #> [[2]] #> #> scan: 1 #> a . NA . NA #> b . . . NA #> c . . . 1 #> e . . . . #> #> scan: 2 #> a . NA NA . #> b . . NA . #> c . . . 1 #> e . . . . #> #> ... ( 159 more scans) #> #> scan: 162 #> a . 1 NA NA #> b . . 1 1 #> c . . . NA #> e . . . . #> #> #> Hidden attributes: #> scanList.type - raw.scanList - Adj - samp.effort - n.scans - mode #> Adj.subfun - edge.Prob - focalList - theoretical.scanList #> #> attr(,"class") #> [1] "sLlist"