= Python Embedded into Mussa =

This quite a new feature, and is only available as of [493].

There are two ways to interact with mussa via python. One is via the embedded interpreter, the other by a python extension module. The advantage to the embedded interpreter is that it is possible to launch a Mussa GUI window to view an analysis that was created via python. The advantage to the extension module is that it doesn't replace your interpreter and that its easier to run scripts from the shell. (There's also the problem that the embedded interpreter probably wont work under Microsoft Windows).

== Building Python Enabled Mussa ==

Patches [493] and [494] currently force building the python version. Soon I'll add a CMake configuration variable to make building this optional.

The result of this is a mussa executable which has a python interpreter embedded in it.

[http://mussagl-universal-b493.dmg OS X Universal Binary of Mussa with Python]

There are some situations where Mussa will generate a bunch of QObject:moveToThread warnings, this appears to be due to some detail of how Qt's icon management works, and it doesn't seem to cause problems and also there's nothing I can do about those warning messages.

=== Running ===

To run the embedded version of mussa you will need to launch mussa from the command line.

{{{ mussagl --python }}}

Though on OS X the executable is buried deep within the mussa application folder.

{{{ ./mussagl.app/Contents/MacOS/mussagl --python }}}

The interpreter will be preloaded with the mussa and mussaqui modules.

== Building Mussa Python Extension ==

Also the current build system produces an extension module which can be imported into a currently running python interpreter. Though I'm not currently shipping a binary that includes it.

I hope there's some way of building a python binary egg from this CMake generated module.

For this, if you have the python module, it just needs to be placed on your python path. and then

{{{
$ python
>>> import mussa
}}}

should work.

== Using Mussa from Python ==

To actually use Mussa from python.

The following code will construct a three-way mussa analysis, and run it with a threshold of 8 base-pairs matching in 10 base-pair window.

(Sometime soon I'll try to fix .add_sequence() to also take strings)

{{{
  s1 = mussa.Sequence("A"*10)
  s2 = mussa.Sequence("GG"+"A"*8+"GG")
  s3 = mussa.Sequence("T"*10)
  m = mussa.Mussa()
  m.window = 10
  m.threshold = 8
  m.add_sequence(s1)
  m.add_sequence(s2)
  m.add_sequence(s3)
  m.analyze()
}}}

If you're running the embedded version of mussa python, you can view that analysis with

{{{
  mussaqui.MussaWindow(m)
}}}

Since this functionality is so new, the window doesn't necessarily render with all the paths displayed on it, so you'll need to change the threshold in order to update the display.

Also since the GUI and interpreter are implemented in separate threads changing the mussa analysis while the GUI is viewing it is not safe.

Alternatively if one wants to examine the results of running a mussa analysis...
{{{ paths = m.paths() }}}
will return an object that holds the Nway Paths.

From there, you can do {{{ len(paths) }}} to see how many paths were found. 

The interface to this part of the code is a bit clunky so actually viewing the nway offsets are a bit clunky.

{{{
conserved_paths = [ x for x in paths.pathz] # (pathz is only available as an iterable)
}}}

Conserved paths have 3 useful variables, a score, a window size, and the indices into the sequences. Unfortunately the indices are also only available as an interable.

{{{
print [ x for x in conserved_paths[0].track_indices
}}}

Negative values indicate that the match is to the reverse strand, most likely the absolute value represents the far left edge of the match.