Write documentation for experiment and schema

[RoboDoig]

No description provided.

[ederancz]

I suggest to write incrementally with the issues we encounter.
Here are the first few issues in order of urgency.

0. details on acquisition folders

ExperimentEvents - such as halt, can be multiple consecutive files
OnixAnalogClock - timestamps of photodiode
OnixAnalogData - data of photodiode
OnixAnalogFrameCount - photodiode data is buffered (chunked) so this is needed for processing
OnixAnalogHubSyncCounter - we don't know
OnixDigital - csv file from the digital out and rerecorded in (synchronisation for photometry)
OnixHarp - csv file with Clock(hardware clock = HARP synchroniser device), HubClock, HarpTime, explore "issues" to understand better (Nora has some whatsApp with Andrew about this)

1. Unit conversions for the most important H1 and H2 registers

flowY to degrees - What is the sensor resolution (range 100-12000 cpi, but I can't find it where is it set).
pulse interval to motor displacement in degrees register H2#42
During stationary ball, pulse interval toggles between 20000 and 0, with no motor movement. This is weird as this should be a signed value, with the sign representing rotation direction.
motor encoder to motor position in degrees register on H2

2. Gain definitions.

Gain calculation equations from Andrew below make sense superficially. But unclear what the units are (flowX, flowY, rotary, playback). Ultimately we want to say motor gain = W and visual gain = Z of optical flow sensor (in degrees).
Here are the definitions from Andrew for reference:

Hierarchy
Global
-runGain
	Block
	-blockGain
		Visual
		-flowXToVisual etc…

Definitions:
---Visual
(runGain * blockGain) * (flowX*a + flowY*b + rotary*c + playback*d) = amount to move visual field
---Motor
(runGain * blockGain) * (flowX*e + flowY*f + playback*g) = amount to move motor

3. H2 register documentation with units and range

4. H1 register documentation with units and range

5. Optical flow sensor smoothing

Is there any smoothing applied? Where is it in the workflow and how to change it (no need for separate external parameter in the yml file).

[EleonoraAmbrad]

part of the schema documentation issue, but just encountered: when setting the runThreshold parameters to induce halts, we were wondering about the exact definition of the decayTimestep and the runThresholdDecay. From what we understood, the runThreshold is modified by subtracting position units from it, at a rate controlled by the decayTimestep, but when does this stop? Also, what is the exact function of these two parameters?

[RoboDoig]

You can check these definitions in the schema itself.

As the animal runs a value is accumulated which is compared to the threshold value, when it exceeds this value a halt is produced. If the animal doesn't run, the accumulated value decays back to 0.

decayTimestep: the time in seconds between each decay towards 0
runThresholdDecay: the amount of decay towards 0 applied on each decayTimestep

The units of runThresholdDecay sort of depends what is contributing towards the accumulation of running. This is usually the flow sensors - and in this case the units are related to flow sensor units.

[RoboDoig]

For the schema documentation, it would be nice to use GitHub actions to compile the schema parameter descriptions to a section at the end of the main readme. Could also auto-link to the device schemas for the h1/h2 devices to document data types on the registers.

[ederancz]

additionally to an experiment readme (with throubleshooting), here is an example:
https://github.com/SainsburyWellcomeCentre/aeon_experiments
including best practice to run Bonsai from github repo to save the githash