kwneuro.csd
===========

.. py:module:: kwneuro.csd


Functions
---------

.. autoapisummary::

   kwneuro.csd.combine_response_functions
   kwneuro.csd.estimate_response_function
   kwneuro.csd.compute_csd_fods
   kwneuro.csd.compute_csd_peaks
   kwneuro.csd.combine_csd_peaks_to_vector_volume


Module Contents
---------------

.. py:function:: combine_response_functions(responses: list[kwneuro.resource.ResponseFunctionResource]) -> kwneuro.resource.InMemoryResponseFunctionResource

   Combines multiple response functions into a single group average using the MRtrix3 approach.

   This function harmonizes subjects by scaling their SH coefficients so that the
   isotropic component (L=0) of each subject matches the group's mean L=0 intensity.
   This ensures that differences in scanner gain or global signal intensity do not
   bias the shape of the resulting group-average response.

   :param responses: List of ResponseFunctionResource objects to be combined.

   Returns: An InMemoryResponseFunctionResource containing the combined group-average response function.


.. py:function:: estimate_response_function(dwi: kwneuro.dwi.Dwi, mask: kwneuro.resource.VolumeResource, flip_bvecs_x: bool = True, fa_thr: float = 0.8, sh_order_max: int = 8) -> kwneuro.resource.InMemoryResponseFunctionResource

   Estimate the single-shell single-tissue response function from a DWI dataset using the SSST method.
   :param dwi: The Diffusion Weighted Imaging (DWI) dataset.
   :param mask: A binary brain mask volume. This is used to extract an ROI at the center of the brain.
   :param flip_bvecs_x: Whether to flip the x-component of the b-vectors to match MRtrix3 convention.
   :param fa_thr: FA threshold for calculating the response function.
   :param sh_order_max: Maximum spherical harmonic order to use for the basis model. Default is 8.

   Returns: A resource containing the estimated single-tissue response function.


.. py:function:: compute_csd_fods(dwi: kwneuro.dwi.Dwi, mask: kwneuro.resource.VolumeResource, response: kwneuro.resource.ResponseFunctionResource | None = None, flip_bvecs_x: bool = True, mrtrix_format: bool = False, sh_order_max: int = 8) -> numpy.ndarray

   Computes Fiber Orientation Distributions (FODs) from a DWI dataset using Constrained Spherical Deconvolution (CSD).

   :param dwi: The Diffusion Weighted Imaging (DWI) dataset.
   :param mask: A binary brain mask volume. FODs are computed only within this mask.
   :param response: The single-fiber response function. If `None`, the response function is estimated using an ROI in the center of the brain mask.
   :type response: Optional
   :param flip_bvecs_x: Whether to flip the x-component of the b-vectors to match MRtrix3 convention. Default is True.
   :param mrtrix_format: If True, converts SH coefficients between legacy-descoteaux07 and tournier07.
   :param sh_order_max: Maximum spherical harmonic order to use in the CSD model. Default is 8.

   Returns: Array containing the spherical harmonic coefficients of the obtained FODs.


.. py:function:: compute_csd_peaks(dwi: kwneuro.dwi.Dwi, mask: kwneuro.resource.VolumeResource, response: kwneuro.resource.ResponseFunctionResource | None = None, flip_bvecs_x: bool = True, n_peaks: int = 5, relative_peak_threshold: float = 0.5, min_separation_angle: float = 25) -> tuple[kwneuro.resource.VolumeResource, kwneuro.resource.VolumeResource]

   Compute Constrained Spherical Deconvolution peaks from a DWI resource. This involves
   estimating the response function, fitting the CSD model, and extracting the peaks.
   :param dwi: The Diffusion Weighted Imaging (DWI) dataset.
   :param mask: A binary brain mask volume. CSD is computed only within this mask.
   :param response: The single-fiber response function. If `None`, the response function is estimated using an ROI in the center of the brain mask.
   :type response: Optional
   :param flip_bvecs_x: Whether to flip the x-component of the b-vectors to match MRtrix3 convention.
   :param n_peaks: Number of peaks to extract per voxel. Default is 5.
   :param relative_peak_threshold: Only return peaks greater than relative_peak_threshold * m where m is the largest peak.
   :param min_separation_angle: The minimum distance between directions. If two peaks are too close only the larger of the two is
   :param returned. Must be in range [0:
   :param 90]:

   Returns: A tuple of VolumeResources containing the CSD peak directions stored as a 5-D array of shape [x,y,z,n_peaks,3],
   and the corresponding peak values stored as a 4D array of shape [x,y,z,n_peaks].


.. py:function:: combine_csd_peaks_to_vector_volume(csd_peaks_dirs: kwneuro.resource.VolumeResource, csd_peaks_values: kwneuro.resource.VolumeResource) -> kwneuro.resource.VolumeResource

   Convert CSD peaks from separate direction and value VolumeResources (e.g. Dipy format) into a single volume
   containing a 4D array, where the last dimension is a n_peaks*3-length vector containing
   the x,y,z components of each peak (e.g. MRtrix3 format). The magnitude of each vector (peak value) is stored as its length (norm).
   :param csd_peaks_dirs: VolumeResource containing peak directions (unit vectors).
   :param csd_peaks_values: VolumeResource containing peak values (amplitudes).

   Returns: VolumeResource with 4D array of shape [x,y,z,n_peaks*3].