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.