.. mpsy documentation master file, created by
   sphinx-quickstart on Wed Apr 03 15:04:29 2013.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Control from Python
===================

.. Psychophysics in "pure" Python

Contents:

.. contents::
    :local:
    :depth: 2


Sample experiment
-----------------

We start with a simple example that uses Dot Lattice as the stimulus. Let us design a short  experiment of only three trials. On every trial a fixation dot is presented first,
followed by a stimulus and response. 

A complete code of this experiment is:

.. literalinclude:: ../../mPsy/examples/dots_tut1.py

You can run this experiment by downloading the file and executing it. 

If you are new to Python, try  creating and running the script from scratch. Paste the code from the box above into your text editor, save it as ``dots_tut1.py``. To run it, double click the file name or execute it by typing ``python dots_tut1.py`` in the Terminal.


Code in detail
--------------

Now let us walk through this code. The first few lines initialize the library (line 1), initialize the window (lines 3-4) and create Python variables ``cx, cy`` that will hold the coordinates of screen center:

.. literalinclude:: ../../mPsy/examples/dots_tut1.py
    :lines: 1-7

Next we create presentation screens:

.. literalinclude:: ../../mPsy/examples/dots_tut1.py
    :lines: 9-13


Recording responses
-------------------

We will build on the previous example, by leaving the stimuli intact and adding the code 
that enables tracking various events in the experiment. 

Events are generated by the mPsy presentation module or by the stimuli. Three types of events are generated by default:

 * TRIAL - when a trial starts
 * KEY - when a key is pressed
 * MOUSE - when a mouse button is pressed 

To catch an event we need a function that will be called every time an event is triggered:

.. literalinclude:: ../../mPsy/examples/dots_tut2.py
    :lines: 4-9,  54-55

Function ``record_event()`` could have any name and its parameters could be called differently. But the number of parameters and their order must be the same. These parameters are:

 * event - text containing the name of the event
 * time - numerical value in seconds from experiment onset
 * trial - trial object: an important object in mPsy; 
   it contains information about the stimuli and their parameters
 * args - contain properties of the event:
   - for KEY event the name of the key pressed,  
   - for MOUSE event the coordinate and the button clicked.
 
When you execute this experiment, file ``dots2.log`` is created with the contents that look like this:

.. code-block:: none

    TRIAL 0.575153048996 Start []
    KEY 1.31466873576 Start SPACE
    TRIAL 1.3156867604 Fixation []
    TRIAL 2.33855819112 Lattices []
    TRIAL 3.86717378322 Response []
    MOUSE 5.86993089944 Response [814, 453, 1]
    TRIAL 5.87124100698 Fixation []
    TRIAL 6.89199839131 Lattices []
    TRIAL 8.42179287708 Response []
    MOUSE 9.6018394316 Response [627, 428, 1]
    TRIAL 9.60313044609 Fixation []
    TRIAL 10.6309067569 Lattices []
    TRIAL 12.1618943546 Response []
    MOUSE 15.1811783249 Response [814, 456, 1]
    TRIAL 15.1816048716 End [] 

Suppose we want to only keep the response. Then we change the ``record_event()`` function:

.. code-block:: python

    def record_event(event,time,trial,args):
        if event == 'MOUSE' and trial.name == 'Response':
            print >>log, 'RESP', args[0], args[1]

yielding this record:

.. code-block:: none

    RESP 814 453
    RESP 627 428
    RESP 814 456

(In the forthcoming tutorials we will compute whether the response is correct prior to logging.)

Stimulus randomization
----------------------

To randomize stimulus parameters we can use Python lists. Two operations are needed for this: shuffling and concatenation.

The following code creates a list of values, which are then shuffled using Python function ``shuffle()``. It is an example of shuffling "in-place" where we modify the original list rather than creating a new variable.

.. code-block:: python

    >> ratios = [1.0,1.1,1.2,1.3,1.4,1.5]
    >> shuffle(ratios)
    >> ratios
    [1.0, 1.3, 1.4, 1.1, 1.2, 1.5]


To create a more complicated set of parameters we can concatenate list using the ``+`` operator
or make multiple copies of a list with the ``*`` operator:

.. code-block:: python

    >> ratios = [1.0,1.1,1.2]
    >> ratios + ratios
    [1.0, 1.1, 1.2, 1.0, 1.1, 1.2]
    >> ratios*3
    [1.0, 1.1, 1.2, 1.0, 1.1, 1.2, 1.0, 1.1, 1.2]
    >> [ratios,ratios]*2
    [[1.0, 1.1, 1.2], [1.0, 1.1, 1.2], [1.0, 1.1, 1.2], [1.0, 1.1, 1.2]]

To create three blocks of shuffled trials:

.. code-block:: python

    trials = []
    for i in xrange(4):
        ratios = [1.0,1.1,1.2]
        shuffle(ratios)
        trials.append(ratios)

Then

.. code-block:: python

    >> trials
    [[1.0, 1.2, 1.1],[1.0, 1.1, 1.2],[1.2, 1.1, 1.0],[1.0, 1.2, 1.1]]

In list of blocks can be shuffled as well:

.. code-block:: python

    >> shuffle(trials)
    >> trials
    [[1.0, 1.1, 1.2], [1.0, 1.1, 1.2], [1.2, 1.0, 1.1], [1.0, 1.2, 1.1]]