class_docstr: Distributed Searchlight
  
  Run a user-defined function over each voxel in a multi-subject
  dataset.
  
  Optionally, users can define a block function which runs over
  larger portions of the volume called blocks.
  
  Parameters
  ----------
  
  sl_rad: radius, in voxels, of the sphere inscribed in the
             searchlight cube, not counting the center voxel
  
  max_blk_edge: max edge length, in voxels, of the 3D block
  
  shape: brainiak.searchlight.searchlight.Shape indicating the
  shape in voxels of the searchlight region
  
  min_active_voxels_proportion: float
      If a searchlight region does not have more than this minimum
      proportion of active voxels in the mask, it is not processed by the
      searchlight function. The mask used for the test is the
      intersection of the global (brain) mask and the `Shape` mask. The
      seed (central) voxel of the searchlight region is taken into
      consideration.
class_docstr_tok: ["Distributed","Searchlight","Run","a","user-defined","function","over","each","voxel","in","a","multi-subject","dataset",".","Optionally",",","users","can","define","a","block","function","which","runs","over","larger","portions","of","the","volume","called","blocks",".","Parameters","--","--","--","--","--","sl_rad",":","radius",",","in","voxels",",","of","the","sphere","inscribed","in","the","searchlight","cube",",","not","counting","the","center","voxel","max_blk_edge",":","max","edge","length",",","in","voxels",",","of","the","3D","block","shape",":","brainiak.searchlight.searchlight.Shape","indicating","the","shape","in","voxels","of","the","searchlight","region","min_active_voxels_proportion",":","float","If","a","searchlight","region","does","not","have","more","than","this","minimum","proportion","of","active","voxels","in","the","mask",",","it","is","not","processed","by","the","searchlight","function",".","The","mask","used","for","the","test","is","the","intersection","of","the","global","(","brain",")","mask","and","the","`","Shape","`","mask",".","The","seed","(","central",")","voxel","of","the","searchlight","region","is","taken","into","consideration","."]
docstr: Distribute data to MPI ranks
  
  Parameters
  ----------
  
  subjects : list of 4D arrays containing data for one or more subjects.
        Each entry of the list must be present on at most one rank,
        and the other ranks contain a "None" at this list location.
  
        For example, for 3 ranks you may lay out the data in the
        following manner:
  
        Rank 0: [Subj0, None, None]
        Rank 1: [None, Subj1, None]
        Rank 2: [None, None, Subj2]
  
        Or alternatively, you may lay out the data in this manner:
  
        Rank 0: [Subj0, Subj1, Subj2]
        Rank 1: [None, None, None]
        Rank 2: [None, None, None]
  
  mask: 3D array with "True" entries at active vertices
docstr_tok: ["Distribute","data","to","MPI","ranks","Parameters","--","--","--","--","--","subjects",":","list","of","4D","arrays","containing","data","for","one","or","more","subjects",".","Each","entry","of","the","list","must","be","present","on","at","most","one","rank",",","and","the","other","ranks","contain","a","``","None","''","at","this","list","location",".","For","example",",","for","3","ranks","you","may","lay","out","the","data","in","the","following","manner",":","Rank","0",":","[","Subj0",",","None",",","None","]","Rank","1",":","[","None",",","Subj1",",","None","]","Rank","2",":","[","None",",","None",",","Subj2","]","Or","alternatively",",","you","may","lay","out","the","data","in","this","manner",":","Rank","0",":","[","Subj0",",","Subj1",",","Subj2","]","Rank","1",":","[","None",",","None",",","None","]","Rank","2",":","[","None",",","None",",","None","]","mask",":","3D","array","with","``","True","''","entries","at","active","vertices"]
code: def distribute(self, subjects, mask):
      """Distribute data to MPI ranks
  
      Parameters
      ----------
  
      subjects : list of 4D arrays containing data for one or more subjects.
            Each entry of the list must be present on at most one rank,
            and the other ranks contain a "None" at this list location.
  
            For example, for 3 ranks you may lay out the data in the
            following manner:
  
            Rank 0: [Subj0, None, None]
            Rank 1: [None, Subj1, None]
            Rank 2: [None, None, Subj2]
  
            Or alternatively, you may lay out the data in this manner:
  
            Rank 0: [Subj0, Subj1, Subj2]
            Rank 1: [None, None, None]
            Rank 2: [None, None, None]
  
      mask: 3D array with "True" entries at active vertices
  
      """
      if mask.ndim != 3:
          raise ValueError("mask should be a 3D array")
  
      for idx, subj in enumerate(subjects):
          if subj is not None:
              if subj.ndim != 4:
                  raise ValueError(
                      "subjects[{}] must be 4D".format(idx)
                  )
  
      self.mask = mask
      rank = self.comm.rank
  
      # Get/set ownership
      ownership = self._get_ownership(subjects)
      all_blocks = self._get_blocks(mask) if rank == 0 else None
      all_blocks = self.comm.bcast(all_blocks)
  
      # Divide data and mask
      splitsubj = [
          self._split_volume(s, all_blocks) if s is not None else None
          for s in subjects
      ]
      submasks = self._split_volume(mask, all_blocks)
  
      # Scatter points, data, and mask
      self.blocks = self._scatter_list(all_blocks, 0)
      self.submasks = self._scatter_list(submasks, 0)
      self.subproblems = [
          self._scatter_list(s, ownership[s_idx])
          for (s_idx, s) in enumerate(splitsubj)
      ]
  
imports: from multiprocessing import Pool
  import numpy
  from mpi4py import MPI
  from scipy.spatial.distance import cityblock, euclidean
  from ..utils.utils import usable_cpu_count
label_desc: Use image node_id 7 for calling the Searchlight obj's underlying member method code with example usage: obj.distribute(subjects, mask) without return types