braintools.input.Burst

class braintools.input.Burst(n_bursts, burst_amp, burst_freq, burst_duration, inter_burst_interval, duration)

Generate burst pattern input.

Creates a pattern of rectangular bursts separated by quiet periods. This is useful for simulating rhythmic activity, theta-burst stimulation, or any protocol requiring repeated stimulation periods.

Parameters:

• n_bursts (int) – Number of bursts to generate.

• burst_amp (float) – Amplitude during bursts. Can include units.

• burst_freq (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Frequency of oscillation within each burst.

• burst_duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Duration of each individual burst.

• inter_burst_interval (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Time between the start of consecutive bursts.

• duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Total duration of the input signal.

n_bursts

The number of bursts.

Type:

int

burst_amp

The burst amplitude.

Type:

float

burst_freq

The oscillation frequency within bursts.

Type:

Quantity or float

burst_duration

The duration of each burst.

Type:

Quantity or float

inter_burst_interval

The interval between burst starts.

Type:

Quantity or float

duration

The total duration.

Type:

Quantity or float

See also

Spike

For individual spikes at specific times.

DoubleExponential

For more realistic burst shapes.

Notes

The bursts are oscillatory (sinusoidal) at the specified frequency. The functional burst API generates sin(2*pi*freq*t) oscillations. For DC (rectangular) bursts, this class is not suitable - use repeated Step or Spike instead.

Examples

Oscillatory bursts at 50Hz:

>>> bursts = Burst(
...     n_bursts=5,
...     burst_amp=1.0 * u.nA,
...     burst_freq=50 * u.Hz,  # 50Hz oscillation
...     burst_duration=30 * u.ms,
...     inter_burst_interval=100 * u.ms,
...     duration=500 * u.ms
... )
>>> array = bursts()

Oscillatory bursts (theta-burst stimulation):

>>> theta_bursts = Burst(
...     n_bursts=10,
...     burst_amp=2.0,
...     burst_freq=100 * u.Hz,  # 100Hz oscillation within bursts
...     burst_duration=40 * u.ms,
...     inter_burst_interval=200 * u.ms,  # 5Hz burst rate
...     duration=2000 * u.ms
... )

Bursts with ramped amplitude:

>>> from braintools.input import Ramp
>>> burst = Burst(5, 1.0, 50 * u.Hz, 30 * u.ms, 100 * u.ms, 500 * u.ms)
>>> ramp = Ramp(0.5, 1.5, 500 * u.ms)
>>> modulated_burst = burst * ramp

Burst pattern with noise:

>>> from braintools.input import WienerProcess
>>> bursts = Burst(4, 1.5, 30 * u.Hz, 50 * u.ms, 150 * u.ms, 600 * u.ms)
>>> noise = WienerProcess(600 * u.ms, sigma=0.1)
>>> noisy_bursts = bursts + noise

Gamma bursts in theta rhythm:

>>> # 40Hz gamma bursts at 5Hz theta rhythm
>>> gamma_in_theta = Burst(
...     n_bursts=15,
...     burst_amp=1.0 * u.nA,
...     burst_freq=40 * u.Hz,  # Gamma frequency
...     burst_duration=100 * u.ms,
...     inter_burst_interval=200 * u.ms,  # Theta rhythm (5Hz)
...     duration=3000 * u.ms
... )

Paired bursts protocol:

>>> # Two bursts with short interval, then long gap
>>> burst1 = Burst(1, 1.0, 100 * u.Hz, 20 * u.ms, 100 * u.ms, 100 * u.ms)
>>> burst2 = Burst(1, 1.2, 100 * u.Hz, 20 * u.ms, 100 * u.ms, 100 * u.ms).shift(30 * u.ms)
>>> paired = burst1 + burst2
>>> protocol = paired.repeat(5)  # Repeat paired bursts

Burst with exponential decay envelope:

>>> from braintools.input import ExponentialDecay
>>> bursts = Burst(8, 1.0, 50 * u.Hz, 25 * u.ms, 75 * u.ms, 600 * u.ms)
>>> envelope = ExponentialDecay(1.0, 150 * u.ms, 600 * u.ms)
>>> decaying_bursts = bursts * envelope

__init__(n_bursts, burst_amp, burst_freq, burst_duration, inter_burst_interval, duration)

Initialize burst input.

Parameters:

• n_bursts (int) – Number of bursts.

• burst_amp (float) – Amplitude during bursts.

• burst_freq (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Frequency within bursts (0 for DC).

• burst_duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Duration of each burst.

• inter_burst_interval (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Interval between burst starts.

• duration (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Total duration of the input.

Methods

__init__(n_bursts, burst_amp, burst_freq, ...)	Initialize burst input.
apply(func)	Apply a custom function to the input.
clip([min_val, max_val])	Clip the input values to a range.
generate()	Generate the burst input array using functional API.
repeat(n_times)	Repeat the input pattern n times.
scale(factor)	Scale the input by a factor.
shift(time_shift)	Shift the input in time.
smooth(tau)	Apply exponential smoothing to the input.

Attributes

dt	Get the time step from global environment.
n_steps	Get the number of time steps.
shape	Get the shape of the input array.