| jaspscan

## Wiki

The master copies of EMBOSS documentation are available at http://emboss.open-bio.org/wiki/Appdocs on the EMBOSS Wiki.

Please help by correcting and extending the Wiki pages.

## Function

Scans DNA sequences for transcription factors

## Description

jaspscan scans one or more DNA sequences for transcription factor binding sites from the JASPAR database. Matches are searched for using fast sequence word-matching, optionally allowing mismatches. Because the binding sites are so small, there will be many spurious (false positive) matches.

An output file is written with information on the matches, including sequence ID and accession number, the start and end positions of the match in an input sequence and the sequence of the region where a match has been found. Binding factor information, where available, is given at the end of the matches for each matching entry.

## Usage

Here is a sample session with jaspscan

    % jaspscan -both
    Scans DNA sequences for transcription factors
    Input nucleotide sequence(s): tembl:m23100
    Jaspar matrix set
             C : Core
             F : Fam
             P : Phylofacts
             N : CNE
             O : POLII
             S : SPLICE
    Matrix set [C]:
    Comma separated matrix list [all]: ma0079
    Threshold percentage [80.0]:
    Output report [m23100.jaspscan]:

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

## Command line arguments

    Scans DNA sequences for transcription factors
    Version: EMBOSS:6.2.0

       Standard (Mandatory) qualifiers:
      [-sequence]          seqall     Nucleotide sequence(s) filename and optional
                                      format, or reference (input USA)
       -menu               menu       [C] Matrix set (Values: C (Core); F (Fam); P
                                      (Phylofacts); N (CNE); O (POLII); S
                                      (SPLICE))
       -matrices           string     [all] The name 'all' reads in all matrix
                                      files from the selected
                                      JASPAR matrix set. You can specify
                                      individual matrices by giving
                                      their names with commas between then, such
                                      as:
                                      'ma0001,ma0015'.
                                      The case of the names is not important. You
                                      can specify a file of
                                      matrix names to read in by giving the name
                                      of the file holding the
                                      matrix names with a '@' character in front
                                      of it, for example,
                                      '@matrix.list'.
                                      Blank lines and lines starting with a hash
                                      character or '!' are ignored and all other
                                      lines are concatenated together with a comma
                                      character ',' and then treated as the list
                                      of enzymes to search
                                      for.
                                      An example of a file of matrix names is:
                                      ! my matrices
                                      ma0001, ma0002
                                      ! other matrices
                                      ma0010
                                      ma0032
                                      ma0053 (Any string)
       -threshold          float      [80.0] If the matrix score is greater than
                                      or equal to this percentage
                                      then a hit will be reported (Any numeric
                                      value)
      [-outfile]           report     [*.jaspscan] Output report file name

       Additional (Optional) qualifiers:
       -exclude            string     The names of any matrices to exclude from
                                      the 'matrices'
                                      list. Matrices are specified in the same way
                                      as for the
                                      selection list. (Any string)
       -both               boolean    [N] If set then both the forward and reverse
                                      strands are searched

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

       "-sequence" 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

       "-outfile" associated qualifiers
       -rformat2           string     Report format
       -rname2             string     Base file name
       -rextension2        string     File name extension
       -rdirectory2        string     Output directory
       -raccshow2          boolean    Show accession number in the report
       -rdesshow2          boolean    Show description in the report
       -rscoreshow2        boolean    Show the score in the report
       -rstrandshow2       boolean    Show the nucleotide strand in the report
       -rusashow2          boolean    Show the full USA in the report
       -rmaxall2           integer    Maximum total hits to report
       -rmaxseq2           integer    Maximum hits to report for one sequence

       General qualifiers:
       -auto               boolean    Turn off prompts
       -stdout             boolean    Write first file to standard output
       -filter             boolean    Read first file from standard input, write
                                      first file to 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 and exit. 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 dying program messages
       -version            boolean    Report version number and exit

Qualifier | Type | Description | Allowed values | Default
--- | --- | --- | --- | ---
Standard (Mandatory) qualifiers
[-sequence] (Parameter 1) | seqall | Nucleotide sequence(s) filename and optional format, or reference (input USA) | Readable sequence(s) | Required

-menu

list

Matrix set

C | (Core)
F | (Fam)
P | (Phylofacts)
N | (CNE)
O | (POLII)
S | (SPLICE)

C

-matrices

string

The name 'all' reads in all matrix files from the selected JASPAR matrix set. You can specify individual matrices by giving their names with commas between then, such as: 'ma0001,ma0015'. The case of the names is not important. You can specify a file of matrix names to read in by giving the name of the file holding the matrix names with a '@' character in front of it, for example, '@matrix.list'. Blank lines and lines starting with a hash character or '!' are ignored and all other lines are concatenated together with a comma character ',' and then treated as the list of enzymes to search for. An example of a file of matrix names is: ! my matrices ma0001, ma0002 ! other matrices ma0010 ma0032 ma0053

Any string

all

-threshold | float | If the matrix score is greater than or equal to this percentage then a hit will be reported | Any numeric value | 80.0
[-outfile] (Parameter 2) | report | Output report file name | Report output file | <*>.jaspscan
Additional (Optional) qualifiers
-exclude | string | The names of any matrices to exclude from the 'matrices' list. Matrices are specified in the same way as for the selection list. | Any string |
-both | boolean | If set then both the forward and reverse strands are searched | Boolean value Yes/No | No
Advanced (Unprompted) qualifiers
(none)
Associated qualifiers
"-sequence" associated seqall qualifiers
-sbegin1 -sbegin_sequence | integer | Start of each sequence to be used | Any integer value | 0
-send1 -send_sequence | integer | End of each sequence to be used | Any integer value | 0
-sreverse1 -sreverse_sequence | boolean | Reverse (if DNA) | Boolean value Yes/No | N
-sask1 -sask_sequence | boolean | Ask for begin/end/reverse | Boolean value Yes/No | N
-snucleotide1 -snucleotide_sequence | boolean | Sequence is nucleotide | Boolean value Yes/No | N
-sprotein1 -sprotein_sequence | boolean | Sequence is protein | Boolean value Yes/No | N
-slower1 -slower_sequence | boolean | Make lower case | Boolean value Yes/No | N
-supper1 -supper_sequence | boolean | Make upper case | Boolean value Yes/No | N
-sformat1 -sformat_sequence | string | Input sequence format | Any string |
-sdbname1 -sdbname_sequence | string | Database name | Any string |
-sid1 -sid_sequence | string | Entryname | Any string |
-ufo1 -ufo_sequence | string | UFO features | Any string |
-fformat1 -fformat_sequence | string | Features format | Any string |
-fopenfile1 -fopenfile_sequence | string | Features file name | Any string |
"-outfile" associated report qualifiers
-rformat2 -rformat_outfile | string | Report format | Any string | seqtable
-rname2 -rname_outfile | string | Base file name | Any string |
-rextension2 -rextension_outfile | string | File name extension | Any string |
-rdirectory2 -rdirectory_outfile | string | Output directory | Any string |
-raccshow2 -raccshow_outfile | boolean | Show accession number in the report | Boolean value Yes/No | N
-rdesshow2 -rdesshow_outfile | boolean | Show description in the report | Boolean value Yes/No | N
-rscoreshow2 -rscoreshow_outfile | boolean | Show the score in the report | Boolean value Yes/No | Y
-rstrandshow2 -rstrandshow_outfile | boolean | Show the nucleotide strand in the report | Boolean value Yes/No | Y
-rusashow2 -rusashow_outfile | boolean | Show the full USA in the report | Boolean value Yes/No | N
-rmaxall2 -rmaxall_outfile | integer | Maximum total hits to report | Any integer value | 0
-rmaxseq2 -rmaxseq_outfile | integer | Maximum hits to report for one sequence | Any integer value | 0
General qualifiers
-auto | boolean | Turn off prompts | Boolean value Yes/No | N
-stdout | boolean | Write first file to standard output | Boolean value Yes/No | N
-filter | boolean | Read first file from standard input, write first file to standard output | Boolean value Yes/No | N
-options | boolean | Prompt for standard and additional values | Boolean value Yes/No | N
-debug | boolean | Write debug output to program.dbg | Boolean value Yes/No | N
-verbose | boolean | Report some/full command line options | Boolean value Yes/No | Y
-help | boolean | Report command line options and exit. More information on associated and general qualifiers can be found with -help -verbose | Boolean value Yes/No | N
-warning | boolean | Report warnings | Boolean value Yes/No | Y
-error | boolean | Report errors | Boolean value Yes/No | Y
-fatal | boolean | Report fatal errors | Boolean value Yes/No | Y
-die | boolean | Report dying program messages | Boolean value Yes/No | Y
-version | boolean | Report version number and exit | Boolean value Yes/No | N

## Input file format

jaspscan reads any normal sequence USAs.

### Input files for usage example

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

### Database entry: tembl:m23100

    ID   M23100; SV 1; linear; genomic DNA; STD; HUM; 2085 BP.
    XX
    AC   M23100; M32822;
    XX
    DT   06-JUL-1989 (Rel. 20, Created)
    DT   14-NOV-2006 (Rel. 89, Last updated, Version 10)
    XX
    DE   Human insulin receptor (INSR) gene, exon 1, clones lambda-hINSR-(1-13).
    XX
    KW   Alu repeat; insulin receptor.
    XX
    OS   Homo sapiens (human)
    OC   Eukaryota; Metazoa; Chordata; Craniata; Vertebrata; Euteleostomi; Mammalia;
    OC   Eutheria; Euarchontoglires; Primates; Haplorrhini; Catarrhini; Hominidae;
    OC   Homo.
    XX
    RN   [1]
    RP   1-1933
    RX   DOI; 10.1073/pnas.86.1.114.
    RX   PUBMED; 2911561.
    RA   Seino S., Seino M., Nishi S., Bell G.I.;
    RT   "Structure of the human insulin receptor gene and characterization of its
    RT   promoter";
    RL   Proc. Natl. Acad. Sci. U.S.A. 86(1):114-118(1989).
    XX
    RN   [2]
    RP   1-2085
    RX   PUBMED; 2210055.
    RA   Seino S., Seino M., Bell G.I.;
    RT   "Human insulin-receptor gene. Partial sequence and amplification of exons
    RT   by polymerase chain reaction";
    RL   Diabetes 39(1):123-128(1990).
    XX
    DR   EMBL-JOIN; M32972.
    DR   TRANSFAC; R03068; HS$INSR_01.
    XX
    CC   Draft entry and computer-readable sequence for [1] kindly submitted
    CC   by G.Bell, 14-MAR-1990.
    XX
    FH   Key             Location/Qualifiers
    FH
    FT   source          1..2085
    FT                   /organism="Homo sapiens"
    FT                   /map="19p13.3-p13.2"
    FT                   /mol_type="genomic DNA"
    FT                   /dev_stage="foetus"
    FT                   /tissue_type="liver"
    FT                   /db_xref="taxon:9606"
    FT   repeat_region   <1..76
    FT                   /rpt_family="Alu"

      [Part of this file has been deleted for brevity]

    FT                   /number=1
    FT                   /note="alternative exon 1; G00-119-352"
    FT   exon            1548..1923
    FT                   /gene="INSR"
    FT                   /number=1
    FT                   /note="alternative exon 1; G00-119-352"
    FT   sig_peptide     1824..1904
    FT                   /gene="INSR"
    FT                   /note="G00-119-352"
    FT   intron          1924..>2085
    FT                   /gene="INSR"
    FT                   /number=1
    FT                   /note="G00-119-352"
    XX
    SQ   Sequence 2085 BP; 417 A; 631 C; 702 G; 335 T; 0 other;
         agatctggcc attgcactcc agcctgggca acagagaaaa actccatcta aaaaaaaaaa        60
         aaaaaaaaaa aaaaaacaga gagagagaga gagagagaga gaaggaaacg gaactggggg       120
         gaggatttgc aaaaatatgg ttagggatgg cacttcagag atgaagccat cctggagtgt       180
         tacgggcaag ggaaatgctg gggcaaagcc ccagaggcag gaataggttt ggcctgttgc       240
         atgaacagtg ggtccagctc ctagcaaact gtttattgaa tgaaagaaga atgaatgcct       300
         tgggtctagg gttgtgctgg gcgctttctt aagttttctt tcccgggtac ctccccagaa       360
         ctggcatgca ggtattatta aacccattac acaagtgaaa ctggcccaga gacagaaaag       420
         tccctggtcc aagaccacac aggagtgagg ggtggaggaa ccctcctccc attgagttct       480
         ggctttccta tactgaaagc cccttcctct cctgcagtaa ggtaggtgga accgctgtcc       540
         cgccttgttg gtgaatgtcg ttgctagact tcagacacat acaggctggt ctgctgaaaa       600
         tcagagatgt ccacctgcgc cctattcgag gtctccggcg tcttctttgg cgtcgtcttt       660
         gccctttcag aagcgtctgc acatttttcc aggtgtcatt tctccaactt gaacacaggg       720
         agcgcactgg gcacgcgggc acgtggctgt ccccaggggc ctggcttggg tctcgcccct       780
         gggccggggc gcacgcgcgg gcgggacatc tgggggcgcc cacgcgctct gggacgagtg       840
         tcgctggcca ggcccggact gaggaaaggc gagtgagaca ctactcgcct ggggtgcaaa       900
         atttaaggga gtgaaaaaaa aaaaaaaaga aagaaaccaa aaccacctcg agtcaccaaa       960
         ataaacattt taatgcagta ttttttaaaa aatcaacagg aatcctccaa agcccactat      1020
         gaacaaaata gcaaaatggt agagaaagga tctgtgccgc tgcgtcgggc ctgtggggcg      1080
         cctccggggg tctgaaactg gaggagactc ggggctgtag ggcgcgcgga tctggggcgc      1140
         gccctcggtc ccggcgcgcc cagggcctcc cgcgcggggc ccggcacagg gaggcgggga      1200
         ggcgggcggg gcggggcggg accgggcggc acctccctcc cctgcaagct ttccctccct      1260
         ctcctgggcc tctcccgggc gcagagtccc ttcctaggcc agatccgcgc cgccttttcc      1320
         cgcggcccgc acggggccca gctgacgggc cgcgttgttt acgggccgga gcagccctct      1380
         ctcccgccgc ccgcccgcca cccgccagcc caggtgcccg cccgccagtc agctagtccg      1440
         tcggtccgcg cgtccctctg tcccggagcc cgcagatcgc gacccagagc gcgcggggcc      1500
         gagagccgag agacagtccc gggcgcagcg cggagctccg ggccccgaga tcctgggacg      1560
         gggcccgggc cgcagcggcc ggggggtcgg ggccaccacc gcaagggcct ccgctcagta      1620
         tttgtagctg gcgaagccgc gcgcgccctt cccggggctg cctctgggcc ctccccggca      1680
         ggggggctgc ggcccgcggg tcgcgggcgt ggaagagaag gacgcgcggc ccccagcgcc      1740
         tcttgggtgg ccgcctcgga gcatgacccc cgcgggccag cgccgcgcgc tctgatccga      1800
         ggagaccccg cgctcccgca gccatgggca ccgggggccg gcggggagcg gcggccgcgc      1860
         cgctgctggt ggcggtggcc gcgctgctac tgggcgccgc gggccacctg taccccggag      1920
         agggtgagtc tgggggcgcg ggcgtgggcg gggagcgccg cgatggggag aggaccccac      1980
         ccaagccaaa atcgatcccc cgcttgtgga ctgagaaccc tccccagggg cggggggcgg      2040
         tggccaggac ggtagctcct gcatcgcgta gggggagcgg gaagc                      2085
    //

## Output file format

jaspscan outputs a report format file.

### Output files for usage example

### File: m23100.jaspscan

    ########################################
    # Program: jaspscan
    # Rundate: Fri 15 Jan 2010 12:00:00
    # Commandline: jaspscan
    #    -both
    #    -sequence tembl:m23100
    #    -matrices ma0079
    # Report_format: seqtable
    # Report_file: m23100.jaspscan
    ########################################

    #=======================================
    #
    # Sequence: M23100     from: 1   to: 2085
    # HitCount: 18
    #
    # Database scanned: JASPAR_CORE  Threshold: 80.000
    #
    #=======================================

      Start     End  Strand Score_Percent ID     Name   Species      Class           Supergroup Protein_Seq Experiment Source_PMID Info_Content Closest_Jaspar Closest_Transfac MCS_Score Built_From Sequence
        117     126       +        82.143 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          gggggaggat
       1191    1200       +        89.286 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          gaggcgggga
       1203    1212       +        83.929 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          cgggcggggc
       1208    1217       +        89.286 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggcggggc
       1213    1222       +        80.357 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggcgggac
       1704    1713       +        82.143 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          cgggcgtgga
       1838    1847       +        82.143 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ccggcgggga
       1933    1942       +        82.143 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggcgcggg
       1945    1954       +        89.286 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          tgggcgggga
       2027    2036       +        89.286 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggcggggg
       2032    2041       +        87.500 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggggcggt
       2034    2043       +        82.143 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggcggtgg
       1252    1261       -        80.357 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          gagggaggga
       1304    1313       -        80.357 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          gcggcgcgga
       1805    1814       -        80.357 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          agcgcggggt
       1974    1983       -        89.286 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          tgggtggggt
       2016    2025       -        80.357 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          ggggagggtt
       2017    2026       -        87.500 MA0079 SP1    Homo sapiens ZN-FINGER, C2H2 vertebrate P08047      SELEX      2192357            9.719 .              .                        . .          tggggagggt

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

## Data files

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

The EMBOSS JASPAR transcription site files are stored in directory 'data/JASPAR/*' under the EMBOSS installation directory.

These files must first be set up using the program 'jaspextract'. Running 'jaspextract' may be the job of your system manager.

The data files are stored in the JASPAR directory of the standard EMBOSS data directory. The subdirectory names are:

- JASPAR_CORE Core files
- JASPAR_FAM Family files
- JASPAR_PHYLOFACT Phylogeny files

The column information is described on the JASPAR home page http://jaspar.genereg.net/

## Notes

None.

## References

1. DNA binding sites: representation and discovery Bioinformatics. 2000 Jan;16(1):16-23
2. Applied bioinformatics for the identification of regulatory elements Nat Rev Genet. 2004 Apr;5(4):276-87

## Warnings

None.

## Diagnostic Error Messages

None.

## Exit status

It always exits with status 0.

## Known bugs

None.

## See also

Program name | Description
--- | ---
tfscan | Identify transcription factor binding sites in DNA sequences

## Author(s)

Alan Bleasby (ajb © ebi.ac.uk)
European Bioinformatics Institute, Wellcome Trust Genome Campus, Hinxton, Cambridge CB10 1SD, UK

## History

Completed 23rd July 2007

## Target users

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

## Comments

None