# `direction`

## Module: `direction.peaks`

`PeaksAndMetrics` |
`peak_directions_nl`(sphere_eval, *[, ...]) | Non Linear Direction Finder.
`peaks_from_model`(model, data, sphere, ...[, ...]) | Fit the model to data and computes peaks and metrics
`reshape_peaks_for_visualization`(peaks) | Reshape peaks for visualization.
`peaks_from_positions`(positions, odfs, ...[, ...]) | Extract the peaks at each positions.

### `PeaksAndMetrics`

class dipy.direction.peaks.PeaksAndMetrics

  Bases: `EuDXDirectionGetter`

  Attributes:
    ang_thr
    qa_thr
    total_weight

  Methods

  `initial_direction`(point) | The best starting directions for fiber tracking from point

  generate_streamline |
  get_direction |

### peak_directions_nl

dipy.direction.peaks.peak_directions_nl(sphere_eval, *, relative_peak_threshold=0.25, min_separation_angle=25, sphere=<dipy.core.sphere.HemiSphere object>, xtol=1e-07)

  Non Linear Direction Finder.

  Parameters:
    sphere_eval callable

      A function which can be evaluated on a sphere.

    relative_peak_threshold float

      Only return peaks greater than `relative_peak_threshold * m` where m is the largest peak.

    min_separation_angle float in [0, 90]

      The minimum distance between directions. If two peaks are too close only the larger of the two is returned.

    sphere Sphere

      A discrete Sphere. The points on the sphere will be used for initial estimate of maximums.

    xtol float

      Relative tolerance for optimization.

  Returns:
    directions array (N, 3)

      Points on the sphere corresponding to N local maxima on the sphere.

    values array (N,)

      Value of sphere_eval at each point on directions.

### peaks_from_model

dipy.direction.peaks.peaks_from_model(model, data, sphere, relative_peak_threshold, min_separation_angle, *, mask=None, return_odf=False, return_sh=True, gfa_thr=0, normalize_peaks=False, sh_order_max=8, sh_basis_type=None, legacy=True, npeaks=5, B=None, invB=None, parallel=False, num_processes=None)

  Fit the model to data and computes peaks and metrics

  Parameters:
    model a model instance

      model will be used to fit the data.

    data ndarray

      Diffusion data.

    sphere Sphere

      The Sphere providing discrete directions for evaluation.

    relative_peak_threshold float

      Only return peaks greater than `relative_peak_threshold * m` where m is the largest peak.

    min_separation_angle float in [0, 90] The minimum distance between

      directions. If two peaks are too close only the larger of the two is returned.

    mask array, optional

      If mask is provided, voxels that are False in mask are skipped and no peaks are returned.

    return_odf bool

      If True, the odfs are returned.

    return_sh bool

      If True, the odf as spherical harmonics coefficients is returned

    gfa_thr float

      Voxels with gfa less than gfa_thr are skipped, no peaks are returned.

    normalize_peaks bool

      If true, all peak values are calculated relative to max(odf).

    sh_order_max int, optional

      Maximum SH order (l) in the SH fit. For sh_order_max, there will be `(sh_order_max + 1) * (sh_order_max + 2) / 2` SH coefficients (default 8).

    sh_basis_type{None, ‘tournier07’, ‘descoteaux07’}

      `None` for the default DIPY basis, `tournier07` for the Tournier 2007 :footcite:p:Tournier2007` basis, and `descoteaux07` for the Descoteaux 2007 :footcite:p:Descoteaux2007` basis (`None` defaults to `descoteaux07`).

    legacy: bool, optional

      True to use a legacy basis definition for backward compatibility with previous `tournier07` and `descoteaux07` implementations.

    npeaks int

      Maximum number of peaks found (default 5 peaks).

    B ndarray, optional

      Matrix that transforms spherical harmonics to spherical function `sf = np.dot(sh, B)`.

    invB ndarray, optional

      Inverse of B.

    parallel: bool

      If True, use multiprocessing to compute peaks and metric (default False). Temporary files are saved in the default temporary directory of the system. It can be changed using `import tempfile` and `tempfile.tempdir = '/path/to/tempdir'`.

    num_processes: int, optional

      If parallel is True, the number of subprocesses to use (default multiprocessing.cpu_count()). If < 0 the maximal number of cores minus `num_processes + 1` is used (enter -1 to use as many cores as possible). 0 raises an error.

  Returns:
    pam PeaksAndMetrics

      An object with `gfa`, `peak_directions`, `peak_values`, `peak_indices`, `odf`, `shm_coeffs` as attributes

  References

### reshape_peaks_for_visualization

dipy.direction.peaks.reshape_peaks_for_visualization(peaks)

  Reshape peaks for visualization.

  Reshape and convert to float32 a set of peaks for visualisation with mrtrix or the fibernavigator.

  Parameters:
    peaks: nd array (…, N, 3) or PeaksAndMetrics object

      The peaks to be reshaped and converted to float32.

  Returns:
    peaks nd array (…, 3*N)

### peaks_from_positions

dipy.direction.peaks.peaks_from_positions(positions, odfs, sphere, affine, *, pmf_gen=None, relative_peak_threshold=0.5, min_separation_angle=25, is_symmetric=True, npeaks=5)

  Extract the peaks at each positions.

  Parameters:
    position array, (N, 3)

      World coordinates of the N positions.

    odfs array, (X, Y, Z, M)

      Orientation distribution function (spherical function) represented on a sphere of M points.

    sphere Sphere

      A discrete Sphere. The M points on the sphere correspond to the points of the odfs.

    affine array (4, 4)

      The mapping between voxel indices and the point space for positions.

    pmf_gen PmfGen

      Probability mass function generator from voxel orientation information. Replaces `odfs` and `sphere` when used.

    relative_peak_threshold float, optional

      Only peaks greater than `min + relative_peak_threshold * scale` are kept, where `min = max(0, odf.min())` and `scale = odf.max() - min`. The `relative_peak_threshold` should be in the range [0, 1].

    min_separation_angle float, optional

      The minimum distance between directions. If two peaks are too close only the larger of the two is returned. The `min_separation_angle` should be in the range [0, 90].

    is_symmetric bool, optional

      If True, v is considered equal to -v.

    npeaks int, optional

      The maximum number of peaks to extract at from each position.

  Returns:
    peaks_arr array (N, npeaks, 3)