indii/fmri/hemodynamic/NeuralBalloonModel.hpp

#ifndef INDII_FMRI_HEMODYNAMIC_NEURALBALLOONMODEL_HPP
#define INDII_FMRI_HEMODYNAMIC_NEURALBALLOONMODEL_HPP

#include "BalloonModel.hpp"
#include "indii/ml/aux/vector.hpp"

namespace indii {
  namespace fmri {
    namespace hemodynamic {

/**
 * Balloon %model driven by %neural activity.
 *
 * @author Lawrence Murray <lawrence@indii.org>
 * @version $Rev: 285 $
 * @date $Date: 2007-07-20 17:25:40 +0100 (Fri, 20 Jul 2007) $
 *
 * This class extends FlowBalloonModel to be driven by %neural activity
 * rather than blood flow, as proposed in @ref Friston2000
 * "Friston et al. (2000)", and further described in @ref Friston2003
 * "Friston et al. (2003)".
 *
 * The %model couples %neural activity to blood flow via an additional
 * vasodilatory signal \f$s\f$, which encapsulates a range of
 * biological processes.
 *
 * @section NeuralBalloonModel_details Details
 **
 * The state variables \f$q\f$ and \f$v\f$ of FlowBalloonModel are
 * extended to include \f$f \equiv f_{in}(t)\f$ and \f$s\f$, the
 * vasodilatory signal. The system of differential equations then
 * includes all four of these state variables:
 *
 * @anchor diffsystem
 * \f{eqnarray*}
 *   \frac{df}{dt} &=& s \\
 *   \frac{ds}{dt} &=& \epsilon u(t) - \frac{s}{\tau_s} -
 *     \frac{(f-1)}{\tau_f} \\
 *   \frac{dq}{dt} &=& \frac{1}{\tau_0}\left[
 *     f\frac{E(t)}{E_0} -
 *     f_{out}(v)\frac{q(t)}{v(t)}
 *     \right] \\
 *   \frac{dv}{dt} &=& \frac{1}{\tau_0}\left[
 *     f - f_{out}(v)
 *     \right]
 * \f}
 *
 * The effect of this is that the %model becomes driven by the new
 * function \f$u(t)\f$, representing %neural activity, rather than the
 * flow function \f$f_{in}(t)\f$.
 *
 * Singularities are handled in the same fashion as FlowBalloonModel.
 *
 * @section usage Usage
 *
 * The %model is used in the same way as FlowBalloonModel. Rather than
 * creating your own function to replace FlowBalloonModel::F_IN and
 * drive the system, however, create your own function to replace
 * NeuralBalloonModel::U instead.
 */
class NeuralBalloonModel : public BalloonModel {
public:
  /**
   * State variables.
   */
  enum StateVariable {
    /**
     * \f$q = \frac{Q(t)}{Q_0}\f$; normalised dHb content of venous
     * compartment at the current time.
     */
    Q,

    /**
     * \f$v = \frac{V(t)}{V_0}\f$; normalised volume of the venous
     * compartment at the current time.
     */
    V,

    /**
     * \f$\dot{f_{in}} = \frac{F_{in}(t)}{F_0}\f$; normalised flow into the
     * venous compartment.
     */
    F,

    /**
     * \f$s\f$; flow inducing signal.
     */
    S
  };

  /**
   * Parameter indices. The first part of this enum matches that of
   * FlowBalloonModel for consistency.
   */
  enum BiophysicalParameter {
    /**
     * \f$V_0\f$; volume of the venous compartment at rest.
     */
    V_0,
  
    /**
     * \f$E_0\f$; oxygen extraction rate of the venous compartment at
     * rest.
     */
    E_0,

    /**
     * \f$\tau_0 = \frac{V_0}{F_0}\f$; mean transit time through the
     * venous compartment at rest.
     */
    TAU_0,

    /**
     * \f$\alpha\f$; Grubb's exponent.
     */
    ALPHA,

    /**
     * \f$\epsilon\f$; efficacy with which %neural activity causes an
     * increase in signal.
     */
    EPSILON,

    /**
     * \f$\tau_s\f$; time constant for signal decay. Note that
     * \f$\tau_s\f$ in @ref Friston2000 "Friston et al. (2000)" equals
     * \f$\frac{1}{\kappa}\f$ in @ref Friston2003 "Friston et al. (2003)".
     */
    TAU_S,

    /**
     * \f$\tau_f\f$; time constant for autoregulatory feedback from
     * blood flow. Note that \f$\tau_f\f$ in @ref Friston2000
     * "Friston et al. (2000)" equals \f$\frac{1}{\gamma}\f$ in @ref
     * Friston2003 "Friston et al. (2003)".
     */
    TAU_F
  };

  /**
   * Function indices. The first part of this enum matches that of
   * FlowBalloonModel for consistency.
   */
  enum BiophysicalFunction {
    /**
     * \f$f_{in}(t) = \frac{F_{in}(t)}{F_0}\f$; normalised flow into
     * the venous compartment.
     */
    F_IN,

    /**
     * \f$f_{out}(t) = \frac{F_{out}(t)}{F_0}\f$; normalised flow out
     * of the venous compartment.
     */
    F_OUT,

    /**
     * \f$E(t)\f$; oxygen extraction rate of the venous compartment.
     */
    E,

    /**
     * \f$u(t)\f$; %neural activity.
     */
    U
  };

  /**
   * Create new %model with default biophysical parameters and
   * functions as defined in NeuralBalloonModelDefaults and
   * FlowBalloonModelDefaults.
   */
  NeuralBalloonModel();

  /**
   * Destructor.
   */
  virtual ~NeuralBalloonModel();

  virtual indii::ml::aux::vector suggestInitialState();

  /**
   * @see indii::ml::ode::DifferentialModel
   */
  virtual void calculateDerivatives(double t, const double y[], double dydt[]);

private:
  /**
   * Number of state variables.
   */
  static const unsigned int DIMENSIONS = 4;

  /**
   * Number of parameters.
   */
  static const unsigned int NUM_PARAMETERS = 7;

  /**
   * Number of functions.
   */
  static const unsigned int NUM_FUNCTIONS = 4;

};

    }
  }
}

#endif

---