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-