class_docstr: Fiber ORientation Estimated using Continuous Axially Symmetric Tensors
  (FORECAST) [1,2,3]_. FORECAST is a Spherical Deconvolution reconstruction
  model for multi-shell diffusion data which enables the calculation of a
  voxel adaptive response function using the Spherical Mean Technique (SMT)
  [2,3]_.
  
  With FORECAST it is possible to calculate crossing invariant parallel
  diffusivity, perpendicular diffusivity, mean diffusivity, and fractional
  anisotropy [2]_
  
  References
  ----------
  .. [1] Anderson A. W., "Measurement of Fiber Orientation Distributions
         Using High Angular Resolution Diffusion Imaging", Magnetic
         Resonance in Medicine, 2005.
  
  .. [2] Kaden E. et al., "Quantitative Mapping of the Per-Axon Diffusion
         Coefficients in Brain White Matter", Magnetic Resonance in
         Medicine, 2016.
  
  .. [3] Zucchelli E. et al., "A generalized SMT-based framework for
         Diffusion MRI microstructural model estimation", MICCAI Workshop
         on Computational DIFFUSION MRI (CDMRI), 2017.
  
  Notes
  -----
  The implementation of FORECAST may require CVXPY (https://www.cvxpy.org/).
class_docstr_tok: ["Fiber","ORientation","Estimated","using","Continuous","Axially","Symmetric","Tensors","(","FORECAST",")","[","1,2,3","]","_",".","FORECAST","is","a","Spherical","Deconvolution","reconstruction","model","for","multi-shell","diffusion","data","which","enables","the","calculation","of","a","voxel","adaptive","response","function","using","the","Spherical","Mean","Technique","(","SMT",")","[","2,3","]","_",".","With","FORECAST","it","is","possible","to","calculate","crossing","invariant","parallel","diffusivity",",","perpendicular","diffusivity",",","mean","diffusivity",",","and","fractional","anisotropy","[","2","]","_","References","--","--","--","--","--","..","[","1","]","Anderson","A.","W.",",","``","Measurement","of","Fiber","Orientation","Distributions","Using","High","Angular","Resolution","Diffusion","Imaging","''",",","Magnetic","Resonance","in","Medicine",",","2005",".","..","[","2","]","Kaden","E.","et","al.",",","``","Quantitative","Mapping","of","the","Per-Axon","Diffusion","Coefficients","in","Brain","White","Matter","''",",","Magnetic","Resonance","in","Medicine",",","2016",".","..","[","3","]","Zucchelli","E.","et","al.",",","``","A","generalized","SMT-based","framework","for","Diffusion","MRI","microstructural","model","estimation","''",",","MICCAI","Workshop","on","Computational","DIFFUSION","MRI","(","CDMRI",")",",","2017",".","Notes","--","--","-","The","implementation","of","FORECAST","may","require","CVXPY","(","https",":","\/\/www.cvxpy.org\/",")","."]
docstr: Analytical and continuous modeling of the diffusion signal with
  respect to the FORECAST basis [1,2,3]_.
  This implementation is a modification of the original FORECAST
  model presented in [1]_ adapted for multi-shell data as in [2,3]_ .
  
  The main idea is to model the diffusion signal as the combination of a
  single fiber response function $F(\mathbf{b})$ times the fODF
  $\rho(\mathbf{v})$
  
  ..math::
      :nowrap:
          \begin{equation}
              E(\mathbf{b}) = \int_{\mathbf{v} \in \mathcal{S}^2} \rho(\mathbf{v}) F({\mathbf{b}} | \mathbf{v}) d \mathbf{v}
          \end{equation}
  
  where $\mathbf{b}$ is the b-vector (b-value times gradient direction)
  and $\mathbf{v}$ is an unit vector representing a fiber direction.
  
  In FORECAST $\rho$ is modeled using real symmetric Spherical Harmonics
  (SH) and $F(\mathbf(b))$ is an axially symmetric tensor.
  
  
  Parameters
  ----------
  gtab : GradientTable,
      gradient directions and bvalues container class.
  sh_order : unsigned int,
      an even integer that represent the SH order of the basis (max 12)
  lambda_lb: float,
      Laplace-Beltrami regularization weight.
  dec_alg : str,
      Spherical deconvolution algorithm. The possible values are Weighted Least Squares ('WLS'),
      Positivity Constraints using CVXPY ('POS') and the Constraint
      Spherical Deconvolution algorithm ('CSD'). Default is 'CSD'.
  sphere : array, shape (N,3),
      sphere points where to enforce positivity when 'POS' or 'CSD'
      dec_alg are selected.
  lambda_csd : float,
      CSD regularization weight.
  
  References
  ----------
  .. [1] Anderson A. W., "Measurement of Fiber Orientation Distributions
         Using High Angular Resolution Diffusion Imaging", Magnetic
         Resonance in Medicine, 2005.
  
  .. [2] Kaden E. et al., "Quantitative Mapping of the Per-Axon Diffusion
         Coefficients in Brain White Matter", Magnetic Resonance in
         Medicine, 2016.
  
  .. [3] Zucchelli M. et al., "A generalized SMT-based framework for
         Diffusion MRI microstructural model estimation", MICCAI Workshop
         on Computational DIFFUSION MRI (CDMRI), 2017.
  
  Examples
  --------
  In this example, where the data, gradient table and sphere tessellation
  used for reconstruction are provided, we model the diffusion signal
  with respect to the FORECAST and compute the fODF, parallel and
  perpendicular diffusivity.
  
  >>> import warnings
  >>> from dipy.data import default_sphere, get_3shell_gtab
  >>> gtab = get_3shell_gtab()
  >>> from dipy.sims.voxel import multi_tensor
  >>> mevals = np.array(([0.0017, 0.0003, 0.0003],
  ...                    [0.0017, 0.0003, 0.0003]))
  >>> angl = [(0, 0), (60, 0)]
  >>> data, sticks = multi_tensor(gtab,
  ...                             mevals,
  ...                             S0=100.0,
  ...                             angles=angl,
  ...                             fractions=[50, 50],
  ...                             snr=None)
  >>> from dipy.reconst.forecast import ForecastModel
  >>> from dipy.reconst.shm import descoteaux07_legacy_msg
  >>> with warnings.catch_warnings():
  ...     warnings.filterwarnings(
  ...         "ignore", message=descoteaux07_legacy_msg,
  ...         category=PendingDeprecationWarning)
  ...     fm = ForecastModel(gtab, sh_order=6)
  >>> f_fit = fm.fit(data)
  >>> d_par = f_fit.dpar
  >>> d_perp = f_fit.dperp
  >>> with warnings.catch_warnings():
  ...     warnings.filterwarnings(
  ...         "ignore", message=descoteaux07_legacy_msg,
  ...         category=PendingDeprecationWarning)
  ...     fodf = f_fit.odf(default_sphere)
docstr_tok: ["Analytical","and","continuous","modeling","of","the","diffusion","signal","with","respect","to","the","FORECAST","basis","[","1,2,3","]","_",".","This","implementation","is","a","modification","of","the","original","FORECAST","model","presented","in","[","1","]","_","adapted","for","multi-shell","data","as","in","[","2,3","]","_",".","The","main","idea","is","to","model","the","diffusion","signal","as","the","combination","of","a","single","fiber","response","function","$","F","(","\\mathbf","{","b","}",")","$","times","the","fODF","$","\\rho","(","\\mathbf","{","v","}",")","$","..","math",":",":",":","nowrap",":","\\begin","{","equation","}","E","(","\\mathbf","{","b","}",")","=","\\int_","{","\\mathbf","{","v","}","\\in","\\mathcal","{","S","}","^2","}","\\rho","(","\\mathbf","{","v","}",")","F","(","{","\\mathbf","{","b","}","}","|","\\mathbf","{","v","}",")","d","\\mathbf","{","v","}","\\end","{","equation","}","where","$","\\mathbf","{","b","}","$","is","the","b-vector","(","b-value","times","gradient","direction",")","and","$","\\mathbf","{","v","}","$","is","an","unit","vector","representing","a","fiber","direction",".","In","FORECAST","$","\\rho","$","is","modeled","using","real","symmetric","Spherical","Harmonics","(","SH",")","and","$","F","(","\\mathbf","(","b",")",")","$","is","an","axially","symmetric","tensor",".","Parameters","--","--","--","--","--","gtab",":","GradientTable",",","gradient","directions","and","bvalues","container","class",".","sh_order",":","unsigned","int",",","an","even","integer","that","represent","the","SH","order","of","the","basis","(","max","12",")","lambda_lb",":","float",",","Laplace-Beltrami","regularization","weight",".","dec_alg",":","str",",","Spherical","deconvolution","algorithm",".","The","possible","values","are","Weighted","Least","Squares","(","'WLS","'",")",",","Positivity","Constraints","using","CVXPY","(","'POS","'",")","and","the","Constraint","Spherical","Deconvolution","algorithm","(","'CSD","'",")",".","Default","is","'CSD","'",".","sphere",":","array",",","shape","(","N,3",")",",","sphere","points","where","to","enforce","positivity","when","'POS","'","or","'CSD'","dec_alg","are","selected",".","lambda_csd",":","float",",","CSD","regularization","weight",".","References","--","--","--","--","--","..","[","1","]","Anderson","A.","W.",",","``","Measurement","of","Fiber","Orientation","Distributions","Using","High","Angular","Resolution","Diffusion","Imaging","''",",","Magnetic","Resonance","in","Medicine",",","2005",".","..","[","2","]","Kaden","E.","et","al.",",","``","Quantitative","Mapping","of","the","Per-Axon","Diffusion","Coefficients","in","Brain","White","Matter","''",",","Magnetic","Resonance","in","Medicine",",","2016",".","..","[","3","]","Zucchelli","M.","et","al.",",","``","A","generalized","SMT-based","framework","for","Diffusion","MRI","microstructural","model","estimation","''",",","MICCAI","Workshop","on","Computational","DIFFUSION","MRI","(","CDMRI",")",",","2017",".","Examples","--","--","--","--","In","this","example",",","where","the","data",",","gradient","table","and","sphere","tessellation","used","for","reconstruction","are","provided",",","we","model","the","diffusion","signal","with","respect","to","the","FORECAST","and","compute","the","fODF",",","parallel","and","perpendicular","diffusivity",".",">",">",">","import","warnings",">",">",">","from","dipy.data","import","default_sphere",",","get_3shell_gtab",">",">",">","gtab","=","get_3shell_gtab","(",")",">",">",">","from","dipy.sims.voxel","import","multi_tensor",">",">",">","mevals","=","np.array","(","(","[","0.0017",",","0.0003",",","0.0003","]",",","...","[","0.0017",",","0.0003",",","0.0003","]",")",")",">",">",">","angl","=","[","(","0",",","0",")",",","(","60",",","0",")","]",">",">",">","data",",","sticks","=","multi_tensor","(","gtab",",","...","mevals",",","...","S0=100.0",",","...","angles=angl",",","...","fractions=","[","50",",","50","]",",","...","snr=None",")",">",">",">","from","dipy.reconst.forecast","import","ForecastModel",">",">",">","from","dipy.reconst.shm","import","descoteaux07_legacy_msg",">",">",">","with","warnings.catch_warnings","(",")",":","...","warnings.filterwarnings","(","...","``","ignore","''",",","message=descoteaux07_legacy_msg",",","...","category=PendingDeprecationWarning",")","...","fm","=","ForecastModel","(","gtab",",","sh_order=6",")",">",">",">","f_fit","=","fm.fit","(","data",")",">",">",">","d_par","=","f_fit.dpar",">",">",">","d_perp","=","f_fit.dperp",">",">",">","with","warnings.catch_warnings","(",")",":","...","warnings.filterwarnings","(","...","``","ignore","''",",","message=descoteaux07_legacy_msg",",","...","category=PendingDeprecationWarning",")","...","fodf","=","f_fit.odf","(","default_sphere",")"]
code: def __init__(
      self,
      gtab,
      sh_order=8,
      lambda_lb=1e-3,
      dec_alg="CSD",
      sphere=None,
      lambda_csd=1.0,
  ):
      r"""Analytical and continuous modeling of the diffusion signal with
      respect to the FORECAST basis [1,2,3]_.
      This implementation is a modification of the original FORECAST
      model presented in [1]_ adapted for multi-shell data as in [2,3]_ .
  
      The main idea is to model the diffusion signal as the combination of a
      single fiber response function $F(\mathbf{b})$ times the fODF
      $\rho(\mathbf{v})$
  
      ..math::
          :nowrap:
              \begin{equation}
                  E(\mathbf{b}) = \int_{\mathbf{v} \in \mathcal{S}^2} \rho(\mathbf{v}) F({\mathbf{b}} | \mathbf{v}) d \mathbf{v}
              \end{equation}
  
      where $\mathbf{b}$ is the b-vector (b-value times gradient direction)
      and $\mathbf{v}$ is an unit vector representing a fiber direction.
  
      In FORECAST $\rho$ is modeled using real symmetric Spherical Harmonics
      (SH) and $F(\mathbf(b))$ is an axially symmetric tensor.
  
  
      Parameters
      ----------
      gtab : GradientTable,
          gradient directions and bvalues container class.
      sh_order : unsigned int,
          an even integer that represent the SH order of the basis (max 12)
      lambda_lb: float,
          Laplace-Beltrami regularization weight.
      dec_alg : str,
          Spherical deconvolution algorithm. The possible values are Weighted Least Squares ('WLS'),
          Positivity Constraints using CVXPY ('POS') and the Constraint
          Spherical Deconvolution algorithm ('CSD'). Default is 'CSD'.
      sphere : array, shape (N,3),
          sphere points where to enforce positivity when 'POS' or 'CSD'
          dec_alg are selected.
      lambda_csd : float,
          CSD regularization weight.
  
      References
      ----------
      .. [1] Anderson A. W., "Measurement of Fiber Orientation Distributions
             Using High Angular Resolution Diffusion Imaging", Magnetic
             Resonance in Medicine, 2005.
  
      .. [2] Kaden E. et al., "Quantitative Mapping of the Per-Axon Diffusion
             Coefficients in Brain White Matter", Magnetic Resonance in
             Medicine, 2016.
  
      .. [3] Zucchelli M. et al., "A generalized SMT-based framework for
             Diffusion MRI microstructural model estimation", MICCAI Workshop
             on Computational DIFFUSION MRI (CDMRI), 2017.
  
      Examples
      --------
      In this example, where the data, gradient table and sphere tessellation
      used for reconstruction are provided, we model the diffusion signal
      with respect to the FORECAST and compute the fODF, parallel and
      perpendicular diffusivity.
  
      >>> import warnings
      >>> from dipy.data import default_sphere, get_3shell_gtab
      >>> gtab = get_3shell_gtab()
      >>> from dipy.sims.voxel import multi_tensor
      >>> mevals = np.array(([0.0017, 0.0003, 0.0003],
      ...                    [0.0017, 0.0003, 0.0003]))
      >>> angl = [(0, 0), (60, 0)]
      >>> data, sticks = multi_tensor(gtab,
      ...                             mevals,
      ...                             S0=100.0,
      ...                             angles=angl,
      ...                             fractions=[50, 50],
      ...                             snr=None)
      >>> from dipy.reconst.forecast import ForecastModel
      >>> from dipy.reconst.shm import descoteaux07_legacy_msg
      >>> with warnings.catch_warnings():
      ...     warnings.filterwarnings(
      ...         "ignore", message=descoteaux07_legacy_msg,
      ...         category=PendingDeprecationWarning)
      ...     fm = ForecastModel(gtab, sh_order=6)
      >>> f_fit = fm.fit(data)
      >>> d_par = f_fit.dpar
      >>> d_perp = f_fit.dperp
      >>> with warnings.catch_warnings():
      ...     warnings.filterwarnings(
      ...         "ignore", message=descoteaux07_legacy_msg,
      ...         category=PendingDeprecationWarning)
      ...     fodf = f_fit.odf(default_sphere)
      """
      OdfModel.__init__(self, gtab)
  
      # round the bvals in order to avoid numerical errors
      self.bvals = np.round(gtab.bvals / 100) * 100
      self.bvecs = gtab.bvecs
  
      if 0 <= sh_order <= 12 and not bool(sh_order % 2):
          self.sh_order = sh_order
      else:
          msg = "sh_order must be a non-zero even positive number "
          msg += "between 2 and 12"
          raise ValueError(msg)
  
      if sphere is None:
          sphere = default_sphere
          self.vertices = sphere.vertices[
              0 : int(sphere.vertices.shape[0] / 2), :
          ]
  
      else:
          self.vertices = sphere
  
      self.b0s_mask = self.bvals == 0
      self.one_0_bvals = np.r_[0, self.bvals[~self.b0s_mask]]
      self.one_0_bvecs = np.r_[
          np.array([0, 0, 0]).reshape(1, 3),
          self.bvecs[~self.b0s_mask, :],
      ]
  
      self.rho = rho_matrix(self.sh_order, self.one_0_bvecs)
  
      # signal regularization matrix
      self.srm = rho_matrix(4, self.one_0_bvecs)
      self.lb_matrix_signal = lb_forecast(4)
  
      self.b_unique = np.sort(np.unique(self.bvals[self.bvals > 0]))
      self.wls = True
      self.csd = False
      self.pos = False
  
      if dec_alg.upper() == "POS":
          if not have_cvxpy:
              cvxpy.import_error()
  
          self.wls = False
          self.pos = True
  
      if dec_alg.upper() == "CSD":
          self.csd = True
  
      self.lb_matrix = lb_forecast(self.sh_order)
      self.lambda_lb = lambda_lb
      self.lambda_csd = lambda_csd
      self.fod = rho_matrix(sh_order, self.vertices)
  
imports: from warnings import warn
  import numpy
  from dipy.reconst.cache import Cache
  from dipy.reconst.multi_voxel import multi_voxel_fit
  from dipy.reconst.csdeconv import csdeconv
  from dipy.reconst.shm import real_sh_descoteaux_from_index
  from scipy.special import gamma, hyp1f1
  from dipy.core.geometry import cart2sphere
  from dipy.data import default_sphere
  from dipy.reconst.odf import OdfModel, OdfFit
  from scipy.optimize import leastsq
  from dipy.utils.optpkg import optional_package
label_desc: Use image node_id 1 to create a new ForecastModel object from inherited base classes: OdfModel, Cache with example: obj = ForecastModel(gtab, sh_order, lambda_lb, dec_alg, sphere, lambda_csd)