SequenceControl

class hive.implementation.task_protocol.SequenceControl(sequence: List[int], total_arms: int)

Bases: object

Abstract class for sequence task controlling.

Implement node

1. keep the internal state in the protocol function instead of class attributes.

   because not only the Task would use this sequence control, but other function would use during the session. We need to keep the state isolated.

2. sequence control is not the first object to keep the visiting history.

   Task is the first object to keep the visiting history (not only the arm visiting history). The only reason why sequence control keep a visiting history is to infer the future correct arm.

3. time depend task

   The sequence control can keep a timer as a variable in the protocol function, which should be independent with the Task. If you want the make more complex behavior, you can specialize the sequence control and overwrite the type of the generator to Generator[SequenceStepResult, int, None].

sequence

list of arm ID. According to the sequence, it means the correct visiting sequence in general.

Type

list of int

total_arms

total used arms, which indicate the maxima number of the arms the animal can visit. It does not required the actual number of used arms, it is only used to validate the input.

Type

int

Attributes Summary

sequence_str

present sequence in str

Methods Summary

foreach_steps(visit[, start, stop, ...])	go through the visit history.
protocol()	generate a sequence control generator.

Attributes Documentation

sequence_str

present sequence in str

Methods Documentation

foreach_steps(visit: List[int], start: int = 0, stop: Optional[int] = None, pass_initial_step=False) → Iterable[Tuple[int, int, SequenceStepResult]]

go through the visit history.

example of using

# get a sequence control
control = LinearTrackSeqControl()

# count how many correct visiting
success = 0

for trial, visit, result in control.foreach_steps(visit):
    if result.success:
        success += 1

Parameters

• visit – visit history

• start – from trial

• stop – stop at trial

• pass_initial_step – pass initial step to consumer function

abstract protocol() → Generator[SequenceStepResult, int, None]

generate a sequence control generator. You can see LinearTrackSeqControl as example to learn how to create a generator.

Example to create a protocol

def protocol(self) -> Generator[SequenceStepResult, int, None]:
    # we use all arms
    # arm 0 is a special case, it indicate that the animal back to the center platform.
    possible = list(range(1, self.total_arms))

    # first, yield the initial state
    visit: int = (yield SequenceStepResult(None, None, possible))

    while True: # during the task
        # validate the input
        if not (0 <= visit <= self.total_arms): # not a valid input
            success = None
        elif next_visit == 0: # the animal back to center platform
            success = None
        else:
            # handle visit, get the result of success and update the internal states
            success = ...

        # yield the current state, and get the next visit
        visit: int = (yield SequenceStepResult(None, None, possible))

Example to use the protocol

# get a sequence control
control = LinearTrackSeqControl()

# create a protocol
gen = control.protocol()

# get the initial state
state = gen.send(None)

# and update the device according to the initial state
update_state(state)

while True: # during the task
    # waiting the animal enter the platform
    visit = wait_for_next_visit()

    # get the visit result
    result = gen.send(visit)

    # give food if the animal made a correct visiting.
    if result.success:
        # give food to where the animal stand
        give_food(visit)

    # update the device according to the current state
    update_state(result)

# end of task. close the generator
gen.close()

Returns

generator of SequenceStepResult

Return type

generator

References

LinearTrackSeqControl DefaultSeqControl ErrCorrSeqControl IncrementalDifficultySeqControl