chromeister

An ultra fast, heuristic approach to detect conserved signals in extremely large pairwise genome comparisons.

Requirements

GCC compiler (any version that is not completely outdated should do), the R programming language (base installation) and python3 (tested on 3.5 and 3.8). Please make sure that on your linux CC resolves to GCC, otherwise it might not work.

Simply download the .zip and unzip it, or clone the repository. Then issue the following command:

cd chromeister && make all -C src/ && python3 -m venv chromeisterenv && source chromeisterenv/bin/activate && pip install -r src/requirements.txt

This will compile CHROMEISTER and create a virtualenv where the python libraries will be installed (see src/requirements.txt)

If the installation finished without errors, you are ready to go! If you encounter the following problem ImportError: No module named 'skbuild' you might need to do source chromeisterenv/bin/activate && pip install --upgrade pip and then run pip install -r src/requirements.txt to finish the installation.

NOTE: python and its libraries are only used for the detection of events. If the binaries compile (i.e. the make all) then you can still run CHROMEISTER and plot the results, even if the python installation did not work.

Use

There are several ways in which CHROMEISTER can be used. The simplest one is to run a 1-vs-1 comparison and then compute the score and the plot. To do so, use the binaries at the bin folder:

Simple execution

You can run CHROMEISTER directly by issuing:

CHROMEISTER -query seqX -db seqY -out dotplot.mat && Rscript compute_score.R dotplot.mat 1000

If you do not want a grid on the output dotplot (which is recommended when running comparisons with a lot of scaffolds for instance) then run the same command but replace compute_score by compute_score-nogrid, see below:

CHROMEISTER -query seqX -db seqY -out dotplot.mat && Rscript compute_score-nogrid.R dotplot.mat 1000

The 1000 value is the default size of dotplot.mat, i.e. the resolution of the matrix -- if you want to change this (for example to generate a larger image (if you use 2000 it will generate a plot of 2000x2000, so be careful) include also the parameter -dimension in CHROMEISTER. Example command with larger resolution:

CHROMEISTER -query seqX -db seqY -out dotplot.mat -dimension 2000 && Rscript compute_score.R dotplot.mat 2000

And if you want to run the events detection, use (make sure that your virtualenv chromeisterenv is in the chromeister root folder:

source ../chromeisterenv/bin/activate && python3 bin/detect_events.py dotplot.mat.raw.txt

This will generate a dotplot.mat.events.txt file containing the detected events and classified. If you want to get a plot of the signal with the overlapped detected events, issue the same command but add at the end the parameter png (separated by a space).

You can also use the script that is in the bin folder (which will do all of the above for you):

run_and_plot_chromeister.sh (input sequence A) (input sequence B) (KMER size) (DIMENSION of plot) (inexactitude level) [optional: grid]

(see parameters at the end) (the grid keyword at the end can be included/omitted depending if you want grid in the output dotplot)

This will generate the following items:

• Comparison matrix, i.e. a scaled matrix containing the unique and inexact hits
• Plot of the comparison with the automatic scoring distance and grid separating different sequences (chromosomes for instance)
• CSV file containing the coordinates of each sequence/chromosome contained within the query and the reference
• Events file. A text file where each row is a synteny block. Note: these events are Large-Scale Genome Rearrangements heuristically determined and classified as {Synteny block, transposition, inversion, ...} - but this is only an informative labelling that only considers coordinates - do not blindly believe in the classification, but rather do your own labelling based on the events.
• Guides to be used in an exhaustive GECKO comparison (reduces runtime)

All vs All execution

You can run massive all versus all comparisons in two diferent ways:

• Comparing all the sequences in one folder. This accounts for 1/2 * n * (n+1) comparisons, hence it will not compare sequence B to sequence A if the comparison for sequence A to sequence B already existed.

  • To run this mode, use the script in the bin folder: allVsAll.sh <sequences folder> <extension (e.g. fasta)> <matrix size (1000 for chromosomes, 2000 for full genomes)> <kmer size 32 (32 is best)> <inexactitude level (4 is recommended)>

• Comparing two folders containing sequences. This accounts for n * m comparisons, therefore it will compare ALL to ALL. Use this for instance to compare all chromosomes of one genome to all chromosomes of another genome.

  • To run this mode, use the script in the bin folder: allVsAll_incremental.sh <sequences folder 1> <sequences folder 2> <extension (e.g. fasta)> <matrix size (1000 for chromosomes, 2000 for full genomes)> <kmer size 32 (32 is best)> <inexactitude level (4 is recommended)>

At the end of both comparisons, an index will be created summarizing the scores per each comparison. This index has the following format (see header and example below): header: <SpX, SpY, IDX, IDY, IMG, CHNumberX, CHNumberY, Score, LengthX, LengthY> example: BRAOL.Chr.C1,BRAOL.Chr.C2,>C1 dna:chromosome chromosome:v2.1:C1:1:43764888:1 REF,>C2 dna:chromosome chromosome:v2.1:C2:1:52886895:1 REF,BRAOL.C hr.C1.fasta-BRAOL.Chr.C2.fasta.mat.filt.png,C1,C2, 0.996,43764888,52886895

Notice that you can easily run this in parallel by just re-issuing the command (i.e. execute same command as many times as you want, each time another core will help in the processing).

Converting CHROMEISTER signal into alignments

First of all, consider whether it is interesting or not to use CHROMEISTER for "fine-grained" results. CHROMEISTER is recommended for VERY coarse-grained and full-genome comparisons in order to quickly assess similarity between genomes. Thus it does NOT produce alignments. However, if you find yourself in a situation where you want to convert the signal of CHROMEISTER into alignments (e.g. two large genomes), this can be done. The following tutorial shows how to do it, with human chromosome X and mouse chromosome X as example:

1. First, run CHROMEISTER like this:

   ./CHROMEISTER -query HOMSA.Chr.X.fasta -db MUSMU.Chr.X.fasta -out dotplot.mat -dimension 1000 && Rscript compute_score.R dotplot.mat 1000

2. Check the "dotplot.mat.filt.png" corresponding to the dotplot between both chromosomes to see if there is any similarity. If so, proceed to next step.

3. Clone the following repository: https://github.com/estebanpw/gecko

   git clone https://github.com/estebanpw/gecko

4. Switch branch to the one named "inmemory_guided_chrom" and compile it. To do so, issue the following command:

   cd gecko && git checkout inmemory_guided_chrom && make all -C src

5. Now run the script "guidefastas" in the bin folder. See below:

   bin/guidefastas.sh HOMSA.Chr.X.fasta MUSMU.Chr.X.fasta hits-XY-dotplot.mat.hits 1000 100 60 32

   You can add the following arguments to the execution:

• --alignments : This one will extract the alignments and write them to a file with extension .alignments in the all-results folder.
• --names : This one will output the names of the sequences to which each fragment belongs instead of their sequence number (e.g. if comparing chromosomes 1 and 2 of Homo sapiens vs Mus musculus then 0,1 will now be Homo s. chr1, Mus m. chr2)
• --sort : This will sort output frags in the csv file according first to the comparison they belong to and secondly by coordinates.
• --local : This one will convert the coordinates i