NetResponse Analysis Tools for Matlab
====================================================================

version 0.2
project homepage: http://www.cis.hut.fi/projects/mi/software/NetResponse/

This is a Matlab implementation of the NetResponse algorithm, which is
described in publications available at the project homepage. 

Copyright (C) 2008-2010 Leo Lahti

NOTE: The Matlab source is provided for your convenience but it is not
actively supported. We recommend using the associated R package which
can be downloaded from the project homepage.

CITATIONS: If you use this implementation, please cite the
publications at the project homepage.

LICENCE: This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License as
published by the Free Software Foundation; either version 2, or (at
your option) any later version.
 
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License (included in file License.txt in the
program package) for more details.

The implementation of the NetSign algorithm is based on the
Variational Dirichlet Process Gaussian Mixture Model implementation,
Copyright (C) 2007 Kenichi Kurihara. All rights reserved., and AIVGA
Agglomerative Independent Variable Group Analysis package (v. 1.0)
Copyright (C) 2001-2007 Esa Alhoniemi, Antti Honkela, Krista Lagus,
Jeremias Seppa, Harri Valpola, and Paul Wagner For more details on
AIVGA, see http://www.cis.hut.fi/projects/ivga/

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
OF THE POSSIBILITY OF SUCH DAMAGE.


Compiling the MEX files
-----------------------

The toolbox uses some MEX files (vdp_*.c, mix.c) to speed up learning
of the mixture models.  If the precompiled versions are not
sufficient, the files can be compiled either manually or from Matlab
using the included netsign_compile script.


Basic usage
-----------

netresponse             The main function. Agglomerative detection of local
			subnetworks where interacting nodes show
			coordinated responses across a variety of
			conditions, as estimated by infinite Gaussian
			mixture model. Each subnetwork is
			approximately independent of the neighboring
			nodes in the network.


netsign_import_data       This function is used to import data. 


netsign_compile         Compiles or recompiles the C implementation of
			the mixture model for the hardware
                        platform. Call this function and try again if
                        you get warnings about a missing C
                        implementation or errors related to MEX
                        functions.




Examples
--------

Load the following files to your working directory from the project homepage:
expressions.tab, network.mat, network_genes.mat 
(Use the same order for network_genes.mat as in network.mat)

See main.m for an complete example on importing data and performing
the analysis.


You can perform analysis in Matlab prompt with the following:


To import data in the specified files:

>> [D, netw] = netsign_import_data(expressionFile,networkFile,networkGenesFile);


To compute a grouping for the features in data matrix 'D', constrained
by the network 'netw':

>> randseed(32633);
>> result = netresponse(D, netw)

To investigate subnetwork k at the final agglomeration step (i.e. step
length(result.groupings))

>> k = 1;
>> result.groupings{length(result.groupings)}{k}


To inspect compressed representation of the model at the last
agglomeration step:

>> res.models{length(result.groupings)}{k}



For more information, see the project homepage.

