Structure of the Refactoring of the Experiment class Library

[Parvfect]

Hey, this is Parv Agarwal - and I'm the GSOC student working on the Experiment Class refactor such that it gets rid of the repeated code and makes it more generic using classes etc. following what's detailed in https://docs.google.com/document/d/11zC94sozuMYtfOcvQl38MuaC1HednfGrA1ymsTapKHk/edit#heading=h.ms4qewfw0h65.

I have a question on how that needs to be done however, since there are various ways it can be done. There is a lot of repeated code in each experiment, and most of it in the main process function seems to follow this algorithm ->

1. Setup Trial List
2. Setup Graphics
3. Show Instruction screen
4. Start EEG Stream
5. Iterate Through Events
   1. Set Intertrial Interval
   2. Present the Stimulus
   3. Push Sample
   4. Offset
   5. Might be some user interaction for cueing etc. → complex operation
6. Cleanup - Closing EEG Stream

There are some variations in the Cueing and Go-No-Go Experiments and I assume further experiments will need additional methods to work with it. I would prefer a main function in a header class that does all the work where the trials, the stimulus and the specific mechanisms of the experiment are passed in as generic types, however this may depend on a lot of things, and could prove tricky especially since its Python.

So the questions are really this,

1. Do we want to have as much code as possible in the master class, somewhat like a main function that works with generic types being passed in? EG. Experiment class has all the code, specific functions, variables, events and stimuli are passed in that are called according to the stage of the cycle?
2. Do we want to just have a common set of shared data members in the form of a data class as per Implement ExperimentSpec to reduce redundancy #76?
3. Do we want to split the main piece of code into a lot of functions like settng up trials, graphics, etc?
4. How different are the next experiments that are going to be incorporated be? Will they be able to stick to such a protocol?

This is the most repeated code in each experiment class,

class Experiment:

    def present(duration=120, eeg: EEG=None, save_fn=None, n_trials=2010, exp_name=""):
        """ Do the present operation for a bunch of experiments """
      
        # Setup Trial list -> Common in most
        parameter = np.random.binomial(1, 0.5, n_trials)
        trials = DataFrame(dict(parameter=parameter, timestamp=np.zeros(n_trials)))

        # Setup Graphics 
        mywin = visual.Window([1600, 900], monitor="testMonitor", units="deg", fullscr=True) 
        """ Does specific thing within Experiment Type to load stimulus data """

        # Show Instruction Screen
        show_instructions(duration=duration)

        # Start EEG Stream, wait for signal to settle, and then pull timestamp for start point
        if eeg:
        if save_fn is None:  # If no save_fn passed, generate a new unnamed save file
            random_id = random.randint(1000,10000)
            save_fn = generate_save_fn(eeg.device_name, "visual_n170", random_id, random_id, "unnamed")
            print(
                f"No path for a save file was passed to the experiment. Saving data to {save_fn}"
            )
        eeg.start(save_fn, duration=record_duration + 5)

        start = time()
        
        # Iterate through the events
        for ii, trial in trials.iterrows():
          
            # Intertrial interval
            core.wait(iti + np.random.rand() * jitter)

            # Some form of presenting the stimulus - sometimes order changed in lower files like ssvep

            # Push sample
            if eeg:
                timestamp = time()
                if eeg.backend == "muselsl":
                    marker = [markernames[label]]
                else:
                    marker = markernames[label]
                eeg.push_sample(marker=marker, timestamp=timestamp)

            # Offset
            mywin.flip()
            if len(event.getKeys()) > 0 or (time() - start) > record_duration:
                break
            event.clearEvents()


        # Close the EEG stream 
        if eeg:
            eeg.stop()

    def show_instructions(instruction_text):
    
        instruction_text = instruction_text % duration

        # graphics
        mywin = visual.Window([1600, 900], monitor="testMonitor", units="deg", fullscr=True)

        mywin.mouseVisible = False

        # Instructions
        text = visual.TextStim(win=mywin, text=instruction_text, color=[-1, -1, -1])
        text.draw()
        mywin.flip()
        event.waitKeys(keyList="space")

        mywin.mouseVisible = True
        mywin.close()

I'm gonna try to play around with the paradigm I have in mind, but let me know what works best in conjuction with every other defined element. Even if we do implement something like I have in mind, we would need to make sure that it plays well with all the code that's already written and calling these individual experiments so would need a lot of creative thinking. Let me know if this seems sensible or is it just simpler to just have shared data members or something.

[ErikBjare]

Just read through this really quickly, and my initial response is very positive!

Do we want to have as much code as possible in the master class, somewhat like a main function that works with generic types being passed in? EG. Experiment class has all the code, specific functions, variables, events and stimuli are passed in that are called according to the stage of the cycle?

Whenever I code I tend to try to make the "master class" just an interface/spec, and then implement a concrete class on top which could do a lot of heavy lifting during init, but will also let people inherit the master class themselves if they want a special init behavior.

Not sure what exactly you mean here by "generic types", generic types of what?

Also: Do you know of/have used mypy? Would be really nice of this new class helped improve the typing situation (and would clarify what these 'generic types' are really about).

Do we want to just have a common set of shared data members in the form of a data class as per
#76?

As it was my suggestion, I think so. But these two things could go hand in hand. An ExperimentSpec could be contructed from code or config, and then used to initialize and run an experiment.

Might not be necessary though with your refactor, not sure.

Do we want to split the main piece of code into a lot of functions like settng up trials, graphics, etc?

Depends? Split if it makes sense (eases readability/leads to code reuse), but don't split for the sake of splitting :)

How different are the next experiments that are going to be incorporated be? Will they be able to stick to such a protocol?

I think we can assume that experiments can be quite multimodal and some will always require a higher degree of customization. @JohnGriffiths is prob better suited to answer this though.

[JohnGriffiths]

Thanks for kicking this off Parv.

Will give my feedback on the Qs soon.

First though wanted to flag something work looking at when thinking about experiment class etc - this repo designed for gtec unicorn (which is also one of our supported devices).

It's not super well documented by looks like a version of some of the things we are contemplating here.

https://github.com/mattpontifex/UnicornHybridBlack

https://github.com/mattpontifex/UnicornHybridBlack/blob/master/Python%20Collect/Gentask/ExampleTask.py

[JohnGriffiths]

Some more reference points - kernel tasks sdk:

https://docs.kernel.com/docs/kernel-tasks-sdk

https://community.kernel.com/data-analysis-izekt4rr/post/example---using-the-kernel-tasks-sdk-Bf6C3yKmSiERTj5

Not sure the latter will be accessible, so here is the content:

---

This is an example of how to implement a PsychoPy-based task using our Kernel Tasks SDK. The Kernel Tasks SDK is available to all customers as software that is provided with your system. This specific example is code from the Finger-Tapping Task that is shipped as an example task with every system.

""" Runs the task from the menu """
import logging
from datetime import datetime
from importlib.metadata import version as get_version

import numpy as np
import pandas as pd
from kernel.sdk.task import TaskClient
from kernel.sdk.task_registry import TaskRegistry
from kernel.tasks.tap.params import TapParams
from kernel.tasks.tap.prompts import TapPrompts
from psychopy import core, event

logger = logging.getLogger(__name__)
event.globalKeys.add(key="c", modifiers=["ctrl"], func=core.quit)
event.globalKeys.add(key="escape", func=core.quit)


def run_task(params: TapParams, prompts: TapPrompts, practice: bool):
    tc = TaskClient(
        multicast_ip=params.ip,
        multicast_port=params.port,
        debug=params.debug_mode,
        enforce_registry_entry=not practice,
        experiment_name="finger_tapping",
        experiment_version=get_version("kernel.tasks.tap"),
    )

    params.send_params(tc)

    # start experiment
    block_stim_info = prompts.practice_block_stim_info if practice else prompts.block_stim_info
    exp_type = "practice" if practice else TaskRegistry.FT02

    quit_request = False

    with tc.experiment(type=exp_type):
        logger.info(f"starting experiment with type {exp_type}")

        # baseline rest period
        if not practice:
            logger.info("initial rest period")
            prompts.win_flip()
            prompts.draw_fixation()
            prompts.win_flip()
            tc.rest(params.baseline_dur)

        # loop through blocks
        for b_type, t_types in block_stim_info:

            prompts.draw_hand(b_type)
            prompts.win_flip()

            # start block
            with tc.block(type=b_type):

                # loop through trials
                for idx_trial, t_type in enumerate(t_types):

                    # ITI
                    with tc.event("ITI"):
                        ITI_dur = np.random.normal(loc=params.ITI_dur_mean, scale=params.ITI_dur_std, size=1)[0]
                        keypresses = event.waitKeys(maxWait=abs(ITI_dur), keyList=params.quit_keys, clearEvents=True)

                    if keypresses:
                        quit_request = True
                        break

                    # start trial
                    with tc.trial(type=t_type):
                        # draw hand + finger cue
                        prompts.draw_hand(b_type)
                        prompts.draw_finger_cue(b_type, t_type)
                        prompts.win_flip()
                        keypresses = event.waitKeys(maxWait=params.tap_dur, keyList=params.quit_keys, clearEvents=True)
                        logger.info(f"tap with type {t_type}")
                        prompts.draw_hand(b_type) if idx_trial != len(t_types) - 1 else prompts.draw_fixation()
                        prompts.win_flip()

                    if keypresses:
                        quit_request = True
                        break
            if quit_request:
                break

            # ease transition b/w blocks
            if practice:
                core.wait(1)
                prompts.win_flip()
            else:
                # rest
                logger.info("rest")
                prompts.draw_fixation()
                prompts.win_flip()
                tc.rest(params.rest_dur)

        if not practice and not quit_request:
            tc.rest(params.end_baseline_dur)

    if practice:
        prompts.draw_end_practice(wait=True)
    else:
        prompts.draw_finished(ease_in=0.5)

    if params.debug_mode:
        df_out = pd.DataFrame(tc.debug_events)
        df_out.timestamp *= 1e-9
        df_out.to_csv(f'task_df_{datetime.now().strftime("%Y%m%d_%H%M%S")}.csv', index=False)

    logger.info("ending experiment")

You can see from this example that we have implemented a TaskClient that abstracts the process of sending event data according to the guidance that we’ve posted here: https://docs.kernel.com/docs/kernel-tasks-sdk

Note that following the documented guidance is necessary for compliance with the SNIRF specification event structure and we recommend using our TaskClient to simplify getting it right when your SNIRF files are exported.

As always, we're here to support any issues you encounter.