stytra.stimulation package


stytra.stimulation.estimators module

class stytra.stimulation.estimators.Estimator(acc_tracking: stytra.collectors.accumulators.QueueDataAccumulator, experiment)[source]

Bases: object

An estimator is an object that estimate quantities required for the control of the stimulus (animal position/speed etc.) from the output stream of the tracking pipelines (position in pixels, tail angles, etc.).

class stytra.stimulation.estimators.VigorMotionEstimator(*args, vigor_window=0.05, base_gain=-12, **kwargs)[source]

Bases: stytra.stimulation.estimators.Estimator

A very common way of estimating velocity of an embedded animal is vigor, computed as the standard deviation of the tail cumulative angle in a specified time window - generally 50 ms.


lag – (Default value = 0)


The rotation matrix for an angle theta

class stytra.stimulation.estimators.PositionEstimator(*args, change_thresholds=None, velocity_window=10, **kwargs)[source]

Bases: stytra.stimulation.estimators.Estimator


stytra.stimulation.stimulus_display module

class stytra.stimulation.stimulus_display.StimulusDisplayWindow(protocol_runner, calibrator, record_stim_framerate=None, gl=False, **kwargs)[source]

Bases: lightparam.param_qt.ParametrizedWidget

Display window for a visual simulation protocol, with a display area that can be controlled and changed from a ProtocolControlWindow.

The display area (either a QWidget or a QOpenGLWidget, see below) is where the paint() method of the current Stimulus will draw the current image. The paint() method is called in the paintEvent() of the QWidget.

Stimuli sequence and its timing is handled via a linked ProtocolRunner object.

Information about real dimensions of the display comes from a calibrator object.

If required, a movie of the displayed stimulus can be acquired and saved.


Set monitor dimensions when changed from the control GUI.

class stytra.stimulation.stimulus_display.StimDisplayWidget(*args, protocol_runner, calibrator, record_stim_framerate)[source]

Bases: object

Widget for the actual display area contained inside the StimulusDisplayWindow.


Generate the stimulus that will be displayed. A QPainter object is defined, which is then passed to the current stimulus paint function for drawing the stimulus.




Function called by the protocol_runner timestep timer that update the displayed image and, if required, grab a picture of the current widget state for recording the stimulus movie.


Finalize stimulus movie. :return: a channel x time x N x M array with stimulus movie


Resets the movie recorder

Module contents

class stytra.stimulation.ProtocolRunner(experiment=None, target_dt=0, log_print=True)[source]

Bases: PyQt5.QtCore.QObject

Class for managing and running stimulation Protocols.

It is thought to be integrated with the stytra.gui.protocol_control.ProtocolControlWidget GUI.

In stytra Protocols are parameterized objects required just for generating a list of Stimulus objects. The engine that run this sequence of Stimuli is the ProtocolRunner class. A ProtocolRunner instance is not bound to a single Protocol object:

  • new Protocols can be set via the self.set_new_protocol() function;

  • current Protocol can be updated (e.g., after changing parameters).

New Protocols are set by their name (a way for restoring state from the config.h5 file), but can also be set by passing a Protocol() class to the internal _set_new_protocol() method. Every time a Protocol is set or updated, the ProtocolRunner uses its get_stimulus_sequence() method to generate a new list of stimuli.

For running the Protocol (i.e., going through the list of Stimulus objects keeping track of time), ProtocolRunner has an internal QTimer whose timeout calls the timestep() method, which:

  • checks elapsed time from beginning of the last stimulus;

  • if required, updates current stimulus state

  • if elapsed time has passed stimulus duration, changes current stimulus.

  • experiment (stytra.experiment.Experiment) – the Experiment object where directory, calibrator et similia will be found.

  • dt (float) – (optional) timestep for protocol updating.

  • log_print (Bool) – (optional) if True, print stimulus log.

  • protocol (str) – (optional) name of protocol to be set at the beginning.



Emitted at every timestep with the index of the current stimulus.


Emitted every change of stimulation, with the index of the new stimulus.


Emitted when the protocol sequence starts.


Emitted when the protocol sequence ends.


Emitted when protocol is changed/updated


Update current Protocol (get a new stimulus list if protocol exist.


Make the protocol ready to start again. Reset all ProtocolRunner and stimuli timers and elapsed times.


Start the protocol by starting the timers.


Update displayed stimulus. This function is the core of the ProtocolRunner class. It is called by every timer timeout. At every timestep, if protocol is running:

  • check elapsed time from beginning of the last stimulus;

  • if required, update current stimulus state

  • if elapsed time has passed stimulus duration, change current



Stop the stimulation sequence. Update log and stop timer.


Append the log appending info from the last stimulus. Add to the stimulus info from Stimulus.get_state() start and stop times.


Update a dynamic log. Called only if one is present.


Get total duration of the protocol in sec, calculated from stimuli durations.


protocol length in seconds.

Return type



Print protocol sequence.

class stytra.stimulation.Protocol[source]

Bases: lightparam.param_qt.ParametrizedQt

Describes a dynamically-generated sequence of Stimuli and their parameters.

Protocol objects generate a list of stimuli, that can optionally be parametrized, so that variants can be made by changing the protocol parameters in the Stytra GUI.

The method Protocol.get_stim_sequence() should be redefined for each experimental protocol: it is called by the ProtocolRunner and it generates a list of stimuli that will be presented during the protocol. When defining new protocols, subclass this class and redefine get_stim_sequence().

By default, all protocols have an optinal initial and final pause and a parameter n_repetitions that specifies the number of times the sequence from Protocol.get_stim_sequence() will be repeated.


Everything concerning calibration, or asset directories that have to be passed to the stimulus is handled in the ProtocolRunner class to leave this class as light as possible.

name = ''

Name of the protocol.


To be specified in each child class to return the proper list of stimuli.