psychopy_ext 0.6.0.4

A framework for a rapid reproducible experimental design, analysis and modeling of data in neuroscience and psychology.

Please refer to the `online documentation <http://psychopy-ext.klab.lt>`_
for a more in depth explanation how to use the package.

What is it?
===========

**psychopy_ext** is a framework for a rapid design, analysis and plotting of experiments in neuroscience and psychology.

Unlike **PsychoPy**, **PyMVPA** or **matplotlib** that are very flexible and support multiple options to suit everyone's needs, the underlying philosophy of **psychopy_ext** is to act as the glue at a higher level of operation by choosing reasonable defaults for these packages and providing patterns for common tasks with a minimal user intervention.


Features
--------

- Easy to run and rerun everything
- Neat project organization
- Templates for building and analyzing experiments (behavioral & fMRI)
- Simplified descriptive statistics
- Pretty plotting
- Automatic running (unit testing) of experiments
- Automatic GUI and command-line interpreter
- Custom needs? Inherit & customize: everything is a class!
- Built-in simple models of vision (Pixel-wise difference, GaborJet, and HMAX'99)

Installation
============

pip install psychopy_ext

(`no success? <http://psychopy-ext.klab.lt/intro/faq.html#pip-failing>`_)


Quick start
===========

First, find demo files in ``site-packages`` (`where is it? <http://psychopy-ext.klab.lt/intro/faq.html#where-is-demo>`_). Copy them to your home folder or another location of your choice (but where you have write permission). Now check the demos:

- For people who use a keyboard:

- In a terminal, navigate to the demos folder
- Type ``python run.py main exp run``. Do the experiment!
- Type ``python run.py main analysis run`` to see how well you did.

- For people who use **PsychoPy** app:

- In coder view, open **run.py** file from the demos folder
- Click the green running man to run it.
- Click on the run button. Do the experiment!
- When done, choose the analysis tab and click on **run** to see how well you did.

- For people who use a mouse on Windows:

- In a file browser, navigate to the demos folder
- Double-click click on **run.bat**
- Click on the run button. Do the experiment!
- When done, choose the analysis tab, and click on **run** to see how well you did.

When done with the demo, inspect **main.py** file to see how it works,
and build your experiment using this template, or try more demos.


Current state of affairs
========================

**psychopy_ext** is currently stable, meaning that I use it myself daily
but there are some limitations:

- I no longer actively use ``fmri`` module so it is no longer guaranteed to work.
- ``stats`` and ``plots`` work well many functions are undocumented.

Future roadmap (a wishlist):

- README generation with the most common commands
- Automatic summary of typical commands for CLI
- More robust command-line operation
- Browser-based project management tool
- ``info`` and ``rp`` should become classes with tips, lists etc
- Full fMRI preprocessing support (maybe)
- Generate full papers via `Open Science Paper <https://github.com/cpfaff/Open-Science-Paper>`_
and `PythonTeX <https://github.com/gpoore/pythontex>`_
- Force metadata by turning ``exp_plan`` into a class
- Integrated Bayesian statistics


Dependencies
============

- general
* `numpy`
* `scipy`
* `pandas 0.17+ <http://pandas.pydata.org/getpandas.html>`_
- exp
* `PsychoPy 1.83.04+ <http://sourceforge.net/projects/psychpy/files/>`_
* `docutils <https://pypi.python.org/pypi/docutils>`_ (will allow rendering docstrings on screen by the ``exp`` class)
* `svgwrite <https://pypi.python.org/pypi/svgwrite>`_ (used to export stimuli to SVG format)
- plots
* `seaborn 0.7+ <https://pypi.python.org/pypi/seaborn>`_ (pretty plots; not really mandatory but required for the benefit of your eyes)
- models
* `sklearn`_
* `skimage`_
* `caffe`
* `matlab_wrapper <https://github.com/mrkrd/matlab_wrapper>`_ (for accessing MATLAB)
- fMRI
* `PyMVPA 2.3.1+ <http://www.pymvpa.org/download.html>`_ (`Windows version for Python 2.7 here <http://www.lfd.uci.edu/~gohlke/pythonlibs/>`_)
* `NiBabel <http://nipy.sourceforge.net/nibabel/installation.html#installation>`_ (install with ``pip install nibabel``)
* `h5py <https://pypi.python.org/pypi/h5py>`_ (install with ``pip install h5py``)


License
=======

Copyright 2010-2016 Jonas Kubilius (http://klab.lt)

Brain and Cognition, KU Leuven (Belgium)

McGovern Institute for Brain Research, MIT (USA)

`GNU General Public License v3 or later <http://www.gnu.org/licenses/>`_

Included external packages and functions (covered by a compatible license):
combinations, combinations_with_replacement, OrderedDict, HMAX, GaborJet

v0.6
------
This is a major release of `psychopy_ext`, containing a number of new features and also API changes that break the behavior of earlier releases.

* NEW: Many models added to ``models``, including a convenient interface to Caffe for deep neural models.
* CHANGED: New pandas versions added support for categorical data and broke ordering. This is now fixed. **However**, this changes the way ``stats.aggregate`` and ``stats.accuracy`` work; **you will need to change your code** to have it work with this new version or, better yet, not use these functions and rely on ``pandas.groupby``. Reorder has been deprecated. Make your data categorical in pandas and use cat.reorder_categories().
* NEW: Many bootstrap methods added to ``stats``.
* DEPRECATED: ``plot`` is now deprecated in favor os ``seaborn`` that does everything ``plot`` was always aiming to do, but much better. There are now only a couple of functions left in ``plot`` that extend the functionality of ``seaborn``.
* NEW: ``mturkexp``: Experimental and very simple wrapper to ``mturkutils`` (moved to ``mturkutils`` as of 0.6.0.2).
* NEW: ``utils``: a collection of convenience functions

v0.5.5
--------
* NEW: Can now record frame timing. Events (in the trial structure creation) now have a keyword "name". If you provide, the timing of that event will be recorded.
* FIXED (hopefully): integration to git.
* FIXED: Minor bug fixes related to the installation, subplots, and MouseResp parameters.

v0.5.4
------
* IMPROVED: Rewrote plot and stats modules to better integrate with pandas' desire to reduce DataFrames into Series whenever possible. So the resulting code should be more robust now. Moreover, the information about splitting of data into rows and cols is now kept separately in the ``_splits`` variable so that the names of rows and columns are not messed up anymore. Downside: you have to manually assign this attribute to the DataFrame after most operations with the DataFrame.
* IMPROVED: The default fixation spot is now without the grey cross that was occluding background before.

v0.5.3
------
* NEW: Generate synthetic fMRI data using ``fmri.GenHRF()``.
* IMPROVED: ploting ROIs, chunks, datasets
* CHANGED: ``exp.create_win`` takes kwargs

v0.5.2
------
* NEW: A prototype of Analyzer for an interactive data analysis! (undocumented; you can try it with ``import psychopy_ext.analyzer; psychopy_ext.analyzer.run())
* NEW: MouseRespGroup for mouse response displays.
* NEW: Error bars and confidence intervals for repeated measures using Loftus & Masson (1994).
* NEW: GridSpec support in plot.
* FIXED: Installation requirements are more loose now. Pure Python packages are installed on the go with pip. Non-pure required Python packages stop installation and tell you what to install manually. Non-pure recommended Python packages allow you to install psychopy_ext but give a warning about what's missing. Also, tries to complain about missing dependencies only when you explicitly need them.
* CHANGED: Info parameter now has 'repository' parameter instead of 'register' and 'push'. You can choose to either 'commit and push' (default) or 'only commit'. This should be more transparent. Moreover, exp.Experiment.run_exp() has been changes such that the whole committing and pushing thing occurs in the exp.Experiment.after_exp().
* CHANGED: keyword 'unstack' in ``stats.aggregate()`` is now 'unstacked' because of the new ``stats.unstack()`` function
* FIXED: In older PsychoPy versions, BaseVisualStim is _BaseVisualStim, so now accepting both.
* IMPROVED: last_keypress now always returns a list (that might be empty)
* IMPROVED: can call a custom method for analyzing fMRI data
* FIXED: Plotting and stats are more robust now.
* FIXED: compactibility with pandas 0.13+ (FrozenList issues and interactive plots causing no display)

v0.5.1.1
--------
* FIXED: mouse inherited from Exp to Task
* DEMOS: updated post_trial syntax

v0.5.1
------
* NEW: Experimental support for mouse inputs (with a demo)
* NEW: Experimental support for exporting displays to SVG (Circle, Line, Rect, ShapeStim, TextStim, ThickShapeStim)
* NEW: demo of the shortest fully functional experiment possible
* FIXED: ThickLineStim can now accept default units for lineWidth
* FIXED: reoder
* ADDED: testing for demos
* FIXED: exp seed creation. Should now reinitialize seeds for each task and for each block.
* FIXED: GUI auto fit to contents in no size passed
* ADDED: write time stamp of the stat and finish of the experiment
* ADDED: psychopy_ext version in log
* FIXED: registering was not implemented even though Experiment was already using it
* FIXED: trial number printed at the begining, not at the end of the trial
* FIXED: GroupStim now properly converts stimuli to list

v0.5, 2013-10-24
----------------
First stable version, all tests pass.

v0.5a1, 2013-07-15
------------------
Skipping to 0.5 due to a significant change in exp module (Experiment split into Experiment and Task).

v0.4a2, 2013-04
---------------
Alpha version, working more or less

v0.4dev1, 2013-03-06
------------------
Initial dev release as a package

v0.3, 2012
----------
Separation from other projects into a package

v0.2, 2011
----------
Thorough rewrite using classes

v0.1, 2010
------------
Initial implementation for the confsup experiment
(https://bitbucket.org/qbilius/confsup)
Used only functions