| supermatcher

## Function

Finds a match of a large sequence against one or more sequences

## Description

This is a rough and ready local alignment program for large sequences. The reason it is rough and ready is that wordmatch is used to find all the word matches between the first sequence and another sequence. Then by calculating the highest score for a diagonal we can then use this as the centre point for a Smith-Waterman type calculation of a width given by the user. So a narrow diagonal Smith-Waterman is calculated hence the results will be rough but due to the space saving much larger sequences can be aligned.

## Usage

Here is a sample session with supermatcher

    % supermatcher tembl:ec* tembl:eclac -word 50
    Finds a match of a large sequence against one or more sequences
    Gap opening penalty [10.0]:
    Gap extension penalty [0.5]: 3.0
    Output alignment [eclac.supermatcher]:

Go to the input files for this example
Go to the output files for this example

## Command line arguments

       Standard (Mandatory) qualifiers:
      [-asequence]         seqall     Sequence database USA
      [-bsequence]         seqset     Sequence set USA
       -gapopen            float      Gap opening penalty
       -gapextend          float      Gap extension penalty
      [-outfile]           align      Output alignment file name

       Additional (Optional) qualifiers:
       -datafile           matrixf    This is the scoring matrix file used when
                                      comparing sequences. By default it is the
                                      file 'EBLOSUM62' (for proteins) or the file
                                      'EDNAFULL' (for nucleic sequences). These
                                      files are found in the 'data' directory of
                                      the EMBOSS installation.
       -width              integer    Alignment width
       -wordlen            integer    Word length for initial matching
       -errorfile          outfile    Error file to be written to

       Advanced (Unprompted) qualifiers: (none)
       Associated qualifiers:

       "-asequence" associated qualifiers
       -sbegin1             integer    Start of each sequence to be used
       -send1               integer    End of each sequence to be used
       -sreverse1           boolean    Reverse (if DNA)
       -sask1               boolean    Ask for begin/end/reverse
       -snucleotide1        boolean    Sequence is nucleotide
       -sprotein1           boolean    Sequence is protein
       -slower1             boolean    Make lower case
       -supper1             boolean    Make upper case
       -sformat1            string     Input sequence format
       -sdbname1            string     Database name
       -sid1                string     Entryname
       -ufo1                string     UFO features
       -fformat1            string     Features format
       -fopenfile1          string     Features file name

       "-bsequence" associated qualifiers
       -sbegin2             integer    Start of each sequence to be used
       -send2               integer    End of each sequence to be used
       -sreverse2           boolean    Reverse (if DNA)
       -sask2               boolean    Ask for begin/end/reverse
       -snucleotide2        boolean    Sequence is nucleotide
       -sprotein2           boolean    Sequence is protein
       -slower2             boolean    Make lower case
       -supper2             boolean    Make upper case
       -sformat2            string     Input sequence format
       -sdbname2            string     Database name
       -sid2                string     Entryname
       -ufo2                string     UFO features
       -fformat2            string     Features format
       -fopenfile2          string     Features file name

       "-outfile" associated qualifiers
       -aformat3            string     Alignment format
       -aextension3         string     File name extension
       -adirectory3         string     Output directory
       -aname3              string     Base file name
       -awidth3             integer    Alignment width
       -aaccshow3           boolean    Show accession number in the header
       -adesshow3           boolean    Show description in the header
       -ausashow3           boolean    Show the full USA in the alignment
       -aglobal3            boolean    Show the full sequence in alignment

       "-errorfile" associated qualifiers
       -odirectory          string     Output directory

       General qualifiers:
       -auto                boolean    Turn off prompts
       -stdout              boolean    Write standard output
       -filter              boolean    Read standard input, write standard output
       -options             boolean    Prompt for standard and additional values
       -debug               boolean    Write debug output to program.dbg
       -verbose             boolean    Report some/full command line options
       -help                boolean    Report command line options. More
                                      information on associated and general
                                      qualifiers can be found with -help -verbose
       -warning             boolean    Report warnings
       -error               boolean    Report errors
       -fatal               boolean    Report fatal errors
       -die                 boolean    Report deaths

Standard (Mandatory) qualifiers | Allowed values | Default
--- | --- | ---
[-asequence] (Parameter 1) | Sequence database USA | Readable sequence(s) | Required
[-bsequence] (Parameter 2) | Sequence set USA | Readable set of sequences | Required
-gapopen | Gap opening penalty | Number from 1.000 to 100.000 | 10.0 for any sequence type
-gapextend | Gap extension penalty | Number from 0.100 to 10.000 | 0.5 for any sequence type
[-outfile] (Parameter 3) | Output alignment file name | Alignment output file |
Additional (Optional) qualifiers | Allowed values | Default
-datafile | This is the scoring matrix file used when comparing sequences. By default it is the file 'EBLOSUM62' (for proteins) or the file 'EDNAFULL' (for nucleic sequences). These files are found in the 'data' directory of the EMBOSS installation. | Comparison matrix file in EMBOSS data path | EBLOSUM62 for protein EDNAFULL for DNA
-width | Alignment width | Integer 1 or more | 16
-wordlen | Word length for initial matching | Integer 3 or more | 6
-errorfile | Error file to be written to | Output file | supermatcher.error
Advanced (Unprompted) qualifiers | Allowed values | Default
(none)

## Input file format

supermatcher reads two sequence USAs of the same type. They must both be protein or both be nucleic acid sequences.

### Input files for usage example

'tembl:ec*' is a sequence entry in the example nucleic acid database 'tembl'

### Database entry: tembl:eclac

    ID   ECLAC      standard; DNA; PRO; 7477 BP.
    XX
    AC   J01636; J01637; K01483; K01793;
    XX
    SV   J01636.1
    XX
    DT   30-NOV-1990 (Rel. 26, Created)
    DT   04-MAR-2000 (Rel. 63, Last updated, Version 7)
    XX
    DE   E.coli lactose operon with lacI, lacZ, lacY and lacA genes.
    XX
    KW   acetyltransferase; beta-D-galactosidase; galactosidase; lac operon;
    KW   lac repressor protein; lacA gene; lacI gene; lactose permease; lacY gene;
    KW   lacZ gene; mutagenesis; palindrome; promoter region;
    KW   thiogalactoside acetyltransferase.
    XX
    OS   Escherichia coli
    OC   Bacteria; Proteobacteria; gamma subdivision; Enterobacteriaceae;
    OC   Escherichia.
    XX
    RN   [1]
    RP   1243-1266
    RX   MEDLINE; 74055539.
    RA   Gilbert W., Maxam A.;
    RT   "The nucleotide sequence of the lac operator";
    RL   Proc. Natl. Acad. Sci. U.S.A. 70:3581-3584(1973).
    XX
    RN   [2]
    RP   1246-1308
    RX   MEDLINE; 74055540.
    RA   Maizels N.M.;
    RT   "The nucleotide sequence of the lactose messenger ribonucleic acid
    RT   transcribed from the UV5 promoter mutant of Escherichia coli";
    RL   Proc. Natl. Acad. Sci. U.S.A. 70:3585-3589(1973).
    XX
    RN   [3]
    RX   MEDLINE; 74174501.
    RA   Gilbert W., Maizels N., Maxam A.;
    RT   "Sequences of controlling regions of the lactose operon";
    RL   Cold Spring Harb. Symp. Quant. Biol. 38:845-855(1974).
    XX
    RN   [4]
    RA   Gilbert W., Gralla J., Majors A.J., Maxam A.;
    RT   "Lactose operator sequences and the action of lac repressor";
    RL   (in) Sund H., Blauer G. (eds.);
    RL   PROTEIN-LIGAND INTERACTIONS:193-207;
    RL   Walter de Gruyter, New York (1975)
    XX
    RN   [5]
    RP   1146-1282

      [Part of this file has been deleted for brevity]

         cgatttggct acatgacatc aaccatatca gcaaaagtga tacgggtatt atttttgccg      4560
         ctatttctct gttctcgcta ttattccaac cgctgtttgg tctgctttct gacaaactcg      4620
         ggctgcgcaa atacctgctg tggattatta ccggcatgtt agtgatgttt gcgccgttct      4680
         ttatttttat cttcgggcca ctgttacaat acaacatttt agtaggatcg attgttggtg      4740
         gtatttatct aggcttttgt tttaacgccg gtgcgccagc agtagaggca tttattgaga      4800
         aagtcagccg tcgcagtaat ttcgaatttg gtcgcgcgcg gatgtttggc tgtgttggct      4860
         gggcgctgtg tgcctcgatt gtcggcatca tgttcaccat caataatcag tttgttttct      4920
         ggctgggctc tggctgtgca ctcatcctcg ccgttttact ctttttcgcc aaaacggatg      4980
         cgccctcttc tgccacggtt gccaatgcgg taggtgccaa ccattcggca tttagcctta      5040
         agctggcact ggaactgttc agacagccaa aactgtggtt tttgtcactg tatgttattg      5100
         gcgtttcctg cacctacgat gtttttgacc aacagtttgc taatttcttt acttcgttct      5160
         ttgctaccgg tgaacagggt acgcgggtat ttggctacgt aacgacaatg ggcgaattac      5220
         ttaacgcctc gattatgttc tttgcgccac tgatcattaa tcgcatcggt gggaaaaacg      5280
         ccctgctgct ggctggcact attatgtctg tacgtattat tggctcatcg ttcgccacct      5340
         cagcgctgga agtggttatt ctgaaaacgc tgcatatgtt tgaagtaccg ttcctgctgg      5400
         tgggctgctt taaatatatt accagccagt ttgaagtgcg tttttcagcg acgatttatc      5460
         tggtctgttt ctgcttcttt aagcaactgg cgatgatttt tatgtctgta ctggcgggca      5520
         atatgtatga aagcatcggt ttccagggcg cttatctggt gctgggtctg gtggcgctgg      5580
         gcttcacctt aatttccgtg ttcacgctta gcggccccgg cccgctttcc ctgctgcgtc      5640
         gtcaggtgaa tgaagtcgct taagcaatca atgtcggatg cggcgcgacg cttatccgac      5700
         caacatatca taacggagtg atcgcattga acatgccaat gaccgaaaga ataagagcag      5760
         gcaagctatt taccgatatg tgcgaaggct taccggaaaa aagacttcgt gggaaaacgt      5820
         taatgtatga gtttaatcac tcgcatccat cagaagttga aaaaagagaa agcctgatta      5880
         aagaaatgtt tgccacggta ggggaaaacg cctgggtaga accgcctgtc tatttctctt      5940
         acggttccaa catccatata ggccgcaatt tttatgcaaa tttcaattta accattgtcg      6000
         atgactacac ggtaacaatc ggtgataacg tactgattgc acccaacgtt actctttccg      6060
         ttacgggaca ccctgtacac catgaattga gaaaaaacgg cgagatgtac tcttttccga      6120
         taacgattgg caataacgtc tggatcggaa gtcatgtggt tattaatcca ggcgtcacca      6180
         tcggggataa ttctgttatt ggcgcgggta gtatcgtcac aaaagacatt ccaccaaacg      6240
         tcgtggcggc tggcgttcct tgtcgggtta ttcgcgaaat aaacgaccgg gataagcact      6300
         attatttcaa agattataaa gttgaatcgt cagtttaaat tataaaaatt gcctgatacg      6360
         ctgcgcttat caggcctaca agttcagcga tctacattag ccgcatccgg catgaacaaa      6420
         gcgcaggaac aagcgtcgca tcatgcctct ttgacccaca gctgcggaaa acgtactggt      6480
         gcaaaacgca gggttatgat catcagccca acgacgcaca gcgcatgaaa tgcccagtcc      6540
         atcaggtaat tgccgctgat actacgcagc acgccagaaa accacggggc aagcccggcg      6600
         atgataaaac cgattccctg cataaacgcc accagcttgc cagcaatagc cggttgcaca      6660
         gagtgatcga gcgccagcag caaacagagc ggaaacgcgc cgcccagacc taacccacac      6720
         accatcgccc acaataccgg caattgcatc ggcagccaga taaagccgca gaaccccacc      6780
         agttgtaaca ccagcgccag cattaacagt ttgcgccgat cctgatggcg agccatagca      6840
         ggcatcagca aagctcctgc ggcttgccca agcgtcatca atgccagtaa ggaaccgctg      6900
         tactgcgcgc tggcaccaat ctcaatatag aaagcgggta accaggcaat caggctggcg      6960
         taaccgccgt taatcagacc gaagtaaaca cccagcgtcc acgcgcgggg agtgaatacc      7020
         acgcgaaccg gagtggttgt tgtcttgtgg gaagaggcga cctcgcgggc gctttgccac      7080
         caccaggcaa agagcgcaac aacggcaggc agcgccacca ggcgagtgtt tgataccagg      7140
         tttcgctatg ttgaactaac cagggcgtta tggcggcacc aagcccaccg ccgcccatca      7200
         gagccgcgga ccacagcccc atcaccagtg gcgtgcgctg ctgaaaccgc cgtttaatca      7260
         ccgaagcatc accgcctgaa tgatgccgat ccccacccca ccaagcagtg cgctgctaag      7320
         cagcagcgca ctttgcgggt aaagctcacg catcaatgca ccgacggcaa tcagcaacag      7380
         actgatggcg acactgcgac gttcgctgac atgctgatga agccagcttc cggccagcgc      7440
         cagcccgccc atggtaacca ccggcagagc ggtcgac                               7477
    //

## Output file format

The output is a standard EMBOSS alignment file.

The results can be output in one of several styles by using the command-line qualifier -aformat xxx, where 'xxx' is replaced by the name of the required format. Some of the alignment formats can cope with an unlimited number of sequences, while others are only for pairs of sequences.

The available multiple alignment format names are: unknown, multiple, simple, fasta, msf, trace, srs

The available pairwise alignment format names are: pair, markx0, markx1, markx2, markx3, markx10, srspair, score

See: http://emboss.sf.net/docs/themes/AlignFormats.html for further information on alignment formats.

The output alignment is in simple format by default.

### Output files for usage example

### File: supermatcher.error

### File: eclac.supermatcher

    ########################################
    # Program: supermatcher
    # Rundate: Thu Jul 15 2004 12:00:00
    # Align_format: simple
    # Report_file: eclac.supermatcher
    ########################################

    #=======================================
    #
    # Aligned_sequences: 2
    # 1: ECLAC
    # 2: ECLAC
    # Matrix: EDNAFULL
    # Gap_penalty: 10.0
    # Extend_penalty: 3.0
    #
    # Length: 7477
    # Identity:    7477/7477 (100.0%)
    # Similarity:  7477/7477 (100.0%)
    # Gaps:           0/7477 ( 0.0%)
    # Score: 37385.0
    #
    #
    #=======================================

    ECLAC              1 gacaccatcgaatggcgcaaaacctttcgcggtatggcatgatagcgccc     50
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC              1 gacaccatcgaatggcgcaaaacctttcgcggtatggcatgatagcgccc     50

    ECLAC             51 ggaagagagtcaattcagggtggtgaatgtgaaaccagtaacgttatacg    100
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC             51 ggaagagagtcaattcagggtggtgaatgtgaaaccagtaacgttatacg    100

    ECLAC            101 atgtcgcagagtatgccggtgtctcttatcagaccgtttcccgcgtggtg    150
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC            101 atgtcgcagagtatgccggtgtctcttatcagaccgtttcccgcgtggtg    150

    ECLAC            151 aaccaggccagccacgtttctgcgaaaacgcgggaaaaagtggaagcggc    200
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC            151 aaccaggccagccacgtttctgcgaaaacgcgggaaaaagtggaagcggc    200

    ECLAC            201 gatggcggagctgaattacattcccaaccgcgtggcacaacaactggcgg    250
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC            201 gatggcggagctgaattacattcccaaccgcgtggcacaacaactggcgg    250

    ECLAC            251 gcaaacagtcgttgctgattggcgttgccacctccagtctggccctgcac    300
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC            251 gcaaacagtcgttgctgattggcgttgccacctccagtctggccctgcac    300

    ECLAC            301 gcgccgtcgcaaattgtcgcggcgattaaatctcgcgccgatcaactggg    350

      [Part of this file has been deleted for brevity]

    ECLACZ          2501 tgctgattacgaccgctcacgcgtggcagcatcaggggaaaaccttattt   2550
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           3787 tgctgattacgaccgctcacgcgtggcagcatcaggggaaaaccttattt   3836

    ECLACZ          2551 atcagccggaaaacctaccggattgatggtagtggtcaaatggcgattac   2600
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           3837 atcagccggaaaacctaccggattgatggtagtggtcaaatggcgattac   3886

    ECLACZ          2601 cgttgatgttgaagtggcgagcgatacaccgcatccggcgcggattggcc   2650
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           3887 cgttgatgttgaagtggcgagcgatacaccgcatccggcgcggattggcc   3936

    ECLACZ          2651 tgaactgccagctggcgcaggtagcagagcgggtaaactggctcggatta   2700
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           3937 tgaactgccagctggcgcaggtagcagagcgggtaaactggctcggatta   3986

    ECLACZ          2701 gggccgcaagaaaactatcccgaccgccttactgccgcctgttttgaccg   2750
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           3987 gggccgcaagaaaactatcccgaccgccttactgccgcctgttttgaccg   4036

    ECLACZ          2751 ctgggatctgccattgtcagacatgtataccccgtacgtcttcccgagcg   2800
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4037 ctgggatctgccattgtcagacatgtataccccgtacgtcttcccgagcg   4086

    ECLACZ          2801 aaaacggtctgcgctgcgggacgcgcgaattgaattatggcccacaccag   2850
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4087 aaaacggtctgcgctgcgggacgcgcgaattgaattatggcccacaccag   4136

    ECLACZ          2851 tggcgcggcgacttccagttcaacatcagccgctacagtcaacagcaact   2900
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4137 tggcgcggcgacttccagttcaacatcagccgctacagtcaacagcaact   4186

    ECLACZ          2901 gatggaaaccagccatcgccatctgctgcacgcggaagaaggcacatggc   2950
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4187 gatggaaaccagccatcgccatctgctgcacgcggaagaaggcacatggc   4236

    ECLACZ          2951 tgaatatcgacggtttccatatggggattggtggcgacgactcctggagc   3000
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4237 tgaatatcgacggtttccatatggggattggtggcgacgactcctggagc   4286

    ECLACZ          3001 ccgtcagtatcggcggaattccagctgagcgccggtcgctaccattacca   3050
                         ||||||||||||||||||||||||||||||||||||||||||||||||||
    ECLAC           4287 ccgtcagtatcggcggaattccagctgagcgccggtcgctaccattacca   4336

    ECLACZ          3051 gttggtctggtgtcaaaaataataataa   3078
                         ||||||||||||||||||||||||||||
    ECLAC           4337 gttggtctggtgtcaaaaataataataa   4364

    #---------------------------------------
    #---------------------------------------

The file 'supermatcher.error' will contain any errors that occured during the program. This may be that wordmatch could not find any matches hence no suitable start point is found for the smith-waterman calculation.

## Data files

For protein sequences EBLOSUM62 is used for the substitution matrix. For nucleotide sequence, EDNAMAT is used. Others can be specified.

EMBOSS data files are distributed with the application and stored in the standard EMBOSS data directory, which is defined by the EMBOSS environment variable EMBOSS_DATA.

To see the available EMBOSS data files, run:

    % embossdata -showall

To fetch one of the data files (for example 'Exxx.dat') into your current directory for you to inspect or modify, run:

    % embossdata -fetch -file Exxx.dat

Users can provide their own data files in their own directories. Project specific files can be put in the current directory, or for tidier directory listings in a subdirectory called ".embossdata". Files for all EMBOSS runs can be put in the user's home directory, or again in a subdirectory called ".embossdata".

The directories are searched in the following order:

- . (your current directory)
- .embossdata (under your current directory)
- ~/ (your home directory)
- ~/.embossdata

## Notes

The time this program takes to do an alignment depends very much on the word size. For short sequences a short word size (e.g. 4) can make it take a very long time. Large word sizes (e.g. 30) for sequences that are very similar give a very quick result. The default of 16 should give reasonable fast alignments.

Because it does a Smith & Waterman alignment (albeit in a narrow region around the diagonal shown to be the 'best' by a word match), this program can use huge amounts of memory if the sequences are large.

Because the alignment is made within a narrow area each side of the 'best' diagonal, if there are sufficient indels between the two sequences, then the path of the Smith & Waterman alignment can wander outside of this area. Making the width larger can avoid this problem, but you then use more memory.

The longer the sequences and the wider the specified alignment width, the more memory will be used.

If the program terminates due to lack of memory you can try the following:

Run the UNIX command 'limit' to see if your stack or memory usage have been limited and if so, run 'unlimit', (e.g.: '% unlimit stacksize').

## References

None.

## Warnings

None.

## Diagnostic Error Messages

None.

## Exit status

It always exits with a status of 0.

## Known bugs

None.

## See also

Program name | Description
--- | ---
matcher | Finds the best local alignments between two sequences
seqmatchall | Does an all-against-all comparison of a set of sequences
water | Smith-Waterman local alignment
wordmatch | Finds all exact matches of a given size between 2 sequences

## Author(s)

Ian Longden (il © sanger.ac.uk)
Sanger Institute, Wellcome Trust Genome Campus, Hinxton, Cambridge, CB10 1SA, UK.

## History

## Target users

This program is intended to be used by everyone and everything, from naive users to embedded scripts.

## Comments

None