docstr: A streamline generator using the particle filtering tractography
  method [1]_.
  
  Parameters
  ----------
  direction_getter : instance of ProbabilisticDirectionGetter
      Used to get directions for fiber tracking.
  stopping_criterion : instance of AnatomicalStoppingCriterion
      Identifies endpoints and invalid points to inform tracking.
  seeds : array (N, 3)
      Points to seed the tracking. Seed points should be given in point
      space of the track (see ``affine``).
  affine : array (4, 4)
      Coordinate space for the streamline point with respect to voxel
      indices of input data. This affine can contain scaling, rotational,
      and translational components but should not contain any shearing.
      An identity matrix can be used to generate streamlines in "voxel
      coordinates" as long as isotropic voxels were used to acquire the
      data.
  step_size : float
      Step size used for tracking.
  max_cross : int or None, optional
      The maximum number of direction to track from each seed in crossing
      voxels. By default all initial directions are tracked.
  maxlen : int, optional
      Maximum length of generated streamlines. Longer streamlines will be
      discarted if `return_all=False`.
  minlen : int, optional
      Minimum length of generated streamlines. Shorter streamlines will
      be discarted if `return_all=False`.
  pft_back_tracking_dist : float
      Distance in mm to back track before starting the particle filtering
      tractography. The total particle filtering tractography distance is
      equal to back_tracking_dist + front_tracking_dist.
      By default this is set to 2 mm.
  pft_front_tracking_dist : float, optional
      Distance in mm to run the particle filtering tractography after the
      the back track distance. The total particle filtering tractography
      distance is equal to back_tracking_dist + front_tracking_dist. By
      default this is set to 1 mm.
  pft_max_trial : int, optional
      Maximum number of trial for the particle filtering tractography
      (Prevents infinite loops).
  particle_count : int, optional
      Number of particles to use in the particle filter.
  return_all : bool, optional
      If true, return all generated streamlines, otherwise only
      streamlines reaching end points or exiting the image.
  random_seed : int, optional
      The seed for the random seed generator (numpy.random.seed and
      random.seed).
  save_seeds : bool, optional
      If True, return seeds alongside streamlines
  min_wm_pve_before_stopping : int, optional
      Minimum white matter pve (1 - stopping_criterion.include_map -
      stopping_criterion.exclude_map) to reach before allowing the
      tractography to stop.
  unidirectional : bool, optional
      If true, the tracking is performed only in the forward direction.
      The seed position will be the first point of all streamlines.
  randomize_forward_direction : bool, optional
      If true, the forward direction is randomized (multiplied by 1
      or -1). Otherwise, the provided forward direction is used.
  initial_directions: array (N, npeaks, 3), optional
      Initial direction to follow from the ``seed`` position. If
      ``max_cross`` is None, one streamline will be generated per peak
      per voxel. If None, `direction_getter.initial_direction` is used.
  
  
  References
  ----------
  .. [1] Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M.
         Towards quantitative connectivity analysis: reducing
         tractography biases. NeuroImage, 98, 266-278, 2014.
docstr_tok: ["A","streamline","generator","using","the","particle","filtering","tractography","method","[","1","]","_.","Parameters","--","--","--","--","--","direction_getter",":","instance","of","ProbabilisticDirectionGetter","Used","to","get","directions","for","fiber","tracking",".","stopping_criterion",":","instance","of","AnatomicalStoppingCriterion","Identifies","endpoints","and","invalid","points","to","inform","tracking",".","seeds",":","array","(","N",",","3",")","Points","to","seed","the","tracking",".","Seed","points","should","be","given","in","point","space","of","the","track","(","see","``","affine","``",")",".","affine",":","array","(","4",",","4",")","Coordinate","space","for","the","streamline","point","with","respect","to","voxel","indices","of","input","data",".","This","affine","can","contain","scaling",",","rotational",",","and","translational","components","but","should","not","contain","any","shearing",".","An","identity","matrix","can","be","used","to","generate","streamlines","in","``","voxel","coordinates","''","as","long","as","isotropic","voxels","were","used","to","acquire","the","data",".","step_size",":","float","Step","size","used","for","tracking",".","max_cross",":","int","or","None",",","optional","The","maximum","number","of","direction","to","track","from","each","seed","in","crossing","voxels",".","By","default","all","initial","directions","are","tracked",".","maxlen",":","int",",","optional","Maximum","length","of","generated","streamlines",".","Longer","streamlines","will","be","discarted","if","`","return_all=False","`",".","minlen",":","int",",","optional","Minimum","length","of","generated","streamlines",".","Shorter","streamlines","will","be","discarted","if","`","return_all=False","`",".","pft_back_tracking_dist",":","float","Distance","in","mm","to","back","track","before","starting","the","particle","filtering","tractography",".","The","total","particle","filtering","tractography","distance","is","equal","to","back_tracking_dist","+","front_tracking_dist",".","By","default","this","is","set","to","2","mm",".","pft_front_tracking_dist",":","float",",","optional","Distance","in","mm","to","run","the","particle","filtering","tractography","after","the","the","back","track","distance",".","The","total","particle","filtering","tractography","distance","is","equal","to","back_tracking_dist","+","front_tracking_dist",".","By","default","this","is","set","to","1","mm",".","pft_max_trial",":","int",",","optional","Maximum","number","of","trial","for","the","particle","filtering","tractography","(","Prevents","infinite","loops",")",".","particle_count",":","int",",","optional","Number","of","particles","to","use","in","the","particle","filter",".","return_all",":","bool",",","optional","If","true",",","return","all","generated","streamlines",",","otherwise","only","streamlines","reaching","end","points","or","exiting","the","image",".","random_seed",":","int",",","optional","The","seed","for","the","random","seed","generator","(","numpy.random.seed","and","random.seed",")",".","save_seeds",":","bool",",","optional","If","True",",","return","seeds","alongside","streamlines","min_wm_pve_before_stopping",":","int",",","optional","Minimum","white","matter","pve","(","1","-","stopping_criterion.include_map","-","stopping_criterion.exclude_map",")","to","reach","before","allowing","the","tractography","to","stop",".","unidirectional",":","bool",",","optional","If","true",",","the","tracking","is","performed","only","in","the","forward","direction",".","The","seed","position","will","be","the","first","point","of","all","streamlines",".","randomize_forward_direction",":","bool",",","optional","If","true",",","the","forward","direction","is","randomized","(","multiplied","by","1","or","-1",")",".","Otherwise",",","the","provided","forward","direction","is","used",".","initial_directions",":","array","(","N",",","npeaks",",","3",")",",","optional","Initial","direction","to","follow","from","the","``","seed","``","position",".","If","``","max_cross","``","is","None",",","one","streamline","will","be","generated","per","peak","per","voxel",".","If","None",",","`","direction_getter.initial_direction","`","is","used",".","References","--","--","--","--","--","..","[","1","]","Girard",",","G.",",","Whittingstall",",","K.",",","Deriche",",","R.",",","&","Descoteaux",",","M.","Towards","quantitative","connectivity","analysis",":","reducing","tractography","biases",".","NeuroImage",",","98",",","266-278",",","2014","."]
code: def __init__(
      self,
      direction_getter,
      stopping_criterion,
      seeds,
      affine,
      step_size,
      max_cross=None,
      maxlen=500,
      minlen=2,
      pft_back_tracking_dist=2,
      pft_front_tracking_dist=1,
      pft_max_trial=20,
      particle_count=15,
      return_all=True,
      random_seed=None,
      save_seeds=False,
      min_wm_pve_before_stopping=0,
      unidirectional=False,
      randomize_forward_direction=False,
      initial_directions=None,
  ):
      r"""A streamline generator using the particle filtering tractography
      method [1]_.
  
      Parameters
      ----------
      direction_getter : instance of ProbabilisticDirectionGetter
          Used to get directions for fiber tracking.
      stopping_criterion : instance of AnatomicalStoppingCriterion
          Identifies endpoints and invalid points to inform tracking.
      seeds : array (N, 3)
          Points to seed the tracking. Seed points should be given in point
          space of the track (see ``affine``).
      affine : array (4, 4)
          Coordinate space for the streamline point with respect to voxel
          indices of input data. This affine can contain scaling, rotational,
          and translational components but should not contain any shearing.
          An identity matrix can be used to generate streamlines in "voxel
          coordinates" as long as isotropic voxels were used to acquire the
          data.
      step_size : float
          Step size used for tracking.
      max_cross : int or None, optional
          The maximum number of direction to track from each seed in crossing
          voxels. By default all initial directions are tracked.
      maxlen : int, optional
          Maximum length of generated streamlines. Longer streamlines will be
          discarted if `return_all=False`.
      minlen : int, optional
          Minimum length of generated streamlines. Shorter streamlines will
          be discarted if `return_all=False`.
      pft_back_tracking_dist : float
          Distance in mm to back track before starting the particle filtering
          tractography. The total particle filtering tractography distance is
          equal to back_tracking_dist + front_tracking_dist.
          By default this is set to 2 mm.
      pft_front_tracking_dist : float, optional
          Distance in mm to run the particle filtering tractography after the
          the back track distance. The total particle filtering tractography
          distance is equal to back_tracking_dist + front_tracking_dist. By
          default this is set to 1 mm.
      pft_max_trial : int, optional
          Maximum number of trial for the particle filtering tractography
          (Prevents infinite loops).
      particle_count : int, optional
          Number of particles to use in the particle filter.
      return_all : bool, optional
          If true, return all generated streamlines, otherwise only
          streamlines reaching end points or exiting the image.
      random_seed : int, optional
          The seed for the random seed generator (numpy.random.seed and
          random.seed).
      save_seeds : bool, optional
          If True, return seeds alongside streamlines
      min_wm_pve_before_stopping : int, optional
          Minimum white matter pve (1 - stopping_criterion.include_map -
          stopping_criterion.exclude_map) to reach before allowing the
          tractography to stop.
      unidirectional : bool, optional
          If true, the tracking is performed only in the forward direction.
          The seed position will be the first point of all streamlines.
      randomize_forward_direction : bool, optional
          If true, the forward direction is randomized (multiplied by 1
          or -1). Otherwise, the provided forward direction is used.
      initial_directions: array (N, npeaks, 3), optional
          Initial direction to follow from the ``seed`` position. If
          ``max_cross`` is None, one streamline will be generated per peak
          per voxel. If None, `direction_getter.initial_direction` is used.
  
  
      References
      ----------
      .. [1] Girard, G., Whittingstall, K., Deriche, R., & Descoteaux, M.
             Towards quantitative connectivity analysis: reducing
             tractography biases. NeuroImage, 98, 266-278, 2014.
      """
  
      if not isinstance(
          stopping_criterion, AnatomicalStoppingCriterion
      ):
          raise ValueError("expecting AnatomicalStoppingCriterion")
  
      self.pft_max_nbr_back_steps = int(
          np.ceil(pft_back_tracking_dist / step_size)
      )
      self.pft_max_nbr_front_steps = int(
          np.ceil(pft_front_tracking_dist / step_size)
      )
      pft_max_steps = (
          self.pft_max_nbr_back_steps + self.pft_max_nbr_front_steps
      )
  
      if (
          self.pft_max_nbr_front_steps < 0
          or self.pft_max_nbr_back_steps < 0
          or pft_max_steps < 1
      ):
          raise ValueError(
              "The number of PFT steps must be greater than 0."
          )
  
      if particle_count <= 0:
          raise ValueError("The particle count must be greater than 0.")
  
      if not 0 <= min_wm_pve_before_stopping <= 1:
          raise ValueError(
              "The min_wm_pve_before_stopping value must be "
              "between 0 and 1."
          )
  
      self.min_wm_pve_before_stopping = min_wm_pve_before_stopping
      self.directions = np.empty((maxlen + 1, 3), dtype=float)
      self.pft_max_trial = pft_max_trial
      self.particle_count = particle_count
      self.particle_paths = np.empty(
          (2, self.particle_count, pft_max_steps + 1, 3), dtype=float
      )
      self.particle_weights = np.empty(self.particle_count, dtype=float)
      self.particle_dirs = np.empty(
          (2, self.particle_count, pft_max_steps + 1, 3), dtype=float
      )
      self.particle_steps = np.empty(
          (2, self.particle_count), dtype=np.intp
      )
      self.particle_stream_statuses = np.empty(
          (2, self.particle_count), dtype=np.intp
      )
      super(ParticleFilteringTracking, self).__init__(
          direction_getter=direction_getter,
          stopping_criterion=stopping_criterion,
          seeds=seeds,
          affine=affine,
          step_size=step_size,
          max_cross=max_cross,
          maxlen=maxlen,
          minlen=minlen,
          fixedstep=True,
          return_all=return_all,
          random_seed=random_seed,
          save_seeds=save_seeds,
          unidirectional=unidirectional,
          randomize_forward_direction=randomize_forward_direction,
          initial_directions=initial_directions,
      )
  
file_path: dipy/dipy/tracking/local_tracking.py
imports: import random
  from collections.abc import Iterable
  from warnings import warn
  import numpy
  from dipy.tracking.localtrack import local_tracker, pft_tracker
  from dipy.tracking.stopping_criterion import AnatomicalStoppingCriterion, StreamlineStatus
  from dipy.tracking import utils
  from dipy.utils import fast_numpy
label_desc: Use image node_id 1 to create a new ParticleFilteringTracking object from inherited base classes: LocalTracking with example: obj = ParticleFilteringTracking(direction_getter, stopping_criterion, seeds, affine, step_size, max_cross, maxlen, minlen, pft_back_tracking_dist, pft_front_tracking_dist, pft_max_trial, particle_count, return_all, random_seed, save_seeds, min_wm_pve_before_stopping, unidirectional, randomize_forward_direction, initial_directions)