README - M.I.D. ver 3.0
-----------------------

------------------------------------------------------------------------------
LICENSE
------------------------------------------------------------------------------

Copyright (C) CNL-T, The Salk Institute for Biological Studies
Authors:  T. Sharpee, M. Kouh, R. Rowekamp, M. Grivich & A. Nandy

The following terms and conditions apply to use of the Programs.
Downloading the programs indicates your acceptance of these terms and 
conditions.

These programs are provided for non-commercial research use only.

The programs will not be distributed further to third parties for any
purpose and will not be decompiled, disassembled or otherwise reverse
engineered.

The Salk Institute makes no representation that the use of the
programs will not infringe any patent or other proprietary right.

The authors will be acknowledged as the source of the program in any 
publications reporting its use.

THE PROGRAMS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF MERCANTABILITY
OR FITNESS FOR A PARTICULAR PURPOSE OR ANY OTHER WARRANTY, EXPRESS OR
IMPLIED. IN NO EVENT SHALL THE SALK INSTITUTE OR THE AUTHOR(S)
BE LIABLE FOR ANY DIRECT OR CONSEQUENTIAL DAMAGES RESULTING
FROM USE OF THE PROGRAMS.  THE USER BEARS THE ENTIRE RISK FOR USE OF
THE PROGRAMS.


------------------------------------------------------------------------------
INTRODUCTION
------------------------------------------------------------------------------

This README file contains installation, build and test instructions for
Maximally Informative Dimensions (M.I.D.) analysis code.


------------------------------------------------------------------------------
DOWNLOAD INSTRUCTIONS
------------------------------------------------------------------------------

Git is required, get git here http://git-scm.com/download

This project is hosted at github: https://github.com/sharpee/mid

There are 4 sections to the code:

1. mid (the base)
2. matlab-plot (example plotting code)
3. demo (demo code) https://github.com/sharpee/mid-demo
4. mxml (mxml C++ libraries, if not already installed. Also available in debian/
  ubuntu package libmxml-dev. Source: www.minixml.org/software.php)
  mirrored at: https://github.com/sharpee/mxml

------------------------------------------------------------------------------
INSTALLATION INSTRUCTIONS
------------------------------------------------------------------------------

Get the Code:
  git clone git://github.com/sharpee/mid.git mid

Optionally, get the Demo:
  git clone git://github.com/sharpee/mid-demo.git mid-demo

Get the mxml package if not already installed on your system:
  cd mid
  git submodule init
  git submodule update
  cd mid/mxml-2.6
  ./configure --prefix="$PWD"
  make
  make install
  cd ../..

Compile the M.I.D. build application:
  cd mid
  make
  make clean

------------------------------------------------------------------------------
INSTRUCTIONS FOR TESTING THE APPLICATION
------------------------------------------------------------------------------

Test the M.I.D. application for the standard analysis:

(A) Independent optimization

Find the first informative dimension:

cd mid-demo

../mid/mid/mid1d 1 params.xml 1

The result is contained in the file:

V1model-1D-n1-v1-p1.dat


(B) Simultaneous optimization

Find the first two informative dimensions by simultaneous
optimization:

../mid/mid/midnd 2 params.xml 1

The two dimensions are contained in the files:

V1model-ND-n2-v1-p1.dat
V1model-ND-n2-v2-p1.dat


Included in the demo folder are the results for the analysis for all 
4 different test parts [p1 ... p4], for both the independant and
simultaneous procedures. This folder also includes PNG versions of the 
output. The matlab scripts used to generate these images are available 
in the MATLAB-<YYYY-MM-DD> folder. The images of the individual vectors
were generated by:

saveVectors(16,16,3);

The average vector images and the comparison to the model vectors were
generated by:

r = dotNormal('mv_model_v1_1110_1.dat','mv_model_v2_1110_1.dat',
'V1model-1D-n2',4,16,16,3);

[**NOTE** This assumes that the MATLAB-<YYYY-MM-DD> folder
is in MATLAB's search path and that the commends are run from
the directory in which which the vector files (*.dat) are stored.
Substitute 'V1model-ND-n2' in the 3rd parameter for the
simultaneous analysis.]


------------------------------------------------------------------------------
FILE FORMATS
------------------------------------------------------------------------------

The spike file typically, but not necessarily ends, in .isk.  The spike 
file is in text format, with each line giving the number of spikes in 
that frame. The movie file typically, but not necessarily, ends in .raw.  
The movie file is in flattened binary format, with the three ordered 
indices being column, row, frame.  The data points can be either integer 
bytes or floating point doubles.  There is no header for either file.  
That type of information is stored in the params.xml file.

Inspect and edit the params.xml file in text editor as necessary.  
A sample params.xml file is shown below:

<?xml version="1.0" encoding="utf-8"?>
<Configuration>

<ParametersGroup name="Spike Parameters">
<StringListParameter name="spike files" value="11101_1.isk"/>
<IntegerParameter name="number of parts" value="4"/>  
<IntegerParameter name="number of trials" value="0"/>
</ParametersGroup>

<ParametersGroup name="Annealing Parameters">
<IntegerParameter name="max annealing iterations" value="1"/>
<DoubleParameter name="start temperature" value="0.01"/>
<DoubleParameter name="stop temperature" value="1.0e-5"/>
<DoubleParameter name="down temperature factor" value=".95"/>
<DoubleParameter name="up temperature factor" value="5.0"/>
<DoubleParameter name="function tolerance" value="5.0e-5"/>
<IntegerParameter name="updateFactor" value="100"/>
</ParametersGroup>

<ParametersGroup name="Movie Parameters">
<StringListParameter name="movie files" 
value="walk1_ieee_128x128x16384.raw"/>
<EnumeratorParameter name="data type" value="1" 
values="byte:1:double:2" />

<IntegerParameter name="width" value="128"/>
<!-- smallest legal value is one -->
<IntegerParameter name="x offset" value="5"/>
<IntegerParameter name="sta width" value="64"/>
<IntegerParameter name="x downsample" value="4"/>

<IntegerParameter name="height" value="128"/>
<!-- smallest legal value is one -->
<IntegerParameter name="y offset" value="5"/>
<IntegerParameter name="sta height" value="64"/>
<IntegerParameter name="y downsample" value="4"/>

<IntegerParameter name="sta duration" value="3"/>
<!-- smallest legal value is zero -->
<IntegerParameter name="skipped sta frames" value="0"/>
<IntegerListParameter name="number of bins" value="5,10,15"/>
<IntegerListParameter name="number of iterations" 
value="500,500,500"/>
</ParametersGroup>

<ParametersGroup name="Output Parameters">
<StringParameter name="prefix" value="V1model"/>
</ParametersGroup>


</Configuration>


-End of README File-