
Documentation and example file for FLBEND


Installation

To install from source requires compiling and linking to a random number
generation library  (eg. f95 -o flbend flrand.f90 flbend.f90 -lran).  
The file flrand.f90 may require editing if you use a random number generation
library other than RANDLIB (http://odin.mdacc.tmc.edu/anonftp/page_2.html).



1.  Input Files

1.1 "seeds"  

A file with two integers on the first line, used to set the random number 
	generator.  The file will be updated with a new file containing two 
	pseudo-random integers.

1.2 "data"

Line 1, 5 integers, <int1> to <int5>

<int1>  The dimension of the covariance matrix, = n

<int2>  The number of distance minimisation cycles, a larger number will give 
	a final matrix "closer" to the non-PD matrix (suggest at 
	least 5 * n * n)

<int3>  The number of samples drawn in an attempt to find a rounded PD 
	matrix, suggest start with n * n, and increase if program fails 
	to find a PD rounded solution.

<int4>  The number of sampling steps.  Having found a PD rounded solution, 
	the program can explore the region surrounding this solution, 
	producing minimum and maximum values for each covariance.  A matrix 
	comprising the minimums and maximums probably isn't PD, but these 
	values occurred in a PD matrix.

<int5>  The number of digits to the right of the decimal point to which a 
	PD rounded solution for the correlation matrix is required.



The next n lines contain an integer and two reals, <int1>  <real1> and <real2>

<int1>  The trait number

<real1> An estimate of the variance

<real2> An estimate of the standard error of the variance


The next line contains either a "V" or a "R", indicating that either 
covariances or correlations follow.


The remaining lines contain an upper-triangular representation of the 
covariance or correlation matrix.  
Each line has the form <int1> <int2> <real1> <real2> 

<int1>  Row

<int2>  Column

<real1>  Estimated covariance or correlation

<real2>  Estimated standard error of covariance or correlation.


2.  Output Files

"MATS"  For examination only, solutions given are rounded and not guaranteed 
	to be PD. 

i	row   
j  	column
Vin 	Covariance input
SE 	Standard error input (covariance scale)
Rin     Correlation input
SE   	Standard error input (correlation scale)
Vmd 	Covariance matrix, minimum distance
Rmd  	Correlation matrix, minimum distance
Vmin    Matrix of minimum covariances
Vmax    Matrix of maximum covariances
Rmin    Matrix of minimum correlations
Rmax    Matrix of maximum correlations


"PDMAT" Similar to "MATS", but with full precision, use these in following 
	applications.


XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Example data file

XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
3 1000  1000 1000 5 
1 0.5425 0.1
2 0.4421 0.1
3 0.1987 0.1
V
1 1 0.5425 0.1
1 2 0.4417 0.3
1 3 0.3224 0.3
2 2 0.4421 0.1
2 3 0.2866 0.3
3 3 0.1987 0.4

There are 3 traits, we want 1000 minimisation steps followed by up to 1000 
rounding steps followed by 1000 sampling steps.  The correlation matrix should
be PD when rounded to 5 places to the right of the decimal point.

The covariance matrix input is

   0.5425   0.4417   0.3224
   0.4417   0.4421   0.2866
   0.3224   0.2866   0.1987

and the estimated standard errors are 

0.1 0.3 0.3
0.3 0.1 0.3
0.3 0.3 0.1


