# last-dotplot

This script makes a dotplot, a.k.a. Oxford Grid, of pair-wise sequence alignments in MAF or LAST tabular format. It requires the Python Imaging Library to be installed. It can be used like this:

    last-dotplot my-alignments my-plot.png

The output can be in any format supported by the Imaging Library:

    last-dotplot alns alns.gif

To get a nicer font, try something like:

    last-dotplot -f /usr/share/fonts/truetype/freefont/FreeSans.ttf alns alns.png

If the fonts are located somewhere different on your computer, change this as appropriate.

## Choosing sequences

If there are too many sequences, the dotplot will be very cluttered, or the script might give up with an error message. You can exclude sequences with names like "chrUn_random522" like this:

    last-dotplot -1 'chr[!U]*' -2 'chr[!U]*' alns alns.png

Option "-1" selects sequences from the 1st (horizontal) genome, and "-2" selects sequences from the 2nd (vertical) genome. 'chr[!U]*' is a pattern that specifies names starting with "chr", followed by any character except U, followed by anything.

Pattern | Meaning
`*` | zero or more of any character
`?` | any single character
`[abc]` | any character in abc
`[!abc]` | any character not in abc

If a sequence name has a dot (e.g. "hg19.chr7"), the pattern is compared to both the whole name and the part after the dot.

You can specify more than one pattern, e.g. this gets sequences with names starting in "chr" followed by one or two characters:

    last-dotplot -1 'chr?' -1 'chr??' alns alns.png

You can also specify a sequence range; for example this gets the first 1000 bases of chr9:

    last-dotplot -1 chr9:0-1000 alns alns.png

## Options

> `-h, --help` | Show a help message, with default option values, and exit.
> `-v, --verbose` | Show progress messages & data about the plot.
> `-1 PATTERN, --seq1=PATTERN` | Which sequences to show from the 1st (horizontal) genome.
> `-2 PATTERN, --seq2=PATTERN` | Which sequences to show from the 2nd (vertical) genome.
> `-x WIDTH, --width=WIDTH` | Maximum width in pixels.
> `-y HEIGHT, --height=HEIGHT` | Maximum height in pixels.
> `-c COLOR, --forwardcolor=COLOR` | Color for forward alignments.
> `-r COLOR, --reversecolor=COLOR` | Color for reverse alignments.
> `--sort1=N` | Put the 1st genome's sequences left-to-right in order of: their appearance in the input (0), their names (1), their lengths (2).
> `--sort2=N` | Put the 2nd genome's sequences top-to-bottom in order of: their appearance in the input (0), their names (1), their lengths (2).
> `--trim1` | Trim unaligned sequence flanks from the 1st (horizontal) genome.
> `--trim2` | Trim unaligned sequence flanks from the 2nd (vertical) genome.
> `--border-pixels=INT` | Number of pixels between sequences.
> `--border-color=COLOR` | Color for pixels between sequences.

### Text options

> `-f FILE, --fontfile=FILE` | TrueType or OpenType font file.
> `-s SIZE, --fontsize=SIZE` | TrueType or OpenType font size.
> `--lengths1` | Show sequence lengths for the 1st (horizontal) genome.
> `--lengths2` | Show sequence lengths for the 2nd (vertical) genome.

### Annotation options

These options read annotations of sequence segments, and draw them as colored horizontal or vertical stripes. This looks good only if the annotations are reasonably sparse: e.g. you can't sensibly view 20000 gene annotations in one small dotplot.

> `--bed1=FILE` | Read BED-format annotations for the 1st genome. They are drawn as stripes, with coordinates given by the first three BED fields. The color is specified by the RGB field if present, else pale red if the strand is "+", pale blue if "-", or pale purple.
> `--bed2=FILE` | Read BED-format annotations for the 2nd genome.
> `--rmsk1=FILE` | Read repeat annotations for the 1st genome, in RepeatMasker .out or rmsk.txt format. The color is pale purple for "low complexity" and "simple repeats", else pale red for "+" strand and pale blue for "-" strand.
> `--rmsk2=FILE` | Read repeat annotations for the 2nd genome.

### Gene options

> `--genePred1=FILE` | Read gene annotations for the 1st genome in genePred format.
> `--genePred2=FILE` | Read gene annotations for the 2nd genome.
> `--exon-color=COLOR` | Color for exons.
> `--cds-color=COLOR` | Color for protein-coding regions.

### Unsequenced gap options

Note: these "gaps" are not alignment gaps (indels): they are regions of unknown sequence.

> `--gap1=FILE` | Read unsequenced gaps in the 1st genome from an agp or gap file.
> `--gap2=FILE` | Read unsequenced gaps in the 2nd genome from an agp or gap file.
> `--bridged-color=COLOR` | Color for bridged gaps.
> `--unbridged-color=COLOR` | Color for unbridged gaps.

An unsequenced gap will be shown only if it covers at least one whole pixel.

### Colors

Colors can be specified in various ways described here.