perturbation
behaviour.perturbation
Symbolic reading, code generation and plotting for :class:Stimulus.
Attached to the generated classes by name (StimulusBehaviour -> Stimulus), so a stimulus carries these however it was built — loaded from YAML, nested in an experiment, or constructed directly. The experiment loader used to reassign __class__ to reach the nested one, which left every other construction path without them.
A stimulus is emitted as a Python definition, and the only name it has is label, which is free text. :attr:StimulusBehaviour.identifier is that one resolution — the templates and :meth:StimulusBehaviour.execute both read it, so what is emitted and what is looked up afterwards cannot drift apart.
Attributes
| Name | Description |
|---|---|
| logger |
Classes
| Name | Description |
|---|---|
| StimulusBehaviour | Loading, symbolic reading, rendering and plotting for an exogenous stimulus. |
StimulusBehaviour
behaviour.perturbation.StimulusBehaviour()Loading, symbolic reading, rendering and plotting for an exogenous stimulus.
Attributes
| Name | Description |
|---|---|
| identifier | The Python name the stimulus is emitted under. |
| metadata | The stimulus itself, exposed as its own metadata. |
Methods
| Name | Description |
|---|---|
| execute | Build an executable stimulus for the requested backend. |
| from_datamodel | Copy a datamodel Stimulus’s fields into a new one. |
| from_file | Load a Stimulus from a YAML metadata file. |
| from_ontology | Construct a Stimulus from an ontology class or its label. |
| get_expression | Generate a sympy expression for the equation using metadata. |
| plot | Plot the stimulus time course. |
| render_code | Render the stimulus to backend source code. |
execute
behaviour.perturbation.StimulusBehaviour.execute(
format='tvb',
connectivity=None,
region_indices=None,
weighting=None,
**kwargs,
)Build an executable stimulus for the requested backend.
For "tvb", evaluates the rendered stimulus equation, resolves a connectivity (creating a single-region one when needed) and a per-region weighting, and returns a TVB StimuliRegion. For "python"/"jax", returns a callable stimulus function built from the symbolic equation, or from an audio file when the stimulus is defined by a dataLocation.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| format | Target backend: "tvb", "python", or "jax". |
'tvb' |
|
| connectivity | Connectivity for the TVB StimuliRegion; a one-region connectivity is created when omitted. |
None |
|
| region_indices | Indices of the stimulated regions; when omitted, a random permutation of all regions is used. | None |
|
| weighting | Per-region weights; defaults to 1 on region_indices and 0 elsewhere. |
None |
|
| **kwargs | Extra values forwarded to code rendering or audio loading (e.g. sampling_rate, duration). |
{} |
Returns
| Name | Type | Description |
|---|---|---|
A TVB StimuliRegion for "tvb", or a callable stimulus function for |
||
"python"/"jax". |
from_datamodel
behaviour.perturbation.StimulusBehaviour.from_datamodel(instance)Copy a datamodel Stimulus’s fields into a new one.
from_file
behaviour.perturbation.StimulusBehaviour.from_file(filepath)Load a Stimulus from a YAML metadata file.
from_ontology
behaviour.perturbation.StimulusBehaviour.from_ontology(ontoclass)Construct a Stimulus from an ontology class or its label.
When given a string, searches the ontology for a stimulus class with that label, raising if none is found and warning if several match, then converts the resolved class to metadata via class2metadata.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| ontoclass | A stimulus label to look up, or an ontology stimulus class. | required |
Returns
| Name | Type | Description |
|---|---|---|
A Stimulus populated from the ontology class. |
Raises
| Name | Type | Description |
|---|---|---|
| ValueError | If no stimulus class matches the given label. |
get_expression
behaviour.perturbation.StimulusBehaviour.get_expression()Generate a sympy expression for the equation using metadata.
The one place a stimulus is parsed: the equation’s parameters shadow the SymPy builtins they collide with, and t is the time symbol whichever spelling the metadata used — a right-hand side or a list of conditional branches.
Returns
| Name | Type | Description |
|---|---|---|
| tuple | tuple | (expression, parameters) — the symbolic expression of the equation |
| tuple | (or None) and the resolved parameter substitution dict. |
plot
behaviour.perturbation.StimulusBehaviour.plot(
duration=1000,
dt=0.1,
ax=None,
plot_onset=True,
cut_transient=0,
**kwargs,
)Plot the stimulus time course.
Evaluates the python stimulus function over [cut_transient, duration] at step dt and draws it, optionally marking the onset parameter with a vertical line.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| duration | End of the time window in milliseconds. | 1000 |
|
| dt | Sampling step in milliseconds. | 0.1 |
|
| ax | Existing matplotlib axes to draw on; a new figure is created and returned when omitted. | None |
|
| plot_onset | Whether to mark the onset parameter with a vertical line. |
True |
|
| cut_transient | Start of the time window in milliseconds. | 0 |
|
| **kwargs | Extra keyword arguments forwarded to ax.plot (plus sampling_rate, used for stimulus evaluation). |
{} |
Returns
| Name | Type | Description |
|---|---|---|
The created matplotlib figure when ax was not supplied; otherwise nothing. |
render_code
behaviour.perturbation.StimulusBehaviour.render_code(format='tvb', **kwargs)Render the stimulus to backend source code.
Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| format | Target backend: "tvb" for a TVB stimulus equation, or "python"/"jax" for a standalone stimulus function. |
'tvb' |
|
| **kwargs | Extra values forwarded to the template. | {} |
Returns
| Name | Type | Description |
|---|---|---|
| The formatted source code as a string. |