mne_rt.protocols.TransferProtocol#

class mne_rt.protocols.TransferProtocol(fname: str | Path, modality: str, direction: str = 'up', zscore_threshold: float = 0.5, adapt_rate: float = 0.0, smoothing: float = 0.0)#

Bases: object

Cross-session transfer NF protocol seeded from a prior-session file.

Loads a previous session’s NF feature time-series from a BIDS behavioural JSON file (beh/*.json), computes the prior mean and standard deviation, and initialises Welford’s online algorithm as if those samples had already been observed. Subsequent calls to evaluate() continue updating the running statistics, but because the prior already contributes, no warmup period is needed.

The JSON file must follow MNE-RT’s BIDS behavioural format:

{
    "meta": {"modalities": ["sensor_power"], ...},
    "data": {"sensor_power": [0.1, 0.2, ...]}
}

Parameters:

fnamestr | Path: Path to a prior-session BIDS behavioural JSON file.
modalitystr: Key inside data from which to read the prior time-series (e.g., "sensor_power").
direction{“up”, “down”}, default “up”: “up” -> reward when z-score > zscore_threshold. “down” -> reward when z-score < -zscore_threshold.
zscore_thresholdfloat, default 0.5: Minimum absolute z-score required to issue a reward. Must be >= 0.
adapt_ratefloat, default 0.0: Controls how quickly the running statistics adapt to the new session. Set to 0.0 to freeze the prior statistics (pure transfer); higher values let the statistics drift toward the current session. Implemented as an EMA blend between the Welford update and the frozen prior: the effective weight of each new sample is adapt_rate (must be in [0, 1)).
smoothingfloat, default 0.0: EMA smoothing coefficient applied to the raw input before z-scoring. Must be in [0, 1). 0.0 disables smoothing.

Raises:

FileNotFoundError: If fname does not point to an existing file.
KeyError: If the "data" key is absent from the JSON or modality is not found inside data.
ValueError: If any numerical parameter is outside its valid range, or if the prior data array has fewer than 2 elements (insufficient for std).

Notes

The Welford accumulator is initialised with:

n    = len(prior_data)
mean = mean(prior_data)
M2   = var(prior_data, ddof=1) * (n - 1)

so the running std_ on the first call to evaluate() equals the prior standard deviation. When adapt_rate > 0 each new sample contributes weight adapt_rate to the mean and M2, while the existing accumulator retains weight 1 - adapt_rate.

Examples

Seed today’s session from yesterday’s baseline:

from mne_rt.protocols.transfer import TransferProtocol

proto = TransferProtocol(
    fname="sub-01/ses-01/beh/sub-01_ses-01_task-nf_beh.json",
    modality="sensor_power",
    direction="up",
    zscore_threshold=0.5,
)
for value in nf_stream:
    crossed, magnitude = proto.evaluate(value)
    if crossed:
        send_reward(magnitude)

Added in version 1.0.0.

__init__(fname: str | Path, modality: str, direction: str = 'up', zscore_threshold: float = 0.5, adapt_rate: float = 0.0, smoothing: float = 0.0) → None[source]#

Methods

`__init__`(fname, modality[, direction, ...])
`evaluate`(value)	Evaluate one NF value and return (crossed, magnitude).
`reset`()	Reset to the prior statistics without re-reading the file.

Attributes

`mean_`	Current running mean (prior-seeded).
`n_evaluated`	Number of values evaluated since init or last `reset()`.
`n_prior`	Number of samples in the prior session data (read-only).
`prior_mean`	Mean of the prior session data (read-only).
`prior_std`	Standard deviation of the prior session data (read-only).
`std_`	Current running standard deviation (prior-seeded).
`zscore`	Z-score computed during the most recent `evaluate()` call.

evaluate(value: float) → tuple[bool, float][source]#

Evaluate one NF value and return (crossed, magnitude).

Updates the running baseline statistics (seeded from the prior) with the (optionally smoothed) input, computes the z-score against the running mean and standard deviation, and determines whether the reward criterion is met.

Parameters:

valuefloat: Current NF feature value.

Returns:

crossedbool: True if the z-score criterion is met in the target direction.
magnitudefloat: Absolute value of the z-score when crossed is True; 0.0 otherwise.

Notes

When adapt_rate = 0.0 the running statistics are frozen at the prior values: every evaluation is z-scored against the prior mean/std. When adapt_rate > 0 new samples gradually shift the running statistics toward the current session distribution.

property mean_: float#

Current running mean (prior-seeded).

Before any adaptations this equals prior_mean.

property n_evaluated: int#: Number of values evaluated since init or last reset().

property n_prior: int#: Number of samples in the prior session data (read-only).

property prior_mean: float#: Mean of the prior session data (read-only).

property prior_std: float#: Standard deviation of the prior session data (read-only).

reset() → None[source]#

Reset to the prior statistics without re-reading the file.

Restores the Welford accumulators to the values computed from the prior data during __init__, clears the smoothed state, and resets the evaluation counter. All constructor parameters are preserved.

property std_: float#

Current running standard deviation (prior-seeded).

Before any adaptations this equals prior_std.

property zscore: float#

Z-score computed during the most recent evaluate() call.

Returns 0.0 before any evaluation.