braintools.cogtask.circular

Contents

braintools.cogtask.circular#

braintools.cogtask.circular(key, coherence_key=None, base_value=0.5, max_coherence=100.0, as_index=False, num_dirs=None)[source]#

Cosine-tuned directional encoder.

The output of unit i (for i in [0, feature.num)) is base_value + (coh / (2 * max_coherence)) * cos(pref_i - direction), where preferred directions pref_i are uniformly spaced on the circle.

Parameters:
  • key (str) – Context key holding the direction. By default this is an angle in radians; if as_index=True, it is interpreted as an integer index in [0, num_dirs) and converted to 2π * idx / num_dirs.

  • coherence_key (str | None) – Context key with a coherence in [0, max_coherence]. If None the encoder uses max_coherence (full strength).

  • base_value (float) – Additive baseline (default 0.5).

  • max_coherence (float) – Coherence normalization constant (default 100).

  • as_index (bool) – Interpret ctx[key] as an integer index rather than radians.

  • num_dirs (int | None) – Number of discrete directions when as_index=True. Defaults to feature.num.

Returns:

Encoder function (ctx, feature) -> np.ndarray

Return type:

Callable[[Context, Feature], Array]

Examples

>>> import jax.numpy as jnp
>>> import numpy as np
>>> from braintools.cogtask import Context, Feature, circular
>>> ctx = Context()
>>> ctx.update(direction=jnp.pi / 2, coherence=50.0, sample_idx=1)
>>> encode = circular('direction', 'coherence')  # angle in radians
>>> np.asarray(encode(ctx, Feature(4, 'motion')), dtype=float).round(3)
array([0.5 , 0.75, 0.5 , 0.25])
>>>
>>> # Discrete direction index 1 of 4, i.e. pi / 2, at full coherence
>>> enc = circular('sample_idx', as_index=True)
>>> np.asarray(enc(ctx, Feature(4, 'stimulus')), dtype=float).round(3)
array([0.5, 1. , 0.5, 0. ])