act_start_chapter.sgml

<CHAPTER ID="START">
  <TITLE>Starting &prog;</TITLE>

  <SECT1 ID="COMPARISON-RUN">
    <TITLE>Running a Comparison</TITLE>
    <PARA>
Before running &prog; you will need to obtain a comparison file. 
&prog; supports three different comparison file formats:
    </PARA>
    <ITEMIZEDLIST>
      <LISTITEM>
        <FORMALPARA>
          <TITLE>The output of <ULINK
          URL="http://www.ncbi.nlm.nih.gov/BLAST/">BLAST
            </ULINK> version 2.2.2 or better</TITLE>
          <PARA>
The <COMMAND>blastall</COMMAND> command must be run with the <COMMAND>-m
8</COMMAND> flag which generates one line of information per HSP.
          </PARA>
        </FORMALPARA>
      </LISTITEM>
      <LISTITEM>
        <FORMALPARA>
          <TITLE>MEGABLAST output</TITLE>
          <PARA>
ACT can also read the output of <ULINK
URL="http://www.ncbi.nlm.nih.gov/BLAST/bl2seq/megablast.html">MEGABLAST</ULINK>,
which is part of the blast distribution.
          </PARA>
        </FORMALPARA>
      </LISTITEM>
      <LISTITEM>
        <FORMALPARA>
          <TITLE>MSPcrunch output</TITLE>
          <PARA>
<ULINK URL="http://www.cgr.ki.se/cgr/groups/sonnhammer/MSPcrunch.html"
TYPE="external">MSPcrunch</ULINK> is program for UNIX and GNU/Linux systems
which can post-process <ULINK
URL="http://www.ncbi.nlm.nih.gov/BLAST/">BLAST</ULINK> version 1 output into
an easier to read format.  MSPcrunch much be run with the
<LITERAL>-d</LITERAL> flag.
          </PARA>
        </FORMALPARA>
      </LISTITEM>
    </ITEMIZEDLIST>

    <SECT2 ID="COMPARISON-BIG-BLAST">
      <TITLE><COMMAND>big_blast.pl</COMMAND></TITLE>
      <PARA>
At the Sanger Centre we generally use a perl script called <ULINK
URL="ftp://ftp.sanger.ac.uk/pub/pathogens/software/artemis/extra/big_blast.pl"
TYPE="external"><LITERAL>big_blast.pl</LITERAL></ULINK> to run blast and
generate a file of results in MSPcrunch format.  To run this script you will
need to install a copy of the Pathogen Sequencing Unit <ULINK
URL="ftp://ftp.sanger.ac.uk/pub/pathogens/software/artemis/extra/zoo_modules.tar.gz"
TYPE="external">internal perl modules</ULINK>.  <ULINK
URL="ftp://ftp.sanger.ac.uk/pub/pathogens/software/artemis/extra/big_blast.pl"
TYPE="external"><LITERAL>big_blast.pl</LITERAL></ULINK> can also be used to
process blast results after the fact with a command line like this:
      </PARA>

      <PARA>
        <COMMAND>
big_blast.pl blast_results.out
        </COMMAND>
      </PARA>
      <PARA>
Note that big_blast.pl has only been tested on UNIX and GNU/Linux machines.
      </PARA>
    </SECT2>

    <SECT2 ID="COMPARISON-FILE-FORMAT">
      <TITLE>The MSPcrunch Comparison File Format</TITLE>
      <PARA>
Here is an example input file file generated by <LITERAL>MSPcrunch
-d</LITERAL>.
        <SYNOPSIS>
1399 97.00 940 2539 sequence1.dna 1 1596 AF140550.seq
1033 93.00 9041 10501 sequence1.dna 9420 10880 AF140550.seq
828 95.00 6823 7890 sequence1.dna 7211 8276 AF140550.seq
773 94.00 2837 3841 sequence1.dna 2338 3342 AF140550.seq
        </SYNOPSIS>
      </PARA>
      <PARA>
The columns have the following meanings (in order): score, percent identity,
match start in the query sequence, match end in the query sequence, query
sequence name, subject sequence start, subject sequence end, subject sequence
name.
      </PARA>
      <PARA>
The columns are separated by spaces.
      </PARA>
    </SECT2>
  </SECT1>

  <SECT1 ID="RUNNINGUNIX">
    <TITLE>Running &prog; on UNIX and GNU/Linux Systems</TITLE>
    <PARA>
On Unix and GNU/Linux the easiest way to run the program is to run the script
called <COMMAND>act</COMMAND> in the &prog; installation directory (see <XREF
LINKEND="INSTALLATION">) like this:
    </PARA>

    <PARA>
      <COMMAND>~/act/act</COMMAND>
    </PARA>

    <PARA>
If all goes well you will be presented with a small window with one menu (the
File menu).  See <XREF LINKEND="LAUNCH-WINDOW"> for a description of this
window.
    </PARA>

    <PARA>
Alternatively you start &prog; with the names of two sequence/EMBL/GENBANK
files and a file containing the comparison data eg:
    </PARA>

    <PARA>
      <COMMAND>
~/act/act sequence1 blast_output.crunch sequence2
      </COMMAND>
    </PARA>

    <PARA>
If you have more than two sequences (there is no upper limit) they should be
listed on the command line separated by the corresponding comparison file:
    </PARA>

    <PARA> 
      <COMMAND>
~/act/act sequence1 seq2_v_seq1.crunch sequence2 seq3_v_seq2.crunch sequence3 
      </COMMAND>
    </PARA>

    <PARA>
See <XREF LINKEND="UNIXARGS"> for a list of the other possible command line
arguments.
    </PARA>

    <PARA>
Here is an alternative way to run &prog; if the <COMMAND>act</COMMAND> script
doesn't work for you:
    </PARA>

    <PARA>
      <COMMAND>
cd ~/act
      </COMMAND>
    </PARA>

    <PARA>
      <COMMAND>
java -Dartemis.environment=UNIX Dad
      </COMMAND>
    </PARA>
  </SECT1>

&unixargs;

  <SECT1 ID="RUNNINGMAC">
    <TITLE>Running &prog; on Macintosh Systems</TITLE>
    <PARA>
On Macintosh machines &prog; can be started by double clicking on the ACT
icon.
    </PARA>
  </SECT1>

  <SECT1 ID="RUNNINGPC">
    <TITLE>Running &prog; on Windows Systems</TITLE>
    <PARA>
On systems with Java 1.2 (AKA Java 2) or better installed &prog; can be
started by double clicking on the act.jar icon.
    </PARA>
  </SECT1>

  <SECT1 ID="LAUNCH-WINDOW">
    <TITLE>The &prog; Launch Window</TITLE>
    <PARA>
This is the first window that opens when you start &prog;.
    </PARA>

    <SECT2 ID="LAUNCH-WINDOW-FILE-MENU">
      <TITLE>The File Menu</TITLE>
      <SECT3 ID="LAUNCH-WINDOW-FILE-MENU-OPEN">
        <TITLE>Open ...</TITLE>
        <PARA>
If you select this menu item a file requester will be displayed which allows
you to open the sequence files and the comparison files.  If the files you
select are read successfully, a new window will open, which shows the
sequences and the comparison.  See <XREF LINKEND="MAINWINDOW-CHAPTER"> to find
out how to use the main window.  The comparison file is described in <XREF
LINKEND="COMPARISON-FILE-FORMAT">.
        </PARA>
        <PARA>
The "more files ..." button expands the window so that more sequence and
comparison files can be read.
        </PARA>
      </SECT3>

      <SECT3 ID="LAUNCH-WINDOW-FILE-MENU-QUIT">
        <TITLE>Quit</TITLE>
        <PARA>
This menu item will close all windows and then exit the program
        </PARA>
      </SECT3>
    </SECT2>

&options-menu;
  </SECT1>
</CHAPTER>