Class TrialHandler

Advances to next trial and returns it. Updates attributes; thisTrial, thisTrialN and thisIndex If the trials have ended this method will raise a StopIteration error. This can be handled with code such as:

trials = TrialHandler(.......)
for eachTrial in trials:#automatically stops when done
    #do stuff

or:

trials = TrialHandler(.......)
while True: #ie forever
    try:
        thisTrial = trials.next()
    except StopIteration:#we got a StopIteration error
        break #break out of the forever loop
    #do stuff here for the trial

Write a text file with the data and various chosen stimulus attributes

Parameters:

• fileName, - will have .dlm appended (so you can double-click it to open in excel) and can include path info.
• stimOut, - the stimulus attributes to be output. To use this you need to use a list of dictionaries and give here the names of dictionary keys that you want as strings
• dataOut, - a list of strings specifying the dataType and the analysis to be performed,in the form dataType_analysis. The data can be any of the types that you added using trialHandler.data.add() and the analysis can be either 'raw' or most things in the numpy library, including; 'mean','std','median','max','min'... The default values will output the raw, mean and std of all datatypes found
• delim, - allows the user to use a delimiter other than tab ("," is popular with file extension ".csv")
• matrixOnly, - outputs the data with no header row or extraInfo attached
• appendFile, - will add this output to the end of the specified file if it already exists

Basically just saves a copy of self (with data) to a pickle file.

This can be reloaded if necess and further analyses carried out.

Save a summary data file in Excel OpenXML format workbook (:term:`xlsx`) for processing 
in most spreadsheet packages. This format is compatible with 
versions of Excel (2007 or greater) and and with OpenOffice (>=3.0).

It has the advantage over the simpler text files (see :func:`TrialHandler.saveAsText()` )
that data can be stored in multiple named sheets within the file. So you could have a single file
named after your experiment and then have one worksheet for each participant. Or you could have 
one file for each participant and then multiple sheets for repeated sessions etc. 

The file extension `.xlsx` will be added if not given already.

:Parameters:

    fileName: string
        the name of the file to create or append. Can include relative or absolute path

    sheetName: string
        the name of the worksheet within the file 
        
    stimOut: list of strings
        the attributes of the trial characteristics to be output. To use this you need to have provided  
        a list of dictionaries specifying to trialList parameter of the TrialHandler 
        and give here the names of strings specifying entries in that dictionary         
    
    dataOut: list of strings
        specifying the dataType and the analysis to
        be performed, in the form `dataType_analysis`. The data can be any of the types that
        you added using trialHandler.data.add() and the analysis can be either
        'raw' or most things in the numpy library, including 
        'mean','std','median','max','min'. e.g. `rt_max` will give a column of max reaction 
        times across the trials assuming that `rt` values have been stored. 
        The default values will output the raw, mean and std of all datatypes found 
    
    appendFile: True or False
        If False any existing file with this name will be overwritten. If True then a new worksheet will be appended.
        If a worksheet already exists with that name a number will be added to make it unique.