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 \ ...@@ -2,8 +2,8 @@ all: public/good_practices.html \
public/good_practices.pdf \ public/good_practices.pdf \
README.md README.md
public/good_practices.html: good_practices.tex bibliography.bib public/good_practices.html: good_practices.tex bibliography.bib github-pandoc.css
pandoc good_practices.tex --bibliography=bibliography.bib -o public/good_practices.html 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 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. We spend an increasing amount of time building and using software.
However, most of us are never taught how to do this correctly and 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. ...@@ -26,8 +68,7 @@ This document summarizes a set of good practices in bioinformatics.
These good practices were compiled from different sources, often These good practices were compiled from different sources, often
overlapping, listed in the References starting page of this document. 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 first step at the start of a bioinformatic project is to plan for
the structure of the project. Following this structure will facilitate the structure of the project. Following this structure will facilitate
...@@ -55,8 +96,7 @@ The project must have the following structure: ...@@ -55,8 +96,7 @@ The project must have the following structure:
You can get a template of this organization on the following `git` You can get a template of this organization on the following `git`
repository: <https://gitbio.ens-lyon.fr/LBMC/hub/minimal_git_repo>. 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` #### The `README`
...@@ -101,8 +141,7 @@ to-do list with a clear description of its items, so they make sense to ...@@ -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 newcomers. This will also help you to keep track of the work progress
and time-table. and time-table.
`data` folder ## `data` folder
-------------
The `data` folder must contain a `.gitignore` file whose content is The `data` folder must contain a `.gitignore` file whose content is
simply "`*`". Therefore, `git` will ignore files in this folder (See 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 ...@@ -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" time (See Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} for more information on testing). 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 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 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 ...@@ -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" Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} on tests-driven development. 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 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 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 ...@@ -190,8 +227,7 @@ compute results and generate figures. You can use
[`Makefile`](http://bellet.info/creatis/unix/makefile.html) to automate [`Makefile`](http://bellet.info/creatis/unix/makefile.html) to automate
the generation of documents in the `doc` folder. the generation of documents in the `doc` folder.
`results` folder ## `results` folder
----------------
The `results` folder must contain a `.gitignore` file whose content is The `results` folder must contain a `.gitignore` file whose content is
simply "`*`". Therefore, `git` will ignore files in this folder (See 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 ...@@ -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 that are only consuming space. You can use a `results/tmp` folder to
make this distinction. make this distinction.
`bin` folder ## `bin` folder
------------
The `bin` folder which historically contains any compiled binary file The `bin` folder which historically contains any compiled binary file
must also contain third party scripts and software. You should be able 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 ...@@ -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 automatically filed if necessary by the execution of the content of the
`src` folder. `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. 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 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 ...@@ -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 will also be useful for the persons that are going to reuse your data
(in meta-analysis for example) and to cite them. (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 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 [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. ...@@ -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 - You will get a reminder when the end of the embargo is near. Thus
your precious data won't go public inadvertently. 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 The PSMN (Pôle Scientifique de Modélisation Numérique) is the
preferential high-performance computing (HPC) center the LBMC have 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 ...@@ -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 procedure. This will also facilitate access to your data for the people
working on your project if they use the PSMN computing facilities.\ 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 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 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 ...@@ -316,8 +347,7 @@ synchronize folders on their servers (100Gb). The UE provides a
synchronization service called [b2drop](https://b2drop.eudat.eu) to synchronization service called [b2drop](https://b2drop.eudat.eu) to
synchronize folders on their servers (20Gb). 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 Biologists keep their lab journal up to date so their future self or
other people can check on and reproduce their work. In bioinformatics 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 ...@@ -346,10 +376,9 @@ This will also help you to comply with the recommendations of the
Section [\[sec:coding\]](#sec:coding){reference-type="ref" Section [\[sec:coding\]](#sec:coding){reference-type="ref"
reference="sec:coding"} on coding.\ reference="sec:coding"} on coding.\
You can find the LBMC course on `git` at 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. We chose `git` for the version control software to use at the LBMC.
`git` can be easily installed on most operating systems with the `git` can be easily installed on most operating systems with the
...@@ -374,8 +403,7 @@ commands: ...@@ -374,8 +403,7 @@ commands:
git config --global user.name "first_name last_name" git config --global user.name "first_name last_name"
git config --global user.email first_name.last_name@ens-lyon.fr 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 To start recording your bioinformatic journal you simply need to place
yourself in your project directory and use the command: 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 ...@@ -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 their answer online or in the LBMC. Also, don't forget to go to the
`git` formation organized in the LBMC ! `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 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 follow and implement. The goal of this section is to write better code
and scripts in your projects, with validated and reproducible results. 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 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 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 ...@@ -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 same code. If you are using an object-oriented language use
inheritance.\ inheritance.\
Apply a naming convention ## Apply a naming convention
-------------------------
Define a naming convention for your variables, functions, objects, and 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 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`. ...@@ -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 Another advantage of using these tools is to ensure that your code will
be valid for the future evolution of the language. 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 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 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 ...@@ -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 changes in a new branch while keeping a working (if suboptimal) main
branch. branch.
Tests driven development ## Tests driven development
------------------------
The value or your code reside in its number of working lines and not in 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 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` ...@@ -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 folder to check after each step of your pipeline if you get the expected
results. 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;
}
/**