Define the API for DARC experiments

[drbenvincent]

While we have Kirby and Frye et al paradigms available, the focus of the toolbox was to use the Bayesian Adaptive Designs on the DARC paradigm.

At the moment, the design is decided by a small snippet of Python code embedded within PsychoPy. This creates a design object which provides designs for each trial, and accepts the (design, response) pairs for each trial.

What we want, is a concise, easy to understand way to allow people to decide the following:

• Delayed choice tasks
  • Front end delay: yes or no. If there is a front end delay, then we'll need the experimenter to specify what DA values they want. So I don't think a boolean frontenddelay flag would be useful. Instead we just leave this up to the experimenter to define either DA=[0] or something likeDA=[0, 7, 14]
  • Paradigm: fixed reward ratio, fixed delay, fixed delayed reward... Well. Fixed delayed is just a simple case of DB=[7] for example. Fixed delayed reward is a simple case of RB=[100]. Fixed reward ratio is a bit different however. For this we maybe provide an optional DA_DB_ratio parameter.
• Risky choice tasks
• Delayed and Risky choice tasks

Decisions

• For Delayed Choice tasks: just a standard API that we've been using. Ie. we have default values, but we can override inputs for DA, RA, etc...
• Same for Risky Choice tasks and Delayed and Risky Choice tasks.

However... We do want it to be very easy for people to just ask for a delayed or risky or delayed and risky choice tasks. So we could either do 3 corresponding subclasses, or something snazzy with input arguments that can be either a set of design parameters of a general class of experiment.

No... don't have loads of different classes for just different input options. Instead do one of the following:

• another function which acts as a middle-man which feeds out objects into PsychoPy
• have multiple alternative constructors. This is perhaps the best option :)

[drbenvincent]

What we have now is reasonable. In PsychoPy we have this code snippet which allows people to specify what they want by setting what_I_want. This code could be hidden away in a function, but my hunch is that we should keep it here - this is more transparent and it's very clear to the experimenter how to change parameters to suit their needs without digging around in code. While it's not hard, I must try to remember to keep the barriers to entry as low as possible.

what_I_want = 'delayed_choice_task'

if what_I_want is 'delayed_choice_task':

    # create an appropriate model object
    from darc.delayed import models
    model = models.Hyperbolic(n_particles=5_000)

    # create an appropriate design object
    design_thing = DARC_Designs(max_trials=12)

elif what_I_want is 'risky_choice_task':

    # create an appropriate model object
    from darc.risky import models
    model = models.Hyperbolic(n_particles=5_000)

    # create an appropriate design object
    design_thing = DARC_Designs(max_trials=12, 
        DA=[0], DB=[0], PB=[0.1, 0.2, 0.25, 0.5, 0.75, 0.8, 0.9, 0.99])

elif what_I_want is 'delayed_and_risky_choice_task':

    # create an appropriate model object
    from darc.delayed_and_risky import models
    model = models.MultiplicativeHyperbolic(n_particles=5_000)

    # create an appropriate design object
    design_thing = DARC_Designs(max_trials=12, 
        PB=[0.1, 0.2, 0.25, 0.5, 0.75, 0.8, 0.9, 0.99])

else:
    print('I don''t know what you want of me!')
    raise ValueError('value provided for `what_I_want` is not recognised')

I think this is sufficient for now. Might need to come back to this after some user testing. But it's pretty simple and flexible at this point.