Breakdown documentation tasks for module workflows for how to, glossary

Challenge

Current Aeon modules have multiple aspects to them including:

Device configuration
Device events
Device commands
Logging
State persistence
GUI
Alerts

To effectively use any of the existing modules all these aspects may have to be contemplated in the workflow, placing the device module itself is only the first step.

Example: Foraging Patch

UndergroundFeeder

The core of a foraging patch is the underground feeder device. Placing an underground feeder device is easy:

This node establishes a connection to the hardware module and allows configuration of relevant device operation properties.

However, the UndergroundFeeder is not by itself sufficient to define foraging patch behavior, i.e. no data will be saved, no alert notifications will be sent, pellets will not be delivered on crossing thresholds, etc. For example, we usually also need to know how many pellets are stored in the dispenser. The dispenser is a physical module which has no sensors and is loaded manually with pellets. Because there are no automatic sensors that tell us either how many pellets, or even when pellets are loaded, this dispenser "module" is not part of the feeder Harp device.

PatchDispenser

To work around this limitation we defined an additional PatchDispenser module which acts as a storage of the pellet count state. There are two basic actions associated with this dispenser module: discount a pellet; and load the dispenser with N pellets. The dispenser module will integrate these two event streams to compute the expected number of pellets in the feeder at any one time.

Furthermore, the pellet count state needs to be persisted across recording epochs. The reason for this is to allow the patch to be robust to system crashes, i.e. we do not want to forget how many pellets were in the dispenser if the workflow exits. This requires a special state recovery subject which will log this temporary state in the current working directory.

PatchDispenser GUI

The PatchDispenser module also includes a graphical user interface to allow monitoring of the current number of pellets, and controls for delivering pellets manually, reloading the feeder, and resetting the underground feeder state. Many of these will end up being routed as commands and events to the underground feeder device, but some of them like the manual pellet delivery need to be stored in a separate data stream to allow for post-hoc filtering of data, e.g. to distinguish manual deliveries from foraging deliveries triggered by the running wheel.

Patch Alerts

We have "virtual" events which are computed by online analysis of feeder data. For example, we compute missed pellets by monitoring how much the wheel turns following a pellet delivery. If the animal overturns the wheel we count that pellet has being "missed". This event is logged with a separate address into the patch event stream.

Foraging Logic

Finally, we have task-specific states which are associated with individual patches. For example, the current foraging threshold and rate of depletion. These are computed in software by the task logic module and software-timestamped with the latest Harp time from the feeder.

Patch Logging

Logging of the different streams associated with a patch, is therefore currently a combination of all these different hardware and task streams:

Write detailed breakdown of documentation tasks for modular workflow components.

SainsburyWellcomeCentre / aeon_docs