braintools.input.noisy_sinusoidal

braintools.input.noisy_sinusoidal#

braintools.input.noisy_sinusoidal(amplitude, frequency, noise_amplitude, duration, t_start=None, t_end=None, seed=None)#

Generate sinusoidal current input with additive noise.

Creates a sinusoidal waveform with added Gaussian white noise. Useful for testing robustness to noise, stochastic resonance, and realistic synaptic input conditions.

Parameters:

  • amplitude (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Peak amplitude of the sinusoidal component. Supports current units.

  • frequency (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Frequency of the sinusoidal oscillation. Must be in Hz units.

  • noise_amplitude (Array | ndarray | bool | number | bool | int | float | complex | Quantity) – Standard deviation of additive Gaussian noise. Must have same units as amplitude.

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

  • t_start (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Time when noisy sinusoid starts. Before this, output is 0. Default is 0.

  • t_end (Array | ndarray | bool | number | bool | int | float | complex | Quantity | None) – Time when noisy sinusoid ends. After this, output is 0. Default is duration.

  • seed (int | None) – Random seed for reproducible noise. Default is None (uses global random state).

Returns:

current – The noisy sinusoidal current array with shape (n_timesteps,).

Return type:

ndarray or Quantity

Raises:

  • AssertionError – If frequency is not in Hz units.

  • UnitMismatchError – If amplitude and noise_amplitude have different units.

Examples

>>> import brainunit as u
>>> import brainstate
>>> brainstate.environ.set(dt=0.1 * u.ms)

Sinusoid with small noise

>>> current = noisy_sinusoidal(
...     amplitude=10 * u.pA,
...     frequency=10 * u.Hz,
...     noise_amplitude=1 * u.pA,  # 10% noise
...     duration=1000 * u.ms
... )

High noise for stochastic resonance

>>> current = noisy_sinusoidal(
...     amplitude=5 * u.pA,
...     frequency=5 * u.Hz,
...     noise_amplitude=10 * u.pA,  # Noise > signal
...     duration=2000 * u.ms
... )

Theta rhythm with synaptic noise

>>> current = noisy_sinusoidal(
...     amplitude=2 * u.nA,
...     frequency=8 * u.Hz,  # Theta frequency
...     noise_amplitude=0.5 * u.nA,
...     duration=5000 * u.ms
... )

Windowed noisy stimulation

>>> current = noisy_sinusoidal(
...     amplitude=8 * u.pA,
...     frequency=20 * u.Hz,
...     noise_amplitude=2 * u.pA,
...     duration=1000 * u.ms,
...     t_start=200 * u.ms,
...     t_end=800 * u.ms
... )

Reproducible noisy signal

>>> current = noisy_sinusoidal(
...     amplitude=15 * u.pA,
...     frequency=40 * u.Hz,
...     noise_amplitude=3 * u.pA,
...     duration=500 * u.ms,
...     seed=42  # Fixed random seed
... )

Subthreshold oscillation with realistic noise

>>> current = noisy_sinusoidal(
...     amplitude=0.1 * u.nA,
...     frequency=60 * u.Hz,  # Gamma frequency
...     noise_amplitude=0.05 * u.nA,
...     duration=2000 * u.ms,
...     t_start=500 * u.ms
... )

Notes

  • Noise is Gaussian white noise with zero mean

  • Signal-to-noise ratio = amplitude / noise_amplitude

  • Total variance = amplitude²/2 + noise_amplitude²

  • Useful for testing noise robustness and filtering properties