code: def surrogate_3d_dataset(
      n_subj=1,
      shape=(20, 20, 20),
      mask=None,
      sk=1.0,
      noise_level=1.0,
      pos=None,
      ampli=None,
      spatial_jitter=1.0,
      signal_jitter=1.0,
      width=5.0,
      out_text_file=None,
      out_image_file=None,
      seed=False,
  ):
      """Create surrogate (simulated) 3D activation data with spatial noise.
  
      Parameters
      -----------
      n_subj: integer, optional
          The number of subjects, ie the number of different maps
          generated.
      shape=(20,20,20): tuple of 3 integers,
           the shape of each image
      mask=None: Nifti1Image instance,
          referential- and mask- defining image (overrides shape)
      sk: float, optional
          Amount of spatial noise smoothness.
      noise_level: float, optional
          Amplitude of the spatial noise.
          amplitude=noise_level)
      pos: 2D ndarray of integers, optional
          x, y positions of the various simulated activations.
      ampli: 1D ndarray of floats, optional
          Respective amplitude of each activation
      spatial_jitter: float, optional
          Random spatial jitter added to the position of each activation,
          in pixel.
      signal_jitter: float, optional
          Random amplitude fluctuation for each activation, added to the
          amplitude specified by ampli
      width: float or ndarray, optional
          Width of the activations
      out_text_file: string or None, optional
          If not None, the resulting array is saved as a text file with the
          given file name
      out_image_file: string or None, optional
          If not None, the resulting is saved as a nifti file with the
          given file name.
      seed=False:  int, optional
          If seed is not False, the random number generator is initialized
          at a certain value
  
      Returns
      -------
      dataset: 3D ndarray
          The surrogate activation map, with dimensions ``(n_subj,) + shape``
      """
      if seed:
          nr = np.random.RandomState([seed])
      else:
          import numpy.random as nr
  
      if mask is not None:
          shape = mask.shape
          mask_data = mask.get_fdata()
      else:
          mask_data = np.ones(shape)
  
      ijk = np.array(np.where(mask_data)).T
      dataset = []
  
      # make the signal
      for s in range(n_subj):
          data = np.zeros(shape)
          lampli = []
          if pos is not None:
              if len(pos) != len(ampli):
                  raise ValueError(
                      "ampli and pos do not have the same len"
                  )
              lpos = pos + spatial_jitter * nr.randn(1, 3)
              lampli = ampli + signal_jitter * nr.randn(np.size(ampli))
          for k in range(np.size(lampli)):
              data = np.maximum(
                  data, _cone3d(shape, ijk, lpos[k], lampli[k], width)
              )
  
          # make some noise
          noise = nr.randn(shape[0], shape[1], shape[2])
  
          # smooth the noise
          noise = nd.gaussian_filter(noise, sk)
          noise *= noise_level / np.std(noise)
  
          # make the mixture
          data += noise
          data[mask_data == 0] = 0
          dataset.append(data)
  
      dataset = np.array(dataset)
      if n_subj == 1:
          dataset = dataset[0]
  
      if out_text_file is not None:
          dataset.tofile(out_text_file)
  
      if out_image_file is not None:
          save(Nifti1Image(dataset, np.eye(4)), out_image_file)
  
      return dataset
  
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 4 for calling a global function with example usage: surrogate_3d_dataset(n_subj, shape, mask, sk, noise_level, pos, ampli, spatial_jitter, signal_jitter, width, out_text_file, out_image_file, seed) and returns: dataset