docs update

LICENSE

@@ -0,0 +1,26 @@
+maf2synteny is distributed with the BSD license.
+
+Copyright (c) 2013-2014, Mikhail Kolmogorov and coauthors
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above copyright
+      notice, this list of conditions and the following disclaimer in the
+      documentation and/or other materials provided with the distribution.
+    * Neither the name of the authors nor the
+      names of contributors may be used to endorse or promote products
+      derived from this software without specific prior written permission.
+
+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 AUTHORS 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.

README.md

@@ -1,37 +1,66 @@
 maf2synteny
 ===========
 
-A tool for converting for recovering synteny blocks
-from multiple alignment (in MAF fromat)
+A tool that postprocesses whole genome alignment (for two or more genomes)
+and produces coarse-grained synteny blocks. Currently, either 
+[Cactus](https://github.com/ComparativeGenomicsToolkit/cactus)
+or [SibeliaZ](https://github.com/medvedevgroup/SibeliaZ) alignments are supported.
 
-This tool is a standalone version of Ragout module [http://fenderglass.github./Ragout]
+This tool is originally a part of [Ragout package](http://fenderglass.github.io/Ragout).
 
-Install
--------
+Building
+--------
+
+`make`
+
+Building requires C++11 compiler and development environent installed in your system
 
-	make
 
 Usage
 -----
 
-Usage: maf2synteny [-o out_dir] [-s simpl_params] [-m block_sizes] maf_file
-
-positional arguments:
-	maf_file	path to maf file
-
-optional arguments:
-	-o out_dir	path to the output directory [default = .]
-	-s simpl_params	path to a file with simplifcation parameters [default = not set]
-	-b block_sizes	comma-separated list of synteny block scales [default = 5000]
-
-Default simplification parameters:
-----------------------------------
-    10, 10
-    30, 100
-    50, 5000
-    100, 7000
-    500, 10000
-    1500, 50000
-    5000, 100000
-    10000, 500000
-    50000, 1000000
+```
+    Usage: maf2synteny [-o out_dir] [-s simpl_params] [-m block_sizes] alignment_file
+   
+    positional arguments:
+       alignment_file	path to alignment file in maf or gff format
+    
+    optional arguments:
+       -o out_dir	path to the output directory [default = .]
+       -s simpl_params	path to a file with simplifcation parameters [default = not set]
+       -b block_sizes	comma-separated list of synteny block scales [default = 5000]
+```
+
+Input
+-----
+
+maf2synteny takes as input whole genome alignment in `.maf` or `.gff` formats.
+The tools is optimized to work with Cactus or SibeliaZ alignments. Other
+tools that generate alignments in similar format might not be supported.
+
+The main reason for that is that maf2synteny expect all local alignments to be
+non-overlapping, which is a very specific kind of whole genome alignmet.
+Such alignment characterizes all repeated elements in the genome(s)
+in the alphabet of maximum non-overlapping units. If the input alignmet
+does not have this property, maf2synteny will likely not be able to produce good-quality
+synteny blocks.
+
+Simplification parameters
+---------------------------------
+
+One can specify custom graph simplification parameters to control
+the granularity of produced synteny blocks. The paramers
+could be supplied in a text file, where each line contains
+two numbers: `min_block max_gap`. Please refer to the paper below
+for the explanation how these parameters control the block
+generation rpcedure.
+
+Default parameters: {30, 10}, {100, 100}, {500, 1000}, {1000, 5000}, {5000, 15000}
+
+
+Citation
+--------
+
+* Kolmogorov M, Armstrong J, Raney BJ, Streeter I, Dunn M, Yang F, Odom D, Flicek P, Keane TM,
+Thybert D, Paten B. "Chromosome assembly of large and complex genomes using multiple references"
+Genome research. 2018 [doi:10.1101/gr.236273.118](https://genome.cshlp.org/content/28/11/1720.short)