AbstractSequenceTask¶

class hive.implementation.abstract_task.AbstractSequenceTask(action, trigger: Dict[str, Trigger])¶

Bases: Task

Task couple with SequenceControl.

Personalize your task

You can override some functions to custom your task protocol.

Setup the task

reset: Initiate the state machine. Invoked when the SEQUENCE AUTO MODE enable or start command is used.
declare which devices you plan to use:
- use_food_devices
- use_door_devices

Start task (workflow defined in _cmd_start)

start_task: setup devices.
new_seq_control: get the Sequence Control to use (Protocol definition of the task).

During task (workflow defined in visit_arm)

give_food: send commands to the devices according the animal visiting result.

Stop the task (workflow defined in _cmd_end)

stop_task: print task summary

Command line interface to interact with Task.

Command are case-insensitive. These commands can be personalised at the task implementation level.

help: print all commands
mode: list current mode list
mode MODE: set mode to MODE
shortcut: show keyboard shortcut keyboard
shortcut CHARS: set keyboard shortcut keyboard, start from index 1. For example, map “QWER” to arm “1234”
get: list all parameters name
get *: print all parameter value
get PARA: get parameter PARA value
set SEQ…: set sequence (SEQ should be numbers). For example set 1 2 3 4.
set PARA VALUE…: set parameter PARA with VALUE.
seq: show sequence used
seq SEQ…: set sequence (SEQ should be numbers). For example seq 1 2 3 4.
visit: print visit history.
note: print visiting note
note TEXT…: set a TEXT note to current visiting record.
note TRIAL TEXT…: set a TEXT note to trial TRIAL’s visiting record. Use negative value to set last TRIAL’s visiting record.
status: print current task status.
score: print current correct/incorrect count.
start: start task
end: stop task
ARM (arm number): trigger animal vising event by invoking visit_arm. ARM should be a single digit number or the character in keyboard shortcut.
+NUM: temporary increase the max trial limit. It is used when the user trigger animal vising event by mistake. By increasing the limit, it prevent the Task from stopping the task when the trial number over the original limit.
other commands defined in config file.

Add new command in your task

Define a function whose name starts with ‘_cmd_’ and following the command name.

def _cmd_CUSTOM(self, args:str):
    pass

Handle custom event type (when adding new triggers)

Event type already handle:

detection -> process_detection
command -> process_command
battery level -> process_battery_level

def filter_event(self, event_type: str, event_data: str):
    if event_type == "your_custom_event_type":
        # put your custom processing here
        pass
    else:
        super.filter_event(event_type, event_data)

Add a custom mode in your task

def get_mode(self) -> List[str]:
    return [your_mode_list, *super().get_mode()]

def set_mode(self, mode: str = None, verbose=True):
    if mode is None: # print mode status
        self.log_emit("mode " + ",".join(self.get_mode()))

    elif mode == your_mode_name:
        ...

    else:
        super().set_mode(mode, verbose=verbose)

Add a custom parameter

@property
def your_parameter(self):
    pass

@your_parameter.setter
def your_parameter(self, value):
    pass

def get_para(self, para: str = None):
    if para is None:
        return ["your_parameter", *super().get_para()]
    else:
        return super().get_para(para)

timer¶

timer trigger

Type: Timer

door_control¶

door devices control

Type: DoorControl

food_control¶

food devices control

Type: FoodControl

mode_food¶

mode of food giving. one of MODE_FOOD_* .

Type: str

Attributes Summary

`MODE_FOOD_CONSIST`
`MODE_FOOD_INCREASE`
`STATE_INIT`
`STATE_RUN`
`count`	the score of the visiting so far
`current_trial`
`door_forbidden_period`	the period which the door device reject the coming commands when it is perform the action.
`food_basic_mount`	The basic/minima mount of food giving.
`food_inc_mount`	The increase mount of food giving when the animal made the correct visiting continuously.
`food_max_mount`	The maxima mount of food giving.
`keyboard_shortcut`	current keyboard layout used
`max_trial`	maximal number the animal can visit.
`routine_battery_check`	interval of devices battery level checking routine
`running`	Give the state of the automatic mode.
`sequence`	the sequence used in this Task
`state`	current state of this Task.
`stay_duration`	Time duration from the animal last visiting
`task_duration`	Time duration from the task start
`task_start`	Does task start?
`task_start_time`	Time stamp of the task start
`task_stop_time`	Time stamp of the previous task stop.
`time_out`	maximal duration the task can perform.
`time_stay`	maximal duration the animal can stay on a platform.
`use_door_devices`	declare which door devices plan to use.
`use_food_devices`	declare which food devices plan to use.
`visit_history`	the animal visiting history
`visit_notes`	visiting record note
`visit_timestamp`	the animal visiting timestamps

Methods Summary

`all_commands`()	list all support commands
`all_modes`()
`all_states`()
`filter_event`(event_type, event_data)	filter the incoming event.
`get_command`(command)	get command callable/function.
`get_mode`()	get current modes list
`get_para`()	get supported parameters (para is None) or parameter value
`give_food`(visit_arm, result)	invoked when the animal visit the arm.
`invoke_command`(command, *args)	invoke command.
`log_emit`(message)	logging.
`logging_result_visit_arm`(visit_arm)
`new_seq_control`()	get the sequence control.
`process_command`(command)	Process the detect keyboard event.
`process_detection`(device_id)
`process_low_battery`(element_id, percentage)
`reset`()	Initiate the state machine.
`set_mode`([mode, verbose])	print mode list or set mode
`set_para`(para[, value])	set parameter value
`set_visit_note`(message[, trial, replace])	set message to visiting record note.
`setup`(config)	setup this Task from config.
`show_task_summary`()	show task information to log window
`start_task`()	invoked when the task start.
`stop_task`()	invoked when the task stop.
`visit_arm`(visit_arm)	process animal visiting event.

Attributes Documentation

MODE_FOOD_CONSIST = 'food-consist'¶

MODE_FOOD_INCREASE = 'food-increase'¶

STATE_INIT = 'STATE_INIT'¶

STATE_RUN = 'STATE_RUN'¶

count¶: the score of the visiting so far

current_trial¶

door_forbidden_period¶: the period which the door device reject the coming commands when it is perform the action.

food_basic_mount¶: The basic/minima mount of food giving. The value represent the food delivery time.

food_inc_mount¶: The increase mount of food giving when the animal made the correct visiting continuously. The value represent the food delivery time.

food_max_mount¶: The maxima mount of food giving. The value represent the food delivery time.

keyboard_shortcut¶: current keyboard layout used

max_trial¶

maximal number the animal can visit.

Once the animal over this value, Task will invoke ‘END’ command.

routine_battery_check¶: interval of devices battery level checking routine

running¶

sequence¶: the sequence used in this Task

state¶: current state of this Task. one of STATE_* .

stay_duration¶: Time duration from the animal last visiting

task_duration¶: Time duration from the task start

task_start¶: Does task start?

task_start_time¶: Time stamp of the task start

task_stop_time¶

Time stamp of the previous task stop.

None if the task still running.

time_out¶

maximal duration the task can perform.

Once the animal over this value, Task will invoke ‘END’ command.

time_stay¶

maximal duration the animal can stay on a platform.

Once the animal over this value, Task send a message to log window, let user decide what to do next.

use_door_devices¶

declare which door devices plan to use.

It is used to reset the DoorControl. By default, Task only use the food devices which is related to the sequence.

Returns: door devices plan to use
Return type: name list

use_food_devices¶

declare which food devices plan to use.

It is used to reset the FoodControl. By default, Task only use the food devices which is related to the sequence.

Returns: food devices plan to use
Return type: name list

visit_history¶: the animal visiting history

visit_notes¶

visiting record note

Returns: trial number map to note text
Return type: dict

visit_timestamp¶: the animal visiting timestamps

Methods Documentation

all_commands() → List[Tuple[str, Callable[[...], None]]]¶

list all support commands

Return type: list of (command name, command callable)

classmethod all_modes() → List[str]¶

classmethod all_states() → List[str]¶

filter_event(event_type: str, event_data: str)¶

filter the incoming event.

event type

there are common used event types/groups in hive.

detection DEVICE

detection event from trigger like the keyboard or tracking
battery level DEVICE,LEVEL

device battery level callback event

Parameters

event_type – event type or group
event_data – event data

get_command(command: str) → Optional[Callable[[...], None]]¶

get command callable/function.

Parameters: command – command name
Returns: None if not found.
Return type: callable

get_mode() → List[str]¶: get current modes list

get_para() → List[str]¶
get_para(para: str) → Any: get supported parameters (para is None) or parameter value

give_food(visit_arm: int, result: SequenceStepResult)¶

invoked when the animal visit the arm.

This function purpose to send commands to food/door devices.

Parameters

visit_arm – where the animal visiting
result – the result of this visiting

invoke_command(command: str, *args: str)¶

invoke command.

Parameters

command – command name
args – command arguments

Return type

command callable return

log_emit(message: str)¶: logging. type safe version for self.log.emit

logging_result_visit_arm(visit_arm)¶

abstract new_seq_control() → SequenceControl¶: get the sequence control.

process_command(command: str)¶: Process the detect keyboard event.

process_detection(device_id)¶

process_low_battery(element_id: str, percentage: str)¶

reset()¶: Initiate the state machine.

set_mode(mode: Optional[str] = None, verbose=True)¶: print mode list or set mode

set_para(para: str, value: Optional[Any] = None)¶: set parameter value

set_visit_note(message: str, trial: Optional[int] = None, replace=False)¶

set message to visiting record note.

Parameters

message – message text
trial – trial number, None for current trial
replace – replace the text. Otherwise, append to previous text.

setup(config: Dict[str, Any])¶

setup this Task from config.

Parameters: config – section of Task.options in config file

show_task_summary()¶: show task information to log window

start_task()¶: invoked when the task start. this function is used to reset the door/food control.

stop_task()¶: invoked when the task stop.

visit_arm(visit_arm: int)¶

process animal visiting event.

Parameters: visit_arm (int) – where the animal visiting

AbstractSequenceTask¶

Previous topic

Next topic

This Page