Package: wbuild
======
wBuild.. _user-overview:OverviewwBuild is all about making your day easier resolving, updating and cascading various dependencies, pipeline rules and
code structs. The program lets you specify all the needed information in a YAML header right in your R code and let
the automated :code:Snakemakeprocesses do the rest!You can learn more about the features that wBuild provides either taking a look at the :ref:features list <features>or :ref:looking at the HTML output of the demo project <running-demo>. Another interesting thing to take a look at could be
the :ref:installation requirements & procedure <installation>and, in particular, :ref:wBuild project tree structure <project-structure>.You can find functionality overview of wBuild and its relationship with Snakemake :ref:here <overview-of-functionality>.ExampleFirst, we :ref:install <installation>all the needed software requirements, including wBuild.
Then, we :ref:initialize wbuild <wbuild-init>which creates :ref:wBuild files <project-structure>in our project.After that, we create an R script in the  and provide a :ref:YAML header <yaml-headers>with wBuild-supported tags:.. code-block:: R#'---
#' title: Basic Input Demo
#' author: Leonhard Wachutka
#' wb:
#'  input:
#'  - iris: "Data/{wbP}/iris.RDS"
#'  output:
#'  - wBhtml: "Output/html/030_AnalysisOfId_{id}.html"
#'  type: noindex
#' output:
#'  html_document:
#'   code_folding: show
#'   code_download: TRUE
#'---

source('.wBuild/wBuildParser.R')
parseWBHeader("Scripts/Analysis1/050_PythonCode/030_AnalysisTemplate.R")

id = snakemake@wildcards[["id"]]
iris_df = wbReadRDS('iris')
colnames(iris_df) = gsub('\\.','',colnames(iris_df))
hist(iris_df[[id]],main=id)Running :bash:snakemakenow in the root directory of your project will now automatically
parse the parameters out of scripts headers and create an HTML output showing the results of our petal analysis - found in HTML output directory
(:code:./Output/htmlby default) along with a nice navigable HTML structure. Let's open one of the output HTML files, use the
upper footer to navigate to the :ref:needed subproject <scripts-structure>(hereAnalysis1), and we will see a nicely rendered output of our
script:.. image:: /res/images/HTML_output_demo.png
:scale: 70%
:align: left|
|You can read more about :ref:publishing the output HTML to your common server <publishing-the-output>or try launching demonstration yourself as follows:.. _running-demo:Running demo* Install wBuild. You can learn more about the installation process :ref:`here <installation>`.
* Navigate to an *empty* directory.
* Run :bash:`wbuild demo`. This will create a wBuild demo project with various examples.
* Explore the files in :bash:`Scripts/`
* Run :bash:`snakemake` on the root directory to let Snakemake do its thing (see below) and compile the project.
* Open :code:`Output/html/index.html` in your web browser. From there, you can browse through sites showing and describing :ref:`basic features <features>` of wBuild on an example analysis.

.. _overview-of-functionality:

Functionality & workflow
------------------------
wBuild is *not really a standalone application*, much more **a plugin and "code generator" for the later use of Snakemake**, which is *inevitable* part
of a workflow involving wBuild: this way, you run :code:`snakemake` CLI each time you want to build and render your project!

First, wBuild executes the initial, `setup` part of the workflow:

.. image:: /res/images/snakemake_wbuild_diag_setup.jpg
    :scale: 80%

|
After that comes the project build phase. During this step, snakemake with a help of wBuild does process your project and
creates the results. Following diagram shows the process:

.. image:: /res/images/snakemake_wbuild_diag_build.jpg
    :scale: 80%

|
As you see, *Snakemake* actually takes the **main** role in a typical wBuild workflow, so every user is *encouraged* to
learn more about Snakemake - for instance `in its official documentation <http://snakemake.readthedocs.io/en/stable/>`_.
You are also welcome to take a look at the more :ref:`technial features <features>` that wBuild provides.


A small overview of the functionality that wBuild provides:

* wBuild enables reproducible research by appending every R-markdown script to the global analysis pipeline written in snakemake
* All R scripts using R-markdown are compiled via knitr/Rmarkdown and rendered in a navigable web-page
* This is achieved by writing the snakemake rules directly in the header of your R scripts
* Headers allow the same flexibility (i.e. usage of python) as in the traditional Snakefile, but do not separate dependencies from the code where they are actually used.

.. _project-structure:

wBuild project structure
------------------------

Assert :code:`ROOT` is the root directory of your wBuild project.

ROOT/.wBuild
    Is a directory with static wBuild files that *is not to be changed unless necessary*. There are all the
    service files located.

ROOT/wbuild.yaml
    It is a configuration file. Necessary but editable by the user. See :ref:`configuration file <configuration-file>`.

ROOT/.wBuild.depend
    File *autogenerated* by wBuild. Contains rule information for the :ref:`Snakemake pipeline <overview-of-functionality>`.

.. _scripts-structure:

ROOT/Scripts
    Is a directory where all your scripts should be located within **subdirectories**. Organizing your code directly into subdirectories helps you to flexibly structure your project, to
    present them divided by tabs in the HTML output or to
    :ref:`apply the same script to the various equally structured data <script-mapping>`

ROOT/Output
    Is a default output directory. It's subdirectories, :code:`html` and :code:`ProcessedData`, are paths for
    :ref:`published html <publishing-the-output>` and processed data by default (:ref:`you can change it <configuration-file>`).


=======
History
=======

0.1.0 (2017-06-23)
------------------

* First release on PyPI.

1.0 (2017-12-15)
---------------------
* Improved Demo
* Many fixes