# API changes

Here we provide information about functions or classes that have been removed, renamed or are deprecated (not recommended) during different release circles.

## DIPY 1.10.0 changes

General

- PEP 3102 (Keyword-only arguments) has been implemented in the codebase. This means that all the functions/classes that have keyword-only arguments will raise a warning if the user tries to call them with positional arguments.

- Standardized the symbols for the spherical harmonic concepts of order and phase factor with `l_value` and `m_value`, respectively. In case these are arrays, we use `l_values` and `m_values` to be more informative of the type of the variable. For a spherical harmonic 𝑌ℓ𝑚, ℓ is referred to as the order and 𝑚 as phase factor. The parameter `sh_order` in the codebase became `sh_order_max`.

Align

- The alpha parameter in the BundleWarp method has been updated to provide better result for the bundle warping. The default value of alpha has been changed from 0.3 to 0.5.

IO

- The `dipy.io.peaks.save_peaks` and `dipy.io.peaks.load_peaks` functions have been deprecated. Please Use the `dipy.io.peaks.save_pam` and `dipy.io.peaks.load_pam` functions instead.

Reconstruction

- Applied the change of the default cvxpy solver from ECOS to CLARABEL. Starting in CXVPY 1.6.0, ECOS will no longer be installed by default with CVXPY. Since we do not want to add an explicit dependency on ECOS, we switched to the new default solver, Clarabel.

Workflows

- The vol_idx parameter datatype from `dipy_median_otsu` has been changed from variable int to str. this change allows user to provide a range of values for the vol_idx parameter. e.g: –vol_idx 0,1,2 or –vol_idx 4,5,12-20,22.

- The odf_to_sh_order parameter has been removed from multiple workflows. The parameter was not being used and was causing confusion with the sh_order_order parameter.

NN

- A new backend has been added: PyTorch. This backend is becoming the default backend for the NN module. Tensorflow backend is still available but deprecated.

## DIPY 1.9.0 changes

General

- The module `dipy.boots.resampling` has moved to `dipy.stats.resampling`.

- The package `dipy.boots` has been removed.

- FURY minimum version is 0.10.0.

- Multiple deprecated parameters have been removed from the codebase.

IO

- `dipy.io.bvectxt` module is removed

## DIPY 1.8.0 changes

Gradients

- Change in `dipy.core.gradients`, function `reorient_bvecs` now requires the affine to have a shape of (4, 4, n) or (3, 3, n)

Direction

- Change in `dipy.direction.bootstrap_direction_getter`.

    - The parent class was changes from `PmfGenDirectionGetter` to `DirectionGetter`. The `BootPmfGen` functions were merged in `BootDirectionGetter`.

    - The class constructor parameter pmfgen was removed. Parameters data, model and sh_order=0 were added.

    - The class method BootDirectionGetter.from_data() was not changed.

- Change in `dipy.direction.pmf`. The class `BootPmfGen` was removed; its functions were merged in `BootDirectionGetter`.

## DIPY 1.7.0 changes

Denoising

- Change in `dipy.denoise.localpca`, function `genpca` can use fewer images than patch voxels.

- Change in `dipy.denoise.pca_noise_estimate`, function `pca_noise_estimate` has new argument `images_as_samples`

## DIPY 1.6.0 changes

## DIPY 1.5.0 changes

General

- FURY minimum version is 0.8.0

- Distutils has been dropped

- `dipy.io.bvectxt` module is deprecated and will be removed

Denoising

- The default option in the command line for Patch2Self ‘ridge’ -> ‘ols’

Tracking

- Change in `dipy.tracking.pmf`

    - The parent class `PmfGen` has new mandatory parameter `sphere`. The sphere vertices correspond to the spherical distribution of the pmf values.

    - The parent class `PmfGen` has new function `get_pmf_value(point, xyz)` which return the pmf value at location `point` and orientation `xyz`.

Segment

- The deprecated `from dipy.segment.metric import ResampleFeature` was removed and replaced by `from dipy.segment.featurespeed import ResampleFeature`.

## DIPY 1.4.1 changes

General

- The name of the argument for the number of cores/threads has been standardized to:

    - `num_threads` for OpenMP parallelization.

    - `num_processes` for parallelization using multiprocessing package.

- Change in the parallelization logic when using OpenMP:

    - If `num_threads = None` the value of `OMP_NUM_THREADS` environment variable is used. If it is not set then all available threads are used.

    - If `num_threads > 0` that number is used as the number of threads.

    - If `num_threads < 0` the maximum between `1` and `num_cpu_cores - |num_threads + 1|` is selected. If `-1` then all available threads are used.

    - If `num_threads = 0` an error is raised.

- Change in the parallelization logic when using multiprocessing package:

    - The same as with OpenMP with the difference that `num_processes = None` uses all cores directly.

Tracking

- Change in DirectionGetters:

    - The deprecated `dipy.direction.closest_peak_direction_getter.BaseDirectionGetter` was removed and replaced by `dipy.direction.closest_peak_direction_getter.BasePmfDirectionGetter`.

    - The deprecated `dipy.reconst.EuDXDirectionGetter` was removed and replaced by `dipy.reconst.eudx_direction_getter.EuDXDirectionGetter`.

## DIPY 1.4.0 changes

- Migration from Tavis to Azure

## DIPY 1.3.0 changes

- new dependency added: tqdm

Registration

- The argument interp of the method dipy.align.imaffine.AffineMap.transform has been renamed interpolation.

- The argument interp of the method dipy.align.imaffine.AffineMap.transform_inverse has been renamed interpolation.

Segmentation

- The tissue segmentation method `dipy.segment.TissueClassifierHMRF` now checks the tolerance-based stopping criterion at every iteration (previously it was only checked every 10th iteration). This may result in earlier termination of iterations than with previous releases.

## DIPY 1.2.0 changes

Reconstruction

The `dipy.reconst.csdeconv.auto_response` has been renamed `dipy.reconst.csdeconv.auto_response_ssst`.

The `dipy.reconst.csdeconv.response_from_mask` has been renamed `dipy.reconst.csdeconv.response_from_mask_ssst`.

The `dipy.sims.voxel.multi_shell_fiber_response` has been moved to `dipy.reconst.mcsd.multi_shell_fiber_response`.

Segmentation

In prior releases, for users with SciPy < 1.5, a memory overlap bug occurs in `multi_median`, causing an overly smooth output. This has now been fixed, regardless of the user’s installed SciPy version. Users of this function via `median_otsu` thresholding should check the output of their image processing pipelines after the 1.2.0 release to make sure thresholding is still operating as expected (if not, try readjusting the `median_radius` parameter).

Tracking

The `dipy.reconst.peak_direction_getter.EuDXDirectionGetter` has been renamed `dipy.reconst.eudx_direction_getter.EuDXDirectionGetter`.

The command line `dipy_track_local` has been renamed `dipy_track`.

Others

The `dipy.core.gradients.unique_bvals` has been renamed `dipy.core.gradients.unique_bvals_magnitude`.

Visualization

- Use `window.Scene()` instead of `window.Renderer()`.

- Use `scene.clear()` instead of `window.rm_all(scene)`.

- Use `scene.clear()` instead of `window.clear(scene)`.

## DIPY 1.1.1 changes

IO

`img.get_data()` is deprecated since Nibabel 3.0.0. Using `np.asanyarray(img.dataobj)` instead of `img.get_data()`.

Tractogram

`dipy.io.streamlines.StatefulTractogram` can be created by another one.

Workflows

`dipy_nlmeans` command lines have been renamed `dipy_denoise_nlmeans`.

Others

`get_data` has been deprecated by Nibabel and replaced by `get_fdata`. This modification has been applied to all the codebase. The default datatype is now float64.

## DIPY 1.0.0 changes

Some of the changes introduced in the 1.0 release will break backward compatibility with previous versions. This release is compatible with Python 3.5+

Reconstruction

The spherical harmonics bases `mrtrix` and `fibernav` have been renamed to `tournier07` and `descoteaux07` after the deprecation cycle started in the 0.15 release.

We changed `dipy.data.default_sphere` from symmetric724 to repulsion724 which is more evenly distributed.

Segmentation

The API of `dipy.segment.mask.median_otsu` has changed in the following ways: if you are providing a 4D volume, vol_idx is now a required argument. The order of parameters has also changed.

Tractogram loading and saving

The API of `dipy.io.streamlines.load_tractogram` and `dipy.io.streamlines.save_tractogram` has changed in the following ways: When loading trk, tck, vtk, fib, or dpy) a reference nifti file is needed to guarantee proper spatial transformation handling.

Spatial transformation handling

Functions from `dipy.tracking.streamlines` were modified to enforce the affine parameter and uniform docstrings. `deform_streamlines` `select_by_rois`, `orient_by_rois`, `_extract_vals` and `values_from_volume`.

Functions from `dipy.tracking.utils` were modified to enforce the affine parameter and uniform docstring. `density_map` `connectivity_matrix`, `seeds_from_mask`, `random_seeds_from_mask`, `target`, `target_line_based`, `near_roi`, `length` and `path_length` were all modified.

The function `affine_for_trackvis`, `move_streamlines`, `flexi_tvis_affine` and `get_flexi_tvis_affine` were deleted.

Functions from `dipy.tracking.life` were modified to enforce the affine parameter and uniform docstring. `voxel2streamline`, `setup` and `fit` from class `FiberModel` were all modified.

`afq_profile` from `dipy.stats.analysis` was modified similarly.

Simulations

- `dipy.sims.voxel.SingleTensor` has been replaced by `dipy.sims.voxel.single_tensor`

- `dipy.sims.voxel.MultiTensor` has been replaced by `dipy.sims.voxel.multi_tensor`

- `dipy.sims.voxel.SticksAndBall` has been replaced by `dipy.sims.voxel.sticks_and_ball`

Interpolation

All interpolation functions have been moved to a new module name dipy.core.interpolation

Tracking

The voxel_size parameter has been removed from the following function:

- `dipy.tracking.utils.connectivity_matrix`

- `dipy.tracking.utils.density_map`

- `dipy.tracking.utils.stremline_mapping`

- `dipy.tracking._util._mapping_to_voxel`

The `dipy.reconst.peak_direction_getter.PeaksAndMetricsDirectionGetter` has been renamed `dipy.reconst.peak_direction_getter.EuDXDirectionGetter`.

The LocalTracking and ParticleFilteringTracking functions were moved from `dipy.tracking.local.localtracking` to `dipy.tracking.local_tracking`. They now need to be imported from `dipy.tracking.local_tracking`.

- functions argument tissue_classifier were renamed stopping_criterion

The TissueClassifier were renamed StoppingCriterion and moved from `dipy.tracking.local.tissue_classifier` to `dipy.tracking.stopping_criterion`. They now need to be imported from `dipy.tracking.stopping_criterion`.

- TissueClassifier -> StoppingCriterion

- BinaryTissueClassifier -> BinaryStoppingCriterion

- ThresholdTissueClassifier -> ThresholdStoppingCriterion

- ConstrainedTissueClassifier -> AnatomicalStoppingCriterion

- ActTissueClassifier -> ActStoppingCriterion

- CmcTissueClassifier -> CmcStoppingCriterion

The `dipy.tracking.local.tissue_classifier.TissueClass` was renamed `dipy.tracking.stopping_criterion.StreamlineStatus`.

The EuDX tracking function has been removed. EuDX tractography can be performed using `dipy.tracking.local_tracking` using `dipy.reconst.peak_direction_getter.EuDXDirectionGetter`.

Streamlines

`dipy.io.trackvis` has been removed. Use `dipy.io.streamline` instead.

Other

- `dipy.external` package has been removed.

- `dipy.fixes` package has been removed.

- `dipy.segment.quickbundes` module has been removed.

- `dipy.reconst.peaks` module has been removed.

- Compatibility with Python 2.7 has been removed.

## DIPY 0.16 Changes

Stats

Welcome to the new module `dipy.viz.stats`. This module will be used to integrate various analyses.

Tracking

- New option to adjust the number of threads for SLR in Recobundles

- The tracking algorithm excludes the stop point inside the mask during the tracking process.

Notes

- Replacement of Nose by Pytest

## DIPY 0.15 Changes

IO

`load_tck` and `save_tck` from `dipy.io.streamline` have been added. They are highly recommended for managing streamlines.

Gradient Table

The default value of `b0_thresold` has been changed(from 0 to 50). This change can impact your algorithm. If you want to assure that your code runs in exactly the same manner as before, please initialize your gradient table with the keyword argument `b0_threshold` set to 0.

Visualization

`dipy.viz.fvtk` module has been removed. Use `dipy.viz.*` instead. This implies the following important changes: - Use `from dipy.viz import window, actor` instead of `from dipy.viz import fvtk`. - Use ``window.Renderer()` instead of `fvtk.ren()`. - All available actors are in `dipy.viz.actor` instead of `dipy.fvtk.actor`. - UI elements are available in `dipy.viz.ui`.

`dipy.viz` depends on the FURY package. To learn more about FURY, go to https://fury.gl

## DIPY 0.14 Changes

Streamlines

`dipy.io.trackvis` module is deprecated. Use `dipy.io.streamline` instead. Furthermore, `load_trk` and `save_trk` from `dipy.io.streamline` is highly recommended for managing streamlines. When you create streamlines, you should use `from dipy.tracking.streamlines import Streamlines`. This new object uses much less memory and it is easier to process.

Visualization

`dipy.viz.fvtk` module is deprecated. Use `dipy.viz.*` instead. This implies the following important changes: - Use `from dipy.viz import window, actor` instead of `from dipy.viz import fvtk`. - Use ``window.Renderer()` instead of `fvtk.ren()`. - All available actors are in `dipy.viz.actor` instead of `dipy.fvtk.actor`. - UI elements are available in `dipy.viz.ui`.

## DIPY 0.13 Changes

No major API changes.

Notes

`dipy.io.trackvis` module will be deprecated on release 0.14. Use `dipy.io.streamline` instead. `dipy.viz.fvtk` module will be deprecated on release 0.14. Use `dipy.viz.ui` instead.

## DIPY 0.12 Changes

Dropped support for Python 2.6*

It has been 6 years since the release of Python 2.7, and multiple other versions have been released since. As far as we know, DIPY still works well on Python 2.6, but we no longer test on this version, and we recommend that users upgrade to Python 2.7 or newer to use DIPY.

Tracking

`probabilistic_direction_getter.ProbabilisticDirectionGetter` input parameters have changed. Now the optional parameter `pmf_threshold=0.1` (previously fixed to 0.0) removes directions with probability lower than `pmf_threshold` from the probability mass function (pmf) when selecting the tracking direction.

DKI

The default of DKI model fitting was changed from “OLS” to “WLS”.

The default max_kurtosis of the functions axial_kurtosis, mean_kurtosis, radial_kurotis was changed from 3 to 10.

Visualization

Prefer using the UI elements in `dipy.viz.ui` rather than `dipy.viz.widgets`.

IO

Use the module `nibabel.streamlines` for saving trk files and not `nibabel.trackvis`. Requires upgrading to nibabel 2+.

## DIPY 0.10 Changes

New visualization module

`fvtk.slicer` input parameters have changed. Now the slicer function is more powerful and supports RGB images too. See tutorial `viz_slice.py` for more information.

Interpolation The default behavior of the function core.sphere.interp_rbf has changed. The default smoothing parameter is now set to 0.1 (previously 0). In addition, the default norm is now angle (was previously euclidean_norm). Note that the use of euclidean_norm is discouraged, and this norm will be deprecated in the 0.11 release cycle.

Registration

The following utility functions from `vector_fields` module were renamed:

`warp_2d_affine` is now `transform_2d_affine` `warp_2d_affine_nn` is now `transform_2d_affine_nn` `warp_3d_affine` is now `transform_3d_affine` `warp_3d_affine_nn` is now `transform_3d_affine_nn`

## DIPY 0.9 Changes

GQI integration length

The calculation of integration length in GQI2 now matches the calculation in the ‘standard’ method. Using values of 1-1.3 for either is recommended (see docs and references therein).

## DIPY 0.8 Changes

Peaks

The module `peaks` is now available from `dipy.direction` and it can still be accessed from `dipy.reconst` but it will be completely removed in version 0.10.

Resample

The function `resample` from `dipy.align.aniso2iso` is deprecated. Please, use instead `reslice` from `dipy.align.reslice`. The module `aniso2iso` will be completely removed in version 0.10.

## Changes between 0.7.1 and 0.6

Peaks_from_model

The function `peaks_from_model` is now available from `dipy.reconst.peaks` . Please replace all imports like:

    from dipy.reconst.odf import peaks_from_model

with:

    from dipy.reconst.peaks import peaks_from_model

Target

The function `target` from `dipy.tracking.utils` now takes an affine transform instead of a voxel sizes array. Please update all code using `target` in a way similar to this:

    img = nib.load(anat)
    voxel_dim = img.header['pixdim'][1:4]
    streamlines = utils.target(streamlines, img.get_data(), voxel_dim)

to something similar to:

    img = nib.load(anat)
    streamlines = utils.target(streamlines, img.get_data(), img.affine)