=====================================
Building a new application controller
=====================================

Step 0.
Decide what version of the program you want to support and install the application. Check out the features, and decide what functionality you want to support. We'll look at wrapping the formatdb command from the Blast-2.2.20 package available from NCBI at: http://www.ncbi.nlm.nih.gov/BLAST/download.shtml.

caporaso@mentat ~> formatdb --help

For the sake of brevity, we'll support only the basic functionality: creating nucleic acid or protein blast databases in the default format, and with default names (i.e., named based on the names of the input file). 

So, we'll support the -i, -o, and -p options.

Step 1.
Define class variables including:
  _command: the command called to start the application
  _parameters: the parameters to be passed (we'll select a few that we're going to support)
  _input_handler: function describing how to convert a single parameter passed to the app controller object into input for the function
  _suppress_stdout: (if other than False)
  _suppress_stderr: (if other than False)

Step 2. 
Overwrite methods as necessary. Here we need to create a non-default input handler.


Now let's see how our new application controller works.
=======================================================

[~/code/formatdb_appc]|25> import minimal_formatdb
[~/code/formatdb_appc]|26> fdb = minimal_formatdb.MinimalFormatDb()
[~/code/formatdb_appc]|27> res = fdb('/Users/caporaso/data/test_alignments/10_seq.fasta')
[~/code/formatdb_appc]|28> res

# Change a parameter setting
[~/code/formatdb_appc]|31> fdb = minimal_formatdb.MinimalFormatDb()
[~/code/formatdb_appc]|32> fdb.Parameters['-p'].on('T')
[~/code/formatdb_appc]|35> fdb.Parameters['-p'].isOn()
[~/code/formatdb_appc]|36> fdb.Parameters['-p'].Value
[~/code/formatdb_appc]|37> str(fdb.Parameters['-p'])

# Run the appc and investigate the results
[~/code/formatdb_appc]|38> res = fdb('/Users/caporaso/data/test_alignments/10_seq.fasta')
[~/code/formatdb_appc]|39> res


# Clean up our mess
[~/code/formatdb_appc]|43> res = fdb('/Users/caporaso/data/test_alignments/10_seq.fasta')
[~/code/formatdb_appc]|44> ls /Users/caporaso/data/test_alignments/10_seq.fasta.phr
[~/code/formatdb_appc]|45> res.cleanUp()
[~/code/formatdb_appc]|46> ls /Users/caporaso/data/test_alignments/10_seq.fasta.phr


Tips and tricks:
One of the most useful features of application controller object when building and debugging is the HALT_EXEC parameter that can be passed to the constructor. This will cause the program to halt just before executing, and print the command. For example:

[~/code/formatdb_appc]|50> fdb = minimal_formatdb.MinimalFormatDb(HALT_EXEC=True)
[~/code/formatdb_appc]|51> res = fdb('/Users/caporaso/data/test_alignments/10_seq.fasta')

[Traceback omitted]

<type 'exceptions.AssertionError'>: Halted exec with command:
cd "/Users/caporaso/code/formatdb_appc/"; formatdb -o T -i "/Users/caporaso/data/test_alignments/10_seq.fasta" -p F > "/tmp/tmpBpMUXE0ksEhzIZA1SSbS.txt" 2> "/tmp/tmpSKc0PRhTl47SZfkxY0g1.txt"

[~/code/formatdb_appc]|52> ^Z
[1]+  Stopped                 ipython

caporaso@mentat formatdb_appc> cd "/Users/caporaso/code/formatdb_appc/"; formatdb -o T -i "/Users/caporaso/data/test_alignments/10_seq.fasta" -p F