indii/fmri/hemodynamic/BOLDCalculator.hpp

#ifndef INDII_FMRI_HEMODYNAMIC_BOLDCALCULATOR_HPP
#define INDII_FMRI_HEMODYNAMIC_BOLDCALCULATOR_HPP

#include "indii/ml/aux/vector.hpp"
#include "indii/ml/ode/ParameterCollection.hpp"

namespace indii {
  namespace fmri {
    namespace hemodynamic {

      class BalloonModel;

/**
 * Calculates Blood Oxygenation Level Dependent (BOLD) signal from a
 * FlowBalloonModel or NeuralBalloonModel.
 *
 * @author Lawrence Murray <lawrence@indii.org>
 * @version $Rev: 285 $
 * @date $Date: 2007-07-20 17:25:40 +0100 (Fri, 20 Jul 2007) $
 *
 * @section BOLDCalculator_details Details
 *
 * The BOLD signal change \f$\frac{\Delta S}{S}\f$ may be calculated
 * from the \f$q\f$ and \f$v\f$ state variables of a balloon model
 * according to the formula given in @ref Buxton1998
 * "Buxton et al. (1998)":
 *
 * \f[\frac{\Delta S}{S} = V_0\left[ k_1(1-q) + k_2\left(1-\frac{q}{v}\right)
 * + k_3(1-v) \right]\f]
 *
 * where \f$k_1\f$, \f$k_2\f$ and \f$k_3\f$ are constants.
 *
 * @section usage Usage
 *
 * The basic usage idiom is to firstly construct a BalloonModel object
 * and then create the BOLDCalculator coupled to it:
 *
 * @code
 * FlowBalloonModel bm; // or NeuralBalloonModel bm;
 * BOLDCalculator bc(&bm);
 * @endcode
 *
 * The balloon %model may then be simulated as normal and the BOLD
 * signal calculated from it at any time by calling calculate(). This
 * would usually be done after each step of the balloon %model:
 *
 * @code
 * indii::ml::ode::AdaptiveRungeKutta solver(&bm, bm.suggestInitialState());
 * double end = 60.0;
 * double t = 0.0;
 *
 * while (t < end) {
 *   t = solver.step(end);
 *   std::cout << t << '=' << bc.calculate(solver.getState()) << std::endl;
 * }
 * @endcode
 *
 * The BalloonModel object itself may be used as normal, the
 * BOLDCalculator does not modify it in any way, and simply requires
 * it for some parameters.
 */
class BOLDCalculator : public indii::ml::ode::ParameterCollection {
public:
  /**
   * Biophysical parameters. These are initialised according to the
   * values in BOLDCalculatorDefaults, but may be overridden using
   * setParameter().
   */
  enum BiophysicalParameter {
    /**
     * \f$k_1\f$
     */
    K_1,

    /**
     * \f$k_2\f$
     */
    K_2,

    /**
     * \f$k_3\f$
     */
    K_3
  };

  /**
   * Create new BOLD calculator with default biophysical parameters,
   * coupled with the given balloon %model.
   *
   * @param m FlowBalloonModel or NeuralBalloonModel from which to
   * calculate BOLD signal.
   */
  BOLDCalculator(const BalloonModel* m);

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

  /**
   * Calculate BOLD signal from coupled balloon %model and given
   * state.
   *
   * @param y State of the balloon %model, usually provided by the
   * ordinary differential equation solver being used on the balloon
   * %model, such as indii::ml::ode::AdaptiveRungeKutta.
   *
   * @return The BOLD signal produced by the coupled balloon %model in
   * the given state.
   */
  double calculate(const indii::ml::aux::vector& y);

private:
  /**
   * Balloon %model for which to calculate BOLD response.
   */
  const BalloonModel* m;

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

};

    }
  }
}

#endif

---