ezmsg.simbiophys.cosine_encoder

Generic cosine-tuning encoder for polar coordinates.

This module provides a generalized cosine-tuning encoder that maps polar coordinates (magnitude, angle) to multiple output channels with configurable preferred directions, baseline, and modulation parameters.

The encoding formula is:

output = baseline + modulation * magnitude * cos(angle - preferred_direction)

• speed_modulation * magnitude

This implements the offset model from “Decoding arm speed during reaching” (https://ncbi.nlm.nih.gov/pmc/articles/PMC6286377/) with generic terminology suitable for various applications:

• Neural firing rate encoding (baseline=10Hz, modulation=20Hz)

• LFP spectral parameter modulation (baseline=1.0, modulation=0.5)

• Any other cosine-tuning based encoding

Input:

Polar coordinates (magnitude, angle) as AxisArray with shape (n_samples, 2). Use CoordinateSpaces(mode=CART2POL) upstream to convert from Cartesian.

Output:

AxisArray with shape (n_samples, output_ch) containing encoded values.

Classes

class CosineEncoderSettings(model_file=None, output_ch=10, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Bases: Settings

Settings for CosineEncoder.

Either model_file OR the random generation parameters should be specified. If model_file is provided, parameters are loaded from file. Otherwise, parameters are randomly generated.

Parameters:

• model_file (str | None)

• output_ch (int)

• baseline (float)

• modulation (float)

• speed_modulation (float)

• seed (int | None)

model_file: str | None = None

Path to .npz file with encoder parameters (baseline, modulation, pd, speed_modulation). Also supports legacy neural tuning files with keys (b0, m, pd, bs).

output_ch: int = 10

Number of output channels (used if model_file is None).

baseline: float = 0.0

Baseline output value for all channels (used if model_file is None).

modulation: float = 1.0

Directional modulation depth for all channels (used if model_file is None).

speed_modulation: float = 0.0

Speed modulation (non-directional) for all channels (used if model_file is None).

seed: int | None = None

Random seed for reproducibility of preferred directions (used if model_file is None).

__init__(model_file=None, output_ch=10, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Parameters:

• model_file (str | None)

• output_ch (int)

• baseline (float)

• modulation (float)

• speed_modulation (float)

• seed (int | None)

Return type:

None

class CosineEncoderState

Bases: object

State for cosine encoder transformer.

Holds the per-channel encoding parameters. All arrays have shape (1, output_ch) for efficient broadcasting during processing.

baseline

Baseline output value for each channel.

modulation

Directional modulation depth for each channel.

pd

Preferred direction (radians) for each channel.

speed_modulation

Speed modulation (non-directional) for each channel.

ch_axis

Pre-built channel axis for output messages.

baseline: ndarray[tuple[Any, ...], dtype[floating]] | None = None

modulation: ndarray[tuple[Any, ...], dtype[floating]] | None = None

pd: ndarray[tuple[Any, ...], dtype[floating]] | None = None

speed_modulation: ndarray[tuple[Any, ...], dtype[floating]] | None = None

ch_axis: CoordinateAxis | None = None

property output_ch: int

Number of output channels.

validate()

Validate that all parameters have consistent shapes.

Return type:

None

load_from_file(filepath, output_ch=None)

Load parameters from a .npz file.

The file should contain arrays with keys matching the parameter names. For backwards compatibility with neural tuning files, the following key mappings are supported:

• ‘b0’ -> baseline

• ‘m’ -> modulation

• ‘pd’ -> pd (preferred direction)

• ‘bs’ -> speed_modulation

Parameters:

• filepath (str | Path) – Path to .npz file containing parameter arrays.

• output_ch (int | None) – Number of channels to use. If None, uses all in file.

Return type:

None

init_random(output_ch, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Initialize encoder parameters with random preferred directions.

Parameters:

• output_ch (int) – Number of output channels.

• baseline (float) – Baseline value for all channels.

• modulation (float) – Directional modulation depth for all channels.

• speed_modulation (float) – Speed modulation (non-directional) for all channels.

• seed (int | None) – Random seed for reproducibility.

Return type:

None

class CosineEncoderTransformer(*args, **kwargs)

Bases: BaseStatefulTransformer[CosineEncoderSettings, AxisArray, AxisArray, CosineEncoderState]

Transform polar coordinates to multi-channel encoded output.

Input: AxisArray with shape (n_samples, 2) containing polar coordinates

(magnitude, angle) where magnitude is speed and angle is direction.

Output: AxisArray with shape (n_samples, output_ch) containing encoded values.

The encoding formula is:

output = baseline + modulation * magnitude * cos(angle - pd)

• speed_modulation * magnitude

This is a generic encoder suitable for various applications including: - Neural firing rate encoding (baseline=10Hz, modulation=20Hz) - LFP spectral parameter modulation (baseline=1.0, modulation=0.5) - Any other cosine-tuning based encoding

class CosineEncoderUnit(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[CosineEncoderSettings, AxisArray, AxisArray, CosineEncoderTransformer]

Unit wrapper for CosineEncoderTransformer.

Parameters:

settings (Settings | None)

SETTINGS

alias of CosineEncoderSettings

class CosineEncoderSettings(model_file=None, output_ch=10, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Bases: Settings

Settings for CosineEncoder.

Either model_file OR the random generation parameters should be specified. If model_file is provided, parameters are loaded from file. Otherwise, parameters are randomly generated.

Parameters:

• model_file (str | None)

• output_ch (int)

• baseline (float)

• modulation (float)

• speed_modulation (float)

• seed (int | None)

model_file: str | None = None

Path to .npz file with encoder parameters (baseline, modulation, pd, speed_modulation). Also supports legacy neural tuning files with keys (b0, m, pd, bs).

output_ch: int = 10

Number of output channels (used if model_file is None).

baseline: float = 0.0

Baseline output value for all channels (used if model_file is None).

modulation: float = 1.0

Directional modulation depth for all channels (used if model_file is None).

speed_modulation: float = 0.0

Speed modulation (non-directional) for all channels (used if model_file is None).

seed: int | None = None

Random seed for reproducibility of preferred directions (used if model_file is None).

__init__(model_file=None, output_ch=10, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Parameters:

• model_file (str | None)

• output_ch (int)

• baseline (float)

• modulation (float)

• speed_modulation (float)

• seed (int | None)

Return type:

None

class CosineEncoderState

Bases: object

State for cosine encoder transformer.

Holds the per-channel encoding parameters. All arrays have shape (1, output_ch) for efficient broadcasting during processing.

baseline

Baseline output value for each channel.

modulation

Directional modulation depth for each channel.

pd

Preferred direction (radians) for each channel.

speed_modulation

Speed modulation (non-directional) for each channel.

ch_axis

Pre-built channel axis for output messages.

baseline: ndarray[tuple[Any, ...], dtype[floating]] | None = None

modulation: ndarray[tuple[Any, ...], dtype[floating]] | None = None

pd: ndarray[tuple[Any, ...], dtype[floating]] | None = None

speed_modulation: ndarray[tuple[Any, ...], dtype[floating]] | None = None

ch_axis: CoordinateAxis | None = None

property output_ch: int

Number of output channels.

validate()

Validate that all parameters have consistent shapes.

Return type:

None

load_from_file(filepath, output_ch=None)

Load parameters from a .npz file.

The file should contain arrays with keys matching the parameter names. For backwards compatibility with neural tuning files, the following key mappings are supported:

• ‘b0’ -> baseline

• ‘m’ -> modulation

• ‘pd’ -> pd (preferred direction)

• ‘bs’ -> speed_modulation

Parameters:

• filepath (str | Path) – Path to .npz file containing parameter arrays.

• output_ch (int | None) – Number of channels to use. If None, uses all in file.

Return type:

None

init_random(output_ch, baseline=0.0, modulation=1.0, speed_modulation=0.0, seed=None)

Initialize encoder parameters with random preferred directions.

Parameters:

• output_ch (int) – Number of output channels.

• baseline (float) – Baseline value for all channels.

• modulation (float) – Directional modulation depth for all channels.

• speed_modulation (float) – Speed modulation (non-directional) for all channels.

• seed (int | None) – Random seed for reproducibility.

Return type:

None

class CosineEncoderTransformer(*args, **kwargs)

Bases: BaseStatefulTransformer[CosineEncoderSettings, AxisArray, AxisArray, CosineEncoderState]

Transform polar coordinates to multi-channel encoded output.

Input: AxisArray with shape (n_samples, 2) containing polar coordinates

(magnitude, angle) where magnitude is speed and angle is direction.

Output: AxisArray with shape (n_samples, output_ch) containing encoded values.

The encoding formula is:

output = baseline + modulation * magnitude * cos(angle - pd)

• speed_modulation * magnitude

This is a generic encoder suitable for various applications including: - Neural firing rate encoding (baseline=10Hz, modulation=20Hz) - LFP spectral parameter modulation (baseline=1.0, modulation=0.5) - Any other cosine-tuning based encoding

class CosineEncoderUnit(*args, settings=None, **kwargs)

Bases: BaseTransformerUnit[CosineEncoderSettings, AxisArray, AxisArray, CosineEncoderTransformer]

Unit wrapper for CosineEncoderTransformer.

Parameters:

settings (Settings | None)

SETTINGS

alias of CosineEncoderSettings