mne_rt.protocols.PercentileProtocol#

class mne_rt.protocols.PercentileProtocol(percentile: float = 75.0, direction: str = 'up', history_len: int = 100, smoothing: float = 0.0)#

Bases: object

Percentile-based NF reward protocol with rolling history.

Maintains a fixed-length circular buffer of recent (optionally smoothed) NF values. At each call to evaluate() the Nth percentile of that buffer is computed and used as the dynamic reward threshold.

A reward is issued when the current value exceeds ("up") or falls below ("down") that threshold.

Parameters:

percentilefloat: Target percentile in the range (0, 100) used to derive the dynamic threshold from the history buffer. Default is 75.0.
direction{“up”, “down”}: “up” -> reward when value > percentile threshold. “down” -> reward when value < percentile threshold. Default is “up”.
history_lenint: Maximum number of recent values retained in the rolling buffer. Must be >= 2. Default is 100.
smoothingfloat: EMA smoothing coefficient applied to the raw input before comparison. Must be in [0, 1). 0.0 disables smoothing. Applied as: smoothed = (1 - smoothing) * new + smoothing * prev. Default is 0.0.

Raises:

ValueError: If any parameter is outside its valid range.

Notes

The current_threshold is nan until at least two values have been added to the history buffer (numpy.percentile requires at least one element, but a single-element buffer is degenerate).

Examples

Reward when alpha power exceeds the 75th percentile of recent history:

proto = PercentileProtocol(percentile=75.0, direction="up")
for value in nf_stream:
    crossed, magnitude = proto.evaluate(value)
    if crossed:
        send_reward(magnitude)

Added in version 1.0.0.

__init__(percentile: float = 75.0, direction: str = 'up', history_len: int = 100, smoothing: float = 0.0) → None[source]#

Methods

`__init__`([percentile, direction, ...])
`evaluate`(value)	Evaluate one NF value and return (crossed, magnitude).
`reset`()	Reset all state.

Attributes

`current_threshold`	Percentile threshold computed during the last `evaluate()` call.
`hit_rate`	Fraction of recent evaluations that crossed the threshold (0–1).
`n_evaluated`	Total number of values evaluated since init or last reset.

property current_threshold: float#

Percentile threshold computed during the last evaluate() call.

Returns nan until at least two values have been accumulated.

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

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

Appends the (optionally smoothed) value to the rolling buffer, recomputes the percentile threshold, and tests the crossing condition.

Parameters:

valuefloat: Current NF feature value.

Returns:

crossedbool: True if the current value is on the reward side of the percentile threshold.
magnitudefloat: Absolute distance between the current value and the threshold when crossed is True; 0.0 otherwise. Returns 0.0 when the history buffer contains fewer than two entries.

property hit_rate: float#

Fraction of recent evaluations that crossed the threshold (0–1).

Computed over the rolling window defined by history_len. Returns 0.0 when no evaluations have been recorded yet.

property n_evaluated: int#: Total number of values evaluated since init or last reset.

reset() → None[source]#

Reset all state.

Clears the rolling history buffer, hit log, smoothed value, and evaluation counter. All constructor parameters are preserved.