docstr: Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) [1]_
  
  Modification of the Richardson-Lucy algorithm accounting for Rician
  and Noncentral Chi noise distributions, which more accurately
  represent MRI noise. Computes a maximum likelihood estimation of the
  fiber orientation density function (fODF) at each voxel. Includes
  white matter compartments alongside optional GM and CSF compartments
  to account for partial volume effects. This fit can be performed
  voxelwise or globally. The global fit will proceed more quickly than
  the voxelwise fit provided that the computer has adequate RAM (>= 16 GB
  should be sufficient for most datasets).
  
  Kernel for deconvolution constructed using a priori knowledge of white
  matter response function, as well as the mean diffusivity of GM and/or
  CSF. RUMBA-SD is robust against impulse response imprecision, and thus
  the default diffusivity values are often adequate [2]_.
  
  
  Parameters
  ----------
  gtab : GradientTable
  wm_response : 1d ndarray or 2d ndarray or AxSymShResponse, optional
      Tensor eigenvalues as a (3,) ndarray, multishell eigenvalues as
      a (len(unique_bvals_tolerance(gtab.bvals))-1, 3) ndarray in
      order of smallest to largest b-value, or an AxSymShResponse.
      Default: np.array([1.7e-3, 0.2e-3, 0.2e-3])
  gm_response : float, optional
      Mean diffusivity for GM compartment. If `None`, then grey
      matter volume fraction is not computed. Default: 0.8e-3
  csf_response : float, optional
      Mean diffusivity for CSF compartment. If `None`, then CSF
      volume fraction is not computed. Default: 3.0e-3
  n_iter : int, optional
      Number of iterations for fODF estimation. Must be a positive int.
      Default: 600
  recon_type : {'smf', 'sos'}, optional
      MRI reconstruction method: spatial matched filter (SMF) or
      sum-of-squares (SoS). SMF reconstruction generates Rician noise
      while SoS reconstruction generates Noncentral Chi noise.
      Default: 'smf'
  n_coils : int, optional
      Number of coils in MRI scanner -- only relevant in SoS
      reconstruction. Must be a positive int. Default: 1
  R : int, optional
      Acceleration factor of the acquisition. For SIEMENS,
      R = iPAT factor. For GE, R = ASSET factor. For PHILIPS,
      R = SENSE factor. Typical values are 1 or 2. Must be a positive
      int. Default: 1
  voxelwise : bool, optional
      If true, performs a voxelwise fit. If false, performs a global fit
      on the entire brain at once. The global fit requires a 4D brain
      volume in `fit`. Default: True
  use_tv : bool, optional
      If true, applies total variation regularization. This only takes
      effect in a global fit (`voxelwise` is set to `False`). TV can only
      be applied to 4D brain volumes with no singleton dimensions.
      Default: False
  sphere : Sphere, optional
      Sphere on which to construct fODF. If None, uses `repulsion724`.
      Default: None
  verbose : bool, optional
      If true, logs updates on estimated signal-to-noise ratio after each
      iteration. This only takes effect in a global fit (`voxelwise` is
      set to `False`). Default: False
  
  References
  ----------
  .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N.,
         Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y.,
         Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y.,
         Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R.
         (2015). Spherical Deconvolution of Multichannel Diffusion MRI
         Data with Non-Gaussian Noise Models and Spatial Regularization.
         PLOS ONE, 10(10), e0138910.
         https://doi.org/10.1371/journal.pone.0138910
  
  .. [2] Dell’Acqua, F., Rizzo, G., Scifo, P., Clarke, R., Scotti, G., &
         Fazio, F. (2007). A Model-Based Deconvolution Approach to Solve
         Fiber Crossing in Diffusion-Weighted MR Imaging. IEEE
         Transactions on Bio-Medical Engineering, 54, 462–472.
         https://doi.org/10.1109/TBME.2006.888830
docstr_tok: ["Robust","and","Unbiased","Model-BAsed","Spherical","Deconvolution","(","RUMBA-SD",")","[","1","]","_","Modification","of","the","Richardson-Lucy","algorithm","accounting","for","Rician","and","Noncentral","Chi","noise","distributions",",","which","more","accurately","represent","MRI","noise",".","Computes","a","maximum","likelihood","estimation","of","the","fiber","orientation","density","function","(","fODF",")","at","each","voxel",".","Includes","white","matter","compartments","alongside","optional","GM","and","CSF","compartments","to","account","for","partial","volume","effects",".","This","fit","can","be","performed","voxelwise","or","globally",".","The","global","fit","will","proceed","more","quickly","than","the","voxelwise","fit","provided","that","the","computer","has","adequate","RAM","(",">","=","16","GB","should","be","sufficient","for","most","datasets",")",".","Kernel","for","deconvolution","constructed","using","a","priori","knowledge","of","white","matter","response","function",",","as","well","as","the","mean","diffusivity","of","GM","and\/or","CSF",".","RUMBA-SD","is","robust","against","impulse","response","imprecision",",","and","thus","the","default","diffusivity","values","are","often","adequate","[","2","]","_.","Parameters","--","--","--","--","--","gtab",":","GradientTable","wm_response",":","1d","ndarray","or","2d","ndarray","or","AxSymShResponse",",","optional","Tensor","eigenvalues","as","a","(","3",",",")","ndarray",",","multishell","eigenvalues","as","a","(","len","(","unique_bvals_tolerance","(","gtab.bvals",")",")","-1",",","3",")","ndarray","in","order","of","smallest","to","largest","b-value",",","or","an","AxSymShResponse",".","Default",":","np.array","(","[","1.7e-3",",","0.2e-3",",","0.2e-3","]",")","gm_response",":","float",",","optional","Mean","diffusivity","for","GM","compartment",".","If","`","None","`",",","then","grey","matter","volume","fraction","is","not","computed",".","Default",":","0.8e-3","csf_response",":","float",",","optional","Mean","diffusivity","for","CSF","compartment",".","If","`","None","`",",","then","CSF","volume","fraction","is","not","computed",".","Default",":","3.0e-3","n_iter",":","int",",","optional","Number","of","iterations","for","fODF","estimation",".","Must","be","a","positive","int",".","Default",":","600","recon_type",":","{","'smf","'",",","'sos","'","}",",","optional","MRI","reconstruction","method",":","spatial","matched","filter","(","SMF",")","or","sum-of-squares","(","SoS",")",".","SMF","reconstruction","generates","Rician","noise","while","SoS","reconstruction","generates","Noncentral","Chi","noise",".","Default",":","'smf'","n_coils",":","int",",","optional","Number","of","coils","in","MRI","scanner","--","only","relevant","in","SoS","reconstruction",".","Must","be","a","positive","int",".","Default",":","1","R",":","int",",","optional","Acceleration","factor","of","the","acquisition",".","For","SIEMENS",",","R","=","iPAT","factor",".","For","GE",",","R","=","ASSET","factor",".","For","PHILIPS",",","R","=","SENSE","factor",".","Typical","values","are","1","or","2",".","Must","be","a","positive","int",".","Default",":","1","voxelwise",":","bool",",","optional","If","true",",","performs","a","voxelwise","fit",".","If","false",",","performs","a","global","fit","on","the","entire","brain","at","once",".","The","global","fit","requires","a","4D","brain","volume","in","`","fit","`",".","Default",":","True","use_tv",":","bool",",","optional","If","true",",","applies","total","variation","regularization",".","This","only","takes","effect","in","a","global","fit","(","`","voxelwise","`","is","set","to","`","False","`",")",".","TV","can","only","be","applied","to","4D","brain","volumes","with","no","singleton","dimensions",".","Default",":","False","sphere",":","Sphere",",","optional","Sphere","on","which","to","construct","fODF",".","If","None",",","uses","`","repulsion724","`",".","Default",":","None","verbose",":","bool",",","optional","If","true",",","logs","updates","on","estimated","signal-to-noise","ratio","after","each","iteration",".","This","only","takes","effect","in","a","global","fit","(","`","voxelwise","`","is","set","to","`","False","`",")",".","Default",":","False","References","--","--","--","--","--","..","[","1","]","Canales-Rodr\u00edguez",",","E.","J.",",","Daducci",",","A.",",","Sotiropoulos",",","S.","N.",",","Caruyer",",","E.",",","Aja-Fern\u00e1ndez",",","S.",",","Radua",",","J.",",","Mendizabal",",","J.","M.","Y.",",","Iturria-Medina",",","Y.",",","Melie-Garc\u00eda",",","L.",",","Alem\u00e1n-G\u00f3mez",",","Y.",",","Thiran",",","J.-P.",",","Sarr\u00f3",",","S.",",","Pomarol-Clotet",",","E.",",","&","Salvador",",","R.","(","2015",")",".","Spherical","Deconvolution","of","Multichannel","Diffusion","MRI","Data","with","Non-Gaussian","Noise","Models","and","Spatial","Regularization",".","PLOS","ONE",",","10","(","10",")",",","e0138910",".","https",":","\/\/doi.org\/10.1371\/journal.pone.0138910","..","[","2","]","Dell","\u2019","Acqua",",","F.",",","Rizzo",",","G.",",","Scifo",",","P.",",","Clarke",",","R.",",","Scotti",",","G.",",","&","Fazio",",","F.","(","2007",")",".","A","Model-Based","Deconvolution","Approach","to","Solve","Fiber","Crossing","in","Diffusion-Weighted","MR","Imaging",".","IEEE","Transactions","on","Bio-Medical","Engineering",",","54",",","462\u2013472",".","https",":","\/\/doi.org\/10.1109\/TBME.2006.888830"]
code: def __init__(
      self,
      gtab,
      wm_response=np.array([1.7e-3, 0.2e-3, 0.2e-3]),
      gm_response=0.8e-3,
      csf_response=3.0e-3,
      n_iter=600,
      recon_type="smf",
      n_coils=1,
      R=1,
      voxelwise=True,
      use_tv=False,
      sphere=None,
      verbose=False,
  ):
      """
      Robust and Unbiased Model-BAsed Spherical Deconvolution (RUMBA-SD) [1]_
  
      Modification of the Richardson-Lucy algorithm accounting for Rician
      and Noncentral Chi noise distributions, which more accurately
      represent MRI noise. Computes a maximum likelihood estimation of the
      fiber orientation density function (fODF) at each voxel. Includes
      white matter compartments alongside optional GM and CSF compartments
      to account for partial volume effects. This fit can be performed
      voxelwise or globally. The global fit will proceed more quickly than
      the voxelwise fit provided that the computer has adequate RAM (>= 16 GB
      should be sufficient for most datasets).
  
      Kernel for deconvolution constructed using a priori knowledge of white
      matter response function, as well as the mean diffusivity of GM and/or
      CSF. RUMBA-SD is robust against impulse response imprecision, and thus
      the default diffusivity values are often adequate [2]_.
  
  
      Parameters
      ----------
      gtab : GradientTable
      wm_response : 1d ndarray or 2d ndarray or AxSymShResponse, optional
          Tensor eigenvalues as a (3,) ndarray, multishell eigenvalues as
          a (len(unique_bvals_tolerance(gtab.bvals))-1, 3) ndarray in
          order of smallest to largest b-value, or an AxSymShResponse.
          Default: np.array([1.7e-3, 0.2e-3, 0.2e-3])
      gm_response : float, optional
          Mean diffusivity for GM compartment. If `None`, then grey
          matter volume fraction is not computed. Default: 0.8e-3
      csf_response : float, optional
          Mean diffusivity for CSF compartment. If `None`, then CSF
          volume fraction is not computed. Default: 3.0e-3
      n_iter : int, optional
          Number of iterations for fODF estimation. Must be a positive int.
          Default: 600
      recon_type : {'smf', 'sos'}, optional
          MRI reconstruction method: spatial matched filter (SMF) or
          sum-of-squares (SoS). SMF reconstruction generates Rician noise
          while SoS reconstruction generates Noncentral Chi noise.
          Default: 'smf'
      n_coils : int, optional
          Number of coils in MRI scanner -- only relevant in SoS
          reconstruction. Must be a positive int. Default: 1
      R : int, optional
          Acceleration factor of the acquisition. For SIEMENS,
          R = iPAT factor. For GE, R = ASSET factor. For PHILIPS,
          R = SENSE factor. Typical values are 1 or 2. Must be a positive
          int. Default: 1
      voxelwise : bool, optional
          If true, performs a voxelwise fit. If false, performs a global fit
          on the entire brain at once. The global fit requires a 4D brain
          volume in `fit`. Default: True
      use_tv : bool, optional
          If true, applies total variation regularization. This only takes
          effect in a global fit (`voxelwise` is set to `False`). TV can only
          be applied to 4D brain volumes with no singleton dimensions.
          Default: False
      sphere : Sphere, optional
          Sphere on which to construct fODF. If None, uses `repulsion724`.
          Default: None
      verbose : bool, optional
          If true, logs updates on estimated signal-to-noise ratio after each
          iteration. This only takes effect in a global fit (`voxelwise` is
          set to `False`). Default: False
  
      References
      ----------
      .. [1] Canales-Rodríguez, E. J., Daducci, A., Sotiropoulos, S. N.,
             Caruyer, E., Aja-Fernández, S., Radua, J., Mendizabal, J. M. Y.,
             Iturria-Medina, Y., Melie-García, L., Alemán-Gómez, Y.,
             Thiran, J.-P., Sarró, S., Pomarol-Clotet, E., & Salvador, R.
             (2015). Spherical Deconvolution of Multichannel Diffusion MRI
             Data with Non-Gaussian Noise Models and Spatial Regularization.
             PLOS ONE, 10(10), e0138910.
             https://doi.org/10.1371/journal.pone.0138910
  
      .. [2] Dell’Acqua, F., Rizzo, G., Scifo, P., Clarke, R., Scotti, G., &
             Fazio, F. (2007). A Model-Based Deconvolution Approach to Solve
             Fiber Crossing in Diffusion-Weighted MR Imaging. IEEE
             Transactions on Bio-Medical Engineering, 54, 462–472.
             https://doi.org/10.1109/TBME.2006.888830
  
  
      """
  
      if not np.any(gtab.b0s_mask):
          raise ValueError("Gradient table has no b0 measurements")
  
      self.gtab_orig = gtab  # save for prediction
  
      # Masks to extract b0/non-b0 measurements
      self.where_b0s = lazy_index(gtab.b0s_mask)
      self.where_dwi = lazy_index(~gtab.b0s_mask)
  
      # Correct gradient table to contain b0 data at the beginning
      bvals_cor = np.concatenate(([0], gtab.bvals[self.where_dwi]))
      bvecs_cor = np.concatenate(
          ([[0, 0, 0]], gtab.bvecs[self.where_dwi])
      )
      gtab_cor = gradient_table(bvals_cor, bvecs_cor)
  
      # Initialize self.gtab
      OdfModel.__init__(self, gtab_cor)
  
      # Store responses
      self.wm_response = wm_response
      self.gm_response = gm_response
      self.csf_response = csf_response
  
      # Initializing remaining parameters
      if R < 1 or n_iter < 1 or n_coils < 1:
          raise ValueError(
              f"R, n_iter, and n_coils must be >= 1, but R={R},"
              + f"n_iter={n_iter}, and n_coils={n_coils} "
          )
  
      self.R = R
      self.n_iter = n_iter
      self.recon_type = recon_type
      self.n_coils = n_coils
  
      if voxelwise and use_tv:
          raise ValueError(
              "Total variation has no effect in voxelwise fit"
          )
      if voxelwise and verbose:
          warnings.warn(
              "Verbosity has no effect in voxelwise fit", UserWarning
          )
  
      self.voxelwise = voxelwise
      self.use_tv = use_tv
  
      self.verbose = verbose
  
      if sphere is None:
          self.sphere = get_sphere("repulsion724")
      else:
          self.sphere = sphere
  
      if voxelwise:
          self.fit = self._voxelwise_fit
      else:
          self.fit = self._global_fit
  
      # Fitting parameters
      self.kernel = None
  
imports: import logging
  import warnings
  import numpy
  from dipy.core.geometry import vec2vec_rotmat
  from dipy.core.gradients import gradient_table, unique_bvals_tolerance, get_bval_indices
  from dipy.core.onetime import auto_attr
  from dipy.core.sphere import Sphere
  from dipy.data import get_sphere
  from dipy.reconst.shm import lazy_index, normalize_data
  from dipy.reconst.odf import OdfModel, OdfFit
  from dipy.reconst.csdeconv import AxSymShResponse
  from dipy.segment.mask import bounding_box, crop
  from dipy.sims.voxel import single_tensor, all_tensor_evecs
label_desc: Use image node_id 1 to create a new RumbaSDModel object from inherited base classes: OdfModel with example: obj = RumbaSDModel(gtab, wm_response, gm_response, csf_response, n_iter, recon_type, n_coils, R, voxelwise, use_tv, sphere, verbose)