sigdots_control() collects the settings of sigdots() that rarely need changing. Its
defaults are the values used in the SigDoTS paper. Pass its result as the control argument
of sigdots(), for example
sigdots(x, coords, K0 = 10, control = sigdots_control(ell_range = c(0.3, 80))); settings
not named keep their defaults.
Usage
sigdots_control(
k_nn = 6,
n_comp_min = 0.01,
min_node_size = 20,
min_child_size = 8,
B_cap = 5000,
eta_min = 0.01,
ell_range = c(0.3, 40),
ell_candidates = 160,
pairs_per_bin = 4000,
min_pairs_per_bin = 200,
r_cap = 30,
ridge = 1e-06,
nugget = 1e-06,
max_exact_memory_gib = 16,
candidate_seed = NULL,
normal_band = 10
)Arguments
- k_nn
The number of nearest spots each spot is linked to (a whole number, 6 by default; on the hexagonal Visium array each spot has 6 nearest neighbours). Two candidate domains are neighbours, and can be merged into one part of the tree, when some of their spots are linked. The same links are used for every simulated dataset.
- n_comp_min
A number greater than 0 and at most 1 (0.01 by default). When the spots of a candidate domain fall into separate pieces on the nearest-neighbour links, pieces with fewer spots than this share of the candidate domain are ignored when deciding which candidate domains are neighbours, so that a few stray spots do not make distant candidate domains neighbours. If ignoring them would leave the candidate domains unconnected, all pieces are used.
- min_node_size
A whole number (20 by default). A part of the tree with fewer spots is not tested and is reported as a domain.
- min_child_size
A whole number (8 by default). A split that would leave fewer spots than this on either side is not tested, and the part is reported as a domain. A simulated dataset whose top split leaves fewer spots on a side is replaced by a new one, so that the test keeps its number of simulated datasets (
summary()lists how many were replaced). If such simulated datasets outnumber the valid ones, the part is not tested, its spots get no domain, andsigdots()warns.- B_cap
The largest number of simulated datasets a single Monte Carlo test may use (a whole number, 5000 by default, at least
B_max). A test on m of n spots needs about(n - 1) / (alpha * (m - 1))simulated datasets to keep a split, so a test on a small part of a large sample may need more thanB_cap; that part is then reported as a domain without a test, andsigdots()warns. Not used bypvalue_method = "normal_adaptive".- eta_min
The smallest value allowed for
eta, the share of the noise variance that is spatially correlated (a number greater than 0 and smaller than 1, 0.01 by default; the largest value is 1).- ell_range
The range searched for
ell, the distance over which the noise is spatially correlated: two increasing positive numbers, in spot spacings (the median distance from a spot to its nearest other spot in the part being tested),c(0.3, 40)by default.ellis also kept below twice the largest distance between two spots of the same candidate domain. Whensigdots()warns thatellis at the upper end of this range, the true range may be longer, which can make splits easier to keep; rerun with a wider range, for examplec(0.3, 80).- ell_candidates
The number of values of
elltried inell_range, evenly spaced on a log scale (a whole number from 2, 160 by default); the best of them is then refined between its two neighbouring values.- pairs_per_bin, min_pairs_per_bin
etaandellare estimated from pairs of spots in the same candidate domain, grouped by their distance into classes (one per spot spacing from 0.5 to 30.5 spacings, then 30.5-35.5, 35.5-42.5, 42.5-55.5 and 55.5-75 spacings). At mostpairs_per_binpairs (a whole number, 4000 by default) are drawn at random from each class, and a class with fewer thanmin_pairs_per_binpairs (200 by default) is not used. At least 4 usable classes are needed; a part with fewer is not tested, its spots get no domain, andsigdots()warns.- r_cap
The largest number of strong components kept in the correlation between genes of the simulated data (a whole number, 30 by default). The number actually kept is estimated from the data at every test.
- ridge, nugget
Small non-negative numbers added to the diagonals of the gene covariance and of the spatial covariance matrices, for numerical stability (both 1e-6 by default).
- max_exact_memory_gib
For
spatial_method = "exact": the largest memory, in GiB (1 GiB = 2^30 bytes), a test may need (a positive number, 16 by default). If a test is estimated to need more, the run stops before it starts and suggests the Vecchia approximation or a larger value. 16 GiB is reached at about 19,800 spots.- candidate_seed
The random seed used to make the candidate domains (k-means, BANKSY or BayesSpace), one number.
NULL(the default) uses theseedofsigdots(). Setting it separately keeps the candidate domains fixed whileseedchanges the simulated datasets.- normal_band
For
pvalue_method = "normal_adaptive": a number larger than 1 (10 by default). A test whose first p-value lies between its level divided bynormal_bandand its level multiplied bynormal_bandsimulates more datasets, up tonormal_n_refine, before deciding.
Value
A list of class "sigdots_control" holding the settings, for the control argument
of sigdots(). Every value is checked when the list is made; an invalid one stops with a
message naming the setting.
Details
Most analyses need none of these changed. The ones you may need: ell_range and
B_cap, when sigdots() warns about them; max_exact_memory_gib, to use the exact
computation on a large sample; candidate_seed, to reproduce the candidate domains of an
earlier run. Values other than the defaults have not been evaluated.
Examples
sigdots_control()
#> $k_nn
#> [1] 6
#>
#> $n_comp_min
#> [1] 0.01
#>
#> $min_node_size
#> [1] 20
#>
#> $min_child_size
#> [1] 8
#>
#> $B_cap
#> [1] 5000
#>
#> $eta_min
#> [1] 0.01
#>
#> $ell_range
#> [1] 0.3 40.0
#>
#> $ell_candidates
#> [1] 160
#>
#> $pairs_per_bin
#> [1] 4000
#>
#> $min_pairs_per_bin
#> [1] 200
#>
#> $r_cap
#> [1] 30
#>
#> $ridge
#> [1] 1e-06
#>
#> $nugget
#> [1] 1e-06
#>
#> $max_exact_memory_gib
#> [1] 16
#>
#> $candidate_seed
#> NULL
#>
#> $normal_band
#> [1] 10
#>
#> attr(,"class")
#> [1] "sigdots_control"
sigdots_control(ell_range = c(0.3, 80), B_cap = 20000)
#> $k_nn
#> [1] 6
#>
#> $n_comp_min
#> [1] 0.01
#>
#> $min_node_size
#> [1] 20
#>
#> $min_child_size
#> [1] 8
#>
#> $B_cap
#> [1] 20000
#>
#> $eta_min
#> [1] 0.01
#>
#> $ell_range
#> [1] 0.3 80.0
#>
#> $ell_candidates
#> [1] 160
#>
#> $pairs_per_bin
#> [1] 4000
#>
#> $min_pairs_per_bin
#> [1] 200
#>
#> $r_cap
#> [1] 30
#>
#> $ridge
#> [1] 1e-06
#>
#> $nugget
#> [1] 1e-06
#>
#> $max_exact_memory_gib
#> [1] 16
#>
#> $candidate_seed
#> NULL
#>
#> $normal_band
#> [1] 10
#>
#> attr(,"class")
#> [1] "sigdots_control"
