Skip to content

Commit

Permalink
work on documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
mjoppich committed Mar 16, 2017
1 parent a23578c commit 1ef2266
Show file tree
Hide file tree
Showing 7 changed files with 425 additions and 30 deletions.
305 changes: 305 additions & 0 deletions doc/biogui_idea.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,305 @@
.. _bioGUI_working_mechanism :

************************
bioGUI Working mechanism
************************

*bioGUI* heavily relies on the philosophy that everything is a network.
Especially templates are seen as network, both in their visual description but most importantly also in the execution model.

Install modules
================

*bioGUI* install modules are designed to make the regular user's life as easy as possible.
Originally created for WSL, so pure Windows users can also easily install their needed software without the need to care about dependencies, the idea of the *bioGUI* repository evolved.
Install modules are more than just templates, because they install the actual software onto the user's system, while customizing the *bioGUI* template for this application.
All install modules are regular shell scripts, that are called with fixed parameters.

In general, *install modules* can be divided into two parts:

#. installing the software and its dependencies
#. submitting the *bioGUI* template

For the first part, first the command line arguments are collected and saved.
The order of the command line arguments is specified as

#. installation directory (PROGDIR)
#. **sudo** password (if not supplied, installing dependencies is allowed to fail)
#. [0, 1] for adding software binary to $PATH.
#. IP to send template to
#. PORT to send template to

A typical template is then structured as follows:

.. code:: bash
#! Install hisat2-2.0.5
The text after the shebang is shown as title in the *Install template Module*.

.. code:: bash
echo "Dependencies: unzip"
if [ ! "$2" = "" ]; then
echo "Installing dependencies"
echo $2 | sudo -S apt-get update
echo $2 | sudo -S apt-get -y install unzip
else
echo "No sudo password, not installing dependencies"
fi
If a **sudo** password is supplied, dependencies are installed. This must be compatible with Ubuntu's aptitude, as this is what WSL runs on.
Any developer is free to also support Mac OS and *brew*, for instance.

.. code:: bash
## set all variables
PROG=hisat2-2.0.5
PROGDIR=$1
if [ -z "${PROGDIR}" ]; then
PROGDIR=~/bioGUI/progs/
fi
PROGDIRESC=$(echo $PROGDIR | sed 's/ /\\ /g')
## create progdir
mkdir -p "$PROGDIR"
Next some variables need to be set up. It showed of great benefit to create a $PROG variable containing the application and version.
The $PROGDIR variable contains the installation path, which is also checked to exist.
For several reasons it is also a good idea to have an escaped version of the install path by hand.

.. code:: bash
#download and unzip
if [ ! -f "$PROGDIR/$PROG.zip" ]; then
wget ftp://ftp.ccb.jhu.edu/pub/infphilo/hisat2/downloads/hisat2-2.0.5-source.zip -O "$PROGDIR/$PROG.zip"
fi
if [ ! -d "$PROGDIR/$PROG" ]; then
cd "$PROGDIR"
unzip $PROG.zip -d "$PROGDIR/"
fi
Before actually installing the program, make sure to download and unzip/untar the application source code.
For reasons of parsimony, this is only done when the expected file or folder does not exist.

.. code:: bash
#install prog
cd "$PROGDIR/$PROG"
make
if [ $# -gt 2 ]; then
if [ "$3" = "1" ]; then
if ! grep -q "$PROGDIRESC/$PROG" ~/.bashrc; then
echo "export PATH=\"$PROGDIRESC/$PROG:\$PATH\" " >> ~/.bashrc;
fi
fi
fi
After downloading and unzipping, the application can be built in the target directory.
Finally, if wanted, the path to the application's executable is added to the $PATH variable.

.. code:: bash
#now fix spaces in path
perl -pi -e 's/my \$align_prog_s= File::Spec->catpath\(\$vol\,\$script_path\,\$align_bin_s\);/my \$align_prog_s= "\\\"".File::Spec->catpath(\$vol,\$script_path,\$align_bin_s).\"\\\"\";/' hisat2
perl -pi -e 's/my \$align_prog_l= File::Spec->catpath\(\$vol\,\$script_path\,\$align_bin_l\);/my \$align_prog_l= "\\\"".File::Spec->catpath(\$vol,\$script_path,\$align_bin_l).\"\\\"\";/' hisat2
Certain programs may need some fixes to work properly on Mac OS, Linux or WSL.
This is the place where such fixes could go.

Finally we can send the template to *bioGUI*, if an IP address and port have been specified:

.. code:: bash
if [ $# -eq 5 ]; then
IP=$4
PORT=$5
nc $IP $PORT << EOF
<template description="hisat2 2.0.5 aligner" title="hisat2 2.0.5">
...
<const id="bindir">${PROGDIR}/${PROG}/</const>
...
<execute program="hisat2" param="\${cl}" location="\${bindir}" exec="hisat2" wsl="WSLsel">
<output type="COUT" color="green" to="outputstream1" />
<output type="CERR" color="red" to="outputstream2" />
</execute>
</template>
EOF
fi
Make sure to use ``nc`` to send the content, as this will not work on Mac OS otherwise.
In order to customize the template inbetween the ``EOF``, bash variables to be replaced must be written as ``${var-name}``.
This conflicts with how *bioGUI* expects variables. Therefore make sure to escape the backslaash where you want to access variables in the *bioGUI* template!
bioGUI Templates
================
*bioGUI* templates consist of two parts: the ``<window>``-part which defines the visual appearance and the ``<execute>``-part which defines how the command line arguments of an application are assembled from the graphical input elements.
.. _biogui_visual_model:
Visual Model of Templates
=========================
Layouts
-------
There exist three different layouts in *bioGUI*:
#. horizontal
#. vertical
#. grid
Layouts may have either visual components as child, or further layouts.
However a visual component may only have one layout child and this must be the first child.
For instance, the *cols* attribute for the *grid* layout tells how many columns are needed.
If only one attribute is specified, the other attribute is calculated from the number of children and the given attribute.
Layout Components
^^^^^^^^^^^^^^^^^
+--------------+-----------------------+
| **node name**| **allowed attributes**|
+--------------+-----------------------+
|<GRID> | [cols, rows]|
+--------------+-----------------------+
|<HGROUP> | []|
+--------------+-----------------------+
|<VGROUP> | []|
+--------------+-----------------------+
Visual Elements
---------------
In contrast to layout components, visual elements are direct input elements.
Graphical Components
^^^^^^^^^^^^^^^^^^^^
+-------------------+--------------------------------------------------------------+
| **node name** | **allowed attributes** |
+-------------------+--------------------------------------------------------------+
|<ACTION> |[program] |
+-------------------+--------------------------------------------------------------+
|<CHECKBOX> | [selected, selectonwindows, value]|
+-------------------+--------------------------------------------------------------+
|<COMBOBOX> | [selected]|
+-------------------+--------------------------------------------------------------+
|<COMBOITEM> | [value]|
+-------------------+--------------------------------------------------------------+
|<FILEDIALOG> |[filter, folder, location, multiples, multiples_delim, output]|
+-------------------+--------------------------------------------------------------+
|<FILELIST> | [height, title, width]|
+-------------------+--------------------------------------------------------------+
|<FILESELECTBOX> | [delim, filter, location]|
+-------------------+--------------------------------------------------------------+
|<GROUP> | [height, title, width]|
+-------------------+--------------------------------------------------------------+
|<GROUPBOX> | [multi]|
+-------------------+--------------------------------------------------------------+
|<IMAGE> | [height, src, width]|
+-------------------+--------------------------------------------------------------+
|<INPUT> | [multi, type {string, int, float, password}]|
+-------------------+--------------------------------------------------------------+
|<LABEL> | [link]|
+-------------------+--------------------------------------------------------------+
|<RADIOBUTTON> | [value]|
+-------------------+--------------------------------------------------------------+
|<SLIDER> | [max, min, step]|
+-------------------+--------------------------------------------------------------+
|<SLIDERITEM> | [display, value]|
+-------------------+--------------------------------------------------------------+
|<STREAM> | [height, title, width]|
+-------------------+--------------------------------------------------------------+
|<STREAMBOX> | |
+-------------------+--------------------------------------------------------------+
|<WINDOW> | [height, title, width] |
+-------------------+--------------------------------------------------------------+
.. _biogui_execution_model:
Execution Model of Templates
============================
Execution Network
-----------------
Within a *bioGUI* template, the ``<execution>...</execution>`` part defines how the command line argument to be executed is assembled.
The idea is again based on a network of predefined nodes.
The nodes can either be visual components, accessed by their respective **id**, or :ref:`biogui_execution_nodes` .
Upon starting an application with *bioGUI*, the execution network is responsible to construct the command line arguments with which the target application is called.
Therefore all executable nodes in the ``<execution>`` part are searched and *evaluated* one after the other (if there exist several).
Since execution must be started via an ``action`` visual element, which can have a *program* attribute, this allows to specify which executable nodes are executed: if the ``program`` attribute is set, this must match with the ``program`` attribute of the executable node.
Finally an executable node is executed. Upon this the command line arguments are assembled. This is shown exemplarily in the below figure:
.. figure:: ./images/usage/biogui_execution_network.PNG
:width: 90%
Illustration of an *Execution Network* for a simple example application.
The command line arguments for the executable ``sh`` are collected from the nodes with ``id`` s *input* and *output*.
While *input* refers to a visual component node, the *output* id refers to an ``if`` node, which collects data from another visual component node (**3**) or a node which constructs a *netcat* command, depending on whether the visual node with id *os* (**2**) equals ``TRUE`` or not.
List of available execution nodes:
.. _biogui_execution_nodes:
Execution Nodes
^^^^^^^^^^^^^^^
+--------------------------+---------------------------------------------------------------------+
| **node name** | **allowed attributes** |
+--------------------------+---------------------------------------------------------------------+
|<add> | [ID, TYPE, sep]|
+--------------------------+---------------------------------------------------------------------+
|<const> | [ID, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<else> | []|
+--------------------------+---------------------------------------------------------------------+
|<env> | [GET, ID, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<execute> | [EXEC, ID, PROGRAM, TYPE, location, param, program, wsl]|
+--------------------------+---------------------------------------------------------------------+
|<update> | [deferred, target, attrib, value]|
+--------------------------+---------------------------------------------------------------------+
|<messagebox> | [deferred]|
+--------------------------+---------------------------------------------------------------------+
|<file> | [FROM, ID, SEP, TO, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<httpexecute> | [CL_TO_POST, DELIM, ID, PORT, PROGRAM, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<if> | [COMP, ID, SEP, TYPE, VALUE1, VALUE2]|
+--------------------------+---------------------------------------------------------------------+
|<math> | [ID, OP, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<orderedadd> | [FROM, ID, SELECTED, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<output> | [COLOR, DEFERRED, FROM, HOST, ID, LOCATION, PORT, TO, TYPE, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<relocate> | [FROM, ID, PREPEND, TO, TYPE, UNIX, WSL]|
+--------------------------+---------------------------------------------------------------------+
|<replace> | [ID, REPLACE, REPLACE_WITH, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<script> | [ARGV, ID, SCRIPT, TYPE]|
+--------------------------+---------------------------------------------------------------------+
|<value> | [FOR, FROM, ID, TYPE]|
+--------------------------+---------------------------------------------------------------------+
27 changes: 2 additions & 25 deletions doc/developer_guide.rst
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,10 @@

********************
Developer Guide
********************

It is highly recommend to read the mechanism section :ref:`bioGUI_working_mechanism` first.

bioGUI templates
================

.. _biogui_principles_layout:

window-part of template
=======================

layout model
------------

asdasdasd

.. _biogui_principles_execution:

execution-part of template
==========================

execution-model
---------------

asdads

extending bioGUI
Extending bioGUI
================

Window component factory
Expand Down
Binary file added doc/images/usage/biogui_execution_network.PNG
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
3 changes: 3 additions & 0 deletions doc/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,5 +39,8 @@ Please note additional information provided in our :ref:`user_guide`.

user_guide.rst
build_wsl.rst
biogui_idea.rst
developer_guide.rst
nodes.rst
install_template_example.rst
licence.rst
31 changes: 31 additions & 0 deletions doc/install_template_example.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
##############################
bioGUI Install Modules Example
##############################

===============
Example: hisat2
===============

***********************
Dependency/Install Part
***********************



*************
Template Part
*************

=================
Example: poreSTAT
=================

***********************
Dependency/Install Part
***********************



*************
Template Part
*************

0 comments on commit 1ef2266

Please sign in to comment.