formfunction Files

INTRODUCTION
-----------------------
FormFunction is MATLAB software used to execute a mathematical model which investigates how function follows form in a set of genetic networks with two chemical inputs and one protein output. The "opt" directory contains code for maximizing mutual information of the input-output response by performing a numerical search for local optima in the parameter space of the model. The "dat" directory contains code for determining the correlation coefficients between the set of topological feature values and the realizable functions of these networks.

This software is free for scientific use. Please contact us if you plan to use this software for commercial purposes. Do not further distribute without permission of the author. If used in your scientific work, please cite as:

Andrew Mugler, Boris Grinshpun, Riley Franks, Chris H. Wiggins, "A statistical method for revealing form-function relations in biological networks" (Submitted to the Proceedings of the National Academy of Sciences)


INSTALLATION
----------------------
A working copy of the MATLAB computing environment is required.  Before running, check that the desired .m files (MATLAB function files) are in MATLAB's working path. This can be done by navigating to the desired directory prior to running the code or by adding it to your path.


USE
-------
"opt" directory:
    a. GetData.m -> this is the main file for running the optimization procedure
		- choose settings and run optimization
    b. runOpt.m
		- specifies topology (network + unique regulation) as well as the name of the file to which results are saved. 
           	- functions called: optimization.m
    c. optimization.m
		- performs optimization of mutual information
		- functions called: randpt.m, wrapper.m
		i. randpt.m
			- initializes parameters
   d. wrapper.m
		- calculates means, variances, and mutual information
		- functions called: findss.m, findvars.m, mi_mfp.m, plot_pdf_opt.m, plot_mi.m
		i. findss.m
			- calculates steady state output concentrations by solving regulation equations defined in runPoly files
			- functions called: m-files in runPolys folder, jmatrices.m, checkstab.m
		ii. findvars.m
			- calculates output variances
			- functions called: BuchlerAlphas.m, mylyap.m
		iii. mi_mfp.m
			- calculates mutual information
			- functions called: Iint.m
		iv. plot_pdf_opt.m
			- plots conditional distributions

ii. "dat" directory
    a. featureTest.m  --> Run this file to obtain correlation coefficients
		- contains list of features
		- obtains feature values in order to calculate correlation coefficients
		- functions called: features.m,calcPxr.m
    b. calcPxr.m
		- calculates the joint distribution of feature values and rankings, mutual information, and entropy
		- functions called: calcI.m, entropy.m
    		i. calcI.m
			- calculates mutual information from a joint probability matrix
    		ii. entropy.m
			- calculates entropy of a random variable
    c. features.m
		- constructs matrix of feature values
		- functions called: tpc.m
    		i. tpc.m
			- encodes topologies
   d. plot_pdf.m
		- plots conditional distributions for a particular optimization
   e. featmi.m
		- constructs feature-feature adjacency matrix
		- functions called: entropy.m
   f. redundancy_1da.m
		- redundancy plot
		- functions called: featmi.m


DEMO
--------------
Run 'ffdemo.m' (in "opt" directory) in MATLAB, which runs an example optimization for a specific set of inputs.

See documentation in m-files for further information.


LICENSE
--------------
Copyright (c) 2009,2010 Boris Grinshpun <bg2178@columbia.edu>

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 3 of the License, 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 for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.