Getting Started

Minimum data requirements for running SPICE algorithms include the two spatial map observations \(x\) and \(y\), and the spatial coordinates of observations \(coord\). When \(coord\) is not available, the algorithm can also run with the pairwise distance matrix between observations \(D\) (see Advanced examples for more details).

\(x\): ndarray (N,) in python; vector (N,1) in MATLAB. Can contain NaN and Inf.

\(y\): ndarray (N,) in python; vector (N,1) in MATLAB. Can contain NaN and Inf.

\(coord\): ndarray (N,dim) in python; vector (N,dim) in MATLAB, where dim is 3 for 3D data.

In this page, we provide guidance to run SPICE and SPICE-NS using the default settings, in MATLAB and Python. This default setting should be sufficient if you aim to:

  1. Run SPICE, or

  2. Run SPICE-NS for large covareage (e.g., whole-brain) maps on a resolution comparable to fsavearge5 10k vertices map.

Otherwise, I recommend see Advanced examples for more details on appropriate use. These advanced examples include but not limited to:

  1. Run SPICE-NS for small data patches (see ‘Controlling for parcels in SPICE-NS’ in Advanced examples).

  2. Run SPIEC-NS using user-defined parcels (see ‘Controlling for parcels in SPICE-NS’ in Advanced examples).

  3. When \(coord\) is missing (see ‘Run with distance matrix’ in Advanced examples).

  4. Run pairwise associations between a large number of spatial maps (see ‘Large-scale pairwise evaluation’ in Advanced examples).

  5. In the presence of spatial trends (see ‘Impact of spatial trends’ in Advanced examples).

SPICE

  • MATLAB
  • python
% take 70-80s to run (Apple Silicon M1 Pro) on fsaverage5 10k cortical map
% pef - significance p-value
% rX - Pearson correlation coefficient
% nef - effective sample size
[pef, rX, nef, run_status, n_parc, p_naive, fc_para1, fc_para2] = effective_sample_size_estimation(x,y,coord);

# take 3.5min to run (Apple Silicon M1 Pro) on fsaverage5 10k cortical map
# pef - significance p-value
# rX - Pearson correlation coefficient
# nef - effective sample size
import spice
pef, rX, nef, run_status, n_parc, p_naive, fc_para1, fc_para2 = spice.effective_sample_size_estimation(x, y, coord)

SPICE-NS

  • MATLAB
  • python
% SPICE-NS with data-driven parcellation
% take 70-80s to run (Apple Silicon M1 Pro) on fsaverage5 10k cortical map
% pef - significance p-value
% rX - Pearson correlation coefficient
% nef - effective sample size
[pef, rX, nef, run_status, n_parc, p_naive, fc_para1, fc_para2] = effective_sample_size_estimation(x,y,coord,'xparc','auto','yparc','auto');

# SPICE-NS with data-driven parcellation
# take 3.5min to run (Apple Silicon M1 Pro) on fsaverage5 10k cortical map
# pef - significance p-value
# rX - Pearson correlation coefficient
# nef - effective sample size
import spice
pef, rX, nef, run_status, n_parc, p_naive, fc_para1, fc_para2 = spice.effective_sample_size_estimation(x, y, coord, xparc='auto', yparc='auto')