ss_classes_2afc_noflicker.py

"""

Classes for the surround suppression experiment


- Stimulus
- Staircase
- Trial


""" 
import gc

import wx
import numpy as np
import random as random
from psychopy import core, visual, event, gui
from psychopy.sound import Sound as Sound

from ss_tools import sound_freq_sweep, GetFromGui

rgb = np.array([1.0,1.0,1.0])

class Params(object):
    """
    The Params class stores all of the parameters needed during the execution
    of ss_run.

    Once a parameter is set, it is protected and cannot be changed, unless it
    is explicitely removed from the _dont_touch variable. 

    Some parameters are set upon initialization from the file 'ss_params_2afc.py'

    Others are set through a gui which is generated by the method set_by_gui
    
    """
    def __init__(self, p_file='ss_params_2afc_noflicker'):
        """
        Initializer for the params object.

        Parameters
        ----------

        p_file: string, the name of a parameter file, defaults to 'ss_params_2afc_noflicker'

        """
        self._dont_touch = []
        #The following params are read in from a file with dict p.
        im = __import__(p_file)
        for k in im.p.keys():
            self.__setattr__(k,im.p[k])
            self._dont_touch.append(k)

    def __setattr__(self,name,value):
        """
        
        Overloading __setattr__, such that attributes cant be changed once they
        are set, unless they are explicitely removed from the _dont_touch list.

        """

        if name == '_dont_touch':
            super.__setattr__(self,name,value) 
        elif name in self._dont_touch:
            raise ValueError("Parameter %s is protected, please don't touch!"%name)
        else:
            super.__setattr__(self,name,value)
            self._dont_touch.append(name)

    def set_by_gui(self):
        """
        Set additional parameters through a wx GUI object. The wx app needs to
        be started and set in the main loop

        
        """
        
        # Use the GetFromGui class from ss_tools:
        user_choice = GetFromGui(None, -1, 'Session Params',
                                 ['Parallel', 'Orthogonal'])
        # success is achieved if the user presses 'done': 
        if user_choice.success:                
                user_params = {
                    "subject" : user_choice.subject,
                    "surround_ori" : user_choice.surround_ori,
                    "annulus_ori" : user_choice.annulus_ori,
                    "task" : user_choice.TaskType,
                    "_replay":user_choice.replay_contrast}
        else:
            user_choice.Destroy()
            raise ValueError("Program stopped by user")
        # Stop execution of the window
        user_choice.Destroy()
        
        for k in user_params.keys():
            self.__setattr__(k,user_params[k])

    def save(self,f,open_and_close=False):
        """

        This saves the parameters to a text file.

        Takes as an input an already opened file object and returns it in the
        end. Does not open or close the file, unless the variable
        open_and_close is set to True, in which case, the input should be a
        file-name, not a file object

        f is returned either way
        """

        if open_and_close:
            f = file(file_name,'w')
            for k in self.__dict__.keys():
                if k[0]!='_': #Exclude 'private' variables ('_dont_touch' and
                              #'_replay'):
                    f.write('# %s : %s \n'%(k,self.__dict__[k]))
            f.close()

        else:
            for k in self.__dict__.keys():
                if k[0]!='_':
                    f.write('# %s : %s \n'%(k,self.__dict__[k]))
        return f
        
class Event(object):

    """This is the base clase for the events, which sets the template for all
    the events objects """
    def __init__(self,win,**kwargs):
        """
        This always initializes with the window object and with a params
        object
        
        
        """
        #The event has to be attached to some psychopy window object:
        self.win = win 

        #The duration attribute is also necessary: 
        if 'duration' in kwargs.keys():
            self.duration = kwargs['duration']
        else:
            self.duration = 0
            
        #Set the rest of the attributes, if they are provided:
        for k in kwargs:
            self.__setattr__(k,kwargs[k])

    def finalize(self,**kwargs):
        """
        This is a function to finalize the event, before making it happen

        """
        #In the simplest case, just set additional attributes according to the
        #input: 
        for k in kwargs:
            self.__setattr__(k,kwargs[k])
        
    def __call__(self,**kwargs):
        """
        Make the event go for the alloted duration

        This method overloads the __call__ method allowing directly calling 
        the object with the inputs for the event occurence

        """
        
        #Allow to set the duration at this point as well (which would
        #over-ride any previous setting):
        if 'duration' in kwargs.keys():
            self.duration = kwargs['duration']
        

        #In the simplest case, just clear the screen completely at each refresh:
        clock = core.Clock()
        t=0
        while t<self.duration: #Keep going for the duration
            t=clock.getTime()
            #For each of the object attributes, go and check whether it has a
            #'draw' method. If it does, call that method before flipping the
            #window, so that if stimuli objects from psychopy were provided,
            #those will be shown for the duration: 
            for k in self.__dict__:
                try:
                    self.__dict__[k].draw()
                except: #Do nothing in case of an exception:
                    pass
            self.win.flip()

        #Return the entire object at the end, so that we can inspect it:
        return self
    
class Staircase(object):
    """
    This is an object for holding, updating and potentially analyzing
    A psychophysical staircase

    """ 
    def __init__(self,start,step,n_up=3,n_down=1,harder=-1,ub=1,lb=0):
        """
        Initialization function for the staircase class

        Parameters
        ----------
        start: The starting value of the staircase
        step: The size of the step used when updating the staircase
        n_up,n_down: The kind of staircase to be used, defaults to a 3-up,
                     1-down staircase 

        harder: {-1,1} The direction which would make the task harder. Defaults
        to -1, which is true for a contrast detection detection task.

        ub: float, the upper bound on possible values in the staircase
        lb: float, the lower bound on possible values in the staircase
        
        """
        self.value = start
        self.n_up = n_up
        self.step = step
        self.n = 0 #This is what will be compared to n_up for udpating.
        self.harder = np.sign(harder) #Make sure that this is only -1 or 1.
        self.record = [start]
        self.ub = ub
        self.lb = lb
    def update(self,correct):
        """

        This function updates the staircase value, according to the state of
        the staircase, the n/n_up values and whether or not the subject got it
        right. This staircase is then propagated on to the next trial.

        Parameters
        ----------
        correct: {True|False|None => don't update, but record the value} 

        """
        #If none is the input, don't change anything (not even n!) and record
        #the value in this trial:
        if correct is not None:
            if correct:
                if self.n>=self.n_up-1:
                    self.value += self.harder * self.step #'harder' sets the
                                                          #sign of the change
                                                          #to make it harder
                    self.n = 0
                else:
                    self.n +=1

            else:
                self.n = 0
                self.value -= self.harder * self.step #Change in the
                                            #opposite direction than above to
                                            #make it easier!
            #Make sure that the staircase doesn't     
            if self.value > self.ub:
                self.value = self.ub
            if self.value < self.lb:
                self.value = self.lb
            
        #Add to the records the updated value (even on trials where
        #correct=None):
        self.record.append(self.value)

class StimulusBank(): 
    def __init__(self,win,params,tex_res=256):
        
        self.outer_surround = visual.PatchStim(win,tex="sin",mask="circle",
                                          texRes=tex_res,
                                          color=params.surround_contrast,
                                          ori=params.surround_ori,
                                          size=(params.surround_outer-
                                                params.ring_width/2,
                                                params.surround_outer-
                                                params.ring_width/2),
                                          sf=params.spatial_freq,
                                          interpolate=True)

        self.inner_surround = visual.PatchStim(win,tex="sin",mask="circle",
                                               texRes=tex_res,
                                               color=params.surround_contrast,
                                               ori=params.surround_ori,
                                               size=(params.annulus_inner-
                                                     params.ring_width/2,
                                                     params.annulus_inner-
                                                     params.ring_width/2),
                                               sf=params.spatial_freq,
                                               interpolate=True)

        self.annulus = visual.PatchStim(win,tex="sin",mask="circle",
                                                texRes=tex_res,
                                                size=(params.annulus_outer-
                                                      params.ring_width/2,
                                                      params.annulus_outer-
                                                      params.ring_width/2),
                                                sf=params.spatial_freq,
                                                interpolate=True)

        #Set the rings abutting the annulus on both sides:
        ring_width = params.ring_width

        #This is the bit between the annulus and the outer surround: 
        self.ring1 = visual.PatchStim(win, tex=None, mask='circle',
                                      color=-1, #Always black
                                      size=[params.annulus_outer+ring_width/2,
                                            params.annulus_outer+ring_width/2],
                                      interpolate=True)

        #This is the bit between the annulus and the inner surround: 
        self.ring2 = visual.PatchStim(win, tex=None, mask='circle',
                                      color=-1, #Always black
                                      size=[params.annulus_inner+ring_width/2,
                                            params.annulus_inner+ring_width/2],
                                      interpolate=True)

        #This is the central area, between the inner surround and the fixation: 
        self.center_area = visual.PatchStim(win, tex=None, mask='circle',
                                            color=0, #Always gray
                                            size=params.surround_inner,
                                            interpolate=True)


        #Set the spokes:
        spoke_width = params.spoke_width

        self.spokes = []
        num_spokes = params.num_segments #This is hard-coded for now
        for i in np.arange(num_spokes/2):
            self.spokes.append(visual.ShapeStim(win,
                                fillColor = -1,
                                lineColor = -1,
                                vertices = ((-params.spoke_width/2,
                                              params.annulus_outer/2),
                                            (params.spoke_width/2,
                                             -params.annulus_outer/2),
                                            (-params.spoke_width/2,
                                             -params.annulus_outer/2),
                                            (params.spoke_width/2,
                                             params.annulus_outer/2)),
                                ori=i*360/params.num_segments,
                                interpolate = True))

        self.fixation_surround = visual.PatchStim(win, tex= None,
                                         color = -1*rgb,
                                         size=params.fixation_size,
                                         interpolate = True,
                                         )

        self.fixation = visual.PatchStim(win, tex=None,
                                         size=params.fixation_size*3/4,
                                         interpolate=True)

        #Set the center to always be black:
        self.fixation_center = visual.PatchStim(win, tex=None,
                                                color=-1  * rgb,
                                                size=params.fixation_size/4,
                                                interpolate=True,
                                                )

        self.fixation_square = visual.PatchStim(win, tex=None,
                                                color=params.fix_baseline  * rgb,
                                                size=params.fixation_size/8,
                                                interpolate=True,
                                                )
        
class Stimulus(Event):

    """The surround suppression stimulus, including everything """

    def __init__(self,win,params,
                 bank,
                 duration=None,
                 surround_contrast=None,surround_ori=None,
                 annulus_contrast=None, annulus_ori=None, fixation_ori=None,
                 fixation_color=None,fixation_shape=None,
                 tex_res = 128):
        """

        Initialize the object, by setting all the various subobjects

        Parameters
        ----------

        win: a psychopy window object

        params: an object with parameters for setting the size and . Note that
        the units of size here need to be the units that were used to
        initialize the window object (should be degrees).

        bank : A StimulusBank object.
        
        duration: float, The duration of presentation of this
        stimulus. Defaults to None => params.stimulus_duration

        surround_contrast, surround_ori, annulus_contrast, annulus_ori: These
        variables can be used in order to over-ride the values of these
        variables in the params object. They cannot be set online, after the
        object has been initialized, except by calling the setters of the
        psychopy objects.

        fixation_ori: sometimes we might want to rotate the fixation square to
        some other orientation. This allows this. Defaults to None => upright
        square. 

        fixation_color: If we want to change the color of the fixation from
        white (the default) to some other color (rgb argument). 

        fixation_shape: The shape of the mask applied to the fixation
        {None(default) => square | 'circle'}

        
        tex_res: the resolution (in pixels) at which the OpenGL texture is
        rendered (?).
        """
        
        #Carry the window object around with you:
        self.win = win
        #The resolution for the textures:
        self.tex_res = tex_res
        #The temporal frequency of the flicker:
        self.temporal_freq = params.temporal_freq
        #Per default set the targets to None (to be replaced later if needed):
        self.target = None
        self.fixation_target = None

        #Per default, set the duration to be the stimulus duration specified in
        #the parameters:
        if duration is None:
            self.duration = params.stimulus_duration
        else:
            self.duration = duration

        
        #Set the params for the different components of the stimulus. The
        #default is to follow what is given by the params:
        if surround_contrast is None:
            surround_contrast = params.surround_contrast
        if surround_ori is None:
            surround_ori = params.surround_ori
        if annulus_contrast is None:
            annulus_contrast = params.annulus_contrast
        if annulus_ori is None:
            annulus_ori = params.annulus_ori
        #Set both parts of the surround
        self.outer_surround = bank.outer_surround
        self.outer_surround.setColor(surround_contrast)
        self.outer_surround.setOri(surround_ori)

        self.inner_surround = bank.inner_surround 
        self.inner_surround.setColor(surround_contrast)
        self.inner_surround.setOri(surround_ori)
        
        #Set the annulus:
        self.annulus = bank.annulus 
        self.annulus.setColor(annulus_contrast)
        self.annulus.setOri(annulus_ori)
        
        #This is the bit between the annulus and the outer surround: 
        self.ring1 = bank.ring1
        #This is the bit between the annulus and the inner surround: 
        self.ring2 = bank.ring2
        
        #This is the central area, between the inner surround and the fixation: 
        self.center_area = bank.center_area

        self.spokes = bank.spokes

        self.fixation = bank.fixation
        self.fixation_square = bank.fixation_square
        self.fixation.setOri(fixation_ori)
        #self.fixation.setColor(rgb*fixation_color)
        self.fixation.setColor(params.fix_baseline)
        self.fixation_square.setColor(fixation_color)
        #The center is always set to be black:
        self.fixation_surround = bank.fixation_surround
        self.fixation_center = bank.fixation_center
        self.fixation_center.setOri(fixation_ori)
        
    def finalize(self,params,target_co=None,target_loc=None,
                     target_ori=None,fix_target_co=None,fix_foil_co=None,fix_target_loc=None):

        """

        Finalize the stimulus, by setting the target

        Parameters
        ----------

        params: a parameter object with all the pre-defined params

        target_co: the contrast of the target in this trial (set by the
        staircase). Set to None if no target is to be set in this stimulus
        object 

        target_loc: the location of the target (integer between 0 and 7) in
        this trial. defaults to None => random location

        target_ori: The orientation of the target (typically set to the
        same orientation as the annulus). Defaults to None => the
        orientation given in the params object

        fix_target_co: This allows setting of the fixation contrast (the
        difference between white and black), so that it can serve as a
        target.

        fix_target_loc: the location of the fixation target (right{1,default
        behavior if stays as None} or left{any other input})

        """
#        fix_foil_co = params.fix_foil_co
        #If either target location or contrast is set to the default, there
        #will be no target:
        if target_co is None:
            self.target = None        
        elif target_co is None: 
            self.target = None
        else:
        #Now, if there is an annulus target, proceed to setting it:
            if target_ori is None:
                #Get it from the params:
                target_ori = params.target_ori
            #In order to apply a different contrast to the target wedge,
            #generate a mask, which will cover everything except for the
            #target wedge:
            grid_array = np.linspace(-1*self.annulus.size[0],
                                     self.annulus.size[0],
                                     self.annulus.texRes)

            x,y=np.meshgrid(grid_array,grid_array)
            r = np.sqrt(x**2 + y**2)
            theta = np.arctan2(x,y) + np.pi
            target_mask = np.ones((self.annulus.texRes,self.annulus.texRes))

            target_mask[np.where(r>params.annulus_outer-
                                 params.ring_width/2)] = -1

            target_mask[np.where(r<params.annulus_inner-
                                 params.ring_width/2)] = -1

            #Since the whole PatchStim is rotated according to annulus_ori,
            #we need to adjust for that, so that the target locations
            #remain invariant across different orientations (hence
            #subtraction of annulus_ori):
            target_mask[np.where(theta<target_loc*np.deg2rad(360/params.num_segments)-
                                 np.deg2rad(target_ori))] = -1
            target_mask[np.where(theta>(target_loc+1)*np.deg2rad(360/params.num_segments)-
                                 np.deg2rad(target_ori))] = -1
            # 45 is hard-coded for now and depends on the number of
            #targets/wedges we want to have in the annulus (corresponds to the
            #number of spokes as well).

            #Now show the target contrast in the wedge, using that mask:
            self.target = visual.PatchStim(self.win,tex="sin",
                                           mask=target_mask,
                                           #texRes=self.tex_res,
                                           color=target_co  * rgb,
                                           #Need to set the
                                           #color, because the contrast is
                                           #time-dependent (for the
                                           #counter-phase flickering)
                                           size=(params.annulus_outer-
                                                 params.ring_width/2,
                                                 params.annulus_outer-
                                                 params.ring_width/2),
                                           sf=params.spatial_freq,
                                           ori=target_ori,
                                           )
        
        fix_foil_co = 0.5
        if fix_target_co is None:
            self.fixation_target = None
        else:
        #Independtly, set the fixation target with a contrast value:
        #if fix_target_co is not None:
            if fix_target_loc == 1 or fix_target_loc is None: #This is the
                                                                #default
                    pos = [params.fixation_size*3/16,0]
            else:
                    pos = [-params.fixation_size*3/16,0]

            self.fixation_target = visual.PatchStim(self.win,
                                                tex=None,
                                                pos=pos,
                                                color=fix_target_co* rgb,
                                                size=[params.fixation_size*3/8,
                                                      params.fixation_size*3/4])
            self.fixation_foil = visual.PatchStim(self.win,
                                                tex=None,
                                                pos=(-1.0*pos[0],pos[1]),#-1*pos,
                                                color=fix_foil_co* rgb,
                                                size=[params.fixation_size*3/8,
                                                      params.fixation_size*3/4])

        self.target_loc = target_loc
        #This is the nominal target contrast, because in fact, the target
        #contrast oscillates with the counter-phase flickering
        self.nominal_target_co = target_co
        self.fix_target_co = fix_target_co
        self.fix_foil_co = fix_foil_co
        self.fix_target_loc = fix_target_loc
                    
    def __call__(self,params,block_type):
        #Choose a random phase (btwn -pi and pi) to start the presentation
        #with XXX Should this really be random?:
        ph_rand = (np.random.rand(1) * 2*np.pi) - np.pi
        #Start a clock 
        clock = core.Clock()
        t = 0
        while t<self.duration: #Keep going for the duration
            t=clock.getTime()
            
            self.annulus.setContrast(1)#np.sin(ph_rand))# +
#                                            t*self.temporal_freq*np.pi*2))
            self.inner_surround.setContrast(1)#np.sin(ph_rand))# +
#                                            t*self.temporal_freq*np.pi*2))
            self.outer_surround.setContrast(1)#np.sin(ph_rand))# +
#                                            t*self.temporal_freq*np.pi*2))

            if self.target  is not None:
                self.target.setContrast(np.sin(ph_rand))# +
#                                        t*self.temporal_freq*np.pi*2))
                if block_type == 'A' and self.target_loc !=0:
                    self.target.setColor((params.annulus_contrast*rgb)+(((self.nominal_target_co-params.annulus_contrast)*rgb) * np.sin((params.stimulus_duration-t)/params.stimulus_duration * np.pi)) )
                elif block_type == 'B' and self.target_loc !=0:
                    self.target.setColor((self.nominal_target_co*rgb) * np.sin((params.stimulus_duration-t)/params.stimulus_duration * np.pi)) 
            if self.fixation_target is not None:# and self.fix_target_loc !=0:#if self.params.task is 'Fixation':
                if self.target_loc !=0:
                    self.fixation_target.setColor((params.fix_baseline*rgb)+(((self.fix_target_co-params.fix_baseline)*rgb) * np.sin((params.stimulus_duration-t)/params.stimulus_duration * np.pi)) )
                    self.fixation_foil.setColor((params.fix_baseline*rgb)+(((self.fix_foil_co-params.fix_baseline)*rgb) * np.sin((params.stimulus_duration-t)/params.stimulus_duration * np.pi)) )
                
            
            #Draw them (order matters!)
            #if self.outer_surround is not None:
            self.outer_surround.draw()
            self.ring1.draw()
            self.annulus.draw()
            if self.target is not None:
                if self.target_loc is not 0:
                    self.target.draw()
            for spoke in self.spokes:
                spoke.draw()
            self.ring2.draw()
            self.inner_surround.draw()
            self.center_area.draw()
            self.fixation_surround.draw()
            self.fixation.draw()
            if self.fixation_target is not None:
                self.fixation_target.draw()
                self.fixation_foil.draw()
            self.fixation_center.draw()
            self.fixation_square.draw()

            #If there is no time left:
            if clock.getTime()>=self.duration:
                break
            #Otherwise, show the stimulus
            else:
                self.win.flip() #update the screen

        #Return the object, so that we can inspect it:
        return self,ph_rand

class Beginning(Event):
    """
    A class for showing the rings and fixation, so that the stimulus can be presented at the beginning of fMRI runs
    """

    def __init__(self,win,params,
                 bank,
                 duration=None,
                 surround_contrast=None,surround_ori=None,
                 annulus_contrast=None, annulus_ori=None, fixation_ori=None,
                 fixation_color=None,fixation_shape=None,
                 tex_res = 128):
        fixation_ori = 90
        self.win = win 
        self.ring1 = bank.ring1
        #This is the bit between the annulus and the inner surround: 
        self.ring2 = bank.ring2
        self.inner_surround = bank.inner_surround 

        #This is the central area, between the inner surround and the fixation: 
        self.center_area = bank.center_area

        self.spokes = bank.spokes
        self.fixation = bank.fixation
        self.fixation_square = bank.fixation_square
        self.fixation.setOri(fixation_ori)
        self.fixation.setColor(rgb*0)
        self.fixation.setColor(params.fix_baseline)
        self.fixation_square.setColor(0*rgb)
        #The center is always set to be black:
        self.fixation_surround = bank.fixation_surround
        self.fixation_center = bank.fixation_center
        self.fixation_center.setOri(fixation_ori)
        self.outer_surround = bank.outer_surround


        #Set the params for the different components of the stimulus. The
        #default is to follow what is given by the params:
        if surround_contrast is None:
            surround_contrast = params.surround_contrast
        if annulus_contrast is None:
            annulus_contrast = params.annulus_contrast

        #Set both parts of the surround
        self.outer_surround = bank.outer_surround
        self.outer_surround.setColor(0*rgb)#surround_contrast)
        self.outer_surround.setContrast(0)
        self.outer_surround.setColor(surround_contrast)

        self.inner_surround = bank.inner_surround 
        self.inner_surround.setColor(0)#surround_contrast)
        
        #Set the annulus:
        self.annulus = bank.annulus 
        self.annulus.setColor(0)#annulus_contrast)
        
        #This is the bit between the annulus and the outer surround: 
        self.ring1 = bank.ring1
        #This is the bit between the annulus and the inner surround: 
        self.ring2 = bank.ring2
        
        #This is the central area, between the inner surround and the fixation: 
        self.center_area = bank.center_area

        self.spokes = bank.spokes



        if self.outer_surround is not None:
            self.outer_surround.draw()
        self.ring1.draw()
        self.annulus.draw()

        for spoke in self.spokes:
            spoke.draw()
        self.ring2.draw()
        self.inner_surround.draw()
        self.center_area.draw()
        self.fixation_surround.draw()
        self.fixation.draw()

        self.fixation_center.draw()
        self.fixation_square.draw()
        self.win.flip() #update the screen
        core.wait(params.scanner_wait_time)
        return None
    
class Text(Event):

    """
    A class for showing text on the screen until a key is pressed 
    """

    def __init__ (self,win,text='Press a key to continue',
                  keys=['1','2'],**kwargs):
        """
        
        Will do the default thing(show 'text' in white on gray background),
        unless you pass in kwargs, which will just go through to
        visual.TextStim (see docstring of that class for more details)

        keys: list. The keys to which you listen for input
        """

        self.win = win
        
        self.text = visual.TextStim(win,text=text,**kwargs)
        self.keys=keys
        
    #No need for a 'finalize' method in this case.
    
    def __call__(self,duration=np.inf):
        """
        Text is shown to the screen, until a key is pressed or until duration
        elapses (default = inf)
        
        """

        clock = core.Clock()
        t=0
        while t<duration: #Keep going for the duration
            t=clock.getTime()

            self.text.draw()
            self.win.flip()

            for key in event.getKeys():
                if key in self.keys:
                    return


def start_text(win,text=None,keys=['1','2']):
    """

    This is a short-cut function to provide the default usage of the Text
    object

    """

    #Initialize the object and call it in the same line:
    if text is not None:
        T = Text(win,text=text,keys=keys)
    else:
        T = Text(win,keys=keys)()

                
class Response(Event):

    """
    Getting responses from subjects and evaluating their correctness
    
    """
    def __init__(self,params,keys=['1','2'],duration=None):
        """

        Initializer for the Response object. Listening only to '1' and '2',
        unless the keys input variable is set otherwise.
        
        """
        if duration is None:
            self.duration = params.response_duration
        else:
            self.duration = duration
        self.keys=keys
        
    def finalize(self,correct_key=None,file_name=None):
        """

        Which key is the correct one in this trial? Defaults to '1'.
        
        """
        self.correct_key = correct_key
        self.file_name = file_name
        
    def __call__(self):
        """
        
        When the object is called, it evaluates whether the key pressed is
        the right key for that trial and returns 1 if the right key was pressed
        and 0 if the other one was pressed. If no key is replaced during the
        duration will return None

        """
        clock = core.Clock()
        t=0
        
        #If nothing ever gets pressed the value of all these variables gets set
        #to None:
        self.key = None
        self.correct = None
        key_was_pressed = None
        self.response_time = None

        #Loop over this for the duration:
        while t<self.duration:
            t=clock.getTime()
            if key_was_pressed is None:                
                for key in event.getKeys():
                    if key in self.keys:
                        #Record the fact that a key was pressed:
                        key_was_pressed = 1 
                        #Record the response time:
                        self.response_time = clock.getTime()
                        self.key = key
        
                        if key==self.correct_key:
                            self.correct = 1
                        else:
                            self.correct = 0
                    #Quit cleanly:
                    if key=='q':
                        if self.file_name is not None:
                            self.file_name.close()
                        core.quit()
                        
                    #But keep on going even after a key was pressed until
                    #the entire duration has elapsed
                            
class Feedback(Event):

    def __init__(self,params):
        """This provides auditory (and visual?) feedback about performance """ 

        self.incorrect_sound = Sound(sound_freq_sweep(8000, 200, .1))
        self.correct_sound = Sound(sound_freq_sweep(1000,1000,.1))
        self.no_response_sound = Sound(sound_freq_sweep(200, 300, .1))   
        #This will be how long to wait when issued:
        self.duration = params.feedback_duration
        #set the default state to be None
        self.feedback = None
        
    def finalize(self,correct=None):
        """

        What feedback to give depends on whether subjects got it right or
        not

        Parameters
        ----------

        correct: {1|0} for correct incorrect. Default: None => no-response
        """
        if correct is None:
            self.feedback = self.no_response_sound
        elif correct==1:
            self.feedback = self.correct_sound
        elif correct==0:
            self.feedback = self.incorrect_sound
                   
    def __call__(self):
        """
        Play the feedback
        """
        #Start a clock:
        clock = core.Clock()
        t=0
        
        #If the object wasn't properly finalized for some reason:
        if self.feedback is None:
            self.feedback = self.no_response_sound
        
        self.feedback.play()
        self.feedback.play() #For some reason need to call play twice 

        core.wait(clock.getTime()-t) #Wait for the remainder            


class Trial(Event):
    
    def __init__(self,win,params,target_loc=None,fix_target_loc=None,
                 fix_color=None,fix_color_switch=None,fix_ori =None,
                 fix_ori_switch=None,iti=0,block_type = 'A'):
        """

        This function prepares all the events that happen in one trial,
        initializing all the objects and bringing them to a state where all is
        needed is to finalize them and call them.    

        Parameters
        ----------
        win: the psychopy window to be used

        params: a Params object

        target_loc: The location of the annulus target, in which the target is
        to appear. Locations 0,1,2,3 are on the left side and locations
        4,5,6,7 are on the right side of the annulus. Defaults to None, in
        which case no annulus is presented and no response is recorded.

        fix_target_loc: One of two locations in which the fixation target can
        appear: left (1)  or right (2). Defaults to None, in which case no
        target is presented.

        fix_ori: The orientation of the fixation at the beginning of the
        trial. Defaults to None - just take the values from the params.

        fix_color: The color of the fixation at the beginning of the
        trial. Defaults to None - just take the values from the params.

        fix_ori_switch: If switching fixation orientation, this is the
        orientation of the fixation after the switch (occurs during the
        iti). Defaults to None, in which case, no switch occurs.
        
        fix_color_switch: If switching fixation color, this is the color after
        the switch. Defaults to None - no switch occurs.
        
        """
        #Upon initilzation set only very light variables, leaving
        #initialization of the stimulus to the finalization step, below.
        self.win = win
        self.params = params
        self.target_loc = target_loc
        self.fix_target_loc = fix_target_loc
        self.fix_color = fix_color
        self.fix_ori = 90#fix_ori
        self.block_type = block_type

        #If no switch occurs, set the post-switch values to the pre-switch
        #values: 
        if fix_color_switch is None:
            self.fix_color_switch = fix_color
        else:
            self.fix_color_switch = fix_color_switch
        if fix_ori_switch is None:
            self.fix_ori_switch = 0#fix_ori
        else:
            self.fix_ori_switch = fix_ori_switch


    def finalize_stim(self,params,bank,staircase,other_contrast):
        if self.target_loc is None:
            """ Finalize the Trial"""
            #Don't get responses:
            self.response = Response(self.params,keys=[],duration=0)
            #Set the feedback to be a generic event, with nothing in it:
            self.feedback = Event(self.win,duration=0)

            self.stimulus = Stimulus(self.win,self.params,
                                     bank,
                                     annulus_contrast=0,
                                     surround_contrast=params.surround_contrast,
                                     fixation_color=self.fix_color,
                                     fixation_ori=self.fix_ori)
            
            self.correct_key = None
            return #No need to finalize the stimulus
        else:
            #The response and the feedback are real 
            self.response = Response(self.params)
            self.feedback = Feedback(self.params)        
            
        #Preparing the stimulus doesn't depend on which task we are doing:
        if self.block_type == 'A':
                        self.stimulus = Stimulus(self.win,self.params,
                                 bank,
                                 surround_contrast=params.surround_contrast,
                                 annulus_contrast=params.annulus_contrast,
                                 fixation_color=self.fix_color,
                                 fixation_ori = self.fix_ori)
        elif self.block_type == 'B':
                        self.stimulus = Stimulus(self.win,self.params,
                                 bank,
                                 surround_contrast=params.surround_contrast,
                                 annulus_contrast=0,
                                 fixation_color=self.fix_color,
                                 fixation_ori = self.fix_ori)

        #The following steps look the same for either block:
#        fix_foil_co = 0.5
        if self.params.task=='Annulus':
           self.stimulus.finalize(self.params,target_co=staircase.value,
                                target_loc=self.target_loc,
                                fix_target_loc=self.fix_target_loc,
                                fix_target_co=other_contrast)
           if self.target_loc:
               self.correct_key = str(params.present_key)
           else:
               self.correct_key = str(params.absent_key)
    
        elif self.params.task=='Fixation':
            self.stimulus.finalize(self.params,target_co=other_contrast,
                                target_loc=self.target_loc,
                                fix_target_loc=self.fix_target_loc,
                                fix_target_co=staircase.value)            


            if self.fix_target_loc:
                self.correct_key = str(params.present_key)
            else:
                self.correct_key = str(params.absent_key)
        
    def finalize_fix(self,params,bank,staircase,other_contrast):
        """ Finalize only the fixation"""
        self.fixation = Stimulus(self.win,self.params,
                                     bank,
                                     duration=self.params.fixation_duration,
                                     surround_contrast=0,
                                     annulus_contrast=0,
                                     fixation_color=self.fix_color_switch,
                                     fixation_ori=self.fix_ori_switch)

    def wait_iti(self,trial_clock):
            now = trial_clock.getTime()
            wait_time = (self.params.trial_duration) - now
            core.wait(wait_time)

    def save(self,f,insert_header=False):

        """ Save the trial information, including whether subjects got it right
        or not to file

        If insert_header is set to True, it will insert a header line, with the
        variable names in each subsequent column.
        
        """

        if insert_header:
            f.write('Block_Type, ')
            f.write('Annulus target contrast, ')
            f.write('Fixation target contrast, ')
            f.write('Annulus target location, ')
            f.write('Fixation target location, ')
            f.write('Response, ')
            f.write('Correct, ')
            f.write('Response time\n')
                    
        f.write('%s,'%self.block_type)
        f.write('%s, '%self.stimulus.nominal_target_co)
        f.write('%s, '%(self.stimulus.fixation_target.color[0]))
        f.write('%s, '%self.stimulus.target_loc)
        f.write('%s, '%self.stimulus.fix_target_loc)
        f.write('%s, '%self.response.key)
        #Record no-response trials as a -1:
        if self.response.correct is None:
            f.write('%s, '%-1)
        else:
            f.write('%s, '%self.response.correct)
        f.write('%s\n'%self.response.response_time)
        
        #return f
    
def make_trial_list(win,params):
    """

    This function strings together a bunch of Trial objects to generate a list
    of trials, according to the following rules:

    XXX Write down the logic of this.

    Parameters
    ----------
    win: a window object
    params: a Params object

    Returns
    -------

    trial_list: list of Trial objects. Ready to be iterated on :-) 
    
    """ 
    #This will hold all the Trial objects:
    trial_list = []

    #This is simple:
    if params.paradigm == 'rapid_fire':
        for i in range(params.trials_per_block*params.num_blocks):
            trial_list.append( Trial(win,params,
                block_type = 'A',
                target_loc = random.choice([0,int(np.random.rand(1) * params.num_segments)]), 
                fix_target_loc = random.choice([0,int(np.random.rand(1) * params.num_segments)]),
                fix_color=[1,1,1]))

    #This is a bit more complicated:
    elif params.paradigm == 'block':
        #Red fixation for annulus task:
        if params.task == 'Annulus':
            fix_color = [1,0,0]
        #Green fixation for fixation task:
        elif params.task == 'Fixation':
            fix_color = [0,1,0]

    #Append the blocks:    
        for block in range(params.num_blocks/2):
            #Block A Task hemi-block:
            for n_trial in range(params.trials_per_block):
                trial_list.append(
                        Trial(win,params,
                              fix_color=fix_color,
                              #fix_ori = fix_ori,
                              block_type = 'A',
                              target_loc = random.choice([0,int(np.random.rand(1) * params.num_segments)]), 
                              fix_target_loc = random.choice([0,int(np.random.rand(1) * params.num_segments)])
                              ))
 




    #If the input is not valid throw and error:
    else:
            raise ValueError("Need to set params.paradigm to a valid value (in ss_params_2afc_noflicker.py")

    return trial_list