docstr: Constrained Spherical Deconvolution (CSD) [1]_.
  
  Spherical deconvolution computes a fiber orientation distribution
  (FOD), also called fiber ODF (fODF) [2]_, as opposed to a diffusion ODF
  as the QballModel or the CsaOdfModel. This results in a sharper angular
  profile with better angular resolution that is the best object to be
  used for later deterministic and probabilistic tractography [3]_.
  
  A sharp fODF is obtained because a single fiber *response* function is
  injected as *a priori* knowledge. The response function is often
  data-driven and is thus provided as input to the
  ConstrainedSphericalDeconvModel. It will be used as deconvolution
  kernel, as described in [1]_.
  
  Parameters
  ----------
  gtab : GradientTable
  response : tuple or AxSymShResponse object
      A tuple with two elements. The first is the eigen-values as an (3,)
      ndarray and the second is the signal value for the response
      function without diffusion weighting (i.e. S0).  This is to be able
      to generate a single fiber synthetic signal. The response function
      will be used as deconvolution kernel ([1]_).
  reg_sphere : Sphere (optional)
      sphere used to build the regularization B matrix.
      Default: 'symmetric362'.
  sh_order : int (optional)
      maximal spherical harmonics order. Default: 8
  lambda_ : float (optional)
      weight given to the constrained-positivity regularization part of
      the deconvolution equation (see [1]_). Default: 1
  tau : float (optional)
      threshold controlling the amplitude below which the corresponding
      fODF is assumed to be zero.  Ideally, tau should be set to
      zero. However, to improve the stability of the algorithm, tau is
      set to tau*100 % of the mean fODF amplitude (here, 10% by default)
      (see [1]_). Default: 0.1
  convergence : int
      Maximum number of iterations to allow the deconvolution to
      converge.
  
  References
  ----------
  .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of
         the fibre orientation distribution in diffusion MRI:
         Non-negativity constrained super-resolved spherical
         deconvolution
  .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and
         Probabilistic Tractography Based on Complex Fibre Orientation
         Distributions
  .. [3] Côté, M-A., et al. Medical Image Analysis 2013. Tractometer:
         Towards validation of tractography pipelines
  .. [4] Tournier, J.D, et al. Imaging Systems and Technology
         2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions
docstr_tok: ["Constrained","Spherical","Deconvolution","(","CSD",")","[","1","]","_.","Spherical","deconvolution","computes","a","fiber","orientation","distribution","(","FOD",")",",","also","called","fiber","ODF","(","fODF",")","[","2","]","_",",","as","opposed","to","a","diffusion","ODF","as","the","QballModel","or","the","CsaOdfModel",".","This","results","in","a","sharper","angular","profile","with","better","angular","resolution","that","is","the","best","object","to","be","used","for","later","deterministic","and","probabilistic","tractography","[","3","]","_",".","A","sharp","fODF","is","obtained","because","a","single","fiber","*","response","*","function","is","injected","as","*","a","priori","*","knowledge",".","The","response","function","is","often","data-driven","and","is","thus","provided","as","input","to","the","ConstrainedSphericalDeconvModel",".","It","will","be","used","as","deconvolution","kernel",",","as","described","in","[","1","]","_.","Parameters","--","--","--","--","--","gtab",":","GradientTable","response",":","tuple","or","AxSymShResponse","object","A","tuple","with","two","elements",".","The","first","is","the","eigen-values","as","an","(","3",",",")","ndarray","and","the","second","is","the","signal","value","for","the","response","function","without","diffusion","weighting","(","i.e",".","S0",")",".","This","is","to","be","able","to","generate","a","single","fiber","synthetic","signal",".","The","response","function","will","be","used","as","deconvolution","kernel","(","[","1","]","_",")",".","reg_sphere",":","Sphere","(","optional",")","sphere","used","to","build","the","regularization","B","matrix",".","Default",":","'symmetric362","'",".","sh_order",":","int","(","optional",")","maximal","spherical","harmonics","order",".","Default",":","8","lambda_",":","float","(","optional",")","weight","given","to","the","constrained-positivity","regularization","part","of","the","deconvolution","equation","(","see","[","1","]","_",")",".","Default",":","1","tau",":","float","(","optional",")","threshold","controlling","the","amplitude","below","which","the","corresponding","fODF","is","assumed","to","be","zero",".","Ideally",",","tau","should","be","set","to","zero",".","However",",","to","improve","the","stability","of","the","algorithm",",","tau","is","set","to","tau","*","100","%","of","the","mean","fODF","amplitude","(","here",",","10","%","by","default",")","(","see","[","1","]","_",")",".","Default",":","0.1","convergence",":","int","Maximum","number","of","iterations","to","allow","the","deconvolution","to","converge",".","References","--","--","--","--","--","..","[","1","]","Tournier",",","J.D.",",","et","al",".","NeuroImage","2007",".","Robust","determination","of","the","fibre","orientation","distribution","in","diffusion","MRI",":","Non-negativity","constrained","super-resolved","spherical","deconvolution","..","[","2","]","Descoteaux",",","M.",",","et","al",".","IEEE","TMI","2009",".","Deterministic","and","Probabilistic","Tractography","Based","on","Complex","Fibre","Orientation","Distributions","..","[","3","]","C\u00f4t\u00e9",",","M-A.",",","et","al",".","Medical","Image","Analysis","2013",".","Tractometer",":","Towards","validation","of","tractography","pipelines","..","[","4","]","Tournier",",","J.D",",","et","al",".","Imaging","Systems","and","Technology","2012",".","MRtrix",":","Diffusion","Tractography","in","Crossing","Fiber","Regions"]
code: def __init__(
      self,
      gtab,
      response,
      reg_sphere=None,
      sh_order=8,
      lambda_=1,
      tau=0.1,
      convergence=50,
  ):
      r"""Constrained Spherical Deconvolution (CSD) [1]_.
  
      Spherical deconvolution computes a fiber orientation distribution
      (FOD), also called fiber ODF (fODF) [2]_, as opposed to a diffusion ODF
      as the QballModel or the CsaOdfModel. This results in a sharper angular
      profile with better angular resolution that is the best object to be
      used for later deterministic and probabilistic tractography [3]_.
  
      A sharp fODF is obtained because a single fiber *response* function is
      injected as *a priori* knowledge. The response function is often
      data-driven and is thus provided as input to the
      ConstrainedSphericalDeconvModel. It will be used as deconvolution
      kernel, as described in [1]_.
  
      Parameters
      ----------
      gtab : GradientTable
      response : tuple or AxSymShResponse object
          A tuple with two elements. The first is the eigen-values as an (3,)
          ndarray and the second is the signal value for the response
          function without diffusion weighting (i.e. S0).  This is to be able
          to generate a single fiber synthetic signal. The response function
          will be used as deconvolution kernel ([1]_).
      reg_sphere : Sphere (optional)
          sphere used to build the regularization B matrix.
          Default: 'symmetric362'.
      sh_order : int (optional)
          maximal spherical harmonics order. Default: 8
      lambda_ : float (optional)
          weight given to the constrained-positivity regularization part of
          the deconvolution equation (see [1]_). Default: 1
      tau : float (optional)
          threshold controlling the amplitude below which the corresponding
          fODF is assumed to be zero.  Ideally, tau should be set to
          zero. However, to improve the stability of the algorithm, tau is
          set to tau*100 % of the mean fODF amplitude (here, 10% by default)
          (see [1]_). Default: 0.1
      convergence : int
          Maximum number of iterations to allow the deconvolution to
          converge.
  
      References
      ----------
      .. [1] Tournier, J.D., et al. NeuroImage 2007. Robust determination of
             the fibre orientation distribution in diffusion MRI:
             Non-negativity constrained super-resolved spherical
             deconvolution
      .. [2] Descoteaux, M., et al. IEEE TMI 2009. Deterministic and
             Probabilistic Tractography Based on Complex Fibre Orientation
             Distributions
      .. [3] Côté, M-A., et al. Medical Image Analysis 2013. Tractometer:
             Towards validation of tractography pipelines
      .. [4] Tournier, J.D, et al. Imaging Systems and Technology
             2012. MRtrix: Diffusion Tractography in Crossing Fiber Regions
      """
      # Initialize the parent class:
      SphHarmModel.__init__(self, gtab)
      m, n = sph_harm_ind_list(sh_order)
      self.m, self.n = m, n
      self._where_b0s = lazy_index(gtab.b0s_mask)
      self._where_dwi = lazy_index(~gtab.b0s_mask)
  
      no_params = ((sh_order + 1) * (sh_order + 2)) / 2
  
      if no_params > np.sum(~gtab.b0s_mask):
          msg = "Number of parameters required for the fit are more "
          msg += "than the actual data points"
          warnings.warn(msg, UserWarning)
  
      x, y, z = gtab.gradients[self._where_dwi].T
      r, theta, phi = cart2sphere(x, y, z)
      # for the gradient sphere
      self.B_dwi = real_sh_descoteaux_from_index(
          m, n, theta[:, None], phi[:, None]
      )
  
      # for the sphere used in the regularization positivity constraint
      self.sphere = reg_sphere or small_sphere
  
      r, theta, phi = cart2sphere(
          self.sphere.x, self.sphere.y, self.sphere.z
      )
      self.B_reg = real_sh_descoteaux_from_index(
          m, n, theta[:, None], phi[:, None]
      )
  
      self.response = response
      if isinstance(response, AxSymShResponse):
          r_sh = response.dwi_response
          self.response_scaling = response.S0
          n_response = response.n
          m_response = response.m
      else:
          self.S_r = estimate_response(
              gtab, self.response[0], self.response[1]
          )
          r_sh = np.linalg.lstsq(
              self.B_dwi, self.S_r[self._where_dwi], rcond=-1
          )[0]
          n_response = n
          m_response = m
          self.response_scaling = response[1]
      r_rh = sh_to_rh(r_sh, m_response, n_response)
      self.R = forward_sdeconv_mat(r_rh, n)
  
      # scale lambda_ to account for differences in the number of
      # SH coefficients and number of mapped directions
      # This is exactly what is done in [4]_
      lambda_ = (
          lambda_
          * self.R.shape[0]
          * r_rh[0]
          / (np.sqrt(self.B_reg.shape[0]) * np.sqrt(362.0))
      )
      self.B_reg *= lambda_
      self.sh_order = sh_order
      self.tau = tau
      self.convergence = convergence
      self._X = X = self.R.diagonal() * self.B_dwi
      self._P = np.dot(X.T, X)
  
imports: import warnings
  import numpy
  import numbers
  from scipy.integrate import quad
  from scipy.special import lpn, gamma
  import scipy.linalg
  import scipy.linalg.lapack
  from dipy.data import small_sphere, get_sphere, default_sphere
  from dipy.core.geometry import cart2sphere
  from dipy.core.ndindex import ndindex
  from dipy.sims.voxel import single_tensor
  from dipy.reconst.multi_voxel import multi_voxel_fit
  from dipy.reconst.dti import TensorModel, fractional_anisotropy
  from dipy.reconst.shm import sph_harm_ind_list, real_sh_descoteaux_from_index, sph_harm_lookup, lazy_index, SphHarmFit, real_sh_descoteaux, sh_to_rh, forward_sdeconv_mat, SphHarmModel
  from dipy.reconst.utils import _roi_in_volume, _mask_from_roi
  from dipy.direction.peaks import peaks_from_model
  from dipy.core.geometry import vec2vec_rotmat
  from dipy.utils.deprecator import deprecate_with_version, deprecated_params
label_desc: Use image node_id 1 to create a new ConstrainedSphericalDeconvModel object from inherited base classes: SphHarmModel with example: obj = ConstrainedSphericalDeconvModel(gtab, response, reg_sphere, sh_order, lambda_, tau, convergence)