How to document sample_()

[maelle]

There's a TODO for the details section of the sample_() manual page.

However, it's unclear to me what exactly the arguments of sample_() are. Is it

"One passes the name of a Random graph models (games) function (refer to the 'See also' section) without the sample_ prefix, for instance sbm() rather than sample_sbm(). Arguments to the random graph model function are passed either inside the first argument, or as distinct arguments (refer to the examples).'"?

I also wonder what the use case is for sample_ as opposed to calling the random graph models functions directly?

@szhorvat

library("igraph")
#> 
#> Attaching package: 'igraph'
#> The following objects are masked from 'package:stats':
#> 
#>     decompose, spectrum
#> The following object is masked from 'package:base':
#> 
#>     union
pref_matrix <- cbind(c(0.8, 0.1), c(0.1, 0.7))
withr::with_seed(42, {
  blocky <- sample_(sbm(
    n = 20, pref.matrix = pref_matrix,
    block.sizes = c(10, 10)
  ))
plot(blocky)
})

withr::with_seed(42, {
  blocky2 <- pref_matrix %>%
    sample_sbm(n = 20, block.sizes = c(10, 10))
})
plot(blocky2)

withr::with_seed(42, {
  ## Arguments are passed on from sample_ to sample_sbm
  blocky3 <- pref_matrix %>%
    sample_(sbm(), n = 20, block.sizes = c(10, 10))
plot(blocky3)
})

^{Created on 2024-08-27 with reprex v2.1.0}

[szhorvat]

See how make_ works, and see the examples with modifiers. (That page can use some formatting improvements, #1417) The point is to be able to use modifiers to control the construction.

[maelle]

Thanks! I'll make (or make_ :joy: ) a proposal based on make_ whose See also section I am currently fixing.