code: def surrogate_4d_dataset(
      shape=(20, 20, 20),
      mask=None,
      n_scans=1,
      n_sess=1,
      dmtx=None,
      sk=1.0,
      noise_level=1.0,
      signal_level=1.0,
      out_image_file=None,
      seed=False,
  ):
      """Create surrogate (simulated) 3D activation data with spatial noise.
  
      Parameters
      -----------
      shape = (20, 20, 20): tuple of integers,
           the shape of each image
      mask=None: brifti image instance,
          referential- and mask- defining image (overrides shape)
      n_scans: int, optional,
          number of scans to be simlulated
          overridden by the design matrix
      n_sess: int, optional,
          the number of simulated sessions
      dmtx: array of shape(n_scans, n_rows),
          the design matrix
      sk: float, optional
          Amount of spatial noise smoothness.
      noise_level: float, optional
          Amplitude of the spatial noise.
          amplitude=noise_level)
      signal_level: float, optional,
          Amplitude of the signal
      out_image_file: string or list of strings or None, optional
          If not None, the resulting is saved as (set of) nifti file(s) with the
          given file path(s)
      seed=False:  int, optional
          If seed is not False, the random number generator is initialized
          at a certain value
  
      Returns
      -------
      dataset: a list of n_sess ndarray of shape
               (shape[0], shape[1], shape[2], n_scans)
               The surrogate activation map
      """
      if seed:
          nr = np.random.RandomState([seed])
      else:
          import numpy.random as nr
  
      if mask is not None:
          shape = mask.shape
          affine = get_affine(mask)
          mask_data = mask.get_fdata().astype("bool")
      else:
          affine = np.eye(4)
          mask_data = np.ones(shape).astype("bool")
  
      if dmtx is not None:
          n_scans = dmtx.shape[0]
  
      if (out_image_file is not None) and isinstance(
          out_image_file, str
      ):
          out_image_file = [out_image_file]
  
      shape_4d = shape + (n_scans,)
  
      output_images = []
      if dmtx is not None:
          beta = []
          for r in range(dmtx.shape[1]):
              betar = nd.gaussian_filter(nr.randn(*shape), sk)
              betar /= np.std(betar)
              beta.append(signal_level * betar)
          beta = np.rollaxis(np.array(beta), 0, 4)
  
      for ns in range(n_sess):
          data = np.zeros(shape_4d)
  
          # make the signal
          if dmtx is not None:
              data[mask_data] += np.dot(beta[mask_data], dmtx.T)
  
          for s in range(n_scans):
              # make some noise
              noise = nr.randn(*shape)
  
              # smooth the noise
              noise = nd.gaussian_filter(noise, sk)
              noise *= noise_level / np.std(noise)
  
              # make the mixture
              data[:, :, :, s] += noise
              data[:, :, :, s] += 100 * mask_data
  
          wim = Nifti1Image(data, affine)
          output_images.append(wim)
          if out_image_file is not None:
              save(wim, out_image_file[ns])
  
      return output_images
  
file_path: nipy/nipy/labs/utils/simul_multisubject_fmri_dataset.py
imports: import numpy
  import scipy.ndimage
  from nibabel import Nifti1Image, save
  from nipy.io.nibcompat import get_affine
label_desc: Use image node_id 5 for calling a global function with example usage: surrogate_4d_dataset(shape, mask, n_scans, n_sess, dmtx, sk, noise_level, signal_level, out_image_file, seed) and returns: output_images