respyra.core.target_generator

Target waveform generator for respiratory tracking.

Generates sinusoidal breathing-target waveforms from a sequence of frequency/cycle segments. After a baseline calibration phase the generator maps target values into the participant’s actual force range so the target dot stays within their comfortable breathing amplitude.

Usage

from respyra.core.target_generator import (

SegmentDef, ConditionDef, TargetGenerator, calibrate_from_baseline,

)

center, amplitude = calibrate_from_baseline(baseline_forces) condition = ConditionDef(‘slow_steady’, [SegmentDef(0.1, 3)]) gen = TargetGenerator(condition, center, amplitude)

target_force = gen.get_target(t) # call each frame with tracking time

class respyra.core.target_generator.SegmentDef(freq_hz, n_cycles)[source]

Bases: object

One constant-frequency segment of a breathing-target pattern.

Parameters:

  • freq_hz (float) – Target breathing frequency in Hz (e.g. 0.1 = one breath per 10 s).

  • n_cycles (int) – Number of complete sinusoidal cycles. Using integer cycles guarantees phase continuity at segment boundaries.

freq_hz: float
n_cycles: int
property duration: float

Segment duration in seconds (n_cycles / freq_hz).

class respyra.core.target_generator.ConditionDef(name, segments=<factory>, feedback_gain=1.0)[source]

Bases: object

A named experimental condition composed of one or more segments.

Parameters:

  • name (str) – Human-readable label used in data files (e.g. 'slow_steady').

  • segments (list[SegmentDef]) – Ordered list of segments that form the repeating pattern.

  • feedback_gain (float) – Multiplicative gain applied to the visual trace around the participant’s breathing center. 1.0 = veridical feedback. Values > 1 amplify displayed deviations; < 1 attenuate them.

name: str
segments: list[SegmentDef]
feedback_gain: float = 1.0
property total_duration: float

Total duration of one pass through all segments (seconds).

respyra.core.target_generator.calibrate_from_baseline(force_samples, min_amplitude=0.5)[source]

Derive target center and amplitude from baseline breathing data.

Parameters:

  • force_samples (sequence of float) – Raw force readings (in Newtons) collected during baseline.

  • min_amplitude (float) – Floor for the half-amplitude to prevent degenerate targets when baseline variance is very low.

Return type:

tuple[float, float]

Returns:

  • center (float) – Midpoint of the participant’s breathing range, used as the DC offset for the sinusoidal target.

  • amplitude (float) – Half-amplitude of the sinusoidal target, clamped to at least min_amplitude.

class respyra.core.target_generator.TargetGenerator(condition, center, amplitude)[source]

Bases: object

Real-time sinusoidal breathing-target generator.

Call get_target() each frame with the current tracking time to obtain the target force value for the respiratory tracking dot.

The waveform is center + amplitude * sin(2 * pi * freq * t_local) where t_local is the time within the currently active segment. Multi-segment patterns loop seamlessly because each segment uses an integer number of cycles (phase-continuous boundaries).

Parameters:
get_target(t)[source]

Return the target force value at time t (seconds).

Time is wrapped modulo the total pattern duration so the waveform repeats indefinitely.

Parameters:

t (float) – Elapsed time in seconds since the tracking phase began.

Returns:

Target force in Newtons.

Return type:

float