Metadata-Version: 2.1
Name: wbuild
Version: 1.8.0
Summary: Automatic build tool for R Reports
Home-page: https://github.com/gagneurlab/wBuild
Author: Leonhard Wachutka
Author-email: leonhard@wachutka.eu
License: UNKNOWN
Description: ======
        wBuild
        ======
        
        .. _user-overview:
        
        Overview
        --------
        wBuild 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:`Snakemake` processes 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>`.
        
        Example
        -------
        
        First, 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:`snakemake` now 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/html` by 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>` (here *Analysis1*), 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
        
Keywords: wbuild
Platform: UNKNOWN
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Description-Content-Type: text/markdown
