r-lint 0.1.0

Copyright (c) 2018 QBiC

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Description:
Rmageddon
##############

.. image:: https://travis-ci.org/qbicsoftware/r-lint-cli.svg?branch=master
:target: https://travis-ci.org/qbicsoftware/r-lint-cli

.. image:: https://codecov.io/gh/qbicsoftware/r-lint-cli/branch/master/graph/badge.svg
:target: https://codecov.io/gh/qbicsoftware/r-lint-cli

A small linting and building command line tool for reproducible R analysis with Docker at QBiC.

Motivation
Performing a reproducible analysis with R and share the environment status of an R installation with the
necessary packages and all that with the correct version is a very challenging task.

In order to face this issue, under the umbrella of better reproducibility of computational results, we created
`Rmageddon`, a small command-line tool, that assists in the build of Docker container with specified version of R and
a dedicated, version-defined package installation.

The container collection is hosted on a different GitHub repository: https://github.com/qbicsoftware/r-container-lib.

All containers there passed the linting and have been build with `Rmageddon`.

.. contents:: **Table of Contents**


Installation
============

The easiest way is to install a stable release of ``r-lint`` from PyPi_ with pip_:

.. code-block:: bash

$ pip install r-lint

Or if you want the latest development version, you can install from the ``master`` branch on GitHub with:

.. code-block:: bash

$ pip install git+https://github.com/qbicsoftware/r-lint-cli

.. _PyPi: https://pypi-hypernode.com/
.. _pip: https://pypi-hypernode.com/project/pip/


The command-line interface
===========================

Once you have installed *r-lint*, just call it with the ``--help`` option to get an overview of the subcommands
available in *r-lint*:

.. code-block:: bash

$ r-lint --help
______ __ __ __ __ ______
/\ == \ /\ \ /\ \ /\ "-.\ \ /\__ _\
\ \ __< \ \ \____ \ \ \ \ \ \-. \ \/_/\ \/
\ \_\ \_\ \ \_____\ \ \_\ \ \_\ "\_\ \ \_\
\/_/ /_/ \/_____/ \/_/ \/_/ \/_/ \/_/

2018, QBiC software, Sven Fillinger
sven.fillinger@qbic.uni-tuebingen.de

Usage: r-lint [OPTIONS] COMMAND [ARGS]...

Options:
--version Show the version and exit.
-v, --verbose Verbose output (print debug statements)
--help Show this message and exit.

Commands:
build Resolve R packages resources from Anaconda...
lint Check R project against linting guidelines


If you want to know the positional arguments and options of each subcommand, just type ``r-lint build --help`` or
``r-lint lint --help``.


The subcommand <lint>
---------------------

The subcommand <lint> is actually checking an R container project against some specified rule-set. Currently, *r-lint* is assuming the following project structure:

.. code-block:: bash

.
├── data
│   └── input_data // A collection of input data
| └── ...
├── Dockerfile // Docker container recipe
├── environment.yml // Conda environment recipe
└── scripts
└── example.R // A collection of R scripts
└── ...

Start the linting of a project directoy with:

.. code-block:: bash

$ r-lint lint /path/to/project

The linting will report warnings and failures by default. **Failure** events are recorded, if you did not provide:

- A file named ``Dockerfile``, the receipe for the Docker container
- A file named ``environment.yml``, the **Conda configuration file**

There a **warnings** raised, if you did not provide:

- A folder named ``data``, with the input data for the R analysis
- A folder named ``scripts``, with the R scripts themselves

Dockerfile
For the ``Dockerfile`` some things are mandatory, like:

- ``LABEL name`` - The name of the container. Needs to match the regex ``(Q|q)[a-zA-Z0-9]{4}-ranalysis``, for example **qtest-ranalysis**
- ``LABEL maintainer`` - The name of the container maintainer with email, for example **Sven Fillinger <sven.fillinger@qbic.uni-tuebingen.de>**
- ``LABEL version`` - The 3-digit numeric version string following the `semantic version standard`__
- ``LABEL organization`` - The organization's name
- ``LABEL github`` - The link to the GitHub repository

__ semantic_
.. _semantic: https://semver.org/


The subcommand <build>
----------------------

The subcommand ``build`` is a small helper tool, that is able to parse ``sessionInfo`` output from R and extracts the package names with versions.

It then takes these and checks on `Anaconda cloud`__ if these are available in one of the pre-defined channels `[default, r, bioconda]`. If successful, it will automatically add the corresponding conda package with version in the `environment.yml`. If a package cannot be found, a warning is printed on the command-line. If a specified version of a package is not found, it prints the available versions on the command-line.

To start the build, be sure you have an active internet connection and run it with:

.. code-block:: bash

$ r-lint build <R package list> environment.yml

The ``R package list`` can be obtained from inside your active R session, that was used to run your R analysis successfully. From within your R console, just type:

.. code-block:: R

> sessionInfo()$otherPkgs

This is your R package list, which is needed for r-lint build to work properly.

__ anaconda_
.. _anaconda: https://anaconda.org/

Keywords: R,linting,lint,Docker,container
Platform: UNKNOWN