obitools/obitools4
2
0
Fork 0
mirror of https://github.com/metabarcoding/obitools4.git synced 2025-06-29 16:20:46 +00:00
Code Issues Packages Projects Releases Wiki Activity

Complement to the documentation

Browse Source 
Former-commit-id: 89952a6f3bb261a6aaec24430906e635914ffce4
This commit is contained in:
Eric Coissac
2023-12-04 13:16:34 +01:00
parent eb351a7530
commit 03bef6461d
83 changed files with 65993 additions and 10547 deletions
Download Patch File Download Diff File Expand all files Collapse all files

252
doc/book/OBITools-V4.tex
View File

@ -213,7 +213,7 @@
\begin{document}
\maketitle
\ifdefined\Shaded\renewenvironment{Shaded}{\begin{tcolorbox}[frame hidden, borderline west={3pt}{0pt}{shadecolor}, sharp corners, boxrule=0pt, enhanced, interior hidden, breakable]}{\end{tcolorbox}}\fi
\ifdefined\Shaded\renewenvironment{Shaded}{\begin{tcolorbox}[breakable, interior hidden, enhanced, boxrule=0pt, borderline west={3pt}{0pt}{shadecolor}, sharp corners, frame hidden]}{\end{tcolorbox}}\fi
\renewcommand*\contentsname{Table of contents}
{
@ -368,12 +368,12 @@ take into account the taxonomic annotations, ultimately allowing sorting
and filtering of sequence records based on the taxonomy.
\hypertarget{installation-of-the-obitools}{%
\chapter{Installation of the
obitools}\label{installation-of-the-obitools}}
\chapter{\texorpdfstring{Installation of the
\emph{OBITools}}{Installation of the OBITools}}\label{installation-of-the-obitools}}
\hypertarget{availability-of-the-obitools}{%
\section{Availability of the
OBITools}\label{availability-of-the-obitools}}
\section{\texorpdfstring{Availability of the
\emph{OBITools}}{Availability of the OBITools}}\label{availability-of-the-obitools}}
The \emph{OBITools} are open source and protected by the
\href{http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html}{CeCILL
@ -389,7 +389,7 @@ downloaded from the metabarcoding git server
The \emph{OBITools4} are developped using the \href{https://go.dev/}{GO
programming language}, we stick to the latest version of the language,
today the \(1.19.5\). If you want to download and compile the sources
today the \(1.21.4\). If you want to download and compile the sources
yourself, you first need to install the corresponding compiler on your
system. Some parts of the soft are also written in C, therefore a recent
C compiler is also requested, GCC on Linux or Windows, the Developer
@ -402,6 +402,47 @@ C compiler is available on your system.
\section{Installation with the install
script}\label{installation-with-the-install-script}}
An installation script that compiles the new \emph{OBITools} on your
Unix-like system is available online. The easiest way to run it is to
copy and paste the following command into your terminal
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{curl} \AttributeTok{{-}L}\NormalTok{ https://metabarcoding.org/obitools4/install.sh }\KeywordTok{|} \FunctionTok{bash}
\end{Highlighting}
\end{Shaded}
By default, the script installs the \emph{OBITools} commands and other
associated files into the \texttt{/usr/local} directory. The names of
the commands in the new \emph{OBITools4} are mostly identical to those
in \emph{OBITools2}. Therefore, installing the new \emph{OBITools} may
hide or delete the old ones. If you want both versions to be available
on your system, the installation script offers two options:
\begin{quote}
-i, --install-dir Directory where \emph{OBITools} are installed (as
example use \texttt{/usr/local} not \texttt{/usr/local/bin}).
-p, --obitools-prefix Prefix added to the \emph{OBITools} command names
if you want to have several versions of obitools at the same time on
your system (as example \texttt{-p\ g} will produce \texttt{gobigrep}
command instead of \texttt{obigrep}).
\end{quote}
You can use these options by following the installation command:
\begin{Shaded}
\begin{Highlighting}[]
\ExtensionTok{curl} \AttributeTok{{-}L}\NormalTok{ https://metabarcoding.org/obitools4/install.sh }\KeywordTok{|} \DataTypeTok{\textbackslash{}}
\FunctionTok{bash} \AttributeTok{{-}s} \AttributeTok{{-}{-}} \AttributeTok{{-}{-}install{-}dir}\NormalTok{ test\_install }\AttributeTok{{-}{-}obitools{-}prefix}\NormalTok{ k}
\end{Highlighting}
\end{Shaded}
In this case, the binaries will be installed in the
\texttt{test\_install} directory and all command names will be prefixed
with the letter \texttt{k}. Thus \texttt{obigrep} will be named
\texttt{kobigrep}.
\hypertarget{compilation-from-sources}{%
\section{Compilation from sources}\label{compilation-from-sources}}
@ -409,25 +450,27 @@ script}\label{installation-with-the-install-script}}
\chapter{\texorpdfstring{File formats usable with
\emph{OBITools}}{File formats usable with OBITools}}\label{file-formats-usable-with-obitools}}
OBITools manipulate have to manipulate DNA sequence data and taxonomical
data. They can use some supplentary metadata describing the experiment
and produce some stats about the processed DNA data. All the manipulated
data are stored in text files, following standard data format.
\emph{OBITools} manipulate have to manipulate DNA sequence data and
taxonomical data. They can use some supplentary metadata describing the
experiment and produce some stats about the processed DNA data. All the
manipulated data are stored in text files, following standard data
format.
\hypertarget{the-dna-sequence-data}{%
\chapter{The DNA sequence data}\label{the-dna-sequence-data}}
\section{The DNA sequence data}\label{the-dna-sequence-data}}
Sequences can be stored following various format. OBITools knows some of
them. The central formats for sequence files manipulated by OBITools
scripts are the
\protect\hyperlink{the-fasta-sequence-format}{\texttt{fasta}} and
\protect\hyperlink{the-fastq-sequence-format}{\texttt{fastq}} format.
OBITools extends the both these formats by specifying a syntax to
include in the definition line data qualifying the sequence. All file
formats use the \texttt{IUPAC} code for encoding nucleotides.
Sequences can be stored following various format. \emph{OBITools} knows
some of them. The central formats for sequence files manipulated by
\emph{OBITools} scripts are the
\protect\hyperlink{sec-fasta}{\emph{FASTA}} and
\protect\hyperlink{sec-fastq}{\emph{FASTQ}} format. \emph{OBITools}
extends the both these formats by specifying a syntax to include in the
definition line data qualifying the sequence. All file formats use the
\protect\hyperlink{sec-iupac}{\texttt{IUPAC}} code for encoding
nucleotides.
Moreover these two formats that can be used as input and output formats,
\textbf{OBITools4} can read the following format :
\emph{OBITools4} can read the following format :
\begin{itemize}
\tightlist
@ -442,11 +485,11 @@ Moreover these two formats that can be used as input and output formats,
output files}
\end{itemize}
\hypertarget{the-iupac-code}{%
\section{The IUPAC Code}\label{the-iupac-code}}
\hypertarget{sec-iupac}{%
\subsection{The IUPAC Code}\label{sec-iupac}}
The International Union of Pure and Applied Chemistry (IUPAC\_) defined
the standard code for representing protein or DNA sequences.
The International Union of Pure and Applied Chemistry (\href{}{IUPAC})
defined the standard code for representing protein or DNA sequences.
\begin{longtable}[]{@{}ll@{}}
\toprule()
@ -473,22 +516,24 @@ N & Any base (A, C, G, T, or U) \\
\end{longtable}
\hypertarget{sec-fasta}{%
\section{\texorpdfstring{The \emph{fasta} sequence
format}{The fasta sequence format}}\label{sec-fasta}}
\subsection{\texorpdfstring{The \emph{FASTA} sequence
format}{The FASTA sequence format}}\label{sec-fasta}}
The \textbf{fasta format} is certainly the most widely used sequence
file format. This is certainly due to its great simplicity. It was
originally created for the Lipman and Pearson
\href{http://www.ncbi.nlm.nih.gov/pubmed/3162770?dopt=Citation}{FASTA
program}. OBITools use in more of the classical \texttt{fasta} format an
The \protect\hyperlink{sec-fasta}{\emph{FASTA}} format is certainly the
most widely used sequence file format. This is certainly due to its
great simplicity. It was originally created for the Lipman and Pearson
\href{http://www.ncbi.nlm.nih.gov/pubmed/3162770?dopt=Citation}{\texttt{FASTA}
program}. \emph{OBITools} use in more of the classical
\protect\hyperlink{sec-fasta}{\emph{FASTA}} format an
\texttt{extended\ version} of this format where structured data are
included in the title line.
In \emph{fasta} format a sequence is represented by a title line
beginning with a \textbf{\texttt{\textgreater{}}} character and the
sequences by itself following the :doc:\texttt{iupac} code. The sequence
is usually split other severals lines of the same length (expect for the
last one)
In \protect\hyperlink{sec-fasta}{\emph{FASTA}} format a sequence is
represented by a title line beginning with a
\textbf{\texttt{\textgreater{}}} character and the sequences by itself
following the \protect\hyperlink{sec-iupac}{\texttt{IUPAC}} code. The
sequence is usually split other severals lines of the same length
(expect for the last one)
\begin{verbatim}
>my_sequence this is my pretty sequence
@ -520,34 +565,45 @@ GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
\end{verbatim}
\hypertarget{file-extensions}{%
\subsubsection{File extensions}\label{file-extensions}}
There is no standard file extension for a
\protect\hyperlink{sec-fasta}{\emph{FASTA}} file, but \texttt{.fa} and
\texttt{.fasta}, are commonly used.
\hypertarget{sec-fastq}{%
\section[The \emph{fastq} sequence format]{\texorpdfstring{The
\emph{fastq} sequence
\subsection[The \emph{FASTQ} sequence format]{\texorpdfstring{The
\emph{FASTQ} sequence
format\footnote{This article uses material from the Wikipedia article
\href{http://en.wikipedia.org/wiki/FASTQ_format}{\texttt{FASTQ\ format}}
which is released under the
\texttt{Creative\ Commons\ Attribution-Share-Alike\ License\ 3.0}}}{The fastq sequence format}}\label{sec-fastq}}
\texttt{Creative\ Commons\ Attribution-Share-Alike\ License\ 3.0}}}{The FASTQ sequence format}}\label{sec-fastq}}
The \textbf{FASTQ} format is a text file format for storing both
biological sequences (only nucleic acid sequences) and the associated
quality scores. The sequence and score are each encoded by a single
ASCII character. This format was originally developed by the Wellcome
Trust Sanger Institute to link a
\protect\hyperlink{the-fasta-sequence-format}{FASTA} sequence file to
the corresponding quality data, but has recently become the de facto
The \protect\hyperlink{sec-fastq}{\emph{FASTQ}} format is a text file
format for storing both biological sequences (only nucleic acid
sequences) and the associated sequence quality scores. Every nucleotide
of the sequence and its associated quality score are each encoded by a
single ASCII character. This format was originally developed by the
Wellcome Trust Sanger Institute to link a
\protect\hyperlink{sec-fasta}{\emph{FASTA}} sequence file to the
corresponding quality data, but is now became the \emph{de facto}
standard for storing results from high-throughput sequencers (Cock et
al. 2010).
A fastq file normally uses four lines per sequence.
\emph{OBITools} considers that a
\protect\hyperlink{sec-fastq}{\emph{FASTQ}} file uses four lines to
encode a sequence record.
\begin{itemize}
\tightlist
\item
Line 1 begins with a `@' character and is followed by a sequence
identifier and an \emph{optional} description (like a
:ref:\texttt{fasta} title line).
\protect\hyperlink{sec-fasta}{\emph{FASTA}} title line).
\item
Line 2 is the raw sequence letters.
Line 2 is the sequence letters, in upper or lower case, but
\emph{OBITools} only write sequences as lower cases.
\item
Line 3 begins with a `+' character and is \emph{optionally} followed
by the same sequence identifier (and any description) again.
@ -556,7 +612,7 @@ A fastq file normally uses four lines per sequence.
contain the same number of symbols as letters in the sequence.
\end{itemize}
A fastq file containing a single sequence might look like this:
A \protect\hyperlink{sec-fastq}{\emph{FASTQ}} file looks like this:
\begin{verbatim}
@SEQ_ID
@ -575,21 +631,21 @@ characters in left-to-right increasing order of quality
^_`abcdefghijklmnopqrstuvwxyz{|}~
\end{verbatim}
The original Sanger FASTQ files also allowed the sequence and quality
strings to be wrapped (split over multiple lines), but this is generally
discouraged as it can make parsing complicated due to the unfortunate
choice of ``@'' and ``+'' as markers (these characters can also occur in
the quality string).
If the original Sanger \protect\hyperlink{sec-fastq}{\emph{FASTQ}} files
also allowed the sequence and quality strings to be wrapped (split over
multiple lines), it is not supported by \emph{OBITools} as it make
parsing complicated due to the unfortunate choice of ``@'' and ``+'' as
markers (these characters can also occur in the quality string).
\hypertarget{sequence-quality-scores}{%
\subsection*{Sequence quality scores}\label{sequence-quality-scores}}
\addcontentsline{toc}{subsection}{Sequence quality scores}
\subsubsection*{Sequence quality scores}\label{sequence-quality-scores}}
\addcontentsline{toc}{subsubsection}{Sequence quality scores}
The Phred quality value \emph{Q} is an integer mapping of \emph{p}
(i.e., the probability that the corresponding base call is incorrect).
Two different equations have been in use. The first is the standard
Sanger variant to assess reliability of a base call, otherwise known as
Phred quality score:
(\emph{i.e.}, the probability that the corresponding base call is
incorrect). Two different equations have been in use. The first is the
standard Sanger variant to assess reliability of a base call, otherwise
known as Phred quality score:
\[
Q_\text{sanger} = -10 \, \log_{10} p
@ -621,12 +677,12 @@ equivalently, \(Q = 13\).}
\end{figure}
\hypertarget{encoding}{%
\subsubsection*{Encoding}\label{encoding}}
\addcontentsline{toc}{subsubsection}{Encoding}
\paragraph*{Encoding}\label{encoding}}
\addcontentsline{toc}{paragraph}{Encoding}
The \emph{fastq} format had differente way of encoding the Phred quality
score along the time. Here a breif history of these changes is
presented.
The \protect\hyperlink{sec-fastq}{\emph{FASTQ}} format had differente
way of encoding the Phred quality score along the time. Here a breif
history of these changes is presented. \emph{OBITools}
\begin{itemize}
\tightlist
@ -684,15 +740,65 @@ given run.
to the use of the Sanger format (Phred+33).
\end{itemize}
OBItools follows the Sanger format. Nevertheless, It is possible to read
files encoded following the Solexa/Illumina format by applying a shift
of 62 (see the option \textbf{-\/-solexa} of the OBITools commands).
\emph{OBITools} follows the Sanger format. Nevertheless, It is possible
to read files encoded following the Solexa/Illumina format by applying a
shift of 62 (see the option \textbf{--solexa} of the \emph{OBITools}
commands).
\hypertarget{file-extension}{%
\section{File extension}\label{file-extension}}
\hypertarget{file-extensions-1}{%
\subsubsection{File extensions}\label{file-extensions-1}}
There is no standard file extension for a FASTQ file, but .fq and
.fastq, are commonly used.
There is no standard file extension for a
\protect\hyperlink{sec-fastq}{\emph{FASTQ}} file, but \texttt{.fq} and
\texttt{.fastq}, are commonly used.
\hypertarget{the-taxonomy-files}{%
\section{The taxonomy files}\label{the-taxonomy-files}}
Many OBITools are able to take into account taxonomic data. This is done
by specifying a directory containing all
:doc:\texttt{NCBI\ taxonomy\ dump\ files\ \textless{}./taxdump\textgreater{}}.
\hypertarget{the-sample-description-file}{%
\section{The sample description
file}\label{the-sample-description-file}}
A key file for \emph{OBITools4} is the file describing all samples (PCR)
analyzed in the processed sequencing library file. This file, often
called the \texttt{ngsfilter} file, is a tab separated values (TSV)
file. The format of this file is exactly identical to that used in
\emph{OBITools2} and \emph{OBITools4}.
\texttt{\{tsv,\ .smaller\}\ wolf\_diet\ \ \ \ 13a\_F730603\ \ \ \ \ \ aattaac\ \ TTAGATACCCCACTATGC\ \ \ \ TAGAACAGGCTCCTCTAG\ \ \ \ \ F\ wolf\_diet\ \ \ \ 15a\_F730814\ \ \ \ \ \ gaagtag\ \ TTAGATACCCCACTATGC\ \ \ \ TAGAACAGGCTCCTCTAG\ \ \ \ \ F\ wolf\_diet\ \ \ \ 26a\_F040644\ \ \ \ \ \ gaatatc\ \ TTAGATACCCCACTATGC\ \ \ \ TAGAACAGGCTCCTCTAG\ \ \ \ \ F\ wolf\_diet\ \ \ \ 29a\_F260619\ \ \ \ \ \ gcctcct\ \ TTAGATACCCCACTATGC\ \ \ \ TAGAACAGGCTCCTCTAG\ \ \ \ \ F}
At least six columns must be present in every line of the file.
\begin{itemize}
\item
The first column contains the name of the experience:
An experiment name groups a set of sample together. Sequences
belonging to the experiment are tagged with an attribute
\texttt{experiment} containing the name of the experiment in their
annotation.
\item
The second column contains the sample identifier in the experiment
The sample identifier must be unique in the experiment. The
\texttt{obimultiplex} and \texttt{obitagpcr} commands add to all the
sequences bellonging to the same sample an attribute \texttt{sample}
containing the sample identifier
\item
The third column contains description of the tag used to identify
sequences corresponding to this sample
\item
The fourth column contains the forward primer sequence
\item
The fifth column contains the reverse primer sequence
\item
The sixth column must always contain the character \texttt{F} (full
length)
\end{itemize}
\hypertarget{obitools-v4-tutorial}{%
\chapter{OBITools V4 Tutorial}\label{obitools-v4-tutorial}}

19
doc/book/_freeze/formats/execute-results/epub.json Normal file
View File

File diff suppressed because one or more lines are too long

11
doc/book/_freeze/formats/execute-results/html.json Normal file
View File

File diff suppressed because one or more lines are too long

10
doc/book/_freeze/formats/execute-results/tex.json Normal file
View File

File diff suppressed because one or more lines are too long

19
doc/book/_freeze/index/execute-results/epub.json Normal file
View File

@ -0,0 +1,19 @@
{
"hash": "0d2b5eca01fd0d516bf9dee813b291f8",
"result": {
"markdown": "```{css}\ncode.sourceCode div.cell-output-stdout {\n font-size: 0.8em;\n}\n\ndiv.cell-output-stdout {\n font-size: 0.8em;\n}\n```\n\n\n# Preface {.unnumbered}\n\nThe first version of *OBITools* started to be developed in 2005. This was at the beginning of the DNA metabarcoding story at the Laboratoire d'Ecologie Alpine (LECA) in Grenoble. At that time, with Pierre Taberlet and François Pompanon, we were thinking about the potential of this new methodology under development. PIerre and François developed more the laboratory methods, while I was thinking more about the tools for analysing the sequences produced. Two ideas were behind this development. I wanted something modular, and something easy to extend. To achieve the first goal, I decided to implement obitools as a suite of unix commands mimicking the classic unix commands but dedicated to sequence files. The basic unix commands are very useful for automatically manipulating, parsing and editing text files. They work in flow, line by line on the input text. The result is a new text file that can be used as input for the next command. Such a design makes it possible to quickly develop a text processing pipeline by chaining simple elementary operations. The *OBITools* are the exact counterpart of these basic Unix commands, but the basic information they process is a sequence (potentially spanning several lines of text), not a single line of text. Most *OBITools* consume sequence files and produce sequence files. Thus, the principles of chaining and modularity are respected. In order to be able to easily extend the *OBITools* to keep up with our evolving ideas about processing DNA metabarcoding data, it was decided to develop them using an interpreted language: Python. Python 2, the version available at the time, allowed us to develop the *OBITools* efficiently. When parts of the algorithms were computationally demanding, they were implemented in C and linked to the Python code. Even though Python is not the most efficient language available, even though computers were not as powerful as they are today, the size of the data we could produce using 454 sequencers or early solexa machines was small enough to be processed in a reasonable time.\n\nThe first public version of obitools was [*OBITools2*](https://metabarcoding.org/obitools) [@Boyer2016-gq], this was actually a cleaned up and documented version of *OBITools* that had been running at LECA for years and was not really distributed except to a few collaborators. This is where *OBITools* started its public life from then on. The DNA metabarcoding spring schools provided and still provide user training every year. But *OBITools2* soon suffered from two limitations: it was developed in Python2, which was increasingly abandoned in favour of Python3, and the data size kept increasing with the new illumina machines. Python's intrinsic slowness coupled with the increasing size of the datasets made OBITools computation times increasingly long. The abandonment of all maintenance of Python2 by its developers also imposed the need for a new version of OBITools. \n\n[*OBITools3*](https://metabarcoding.org/obitools3) was the first response to this crisis. Developed and maintained by [Céline Mercier](https://www.celine-mercier.info), *OBITools3* attempted to address several limitations of *OBITools2*. It is a complete new code, mainly developed in Python3, with most of the lower layer code written in C for efficiency. OBITools3 has also abandoned text files for binary files for the same reason of efficiency. They have been replaced by a database structure that keeps track of every operation performed on the data. \n\nHere we present *OBITools4* which can be seen as a return to the origins of OBITools. While *OBITools3* offered traceability of analyses, which is in line with the concept of open science, and faster execution, *OBITools2* was more versatile and not only usable for the analysis of DNA metabarcoding data. *OBITools4* is the third full implementation of *OBITools*. The idea behind this new version is to go back to the original design of *OBITools* which ran on text files containing sequences, like the classic Unix commands, but running at least as fast as *OBITools3* and taking advantage of the multicore architecture of all modern laptops. For this, the idea of relying on an interpreted language was abandoned. The *OBITools4* are now fully implemented in the [GO](https://go.dev) language with the exception of a few small pieces of specific code already implemented very efficiently in C. *OBITools4* also implement a new format for the annotations inserted in the header of every sequences. Rather tha relying on a format specific to *OBITools*, by default *OBITools4* use the [JSON](https://www.json.org) format. This simplifies the writing of parsers in any languages, and thus allows obitools to easiestly interact with other software.\n\n",
"supporting": [
"index_files"
],
"filters": [],
"engineDependencies": {
"jupyter": [
{
"jsWidgets": false,
"jupyterWidgets": false,
"htmlLibraries": []
}
]
}
}
}

11
doc/book/_freeze/index/execute-results/html.json Normal file
View File

@ -0,0 +1,11 @@
{
"hash": "0d2b5eca01fd0d516bf9dee813b291f8",
"result": {
"markdown": "```{css}\ncode.sourceCode div.cell-output-stdout {\n font-size: 0.8em;\n}\n\ndiv.cell-output-stdout {\n font-size: 0.8em;\n}\n```\n\n\n# Preface {.unnumbered}\n\nThe first version of *OBITools* started to be developed in 2005. This was at the beginning of the DNA metabarcoding story at the Laboratoire d'Ecologie Alpine (LECA) in Grenoble. At that time, with Pierre Taberlet and François Pompanon, we were thinking about the potential of this new methodology under development. PIerre and François developed more the laboratory methods, while I was thinking more about the tools for analysing the sequences produced. Two ideas were behind this development. I wanted something modular, and something easy to extend. To achieve the first goal, I decided to implement obitools as a suite of unix commands mimicking the classic unix commands but dedicated to sequence files. The basic unix commands are very useful for automatically manipulating, parsing and editing text files. They work in flow, line by line on the input text. The result is a new text file that can be used as input for the next command. Such a design makes it possible to quickly develop a text processing pipeline by chaining simple elementary operations. The *OBITools* are the exact counterpart of these basic Unix commands, but the basic information they process is a sequence (potentially spanning several lines of text), not a single line of text. Most *OBITools* consume sequence files and produce sequence files. Thus, the principles of chaining and modularity are respected. In order to be able to easily extend the *OBITools* to keep up with our evolving ideas about processing DNA metabarcoding data, it was decided to develop them using an interpreted language: Python. Python 2, the version available at the time, allowed us to develop the *OBITools* efficiently. When parts of the algorithms were computationally demanding, they were implemented in C and linked to the Python code. Even though Python is not the most efficient language available, even though computers were not as powerful as they are today, the size of the data we could produce using 454 sequencers or early solexa machines was small enough to be processed in a reasonable time.\n\nThe first public version of obitools was [*OBITools2*](https://metabarcoding.org/obitools) [@Boyer2016-gq], this was actually a cleaned up and documented version of *OBITools* that had been running at LECA for years and was not really distributed except to a few collaborators. This is where *OBITools* started its public life from then on. The DNA metabarcoding spring schools provided and still provide user training every year. But *OBITools2* soon suffered from two limitations: it was developed in Python2, which was increasingly abandoned in favour of Python3, and the data size kept increasing with the new illumina machines. Python's intrinsic slowness coupled with the increasing size of the datasets made OBITools computation times increasingly long. The abandonment of all maintenance of Python2 by its developers also imposed the need for a new version of OBITools. \n\n[*OBITools3*](https://metabarcoding.org/obitools3) was the first response to this crisis. Developed and maintained by [Céline Mercier](https://www.celine-mercier.info), *OBITools3* attempted to address several limitations of *OBITools2*. It is a complete new code, mainly developed in Python3, with most of the lower layer code written in C for efficiency. OBITools3 has also abandoned text files for binary files for the same reason of efficiency. They have been replaced by a database structure that keeps track of every operation performed on the data. \n\nHere we present *OBITools4* which can be seen as a return to the origins of OBITools. While *OBITools3* offered traceability of analyses, which is in line with the concept of open science, and faster execution, *OBITools2* was more versatile and not only usable for the analysis of DNA metabarcoding data. *OBITools4* is the third full implementation of *OBITools*. The idea behind this new version is to go back to the original design of *OBITools* which ran on text files containing sequences, like the classic Unix commands, but running at least as fast as *OBITools3* and taking advantage of the multicore architecture of all modern laptops. For this, the idea of relying on an interpreted language was abandoned. The *OBITools4* are now fully implemented in the [GO](https://go.dev) language with the exception of a few small pieces of specific code already implemented very efficiently in C. *OBITools4* also implement a new format for the annotations inserted in the header of every sequences. Rather tha relying on a format specific to *OBITools*, by default *OBITools4* use the [JSON](https://www.json.org) format. This simplifies the writing of parsers in any languages, and thus allows obitools to easiestly interact with other software.\n\n",
"supporting": [
"index_files/figure-html"
],
"filters": [],
"includes": {}
}
}

10
doc/book/_freeze/index/execute-results/tex.json Normal file
View File

@ -0,0 +1,10 @@
{
"hash": "6372b3136d3b9e38461c2fd369bcdefd",
"result": {
"markdown": "```{css eval=FALSE}\ncode.sourceCode div.cell-output-stdout {\n font-size: 0.8em;\n}\n\ndiv.cell-output-stdout {\n font-size: 0.8em;\n}\n```\n\n\n# Preface {.unnumbered}\n\nThe first version of *OBITools* started to be developed in 2005. This was at the beginning of the DNA metabarcoding story at the Laboratoire d'Ecologie Alpine (LECA) in Grenoble. At that time, with Pierre Taberlet and François Pompanon, we were thinking about the potential of this new methodology under development. PIerre and François developed more the laboratory methods, while I was thinking more about the tools for analysing the sequences produced. Two ideas were behind this development. I wanted something modular, and something easy to extend. To achieve the first goal, I decided to implement obitools as a suite of unix commands mimicking the classic unix commands but dedicated to sequence files. The basic unix commands are very useful for automatically manipulating, parsing and editing text files. They work in flow, line by line on the input text. The result is a new text file that can be used as input for the next command. Such a design makes it possible to quickly develop a text processing pipeline by chaining simple elementary operations. The *OBITools* are the exact counterpart of these basic Unix commands, but the basic information they process is a sequence (potentially spanning several lines of text), not a single line of text. Most *OBITools* consume sequence files and produce sequence files. Thus, the principles of chaining and modularity are respected. In order to be able to easily extend the *OBITools* to keep up with our evolving ideas about processing DNA metabarcoding data, it was decided to develop them using an interpreted language: Python. Python 2, the version available at the time, allowed us to develop the *OBITools* efficiently. When parts of the algorithms were computationally demanding, they were implemented in C and linked to the Python code. Even though Python is not the most efficient language available, even though computers were not as powerful as they are today, the size of the data we could produce using 454 sequencers or early solexa machines was small enough to be processed in a reasonable time.\n\nThe first public version of obitools was [*OBITools2*](https://metabarcoding.org/obitools) [@Boyer2016-gq], this was actually a cleaned up and documented version of *OBITools* that had been running at LECA for years and was not really distributed except to a few collaborators. This is where *OBITools* started its public life from then on. The DNA metabarcoding spring schools provided and still provide user training every year. But *OBITools2* soon suffered from two limitations: it was developed in Python2, which was increasingly abandoned in favour of Python3, and the data size kept increasing with the new illumina machines. Python's intrinsic slowness coupled with the increasing size of the datasets made OBITools computation times increasingly long. The abandonment of all maintenance of Python2 by its developers also imposed the need for a new version of OBITools. \n\n[*OBITools3*](https://metabarcoding.org/obitools3) was the first response to this crisis. Developed and maintained by [Céline Mercier](https://www.celine-mercier.info), *OBITools3* attempted to address several limitations of *OBITools2*. It is a complete new code, mainly developed in Python3, with most of the lower layer code written in C for efficiency. OBITools3 has also abandoned text files for binary files for the same reason of efficiency. They have been replaced by a database structure that keeps track of every operation performed on the data. \n\nHere we present *OBITools4* which can be seen as a return to the origins of OBITools. While *OBITools3* offered traceability of analyses, which is in line with the concept of open science, and faster execution, *OBITools2* was more versatile and not only usable for the analysis of DNA metabarcoding data. *OBITools4* is the third full implementation of *OBITools*. The idea behind this new version is to go back to the original design of *OBITools* which ran on text files containing sequences, like the classic Unix commands, but running at least as fast as *OBITools3* and taking advantage of the multicore architecture of all modern laptops. For this, the idea of relying on an interpreted language was abandoned. The *OBITools4* are now fully implemented in the [GO](https://go.dev) language with the exception of a few small pieces of specific code already implemented very efficiently in C. *OBITools4* also implement a new format for the annotations inserted in the header of every sequences. Rather tha relying on a format specific to *OBITools*, by default *OBITools4* use the [JSON](https://www.json.org) format. This simplifies the writing of parsers in any languages, and thus allows obitools to easiestly interact with other software.\n\n",
"supporting": [
"index_files/figure-pdf"
],
"filters": []
}
}

19
doc/book/_freeze/installation/execute-results/epub.json Normal file
View File

@ -0,0 +1,19 @@
{
"hash": "cdc3ee1d58e10538db75a4867b10ee0e",
"result": {
"markdown": "# Installation of the *OBITools*\n\n## Availability of the *OBITools*\n\nThe *OBITools* are open source and protected by the [CeCILL 2.1 license](http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html).\n\nAll the sources of the [*OBITools4*](http://metabarcoding.org/obitools4) can be downloaded from the metabarcoding git server (https://git.metabarcoding.org).\n\n## Prerequisites\n\nThe *OBITools4* are developped using the [GO programming language](https://go.dev/), we stick to the latest version of the language, today the $1.21.4$. If you want to download and compile the sources yourself, you first need to install the corresponding compiler on your system. Some parts of the soft are also written in C, therefore a recent C compiler is also requested, GCC on Linux or Windows, the Developer Tools on Mac.\n\nWhatever the installation you decide for, you will have to ensure that a C compiler is available on your system.\n\n## Installation with the install script\n\nAn installation script that compiles the new *OBITools* on your Unix-like system is available online.\nThe easiest way to run it is to copy and paste the following command into your terminal\n\n::: {.cell execution_count=1}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | bash\n```\n:::\n\n\nBy default, the script installs the *OBITools* commands and other associated files into the `/usr/local` directory.\nThe names of the commands in the new *OBITools4* are mostly identical to those in *OBITools2*.\nTherefore, installing the new *OBITools* may hide or delete the old ones. If you want both versions to be \navailable on your system, the installation script offers two options:\n\n\n> -i, --install-dir Directory where *OBITools* are installed \n> (as example use `/usr/local` not `/usr/local/bin`).\n> \n> -p, --obitools-prefix Prefix added to the *OBITools* command names if you\n> want to have several versions of obitools at the\n> same time on your system (as example `-p g` will produce \n> `gobigrep` command instead of `obigrep`).\n\nYou can use these options by following the installation command:\n\n::: {.cell execution_count=2}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | \\\n bash -s -- --install-dir test_install --obitools-prefix k\n```\n:::\n\n\nIn this case, the binaries will be installed in the `test_install` directory and all command names will be prefixed with the letter `k`. Thus `obigrep` will be named `kobigrep`.\n\n\n## Compilation from sources\n\n",
"supporting": [
"installation_files/figure-epub"
],
"filters": [],
"engineDependencies": {
"jupyter": [
{
"jsWidgets": false,
"jupyterWidgets": false,
"htmlLibraries": []
}
]
}
}
}

11
doc/book/_freeze/installation/execute-results/html.json Normal file
View File

@ -0,0 +1,11 @@
{
"hash": "cdc3ee1d58e10538db75a4867b10ee0e",
"result": {
"markdown": "# Installation of the *OBITools*\n\n## Availability of the *OBITools*\n\nThe *OBITools* are open source and protected by the [CeCILL 2.1 license](http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html).\n\nAll the sources of the [*OBITools4*](http://metabarcoding.org/obitools4) can be downloaded from the metabarcoding git server (https://git.metabarcoding.org).\n\n## Prerequisites\n\nThe *OBITools4* are developped using the [GO programming language](https://go.dev/), we stick to the latest version of the language, today the $1.21.4$. If you want to download and compile the sources yourself, you first need to install the corresponding compiler on your system. Some parts of the soft are also written in C, therefore a recent C compiler is also requested, GCC on Linux or Windows, the Developer Tools on Mac.\n\nWhatever the installation you decide for, you will have to ensure that a C compiler is available on your system.\n\n## Installation with the install script\n\nAn installation script that compiles the new *OBITools* on your Unix-like system is available online.\nThe easiest way to run it is to copy and paste the following command into your terminal\n\n::: {.cell execution_count=1}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | bash\n```\n:::\n\n\nBy default, the script installs the *OBITools* commands and other associated files into the `/usr/local` directory.\nThe names of the commands in the new *OBITools4* are mostly identical to those in *OBITools2*.\nTherefore, installing the new *OBITools* may hide or delete the old ones. If you want both versions to be \navailable on your system, the installation script offers two options:\n\n\n> -i, --install-dir Directory where *OBITools* are installed \n> (as example use `/usr/local` not `/usr/local/bin`).\n> \n> -p, --obitools-prefix Prefix added to the *OBITools* command names if you\n> want to have several versions of obitools at the\n> same time on your system (as example `-p g` will produce \n> `gobigrep` command instead of `obigrep`).\n\nYou can use these options by following the installation command:\n\n::: {.cell execution_count=2}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | \\\n bash -s -- --install-dir test_install --obitools-prefix k\n```\n:::\n\n\nIn this case, the binaries will be installed in the `test_install` directory and all command names will be prefixed with the letter `k`. Thus `obigrep` will be named `kobigrep`.\n\n\n## Compilation from sources\n\n",
"supporting": [
"installation_files/figure-html"
],
"filters": [],
"includes": {}
}
}

10
doc/book/_freeze/installation/execute-results/tex.json Normal file
View File

@ -0,0 +1,10 @@
{
"hash": "cdc3ee1d58e10538db75a4867b10ee0e",
"result": {
"markdown": "# Installation of the *OBITools*\n\n## Availability of the *OBITools*\n\nThe *OBITools* are open source and protected by the [CeCILL 2.1 license](http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html).\n\nAll the sources of the [*OBITools4*](http://metabarcoding.org/obitools4) can be downloaded from the metabarcoding git server (https://git.metabarcoding.org).\n\n## Prerequisites\n\nThe *OBITools4* are developped using the [GO programming language](https://go.dev/), we stick to the latest version of the language, today the $1.21.4$. If you want to download and compile the sources yourself, you first need to install the corresponding compiler on your system. Some parts of the soft are also written in C, therefore a recent C compiler is also requested, GCC on Linux or Windows, the Developer Tools on Mac.\n\nWhatever the installation you decide for, you will have to ensure that a C compiler is available on your system.\n\n## Installation with the install script\n\nAn installation script that compiles the new *OBITools* on your Unix-like system is available online.\nThe easiest way to run it is to copy and paste the following command into your terminal\n\n::: {.cell execution_count=1}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | bash\n```\n:::\n\n\nBy default, the script installs the *OBITools* commands and other associated files into the `/usr/local` directory.\nThe names of the commands in the new *OBITools4* are mostly identical to those in *OBITools2*.\nTherefore, installing the new *OBITools* may hide or delete the old ones. If you want both versions to be \navailable on your system, the installation script offers two options:\n\n\n> -i, --install-dir Directory where *OBITools* are installed \n> (as example use `/usr/local` not `/usr/local/bin`).\n> \n> -p, --obitools-prefix Prefix added to the *OBITools* command names if you\n> want to have several versions of obitools at the\n> same time on your system (as example `-p g` will produce \n> `gobigrep` command instead of `obigrep`).\n\nYou can use these options by following the installation command:\n\n::: {.cell execution_count=2}\n``` {.bash .cell-code}\ncurl -L https://metabarcoding.org/obitools4/install.sh | \\\n bash -s -- --install-dir test_install --obitools-prefix k\n```\n:::\n\n\nIn this case, the binaries will be installed in the `test_install` directory and all command names will be prefixed with the letter `k`. Thus `obigrep` will be named `kobigrep`.\n\n\n## Compilation from sources\n\n",
"supporting": [
"installation_files/figure-pdf"
],
"filters": []
}
}

4
doc/book/_quarto.yml
View File

@ -41,12 +41,14 @@ execute:
format:
html:
theme: zephyr
embed-resources: true
pdf:
documentclass: scrreprt
keep-tex: true
epub:
html-math-method: mathml
code-overflow: scroll
css: epub.css

BIN
doc/book/comm_computation_files/figure-epub/unnamed-chunk-1-1.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 19 KiB

BIN
doc/book/comm_computation_files/figure-html/unnamed-chunk-1-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

1
doc/book/comm_metabarcode_design.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
c9abc6ef1d9b10058625347639c0a133059bfe90

0
doc/book/comm_reformat.html Normal file
View File

1
doc/book/commands.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
9be990e7b56476a941dcdd1d074f31e666ec8dc8

1
doc/book/common_options.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
4e6501bd48200758a94734704f075dcadd97a712

0
doc/book/epub.css Normal file
View File

1
doc/book/expressions.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
fcbb404e0aba238ccfab3f5e1ca388985be78115

1
doc/book/formats.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
3c08c12ad322472ca9f3f1137e6dcc9fc9c504b1

167
doc/book/formats.qmd
View File

@ -1,23 +1,20 @@
# File formats usable with *OBITools*
OBITools manipulate have to manipulate DNA sequence data and taxonomical data.
They can use some supplentary metadata describing the experiment and produce
some stats about the processed DNA data. All the manipulated data are stored in
text files, following standard data format.
*OBITools* manipulate have to manipulate DNA sequence data and taxonomical data. They can use some supplentary metadata describing the experiment and produce some stats about the processed DNA data. All the manipulated data are stored in text files, following standard data format.
# The DNA sequence data
## The DNA sequence data
Sequences can be stored following various format. OBITools knows some of them. The central formats for sequence files manipulated by OBITools scripts are the [`fasta`](#the-fasta-sequence-format) and [`fastq`](#the-fastq-sequence-format) format. OBITools extends the both these formats by specifying a syntax to include in the definition line data qualifying the sequence. All file formats use the `IUPAC` code for encoding nucleotides.
Sequences can be stored following various format. *OBITools* knows some of them. The central formats for sequence files manipulated by *OBITools* scripts are the [*FASTA*](#sec-fasta) and [*FASTQ*](#sec-fastq) format. *OBITools* extends the both these formats by specifying a syntax to include in the definition line data qualifying the sequence. All file formats use the [`IUPAC`](#sec-iupac) code for encoding nucleotides.
Moreover these two formats that can be used as input and output formats, **OBITools4** can read the following format :
Moreover these two formats that can be used as input and output formats, *OBITools4* can read the following format :
- [EBML flat file](https://ena-docs.readthedocs.io/en/latest/submit/fileprep/flat-file-example.html) format (use by ENA)
- [Genbank flat file format](https://www.ncbi.nlm.nih.gov/Sitemap/samplerecord.html)
- [ecoPCR output files](https://pythonhosted.org/OBITools/scripts/ecoPCR.html)
- [EBML flat file](https://ena-docs.readthedocs.io/en/latest/submit/fileprep/flat-file-example.html) format (use by ENA)
- [Genbank flat file format](https://www.ncbi.nlm.nih.gov/Sitemap/samplerecord.html)
- [ecoPCR output files](https://pythonhosted.org/OBITools/scripts/ecoPCR.html)
## The IUPAC Code
### The IUPAC Code {#sec-iupac}
The International Union of Pure and Applied Chemistry (IUPAC\_) defined the standard code for representing protein or DNA sequences.
The International Union of Pure and Applied Chemistry ([IUPAC]()) defined the standard code for representing protein or DNA sequences.
| **Code** | **Nucleotide** |
|----------|-----------------------------|
@ -38,48 +35,59 @@ The International Union of Pure and Applied Chemistry (IUPAC\_) defined the stan
| V | A, C, or G (not T, not U) |
| N | Any base (A, C, G, T, or U) |
## The *fasta* sequence format {#sec-fasta}
### The *FASTA* sequence format {#sec-fasta}
The **fasta format** is certainly the most widely used sequence file format. This is certainly due to its great simplicity. It was originally created for the Lipman and Pearson [FASTA program](http://www.ncbi.nlm.nih.gov/pubmed/3162770?dopt=Citation). OBITools use in more of the classical `fasta` format an `extended version` of this format where structured data are included in the title line.
The [*FASTA*](#sec-fasta) format is certainly the most widely used sequence file format. This is certainly due to its great simplicity. It was originally created for the Lipman and Pearson [`FASTA` program](http://www.ncbi.nlm.nih.gov/pubmed/3162770?dopt=Citation). *OBITools* use in more of the classical [*FASTA*](#sec-fasta) format an `extended version` of this format where structured data are included in the title line.
In *fasta* format a sequence is represented by a title line beginning with a **`>`** character and the sequences by itself following the :doc:`iupac` code. The sequence is usually split other severals lines of the same length (expect for the last one)
In [*FASTA*](#sec-fasta) format a sequence is represented by a title line beginning with a **`>`** character and the sequences by itself following the [`IUPAC`](#sec-iupac) code. The sequence is usually split other severals lines of the same length (expect for the last one)
>my_sequence this is my pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
```
>my_sequence this is my pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
```
This is no special format for the title line excepting that this line should be unique. Usually the first word following the **\>** character is considered as the sequence identifier. The end of the title line corresponding to a description of the sequence. Several sequences can be concatenated in a same file. The description of the next sequence is just pasted at the end of the record of the previous one
>sequence_A this is my first pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
>sequence_B this is my second pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
>sequence_C this is my third pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
## The *fastq* sequence format[^01_obitools_doc-1]{#sec-fastq}
The **FASTQ** format is a text file format for storing both biological sequences (only nucleic acid sequences) and the associated quality scores. The sequence and score are each encoded by a single ASCII character. This format was originally developed by the Wellcome Trust Sanger Institute to link a [FASTA](#the-fasta-sequence-format) sequence file to the corresponding quality data, but has recently become the de facto standard for storing results from high-throughput sequencers [@cock2010sanger].
[^01_obitools_doc-1]: This article uses material from the Wikipedia article [`FASTQ format`](http://en.wikipedia.org/wiki/FASTQ_format) which is released under the `Creative Commons Attribution-Share-Alike License 3.0`
A fastq file normally uses four lines per sequence.
- Line 1 begins with a '\@' character and is followed by a sequence identifier and an *optional* description (like a :ref:`fasta` title line).
- Line 2 is the raw sequence letters.
- Line 3 begins with a '+' character and is *optionally* followed by the same sequence identifier (and any description) again.
- Line 4 encodes the quality values for the sequence in Line 2, and must contain the same number of symbols as letters in the sequence.
A fastq file containing a single sequence might look like this:
```
>sequence_A this is my first pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
>sequence_B this is my second pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
>sequence_C this is my third pretty sequence
ACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGT
GTGCTGACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTACGTTGCAGTGTTT
AACGACGTTGCAGTACGTTGCAGT
```
#### File extensions
There is no standard file extension for a [*FASTA*](#sec-fasta) file, but `.fa` and `.fasta`, are commonly used.
### The *FASTQ* sequence format[^formats-1] {#sec-fastq}
[^formats-1]: This article uses material from the Wikipedia article [`FASTQ format`](http://en.wikipedia.org/wiki/FASTQ_format) which is released under the `Creative Commons Attribution-Share-Alike License 3.0`
The [*FASTQ*](#sec-fastq) format is a text file format for storing both biological sequences (only nucleic acid sequences) and the associated sequence quality scores. Every nucleotide of the sequence and its associated quality score are each encoded by a single ASCII character. This format was originally developed by the Wellcome Trust Sanger Institute to link a [*FASTA*](#sec-fasta) sequence file to the corresponding quality data, but is now became the *de facto* standard for storing results from high-throughput sequencers [@cock2010sanger].
*OBITools* considers that a [*FASTQ*](#sec-fastq) file uses four lines to encode a sequence record.
- Line 1 begins with a '\@' character and is followed by a sequence identifier and an *optional* description
(like a [*FASTA*](#sec-fasta) title line).
- Line 2 is the sequence letters, in upper or lower case, but *OBITools* only write sequences as lower cases.
- Line 3 begins with a '+' character and is *optionally* followed by the same sequence identifier
(and any description) again.
- Line 4 encodes the quality values for the sequence in Line 2, and must contain the same number of
symbols as letters in the sequence.
A [*FASTQ*](#sec-fastq) file looks like this:
```
@SEQ_ID
GATTTGGGGTTCAAAGCAGTATCGATCAAATAGTAAATCCATTTGTTCAACTCACAGTTT
+
@ -88,16 +96,16 @@ GATTTGGGGTTCAAAGCAGTATCGATCAAATAGTAAATCCATTTGTTCAACTCACAGTTT
The character '!' represents the lowest quality while '\~' is the highest. Here are the quality value characters in left-to-right increasing order of quality (`ASCII`):
```
```
!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]
^_`abcdefghijklmnopqrstuvwxyz{|}~
```
The original Sanger FASTQ files also allowed the sequence and quality strings to be wrapped (split over multiple lines), but this is generally discouraged as it can make parsing complicated due to the unfortunate choice of "\@" and "+" as markers (these characters can also occur in the quality string).
If the original Sanger [*FASTQ*](#sec-fastq) files also allowed the sequence and quality strings to be wrapped (split over multiple lines), it is not supported by *OBITools* as it make parsing complicated due to the unfortunate choice of "\@" and "+" as markers (these characters can also occur in the quality string).
### Sequence quality scores{.unnumbered}
#### Sequence quality scores {.unnumbered}
The Phred quality value *Q* is an integer mapping of *p* (i.e., the probability that the corresponding base call is incorrect). Two different equations have been in use. The first is the standard Sanger variant to assess reliability of a base call, otherwise known as Phred quality score:
The Phred quality value *Q* is an integer mapping of *p* (*i.e.*, the probability that the corresponding base call is incorrect). Two different equations have been in use. The first is the standard Sanger variant to assess reliability of a base call, otherwise known as Phred quality score:
$$
Q_\text{sanger} = -10 \, \log_{10} p
@ -113,24 +121,18 @@ Although both mappings are asymptotically identical at higher quality values, th
![Relationship between *Q* and *p* using the Sanger (red) and Solexa (black) equations (described above). The vertical dotted line indicates $\mathbf{p}= 0.05$, or equivalently, $Q = 13$.](Probabilitymetrics.png){#fig-Probabilitymetrics}
##### Encoding {.unnumbered}
#### Encoding{.unnumbered}
The *fastq* format had differente way of encoding the Phred quality score along the time. Here a breif history of these changes is presented.
The [*FASTQ*](#sec-fastq) format had differente way of encoding the Phred quality score along the time. Here a breif history of these changes is presented. *OBITools*
- Sanger format can encode a Phred quality score from 0 to 93 using ASCII 33 to 126 (although in raw read data the Phred quality score rarely exceeds 60, higher scores are possible in assemblies or read maps).
- Solexa/Illumina 1.0 format can encode a Solexa/Illumina quality score from -5 to 62 using ASCII 59 to 126 (although in raw read data Solexa scores from -5 to 40 only are expected)
- Starting with Illumina 1.3 and before Illumina 1.8, the format encoded a Phred quality score from 0 to 62 using ASCII 64 to 126 (although in raw read data Phred scores from 0 to 40 only are expected).
- Starting in Illumina 1.5 and before Illumina 1.8, the Phred scores 0 to 2 have a slightly different meaning. The values 0 and 1 are no longer used and the value 2, encoded by ASCII 66 "B".
> Sequencing Control Software, Version 2.6, (Catalog \# SY-960-2601, Part \# 15009921 Rev. A, November 2009, page 30)
> states the following: *If a read ends with a segment of mostly low quality (Q15 or below), then all of the quality
> values in the segment are replaced with a value of 2 (encoded as the letter B in Illumina's text-based encoding of
> quality scores)... This Q2 indicator does not predict a specific error rate, but rather indicates that a specific
> final portion of the read should not be used in further analyses.* Also, the quality score encoded as "B" letter
> may occur internally within reads at least as late as pipeline version 1.6, as shown in the following example:
> Sequencing Control Software, Version 2.6, (Catalog \# SY-960-2601, Part \# 15009921 Rev. A, November 2009, page 30) states the following: *If a read ends with a segment of mostly low quality (Q15 or below), then all of the quality values in the segment are replaced with a value of 2 (encoded as the letter B in Illumina's text-based encoding of quality scores)... This Q2 indicator does not predict a specific error rate, but rather indicates that a specific final portion of the read should not be used in further analyses.* Also, the quality score encoded as "B" letter may occur internally within reads at least as late as pipeline version 1.6, as shown in the following example:
```
```
@HWI-EAS209_0006_FC706VJ:5:58:5894:21141#ATCACG/1
TTAATTGGTAAATAAATCTCCTAATAGCTTAGATNTTACCTTNNNNNNNNNNTAGTTTCTTGAGA
TTTGTTGGGGGAGACATTTTTGTGATTGCCTTGAT
@ -143,8 +145,45 @@ An alternative interpretation of this ASCII encoding has been proposed. Also, in
- Starting in Illumina 1.8, the quality scores have basically returned to the use of the Sanger format (Phred+33).
OBItools follows the Sanger format. Nevertheless, It is possible to read files encoded following the Solexa/Illumina format by applying a shift of 62 (see the option **\--solexa** of the OBITools commands).
*OBITools* follows the Sanger format. Nevertheless, It is possible to read files encoded following the Solexa/Illumina format by applying a shift of 62 (see the option **--solexa** of the *OBITools* commands).
## File extension
#### File extensions
There is no standard file extension for a FASTQ file, but .fq and .fastq, are commonly used.
There is no standard file extension for a [*FASTQ*](#sec-fastq) file, but `.fq` and `.fastq`, are commonly used.
## The taxonomy files
Many OBITools are able to take into account taxonomic data. This is done by specifying
a directory containing all :doc:`NCBI taxonomy dump files <./taxdump>`.
## The sample description file
A key file for *OBITools4* is the file describing all samples (PCR) analyzed in the processed sequencing library file.
This file, often called the `ngsfilter` file, is a tab separated values (TSV) file. The format of this file is exactly
identical to that used in *OBITools2* and *OBITools4*.
```{tsv, .smaller}
wolf_diet 13a_F730603 aattaac TTAGATACCCCACTATGC TAGAACAGGCTCCTCTAG F
wolf_diet 15a_F730814 gaagtag TTAGATACCCCACTATGC TAGAACAGGCTCCTCTAG F
wolf_diet 26a_F040644 gaatatc TTAGATACCCCACTATGC TAGAACAGGCTCCTCTAG F
wolf_diet 29a_F260619 gcctcct TTAGATACCCCACTATGC TAGAACAGGCTCCTCTAG F
```
At least six columns must be present in every line of the file.
- The first column contains the name of the experience:
An experiment name groups a set of sample together. Sequences belonging to the experiment are
tagged with an attribute `experiment` containing the name of the experiment in their annotation.
- The second column contains the sample identifier in the experiment
The sample identifier must be unique in the experiment. The `obimultiplex` and `obitagpcr` commands add
to all the sequences bellonging to the same sample an attribute `sample` containing the sample identifier
- The third column contains description of the tag used to identify sequences corresponding to this sample
- The fourth column contains the forward primer sequence
- The fifth column contains the reverse primer sequence
- The sixth column must always contain the character `F` (full length)

4304
doc/book/index.html Normal file
View File

File diff suppressed because one or more lines are too long

1
doc/book/installation.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
66c05db68b31d840135dabdb2bfa4ddee8fd3957

39
doc/book/installation.qmd
View File

@ -1,6 +1,6 @@
# Installation of the obitools
# Installation of the *OBITools*
## Availability of the OBITools
## Availability of the *OBITools*
The *OBITools* are open source and protected by the [CeCILL 2.1 license](http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.html).
@ -8,11 +8,44 @@ All the sources of the [*OBITools4*](http://metabarcoding.org/obitools4) can be
## Prerequisites
The *OBITools4* are developped using the [GO programming language](https://go.dev/), we stick to the latest version of the language, today the $1.19.5$. If you want to download and compile the sources yourself, you first need to install the corresponding compiler on your system. Some parts of the soft are also written in C, therefore a recent C compiler is also requested, GCC on Linux or Windows, the Developer Tools on Mac.
The *OBITools4* are developped using the [GO programming language](https://go.dev/), we stick to the latest version of the language, today the $1.21.4$. If you want to download and compile the sources yourself, you first need to install the corresponding compiler on your system. Some parts of the soft are also written in C, therefore a recent C compiler is also requested, GCC on Linux or Windows, the Developer Tools on Mac.
Whatever the installation you decide for, you will have to ensure that a C compiler is available on your system.
## Installation with the install script
An installation script that compiles the new *OBITools* on your Unix-like system is available online.
The easiest way to run it is to copy and paste the following command into your terminal
```{bash}
#| eval: false
curl -L https://metabarcoding.org/obitools4/install.sh | bash
```
By default, the script installs the *OBITools* commands and other associated files into the `/usr/local` directory.
The names of the commands in the new *OBITools4* are mostly identical to those in *OBITools2*.
Therefore, installing the new *OBITools* may hide or delete the old ones. If you want both versions to be
available on your system, the installation script offers two options:
> -i, --install-dir Directory where *OBITools* are installed
> (as example use `/usr/local` not `/usr/local/bin`).
>
> -p, --obitools-prefix Prefix added to the *OBITools* command names if you
> want to have several versions of obitools at the
> same time on your system (as example `-p g` will produce
> `gobigrep` command instead of `obigrep`).
You can use these options by following the installation command:
```{bash}
#| eval: false
curl -L https://metabarcoding.org/obitools4/install.sh | \
bash -s -- --install-dir test_install --obitools-prefix k
```
In this case, the binaries will be installed in the `test_install` directory and all command names will be prefixed with the letter `k`. Thus `obigrep` will be named `kobigrep`.
## Compilation from sources

1
doc/book/intro.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
396888557eb60df9c0c43140545cb945f94dba19

1
doc/book/inupt.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
6190e7e7d926a7ed289145ae9808076d3a5e5e18

1
doc/book/output.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
aaa1261fd473ee852e6462abb4cefae7eb36a486

33610
doc/book/results/toto.tasta Normal file
View File

File diff suppressed because it is too large Load Diff

1
doc/book/tutorial.html.REMOVED.git-id Normal file
View File

@ -0,0 +1 @@
568390348c10625dee9c6f3d6d1a3ba54a08aee3

BIN
doc/book/tutorial_files/figure-html/unnamed-chunk-10-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 46 KiB

BIN
doc/book/tutorial_files/figure-html/unnamed-chunk-9-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 45 KiB

BIN
doc/book/tutorial_files/figure-pdf/unnamed-chunk-10-1.pdf Normal file
View File

Binary file not shown.

BIN
doc/book/tutorial_files/figure-pdf/unnamed-chunk-9-1.pdf Normal file
View File

Binary file not shown.