psiaudio.queue module

class AbstractSignalQueue(fs=None)

Bases: object

Base class for a signal queue.

Manages the queuing, tracking, and generation of waveforms for output.

Parameters:

fs (float, optional) – Sampling rate of output that will be using this queue.

append(source, trials, delays=None, duration=None, metadata=None)

cancel(t, delay=0)

clone()

connect(callback, event='added')

count_factories()

count_requested_trials()

Count total requested trials.

Returns:

Total number of requested trials across all keys.

Return type:

int

count_trials()

Count remaining trials.

Returns:

Number of remaining trials.

Return type:

int

decrement_key(key, n=1)

Decrement trials for key

Parameters:

• key (UUID) – Key to decrement

• n (int) – Number of trials to decrement by

Returns:

complete – True if no trials left for key, False otherwise.

Return type:

bool

extend(sources, trials, delays=None, duration=None, metadata=None)

property fs

get_closest_key(t)

get_info(key)

get_max_duration()

get_ts()

insert(source, trials, delays=None, duration=None, metadata=None)

is_empty()

next_key()

next_trial(decrement=True)

Set up the next trial.

This has immediate effect. If you call this (from external code), the current trial will not finish.

Parameters:

decrement (bool, optional) – If True, decrement trial counters, by default True.

pause(t=None)

pop_buffer(samples, decrement=True)

Return the requested number of samples.

Removes stack of waveforms in order determined by internal mechanism, but only returns the requested number of samples. If a partial fragment of a waveform is returned, the remaining part will be returned on subsequent calls to this function.

Parameters:

• samples (int) – Number of samples to return.

• decrement (bool, optional) – If True, decrement the counters as waveforms start, by default True.

Returns:

1D array containing the requested samples.

Return type:

ndarray

pop_key(key, decrement=True)

Remove one trial of the specified key from queue and return data.

Parameters:

• key (str) – UUID of the stimuli source to pop.

• decrement (bool, optional) – If True, decrements the remaining trials. By default True.

Returns:

Information regarding the trial (source, delays, duration, etc).

Return type:

dict

pop_next(decrement=True)

remaining_trials(key)

remove_key(key)

Removes key from queue entirely, regardless of number of trials.

Parameters:

key (str) – UUID of the stimuli source.

requeue(t)

Requeues all trials scheduled after t0.

Note that this only requeues trials for which the trial counter was automatically decremented when the waveform was generated by the queue. When using artifact reject, trial counters are sometimes decremented by the artifact reject algorithm instead (e.g., ABRs) and the assumption is that the external algorithm will not receive “canceled” trials and, therefore, will not decrement the counter.

Parameters:

t (float) – Time in seconds after which to requeue trials.

resume(t=None)

Resumes generating trials from queue

Parameters:

t (float) – Time, in sec, to resume generating trials from queue.

rewind_samples(t, check=True)

Rewind the queue back to a specific time.

Parameters:

• t (float) – Time in seconds to rewind samples back to.

• check (bool, optional) – If True, new time must be before current time of queue. If False, can be set to a later time. By default True.

set_fs(fs)

set_t0(t0)

class BlockedFIFOSignalQueue(**kwargs)

Bases: GroupedFIFOSignalQueue

Iterates through each waveform in a block equal to the number of queued stimuli.

Like the GroupedFIFOSignalQueue except block size is automatically set to the number of waveforms queued. If you have 8 waveforms queued (A-H), the queue iterates through A B C D E F G H until all trials have been presented.

append(*args, **kwargs)

class BlockedRandomSignalQueue(seed=0, **kwargs)

Bases: InterleavedFIFOSignalQueue

next_key()

class FIFOSignalQueue(fs=None)

Bases: AbstractSignalQueue

Return waveforms based on the order they were added to the queue.

next_key()

class GroupedFIFOSignalQueue(group_size, **kwargs)

Bases: FIFOSignalQueue

Iterates through each waveform in the order it was added, but in blocks.

If the block size is 4 and there are 8 waveforms queued (A B C D E F G H): The queue iterates through A B C D until all trials have been presented, then it shifts to E F G H.

Parameters:

group_size (int) – Number of items to group together.

decrement_key(key, n=1)

Decrement trials for key

Parameters:

• key (UUID) – Key to decrement

• n (int) – Number of trials to decrement by

Returns:

complete – True if no trials left for key, False otherwise.

Return type:

bool

next_key()

class InterleavedFIFOSignalQueue(keep_complete_waveforms=True, **kwargs)

Bases: AbstractSignalQueue

Return waveforms based on the order they were added to the queue. However, trials are interleaved.

Parameters:

keep_complete_waveforms (bool, optional) – If True, include all waveforms in the sequence even if we have acquired the desired number for a given waveform. This ensures that the timing between waveforms is not altered. If False, only includes waveforms that we have not achieved the desired number of trials for. By default True.

count_trials()

Count remaining trials.

Returns:

Number of remaining trials.

Return type:

int

decrement_key(key, n=1)

Decrement trials for key

Parameters:

• key (UUID) – Key to decrement

• n (int) – Number of trials to decrement by

Returns:

complete – True if no trials left for key, False otherwise.

Return type:

bool

next_key()

class NotifierQueue

Bases: object

A thread-safe queue that triggers callbacks for specific events.

Events currently supported include ‘added’, ‘removed’, ‘decrement’, and ‘empty’. Callbacks are invoked on a background thread.

connect(callback, event='added')

Connect a callback to the specified event.

Parameters:

• callback (callable) – Function to call when event occurs.

• event (str, optional) – Event to connect to, by default ‘added’.

join()

notify(event, info)

Notify all connected callbacks of an event.

Parameters:

• event (str) – Event name.

• info (dict) – Information dictionary passed to the callbacks.

run()

Worker thread loop to dispatch events.

exception QueueEmptyError

Bases: Exception

Exception raised when attempting to pop from an empty queue.

class RandomSignalQueue(fs=None)

Bases: AbstractSignalQueue

Return waveforms in random order.

next_key()

as_iterator(x)

Ensure the input is treated as an iterator.

If x is None, it defaults to 0. If x cannot be iterated over, it is returned as an infinitely cycling iterator yielding x.

Parameters:

x (any) – Value to convert to an iterator.

Returns:

Iterator yielding values.

Return type:

iterator