Top-down Modulated Pitch Model Files

*** GPM: Top-down modulated pitch model (Version 3.6-beta) ***

This version: December 2013, linux based. Windows version no longer mantained
			  This software runs under MATLAB (and probably under Octave)
			  Tested with MATLAB2013 in a Linux-64bits OS
			  Not warrantied

-----------------------------------------------------------------------------

REFERENCING: 

Balaguer-Ballester E., Clark, N., Coath, M., Krumholz, K. and Denham, S. L.
Understanding Pitch Perception as a Hierarchical Process with Top-Down 
Modulation. PLOS Computational Biology (2009)

Original scripts by Emili Balaguer-Ballester
work contributors are as well Sue Denham, Ray Meddis, Martin Coath, 
Nick Clark, Katrin Krumbholz.

This version by Alejandro Tabas

Work initially funded by EMCAP european project
(Emergence Cognition Through Active Perception, 2005-2008)
http://emcap.iua.upf.es

-----------------------------------------------------------------------------

UPDATES AND SUPPORT:

For updates visit the site of the project:  
	https://sourceforge.net/p/topdownpitchmodel

For any question or giving feedback please contact 
 - Alejandro Tabas <alejandro.tabas@bournemouth.ac.uk>
 - Emili Balaguer-Ballester <eb-ballester@bournemouth.ac.uk>
   http://www.researchgate.net/profile/Emili_Balaguer-Ballester/
   http://staffprofiles.bournemouth.ac.uk/display/eb-ballester

Note that the implementation could be considerably faster but a c-style was 
preferred in order to make it clear for the reader of this code.

-----------------------------------------------------------------------------

INSTALLATION:

To install the package in Linux:

1) Install DSAM and SAMS:

	- Install files can be found in the site of the DSAM project: 
	  https://sourceforge.net/projects/dsam/
	- This version has been tested for DSAM-2.8.44 and SAMS-1.3.10

	If you are running a Debian based system you will probably need to 
	convert the .rpm packages supplied by DSAM into .deb install packages. 
	This can be done using "alien". In my case I had to install the tool:
	$ sudo apt-get install alien
	and then run the application for both files: 
	$ sudo alien dsam-2.8.44-1.x86_64.rpm 
	$ sudo alien sams-1.3.10-0.x86_64.rpm 
	Then you can just install them using dpgk:
	$ dpkg -i dsam-2.8.44-1.x86_64.deb
	$ dpkg -i sams-1.3.10-0.x86_64.deb

	In my case, to get sams working I needed to install two extra libraries:
	$ sudo apt-get install libwxgtk2.8-0 libhunspell-1.2-0

	Before going to the next step verify that sams_ng is working:
	$ sams_ng


2) Move this directory to your preferred location (you can rename it if you 
   want). You can launch it from MATLAB calling the function gpm(). If you
   experience some issue, check that all paths are setted correctly in the
   beginning of the file "DSAM_output.m".


For Windows:

This package has only been tested in Linux, but it should run without problems
also in Windows after installing DSAM and SAMS with a few modifications:
	- modify the path definitions in the first lines of DSAM_output.m to 
	  point to the sams_ng.exe executable
	- change the slashes for backslashes in DSAM_output.m and in the first 
	  line of gmp.m

-----------------------------------------------------------------------------

USE: 

Just need to call the main function gpm() from MATLAB using as argument the
desired .wav file with the stimulus as a string, e.g:
 > gpm('sounds/RandomSequence.wav');

If you cannot get SAMS working from MATLAB, you can run it separately and 
use the output to run GMP:
 > gmp('sounds/RandomSequence.wav', 'tmp/DSAMout.dat', t, cfAN);

The parameters of the model can be supplied as the 5th input of the function,
but they can also be changed in a more comfortable modifying the file 
gmp_config.m

If you are experiencing problems with DSAM, keep an eye in the folder ./tmp/, 
the output from DSAM is temporary stored in there and the script will assume 
that any file with the name 'output.dat' stored in there has been printed by
sams_ng

-----------------------------------------------------------------------------

DESCRIPTION OF THE PACKAGE: 

This is an idealized model (published in Balaguer et al. (2009) as mentioned 
earlier), formulated in terms of interacting neural ensembles, which provides 
a unified account of the multiple temporal scales of auditory perception.
This model uses feedback modulation, which adapts to changes in the input 
stimulus. This sort of 'generative' approach explains a wide range of 
experiments in temporal integration in pitch perception, gap detection 
thresholds and the neuro-magnetic latencies of pitch onset responses in 
cortex, not accounted for previously. The main contribution is to show how 
efferent connections from central to pre-cortical areas may be critical for 
the temporal processing underlying auditory perception. See the manuscript 
"Understanding pitch perception as a hierarchical procces with top-down 
modulation" for detailed model description. It shows that this model can be
considered as an extension of the autocorrelation theories of pitch in a 
formulation resemblant to population models.

Some other references cited in this code:

 - Balaguer Ballester E, Denham SL and Meddis R (2008) A cascade 
   autocorrelation model of pitch perception. J Acoust Soc Am. In press.
   Firston, K. (2003) Learning and Inference in the Brain. Neural Networks
   16: 1325-1352.

 - Meddis R, O'Mard L (1997) A unitary model of pitch perception. 
   J Acoust Soc Am 102: 1811-1820.

 - Kadner A, Berrebi S (2008) Encoding of the temporal features of auditory
   stimuli in the medial nucleous of the trapezoid body and superior 
   paraolivary nucleous of the rat. Neuroscience 151: 868-887.

 - Krumbholz K, Patterson R Seither-Preisler A, Lammertmann C, Lutkenhoner B
   (2003) Neuromagnetic evidence for a pitch processing center in Heschl's
   gyrus. Cereb Cortex 13: 765-772.

 - Wiegrebe L (2001) Searching for the time constant in of neural pitch 
   extraction. J Acoust Soc Am 107: 1082-1091. 

 - Yost W (1996) Pitch and pitch strength of iterated rippled noise: Is it 
   the envelope or fine structure?. J Acoust Soc Am 100: 2720-2730.

-----------------------------------------------------------------------------

For future updates, download manuscripts and other software please contact us,
Lab. page is in progress.

Thank you very much :) 

  Best wishes, 
Alejandro & Emili