immersivecognition / unity-experiment-framework

UXF - Framework for creating human behaviour experiments in Unity
https://immersivecognition.github.io/unity-experiment-framework/
MIT License
214 stars 41 forks source link

Adding an event tracking system (focus is use in M/EEG & fMRI research) #117

Open JAQuent opened 2 years ago

JAQuent commented 2 years ago

Summary of the idea

Create a tracking system that records custom events (e.g. trial start, object picked up etc.) when they happen in system time (not in relative time) so it can be accurately used to model neural data (e.g. in M/EEG & fMRI), where we need to know the exact timing of when relevant things happened because we want to relate them to the data that is saved by another system (e.g MRI-scanner).

event_tracker Illustration of the idea

Detailed description

My current idea is that there is central script called EventTracker.cs that receives bits of informations (like strings) from other scripts (e.g. a script that deals with picking up objects) and records & saves these bits to a .txt file. This system would be for relatively rare events that don't need to be updated every frame in contrast to for instance the player position, so in my opinion this tracker system only needs to write something down when it receives information but not when nothing happens. I also think it would be useful to have this script running across trials & blocks so inforrmation about trial starts can be saved. However, I am not sure whether that conflits with how UXF is set up.

Further comments

I think this kind of functionality might be useful for neuroimaging research because it lets you use relevant information directly. I will work on something like this for my own fMRI research so I am happy & willing to develop such functionally but it would be nice to know how it can be easily integrated with UXF and how it can be general enough so it is useful for other people.

jackbrookes commented 2 years ago

We have SessionLogger:

https://github.com/immersivecognition/unity-experiment-framework/wiki/Logging-system

This does almost everything you need I think?

You could also use a tracker class that has manual record mode assigned, so you just record the data only when you call the Record method.

However, it is very easy to create a script like you suggested, you can build a table of data then pass your data to session.SaveDataTable in a method assigned to session.preSessionEnd. UXF will handle all of the saving. You can even add listeners to session.onTrialBegin to make trial timetamps log too.

Look at SessionLogger for inspiration:

https://github.com/immersivecognition/unity-experiment-framework/blob/master/Assets/UXF/Scripts/SessionLogger.cs

I'll leave this open just for future reference as there can definitely be improvements to the system.

JAQuent commented 2 years ago

This does sound great indeed. I will check how that work for my current project and see if there might be something that can or should be improved.