ESC2025 Course - Tutorial feedback

[bruno-f-cruz]

Day 1

• Consider adding instructions to other python frameworks. Some people suggested that using jupyter notebooks makes it easier to follow the tutorial. However instructions are not clear on how to launch a jupyter notebook from the command line using uv (uv run jupyter-notebook). I have mixed feelings about this as I am actually against using jupyter notebook overal, but leaving it here as it is a common pain point. Maybe we could consider marimo but I think we will need to help people setup anyway... (Also, most of the troubles with installing the package, or using environments results from rogue conda installations. God I hate conda...)
• "Normalizing" timestamps from to "0". This is something that @banchan86 brought up and several people also do. I dont think we want to do this as it is an error prone transformation on the data (e.g. you need to do it for every single stream, exactly once), and I cant get a satisfying answer when I ask "why is it useful"? Nevertheless, if people want this behavior, I think we should document the "write to the seconds register" strategy to force a known offset during acquisition instead of relying on post processing. It should be noted that "read" already has an optional epoch that can be used to achieve something like this. But, once again, it would need to be passed to every single read.
• Adding missing bonsai dependencies to the setup. Specifically, the tutorial requires Bonsai.Gui.ZedGraph and also Bonsai.Harp >= 3.6 (Ambiguous assembly loading order caused by conflicting directory scanning priority between .NET and Bonsai runtime bonsai-rx/bonsai#2321)
• Add instructions on how to run scripts using uv (again not sure this is the goal of the tutorial, but...)
• Add plt.show() to all tutorials to make sure running the snippet will render a plot
• Add a blurb about the meaning of "register". Maybe drawing an analogy between "register" and "function" or "state" could be a a way to go about it.
• Consider adding an hint about automatically naming CSV files to prevent crashes due to name conflict. This happens quite often as people are trying to debug the workflow
• Explicitly bind the name of the file created in HobgoblinDataWriter and the one used during the python analysis (Hobgoblin.harp)
• There is no way to know what is the name of the registers and it is not explained anywhere. People are forced to infer from the name in the register in the Parse node. However the Parse node has the Payload suffix which makes it a bit awkward. If people use jupyter, then get autocompletion which is nice, but there is no "easy" way to know the name of all register otherwise. I am wondering if we should just overload the str method of (RegisterMap) to print all available registers. I dont like this as it makes the print statement quite long. Alternatively we could add a syntactic sugar method to the reader class that simply calls RegisterMap.keys() or, finally, simply document list(reader.registers.keys()) as the way to list all available registers.
• The note at the end of exercise 10 should not be marked as optional. It is an extremely useful exercise to go through.

[glopesdev]

There is no way to know what is the name of the registers and it is not explained anywhere.

You can write dir(device) to find out all names, but it is not currently intuitive so it should go into docs.

[bruno-f-cruz]

Day2

• The python script is missing a "break" at the end of the loop. Otherwise, more than one reponse can be detected per trial
• The final publishSubject should be replaced by BehaviorSubject
• People are generally struggling with the Bool -> Condition. I hate to suggest this, but it may be better to simply output a string "timeout" or "press" and use "equal" inside the condition. Otherwis,e maybe we can try to draw the equivalence to a if-else Python statement. (Aalllsssoooo we should probably just discuss pattern matching for bonsai again lol)
• We may need to make more obvious what the race-condition-to-merge-take(1) does. Some people were struggling with reading it. Simply going over the logic more explicitly may be sufficient. (e.g. if the press happens first, take will cloes the sequence and propagate True...)
• In the first exercise some people were confused (honestly prob a good sign haha) why we didnt have to record the button press to analyze data offline. The point is that harp logs everything, in which the button is also included. Maybe make this explicit in the exercise.