DESCHRAMBLER 
          ======================================

0. Warning
----------
    Please do not use a '.' symbol as a part of a chromosome name.
    The '.' symbol is used as a delimiter to separate a species name and a chromosome name in output files. 
    If the '.' symbol is already in a chromosome name in your sequence files, please convert it to other symbol,
    like '_', before creating the chain/net files. 

1. How to compile?
------------------

    1.1. Type make

        Simple type make to compile the DESCHRAMBLER package.


2. How to run?
--------------

    2.1. Mandatory input files

        DESCHRAMBLER requires the following four files as input. Example files are in 
        the "examples" directory.

        - config.SFs: a configuration file for chain/net directories and species
        - Makefile.SFs: a makefile for generating syntenic fragments
        - tree.txt: a newick tree for used species and a target ancestor
        - params.txt: a parameter file 

        The above four files need to be placed in the same directory.

    2.1.1. config.SFs

        In the file, the following three values need to be specified. Please refer to the example
        file in the "examples" directory.

        - >netdir: a path to the directory that contains net files
                   This directory needs to have a sub-directory structure as below.
                   
                   reference/descendant1/chain/separate chain files for each chromosome (or scaffold)
                   reference/descendant1/net/separate net files for each chromosome (or scaffold)
                   reference/descendant2/chain/separate chain files for each chromosome (or scaffold)
                   reference/descendant2/net/separate net files for each chromosome (or scaffold)
                   reference/descendant3/chain/separate chain files for each chromosome (or scaffold)
                   reference/descendant3/net/separate net files for each chromosome (or scaffold)

                   An example directory, called "chainNet", is in the "examples" directory.

        - >chaindir: a path to the directory that contains chain files
					 Usually, this directory is the same as the one used in >netdir above.

       The chain/net files can be downloaded from the UCSC genome browser (http://genome.ucsc.edu/), 
       or generated by using tools provided by the UCSC genome browser. Please refer to 
       http://genomewiki.ucsc.edu/index.php/Whole_genome_alignment_howto.

        - >species: the list of reference, ingroup and outgroup species 
                    The species information is listed under ">species". Each line has the following 
                    three values delimited by a space.   

                    - Species name: this name must match with the directory name in the chain/net
                      directory and the name in the newick tree in the "tree.txt" file.
                    - Flag indicating whether the species is a reference (0), descendant (1), 
                      or outgroup (2) species
                    - Flag indicating whether the assembly of the species consists of chromosomes (1) 
                      or not (0) 

        Please do not change the ">resolution" section.

    2.1.2. Makefile.SFs

        You don't need to edit this file. Just copy this file to your working directory. Please use
        the example file in the "examples" directory.

    2.1.3. tree.txt

        This file contains the newick tree for the species listed in the config.SFs file. 
        The target ancestor must be specified by the "@" symbol. Please refer to the example tree
        file in the "examples" directory.       
 
    2.1.4. params.txt

        The following parameters need to be specified.

        - REFSPC: the name of a reference species
                  This name must match with the name used in the chain/net directory, species list in 
                  the config.SFs file, and the tree.txt file.
        - OUTPUTDIR: the output directory 
        - RESOLUTION: block resolution
        - TREEFILE: a path to the newick tree file
        - MINADJSCR: the minimum scores of adjacent syntenic fragments used in reconstruction
        - CONFIGSFSFILE: a path to the config.SFs file          
        - MAKESFSFFILE: a path to the Makefile.SFs file          


    2.2. Run DESCHRAMBLER 

        There is a wrapper Perl script, 'DESCHRAMBLER.pl'. To run DESCHRAMBLER, type as:

            <path to DESCHRAMBLER>/DESCHRAMBLER.pl <path to the parameter file: params.txt> 
 

3. What are produced?
---------------------

    Many files are generated in the output directory that is specified in the parameter file.
    Among them the following files are the most important and useful.

    3.1. block_list.txt (in the "SFs" subdirectory)

        This file contains the coordinates and identifiers of syntenic fragments (SFs) used in 
        reconstruction.

            Column 1: chromosome or scaffold
            Column 2: start position (0-based); add 1 to obtain the actual start position
            Column 3: end position (1-based) 
            Column 4: orientation 
            Column 5: identifier 

    3.2. Conserved.Segments (in the "SFs" directory)

        This file contains the coordinates of genomic regions of each species belonging to each SF.

            Lines starting with ">": ><identifier of an SF>
            Other lines: the coordinates of genomic regions of each species belonging to the SF. The
                format is as follows.
                    <species>.<chromosome or scaffold>:<start position>-<end position> <orientation>

                Here, the start position is 0-based, and the end position is 1-based. You need to
                add 1 to the start position to obtain the actual start position.

    3.3. Ancestor.APCF

        This file contains the list of ancestral predicted chromosome fragments (APCFs), and the order 
        and orientation of SFs in each APCF. 

            Line 1: >ANCESTOR <total number of SFs>
            Lines starting with "#": # APCF <identifier of APCF>
            Other lines: the order and orientation of SFs belonging to the APCF shown immediately above line.
                SFs are shown by using their identifiers (refer to the block_list.txt file).  

    3.4. Ancestor.ADJS

        This file contains the predicted adjacencies of pairs of SFs and their scores used in the 
        Ancestor.APCF file. SFs are shown by using their identifiers (refer to the block_list.txt file).
            
            Column 1: the first SF identifier
            Column 2: the second SF identifier
            Column 3: adjacency score of the first and the second identifiers

        In the first and second columns, 0 means the end of APCFs. For example, "0 64" means the SF 64 
        is placed at the end of a current APCF.      

    3.5. APCF_size.txt

        This file contains the total length of APCFs.

            Column 1: APCF identifier
            Column 2: total length

        The last line shows the sum of total APCF lengths.

    3.6. APCFs

        This file contains the list of coordinates of genomic regions of each species matching to each APCF.

            Lines starting with "#": #<identifier of APCF>
            The coordinates of genomic regions of each species (grouped by species) follow this line. 

    3.7. APCF_<SPC>.merged.map

        This file contains the mapping genomic regions of the SPC species for APCFs. Each mapping is shown
        by using the following three lines.

            ><identifier of mapping>
            APCF.<identifier of APCF>:<start position in APCF>-<end position in APCF> <orientation>
            <SPC>.<chromosome or scaffold>:<start position in SPC>-<end position in SPC> <orientation>

        The start position is 0-based, and the end position is 1-based. You need to add 1 to the start position to 
        obtain the actual start position. 


4. Supplementary data
---------------------

    The chain/net files and reconstruction results are available at our supplementary website
    (http://bioinfo.konkuk.ac.kr/DESCHRAMBLER). 
    
    
5. How to cite
--------------

    Kim J, Farré M, Auvil L, Capitanu B, Larkin DM, Ma J, Lewin HA. Reconstruction and evolutionary history of eutherian chromosomes. Proc Natl Acad Sci U S A. 2017 Jul 3;114(27):E5379-E5388. doi: 10.1073/pnas.1702012114.