DeclarativePhase

class braintools.cogtask.DeclarativePhase(duration, inputs=None, outputs=None, noise=None, on_enter=None, on_exit=None, name=None)

Declarative phase definition with explicit input/output specifications.

Inputs and outputs are described by dictionaries mapping feature names to value specifications. A value spec is either a constant or a callable f(ctx, feature) -> value.

Value shape conventions

Inputs (per spec):

• scalar → broadcast to all (duration, feature.num)

• 1-D, shape (feature.num,) → broadcast along time

• 2-D, shape (duration, feature.num) → written directly

Outputs (categorical mode, ctx.outputs.ndim == 1):

• scalar (int) → constant label over the whole phase

• 1-D, shape (duration,) → time-varying labels

Outputs (vector mode, ctx.outputs.ndim == 2):

• 1-D, shape (feature.num,) → broadcast along time

• 2-D, shape (duration, feature.num) → written directly

param duration:

Phase duration.

type duration:

Quantity

param name:

Phase name.

type name:

str

param inputs:

Mapping of feature name → value spec.

type inputs:

Dict[str, float | int | Array | Callable[[Context, Feature | None], Any]] | None

param outputs:

Output specification (see shape conventions above).

type outputs:

Dict[str, float | int | Array | Callable[[Context, Feature | None], Any]] | None

param noise:

Mapping of feature name → noise sigma (Quantity with unit ms**0.5).

type noise:

Dict[str, Array | ndarray | bool | number | bool | int | float | complex | Quantity] | None

param on_enter:

Hook called when phase begins.

type on_enter:

Callable[[Context], None] | None

param on_exit:

Hook called when phase ends.

type on_exit:

Callable[[Context], None] | None

describe()

Return a human-readable description of this phase’s behavior.

Return type:

str

encode_inputs(ctx)

Fill input buffer based on declarative specifications.

Supports scalar, (feature.num,), and (duration, feature.num) value shapes. Features not specified remain at their default value.

Return type:

None

encode_outputs(ctx)

Fill output buffer based on declarative specifications.

• Categorical mode (ctx.outputs.ndim == 1): use the label key. Accepts a scalar (constant label) or 1-D array of shape (duration,) (time-varying labels).

• Vector mode (ctx.outputs.ndim == 2): write each specified output feature into its slice. Accepts shape (feature.num,) (broadcast along time) or (duration, feature.num).

Return type:

None

on_enter(ctx)

Hook called when phase begins.

Return type:

None

on_exit(ctx)

Hook called when phase ends.

Return type:

None