Verified Commit 3d409d95 authored by Laurent Modolo's avatar Laurent Modolo
Browse files

add style

parent 44ce45b8
Pipeline #292 failed with stage
......@@ -2,8 +2,8 @@ all: public/good_practices.html \
public/good_practices.pdf \
README.md
public/good_practices.html: good_practices.tex bibliography.bib
pandoc good_practices.tex --bibliography=bibliography.bib -o public/good_practices.html
public/good_practices.html: good_practices.tex bibliography.bib github-pandoc.css
pandoc good_practices.tex --bibliography=bibliography.bib -c github-pandoc.css --citeproc --toc --standalone --number-sections -o public/good_practices.html
README.md: good_practices.tex bibliography.bib
pandoc good_practices.tex --bibliography=bibliography.bib -o README.md
pandoc good_practices.tex --bibliography=bibliography.bib --citeproc --toc --standalone --number-sections -o README.md
Introduction
============
---
author:
- Laurent Modolo
bibliography: bibliography.bib
nocite: "[@wilsonBestPracticesScientific2014; @masumTenSimpleRules2013; @bolandTenSimpleRules2017; @listTenSimpleRules2017; @nobleQuickGuideOrganizing2009; @leipzigReviewBioinformaticPipeline2016; @dudleyQuickGuideDeveloping2009; @sandveTenSimpleRules2013; @vicensTenSimpleRules2007; @taschukTenSimpleRules2017; @mieleNineQuickTips2019]"
title: |
Biocomputing at LBMC\
Guide of good practice
---
- [Introduction](#introduction)
- [[1]{.toc-section-number} Project organization
[]{#sec:project.organisation
label="sec:project.organisation"}](#project-organization)
- [[1.1]{.toc-section-number} Text files at the root of the
project
directory](#text-files-at-the-root-of-the-project-directory)
- [[1.2]{.toc-section-number} `data` folder](#data-folder)
- [[1.3]{.toc-section-number} `src` folder](#src-folder)
- [[1.3.1]{.toc-section-number} `tests` folder](#tests-folder)
- [[1.4]{.toc-section-number} `doc` folder](#doc-folder)
- [[1.5]{.toc-section-number} `results` folder](#results-folder)
- [[1.6]{.toc-section-number} `bin` folder](#bin-folder)
- [[2]{.toc-section-number} Data Management []{#sec:data.managment
label="sec:data.managment"}](#data-management)
- [[2.1]{.toc-section-number} Public archives](#public-archives)
- [[2.2]{.toc-section-number} PSMN:](#psmn)
- [[2.3]{.toc-section-number} Code safety](#code-safety)
- [[3]{.toc-section-number} Versioning []{#sec:versioning
label="sec:versioning"}](#versioning)
- [[3.1]{.toc-section-number} Installing `git`](#installing-git)
- [[3.2]{.toc-section-number} Using git](#using-git)
- [[4]{.toc-section-number} Coding []{#sec:coding
label="sec:coding"}](#coding)
- [[4.1]{.toc-section-number} Write programs for people, not
computers](#write-programs-for-people-not-computers)
- [[4.2]{.toc-section-number} Apply a naming
convention](#apply-a-naming-convention)
- [[4.3]{.toc-section-number} Iterative development and continuous
integration](#iterative-development-and-continuous-integration)
- [[4.4]{.toc-section-number} Tests driven
development](#tests-driven-development)
# Introduction {#introduction .unnumbered}
We spend an increasing amount of time building and using software.
However, most of us are never taught how to do this correctly and
......@@ -26,8 +68,7 @@ This document summarizes a set of good practices in bioinformatics.
These good practices were compiled from different sources, often
overlapping, listed in the References starting page of this document.
Project organization[\[sec:project.organisation\]]{#sec:project.organisation label="sec:project.organisation"}
==============================================================================================================
# Project organization []{#sec:project.organisation label="sec:project.organisation"}
The first step at the start of a bioinformatic project is to plan for
the structure of the project. Following this structure will facilitate
......@@ -55,8 +96,7 @@ The project must have the following structure:
You can get a template of this organization on the following `git`
repository: <https://gitbio.ens-lyon.fr/LBMC/hub/minimal_git_repo>.
Text files at the root of the project directory
-----------------------------------------------
## Text files at the root of the project directory
#### The `README`
......@@ -101,8 +141,7 @@ to-do list with a clear description of its items, so they make sense to
newcomers. This will also help you to keep track of the work progress
and time-table.
`data` folder
-------------
## `data` folder
The `data` folder must contain a `.gitignore` file whose content is
simply "`*`". Therefore, `git` will ignore files in this folder (See
......@@ -136,8 +175,7 @@ to check if new modifications work correctly, hence saving you a lot of
time (See Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} for more information on testing).
`src` folder
------------
## `src` folder
If you are developping a new tool, its source code must be in `src`. If
you are developing or using an analysis pipeline, we advise you to put
......@@ -172,8 +210,7 @@ executed to test your code. This will be explained in more detail in the
Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} on tests-driven development.
`doc` folder
------------
## `doc` folder
You like to write stuff? Put it in the `doc` folder. Even if you don't
like to write, write anyway on what you are doing and put it in the
......@@ -190,8 +227,7 @@ compute results and generate figures. You can use
[`Makefile`](http://bellet.info/creatis/unix/makefile.html) to automate
the generation of documents in the `doc` folder.
`results` folder
----------------
## `results` folder
The `results` folder must contain a `.gitignore` file whose content is
simply "`*`". Therefore, `git` will ignore files in this folder (See
......@@ -218,8 +254,7 @@ that could ease the reviewing process of your work and temporary files
that are only consuming space. You can use a `results/tmp` folder to
make this distinction.
`bin` folder
------------
## `bin` folder
The `bin` folder which historically contains any compiled binary file
must also contain third party scripts and software. You should be able
......@@ -230,8 +265,7 @@ from the internet or other sources. This folder can also be
automatically filed if necessary by the execution of the content of the
`src` folder.
Data Management[\[sec:data.managment\]]{#sec:data.managment label="sec:data.managment"}
=======================================================================================
# Data Management []{#sec:data.managment label="sec:data.managment"}
In this section we will present some rules to manage your project data.
Given the size of current NGS data set one must find the balance between
......@@ -261,8 +295,7 @@ numerous conventions for metadata terms that you can follow, like the
will also be useful for the persons that are going to reuse your data
(in meta-analysis for example) and to cite them.
Public archives
---------------
## Public archives
Public archives like [ebi](https://www.ebi.ac.uk/submission/) (UE) or
[ncbi](https://www.ncbi.nlm.nih.gov/home/submit-wizard/) (USA) are free
......@@ -279,8 +312,7 @@ them as soon as you get your raw data.
- You will get a reminder when the end of the embargo is near. Thus
your precious data won't go public inadvertently.
[PSMN](http://www.ens-lyon.fr/PSMN/):
-------------------------------------
## [PSMN](http://www.ens-lyon.fr/PSMN/):
The PSMN (Pôle Scientifique de Modélisation Numérique) is the
preferential high-performance computing (HPC) center the LBMC have
......@@ -295,8 +327,7 @@ Modolo](mailto:laurent.modolo@ens-lyon.fr) if you need help with this
procedure. This will also facilitate access to your data for the people
working on your project if they use the PSMN computing facilities.\
Code safety
-----------
## Code safety
Most of the human bioinformatic work will result in the production of
lines of code or text. While important, the size of such data is often
......@@ -316,8 +347,7 @@ synchronize folders on their servers (100Gb). The UE provides a
synchronization service called [b2drop](https://b2drop.eudat.eu) to
synchronize folders on their servers (20Gb).
Versioning[\[sec:versioning\]]{#sec:versioning label="sec:versioning"}
======================================================================
# Versioning []{#sec:versioning label="sec:versioning"}
Biologists keep their lab journal up to date so their future self or
other people can check on and reproduce their work. In bioinformatics
......@@ -346,10 +376,9 @@ This will also help you to comply with the recommendations of the
Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} on coding.\
You can find the LBMC course on `git` at
[https://gitbio.ens-lyon.fr/LBMC/hub/formations/git\_basis/](https://gitbio.ens-lyon.fr/LBMC/hub/formations/git_basis/-/blob/master/README.md)
[https://gitbio.ens-lyon.fr/LBMC/hub/formations/git_basis/](https://gitbio.ens-lyon.fr/LBMC/hub/formations/git_basis/-/blob/master/README.md)
Installing `git`
----------------
## Installing `git`
We chose `git` for the version control software to use at the LBMC.
`git` can be easily installed on most operating systems with the
......@@ -374,8 +403,7 @@ commands:
git config --global user.name "first_name last_name"
git config --global user.email first_name.last_name@ens-lyon.fr
Using git
---------
## Using git
To start recording your bioinformatic journal you simply need to place
yourself in your project directory and use the command:
......@@ -426,15 +454,13 @@ community around `git` so most of your problems with it should find
their answer online or in the LBMC. Also, don't forget to go to the
`git` formation organized in the LBMC !
Coding[\[sec:coding\]]{#sec:coding label="sec:coding"}
======================================================
# Coding []{#sec:coding label="sec:coding"}
In this section we are going to introduce some concept and rules to
follow and implement. The goal of this section is to write better code
and scripts in your projects, with validated and reproducible results.
Write programs for people, not computers
----------------------------------------
## Write programs for people, not computers
The first goal to follow in your project is to write code for people and
not for computers. We are limited and there is only so much information
......@@ -460,8 +486,7 @@ code small and avoid the problem of maintaining different version of the
same code. If you are using an object-oriented language use
inheritance.\
Apply a naming convention
-------------------------
## Apply a naming convention
Define a naming convention for your variables, functions, objects, and
files at the start of your project and kept it. We advise you to use
......@@ -482,8 +507,7 @@ the `lintr` package for `R`, `g++` for `C/C++` or `pep8` for `python`.
Another advantage of using these tools is to ensure that your code will
be valid for the future evolution of the language.
Iterative development and continuous integration
------------------------------------------------
## Iterative development and continuous integration
Aim to have short development cycle from the conception of your code to
its test. The conception will be simpler and your code will evolve with
......@@ -504,8 +528,7 @@ will involve small changes with minimal side effects. You can make those
changes in a new branch while keeping a working (if suboptimal) main
branch.
Tests driven development
------------------------
## Tests driven development
The value or your code reside in its number of working lines and not in
its number of lines. Thus each modification must be tested. The easiest
......@@ -546,4 +569,4 @@ Integration tests can be used with the content of your `data/examples`
folder to check after each step of your pipeline if you get the expected
results.
[\[sec:bibliography\]]{#sec:bibliography label="sec:bibliography"}
[]{#sec:bibliography label="sec:bibliography"}
/*! normalize.css v2.1.3 | MIT License | git.io/normalize */
/* ==========================================================================
HTML5 display definitions
========================================================================== */
/**
* Correct `block` display not defined in IE 8/9.
*/
article,
aside,
details,
figcaption,
figure,
footer,
header,
hgroup,
main,
nav,
section,
summary {
display: block;
}
/**
* Correct `inline-block` display not defined in IE 8/9.
*/
audio,
canvas,
video {
display: inline-block;
}
/**
* Prevent modern browsers from displaying `audio` without controls.
* Remove excess height in iOS 5 devices.
*/
audio:not([controls]) {
display: none;
height: 0;
}
/**
* Address `[hidden]` styling not present in IE 8/9.
* Hide the `template` element in IE, Safari, and Firefox < 22.
*/
[hidden],
template {
display: none;
}
/* ==========================================================================
Base
========================================================================== */
/**
* 1. Set default font family to sans-serif.
* 2. Prevent iOS text size adjust after orientation change, without disabling
* user zoom.
*/
html {
font-family: sans-serif; /* 1 */
-ms-text-size-adjust: 100%; /* 2 */
-webkit-text-size-adjust: 100%; /* 2 */
}
/**
* Remove default margin.
*/
body {
margin: 0;
}
/* ==========================================================================
Links
========================================================================== */
/**
* Remove the gray background color from active links in IE 10.
*/
a {
background: transparent;
}
/**
* Address `outline` inconsistency between Chrome and other browsers.
*/
a:focus {
outline: thin dotted;
}
/**
* Improve readability when focused and also mouse hovered in all browsers.
*/
a:active,
a:hover {
outline: 0;
}
/* ==========================================================================
Typography
========================================================================== */
/**
* Address variable `h1` font-size and margin within `section` and `article`
* contexts in Firefox 4+, Safari 5, and Chrome.
*/
h1 {
font-size: 2em;
margin: 0.67em 0;
}
/**
* Address styling not present in IE 8/9, Safari 5, and Chrome.
*/
abbr[title] {
border-bottom: 1px dotted;
}
/**
* Address style set to `bolder` in Firefox 4+, Safari 5, and Chrome.
*/
b,
strong {
font-weight: bold;
}
/**
* Address styling not present in Safari 5 and Chrome.
*/
dfn {
font-style: italic;
}
/**
* Address differences between Firefox and other browsers.
*/
hr {
-moz-box-sizing: content-box;
box-sizing: content-box;
height: 0;
}
/**
* Address styling not present in IE 8/9.
*/
mark {
background: #ff0;
color: #000;
}
/**
* Correct font family set oddly in Safari 5 and Chrome.
*/
code,
kbd,
pre,
samp {
font-family: monospace, serif;
font-size: 1em;
}
/**
* Improve readability of pre-formatted text in all browsers.
*/
pre {
white-space: pre-wrap;
}
/**
* Set consistent quote types.
*/
q {
quotes: "\201C" "\201D" "\2018" "\2019";
}
/**
* Address inconsistent and variable font size in all browsers.
*/
small {
font-size: 80%;
}
/**
* Prevent `sub` and `sup` affecting `line-height` in all browsers.
*/
sub,
sup {
font-size: 75%;
line-height: 0;
position: relative;
vertical-align: baseline;
}
sup {
top: -0.5em;
}
sub {
bottom: -0.25em;
}
/* ==========================================================================
Embedded content
========================================================================== */
/**
* Remove border when inside `a` element in IE 8/9.
*/
img {
border: 0;
}
/**
* Correct overflow displayed oddly in IE 9.
*/
svg:not(:root) {
overflow: hidden;
}
/* ==========================================================================
Figures
========================================================================== */
/**
* Address margin not present in IE 8/9 and Safari 5.
*/
figure {
margin: 0;
}
/* ==========================================================================
Forms
========================================================================== */
/**
* Define consistent border, margin, and padding.
*/
fieldset {
border: 1px solid #c0c0c0;
margin: 0 2px;
padding: 0.35em 0.625em 0.75em;
}
/**
* 1. Correct `color` not being inherited in IE 8/9.
* 2. Remove padding so people aren't caught out if they zero out fieldsets.
*/
legend {
border: 0; /* 1 */
padding: 0; /* 2 */
}
/**
* 1. Correct font family not being inherited in all browsers.
* 2. Correct font size not being inherited in all browsers.
* 3. Address margins set differently in Firefox 4+, Safari 5, and Chrome.
*/
button,
input,
select,
textarea {
font-family: inherit; /* 1 */
font-size: 100%; /* 2 */
margin: 0; /* 3 */
}
/**
* Address Firefox 4+ setting `line-height` on `input` using `!important` in
* the UA stylesheet.
*/
button,
input {
line-height: normal;
}
/**
* Address inconsistent `text-transform` inheritance for `button` and `select`.
* All other form control elements do not inherit `text-transform` values.
* Correct `button` style inheritance in Chrome, Safari 5+, and IE 8+.
* Correct `select` style inheritance in Firefox 4+ and Opera.
*/
button,
select {
text-transform: none;
}
/**
* 1. Avoid the WebKit bug in Android 4.0.* where (2) destroys native `audio`
* and `video` controls.
* 2. Correct inability to style clickable `input` types in iOS.
* 3. Improve usability and consistency of cursor style between image-type
* `input` and others.
*/
button,
html input[type="button"], /* 1 */
input[type="reset"],
input[type="submit"] {
-webkit-appearance: button; /* 2 */
cursor: pointer; /* 3 */
}
/**
* Re-set default cursor for disabled elements.
*/
button[disabled],
html input[disabled] {
cursor: default;
}
/**
* 1. Address box sizing set to `content-box` in IE 8/9/10.
* 2. Remove excess padding in IE 8/9/10.
*/
input[type="checkbox"],
input[type="radio"] {
box-sizing: border-box; /* 1 */
padding: 0; /* 2 */
}
/**
* 1. Address `appearance` set to `searchfield` in Safari 5 and Chrome.
* 2. Address `box-sizing` set to `border-box` in Safari 5 and Chrome
* (include `-moz` to future-proof).
*/
input[type="search"] {
-webkit-appearance: textfield; /* 1 */
-moz-box-sizing: content-box;
-webkit-box-sizing: content-box; /* 2 */
box-sizing: content-box;
}
/**
* Remove inner padding and search cancel button in Safari 5 and Chrome
* on OS X.
*/
input[type="search"]::-webkit-search-cancel-button,
input[type="search"]::-webkit-search-decoration {
-webkit-appearance: none;
}
/**
* Remove inner padding and border in Firefox 4+.
*/
button::-moz-focus-inner,
input::-moz-focus-inner {
border: 0;
padding: 0;
}
/**
* 1. Remove default vertical scrollbar in IE 8/9.
* 2. Improve readability and alignment in all browsers.
*/
textarea {
overflow: auto; /* 1 */
vertical-align: top; /* 2 */
}
/* ==========================================================================
Tables
========================================================================== */
/**
* Remove most spacing between table cells.
*/
table {
border-collapse: collapse;
border-spacing: 0;
}
.go-top {