design_exp: Design experiment to perform on theoretical 'scanList'
In R-KenK/SimuNet: Network Simulation Framework, with a Zest of Empiricism

Description Usage Arguments Details Value See Also Examples

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.

1	design_exp(..., .dir = c("forward", "backward"))

`...`	functions of `scanList` objects. Can be a combination of the provided "building blocks" and user-defined function (cf. the example section).
`.dir`	character scalar, either `"forward"` (default) or `"backward"` (see `purrr`'s `compose()`) to indicate in which order inputted functions should be applied (first function first, or vice versa).

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).

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.

perform_exp(), simunet(), design_sampling().

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

# 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)
perform_exp(sL,focal.periRemoved) |> sum_scans()

## on newly simulated scanList within the simunet() wrapper
simunet(Adj = Adj,samp.effort = samp.effort,mode = "upper",n.scans = 120L,
        focal.scan
)

## performing a list of experiments
perform_exp(sL,group.scan,focal.scan)
simunet(Adj = Adj,samp.effort = samp.effort,mode = "upper",n.scans = 120L,
        focal.scan,focal.periRemoved
)