BalloonWindkesselBold

observations.tvb_monitors.BalloonWindkesselBold(
    period=2000.0,
    dt_bw=1.0,
    taus=0.65,
    tauf=0.41,
    tauo=0.98,
    alpha=0.32,
    Eo=0.4,
    vo=0.04,
    TE=0.04,
    voi=None,
    downsample=None,
    *,
    k3=1.0,
)

BOLD signal monitor using Balloon-Windkessel hemodynamic ODE.

Integrates a four-variable ODE system (vasodilatory signal, blood flow, blood volume, deoxyhemoglobin) driven by neural firing rates, then computes BOLD signal from the hemodynamic state.

The user-facing interface uses milliseconds for time parameters (period, dt_bw). Internally the BW ODE is integrated in seconds, matching the standard reference implementation (Friston 2000, Deco 2014).

The monitor supports both stored solutions and native observe= execution. Pass downsample=Identity() to drive it directly on the actual incoming grid, including the output grid of a shared joint stage. Post-hoc execution accepts any callable downsampler. Prepared execution accepts downsamplers implementing the streaming preparation contract, carries their state between blocks, and exposes their live parameters under config.monitor.downsample.

Parameters (user-facing, in ms)

period : float BOLD sampling period (TR) in ms (default: 2000.0) dt_bw : float Integration time step for BW equations in ms (default: 1.0)

Parameters (hemodynamic, in seconds)

taus : float Vasodilatory signal decay time constant in s (default: 0.65) tauf : float Autoregulatory feedback time constant in s (default: 0.41) tauo : float Transit time in s (default: 0.98) alpha : float Grubb’s vessel stiffness exponent (default: 0.32) Eo : float Resting oxygen extraction fraction (default: 0.4) vo : float Resting blood volume fraction (default: 0.04) TE : float Echo time in s (default: 0.04) k3 : float Extravascular signal coefficient (default: 1.0). Keyword-only.

Notes

k1 and k2 remain readable attributes, but are derived from the live Eo and TE values instead of independent parameter leaves. Code that previously replaced those derived leaves should update Eo or TE; k3 remains an independently configurable signal coefficient.

References

Friston et al. (2000). Nonlinear Responses in fMRI: The Balloon Model, Volterra Kernels, and Other Hemodynamics. NeuroImage, 12(4), 466-477.
Deco et al. (2014). How Local Excitation-Inhibition Ratio Impacts the Whole Brain Dynamics. Journal of Neuroscience, 34(23), 7886-7898.

Attributes

Name	Description
k1	Oxygenation coefficient derived from the live Eo and TE values.
k2	Intravascular coefficient derived from the live Eo and TE values.

Methods

Name	Description
prepare	Prepare stateful BW integration for block-wise execution.

prepare

observations.tvb_monitors.BalloonWindkesselBold.prepare(
    grid,
    sample,
    variable_names,
)

Prepare stateful BW integration for block-wise execution.

# BalloonWindkesselBold { #tvboptim.observations.tvb_monitors.BalloonWindkesselBold } ```python observations.tvb_monitors.BalloonWindkesselBold( period=2000.0, dt_bw=1.0, taus=0.65, tauf=0.41, tauo=0.98, alpha=0.32, Eo=0.4, vo=0.04, TE=0.04, voi=None, downsample=None, *, k3=1.0, ) ``` BOLD signal monitor using Balloon-Windkessel hemodynamic ODE. Integrates a four-variable ODE system (vasodilatory signal, blood flow, blood volume, deoxyhemoglobin) driven by neural firing rates, then computes BOLD signal from the hemodynamic state. The user-facing interface uses milliseconds for time parameters (period, dt_bw). Internally the BW ODE is integrated in seconds, matching the standard reference implementation (Friston 2000, Deco 2014). The monitor supports both stored solutions and native ``observe=`` execution. Pass ``downsample=Identity()`` to drive it directly on the actual incoming grid, including the output grid of a shared joint stage. Post-hoc execution accepts any callable downsampler. Prepared execution accepts downsamplers implementing the streaming preparation contract, carries their state between blocks, and exposes their live parameters under ``config.monitor.downsample``. ## Parameters (user-facing, in ms) {.doc-section .doc-section-parameters-user-facing-in-ms} period : float BOLD sampling period (TR) in ms (default: 2000.0) dt_bw : float Integration time step for BW equations in ms (default: 1.0) ## Parameters (hemodynamic, in seconds) {.doc-section .doc-section-parameters-hemodynamic-in-seconds} taus : float Vasodilatory signal decay time constant in s (default: 0.65) tauf : float Autoregulatory feedback time constant in s (default: 0.41) tauo : float Transit time in s (default: 0.98) alpha : float Grubb's vessel stiffness exponent (default: 0.32) Eo : float Resting oxygen extraction fraction (default: 0.4) vo : float Resting blood volume fraction (default: 0.04) TE : float Echo time in s (default: 0.04) k3 : float Extravascular signal coefficient (default: 1.0). Keyword-only. ## Notes {.doc-section .doc-section-notes} ``k1`` and ``k2`` remain readable attributes, but are derived from the live ``Eo`` and ``TE`` values instead of independent parameter leaves. Code that previously replaced those derived leaves should update ``Eo`` or ``TE``; ``k3`` remains an independently configurable signal coefficient. ## References {.doc-section .doc-section-references} - Friston et al. (2000). Nonlinear Responses in fMRI: The Balloon Model, Volterra Kernels, and Other Hemodynamics. NeuroImage, 12(4), 466-477. - Deco et al. (2014). How Local Excitation-Inhibition Ratio Impacts the Whole Brain Dynamics. Journal of Neuroscience, 34(23), 7886-7898. ## Attributes | Name | Description | | --- | --- | | [k1](#tvboptim.observations.tvb_monitors.BalloonWindkesselBold.k1) | Oxygenation coefficient derived from the live Eo and TE values. | | [k2](#tvboptim.observations.tvb_monitors.BalloonWindkesselBold.k2) | Intravascular coefficient derived from the live Eo and TE values. | ## Methods | Name | Description | | --- | --- | | [prepare](#tvboptim.observations.tvb_monitors.BalloonWindkesselBold.prepare) | Prepare stateful BW integration for block-wise execution. | ### prepare { #tvboptim.observations.tvb_monitors.BalloonWindkesselBold.prepare } ```python observations.tvb_monitors.BalloonWindkesselBold.prepare( grid, sample, variable_names, ) ``` Prepare stateful BW integration for block-wise execution.