deletions | additions
diff --git a/Concepts.tex b/Concepts.tex
index 38200cd..2c185a3 100644
--- a/Concepts.tex
+++ b/Concepts.tex
...
of background and gamma factor on the burst size and can lead to a selection
bias of certain channels and/or sub-populations.
For this reason we advocate performing a burst size selection after background
correction and taking into account the gamma factor, as
illustrated discussed in
section~\ref{sec:burstsel}.
diff --git a/Introduction.tex b/Introduction.tex
index 0bba9fd..61d4427 100644
--- a/Introduction.tex
+++ b/Introduction.tex
...
\subsection{What is FRETBursts}
FRETBursts is an open source python software for burst analysis of freely-diffusing
single-molecule Förster Resonance Energy Transfer (smFRET) data.
The software can analyze smFRET measurements
from one or multiple excitation spots~\cite{Ingargiola_2013}. The supported
excitation schemes include single laser, alternating laser excitation (ALEX)
with either CW lasers (µs-ALEX \cite{Kapanidis_2005})
or interleaved pulsed lasers (ns-ALEX~\cite{Laurence_2005} or
Pulsed-Interleaved Excitation (PIE) \cite{M_ller_2005}).
FRETBursts is hosted and openly developed~\cite{Prli__2012} on GitHub, which
simplifies managing issues, feature requests and user contributions.
\subsection{Features overview}
FRETBursts implements both standard and novel algorithms for smFRET data analysis
including background estimation as a function of time (including background accuracy
metrics), sliding-window burst search~\cite{Eggeling_1998}, dual-channel bursts search~\cite{Nir_2006} and
generic and composable burst selection methods based on user-defined criteria
(including a large set of pre-defined selection rules). Novel features include burst size
selection with gamma-corrected burst size, burst weighting, burst search with background-
dependent threshold (in order to guarantee a minimal single-to background ratio~\cite{Michalet_2012}).
Moreover, a large set of FRET distribution fitting options are provided including
FRET distribution fitting through (1) histogram fitting (with arbitrary model functions),
(2) non-parametric weighted \textit{Kernel Density Estimation} (KDE), (3) weighted
Expectation Maximization (EM), (4) Maximum Likelihood fitting using Gaussian models
or Poisson statistic. Finally FRETBursts includes a large number of
predefined and customizable plot functions which (thanks to the \textit{matplotlib}
graphic library) produce publication quality plots in a wide range of formats.
\subsection{Development style}
FRETBursts (and the entire python ecosystem it depends on) is open source
and the source code is fully available for any scientist to study,
review and modify.
The authors encourage users to use GitHub issues for questions, discussions
and bug reports, and to submit patches through GitHub pull requests.
In order to minimize the likelihood of bugs and erroneous results, FRETBursts is developed
following modern software engineering techniques such
as defensive programming, unit testing, regression testing and continuous integration~\cite{Wilson_2014}.
The open source nature of FRETBursts and of the python ecosystem,
not only makes it a more transparent, reviewable platform
for scientific data analysis, but also allows
to leverage state-of-the-art online services as \href{http://https://github.com}{GitHub} for hosting,
issues tracking and code reviews,
\href{https://travis-ci.org}{TravisCI} for continuous integration
(i.e. automated test suite execution on multiple platforms after each commit)
and \href{https://readthedocs.org/}{ReadTheDocs.org} for automatic documentation building and hosting.
All these services would be extremely costly, if at all available,
for a proprietary software or platform.
\subsection{FRETBursts and Jupyter Notebook}
The preferential way to execute FRETBursts is executing one of the tutorials
which are in the form of \href{http://ipython.org/notebook.html}{Jupyter notebooks}.
Jupyter (formerly IPython) notebooks are web-based documents which contain both
code and rich text (including equations, hyperlinks, figures, etc...).
FRETBursts tutorials are notebooks which can be re-executed,
modified or used to process new data files with minimal modifications.
The "notebook workflow"\cite{Shen_2014} not only facilitates
the description of the analysis (by integrating the code in a rich document)
but also greatly enhance its reproducibility by storing an execution trail
that includes software versions, input files, parameters, commands and all
the analysis results (text, figures, tables, etc...).
Given the modality of execution, running The Jupyter Notebook environment streamlines FRETBursts execution (compared to
a traditional script and terminal based approach) and therefore
FRETBursts
does not require can be used even without any prior python knowledge.
The user only needs to get familiar with the
notebook graphical environment, in order to be able to navigate and run the notebooks.
The list of FRETBursts notebooks can be found in the
\verb|FRETBursts_notebooks| repository on GitHub.
\subsection{Paper overview and further resources}
Although running the software is technically simple, understanding the smFRET
burst analysis requires several concepts and definitions.
In this paper we aim to provide a brief introduction to smFRET analysis concepts
and terminology used by FRETBursts. We illustrate how to perform
the fundamental steps of burst analysis, highlighting key parameters
and algorithms available. We will not cover extensively all the FRETBursts
features and options. For more detailed information, the interested readers can refer
to the FRETBursts Reference Documentation and to the source code (that we strive
to make readable and well commented).
Furthermore, users can ask question about FRETBursts use by opening a new issue on GitHub.
The present paper is structured as follows.
In the next subsections, we briefly describe how to install~(\ref{sec:install}) and
load~(\ref{sec:import}) FRETBursts.
In section~\ref{sec:concepts}, we
introduce a few preliminary concepts and some specific terminology needed
to understand the smFRET burst analysis.
In section~\ref{sec:analysis}, we detail the execution the several steps involved
in smFRET burst analysis: data loading (section~\ref{sec:dataload}), defining
excitation alternation periods (section~\ref{sec:alternation}), background
correction (section~\ref{sec:bg_calc}), burst search (section~\ref{sec:burstsearch}),
burst selection (section~\ref{sec:burstsel}) and FRET fitting (section~\ref{sec:fretfit}).
The aim is to provide enough information to understand the specificities of
the different algorithms and to be able to adapt the analysis to new situations.
Finally, in section~\ref{sec:conclusions}, we summarize what we believe to be
the strengths of FRETBursts software.
In addition to this paper, we refer the interested readers to the
\href{http://nbviewer.ipython.org/github/tritemio/FRETBursts_notebooks/blob/master/notebooks/FRETBursts\%20-\%20us-ALEX\%20smFRET\%20burst\%20analysis.ipynb}{FRETBursts µs-ALEX tutorial}
for a single complete example of µs-ALEX data analysis and to the
\href{http://fretbursts.readthedocs.org/}{FRETBursts Reference Documentation}
for a more in-depth description of the software.
The reference documentation
includes also a special section describing how to install and run the software
for users without any prior python knowledge.
Finally, in order to make this paper accessible to the widest number of readers,
we concentrated python-specific details in special subsections titled
\textit{Python details}. These subsections provide deeper insights for readers
already familiar with python and can be safely skipped otherwise. Note also
that all commands shown in this paper can be found in the FRETBursts tutorial notebook
and, in general, do not need to be re-typed.
\subsection{Installing FRETBursts}
\label{sec:install}
Installing FRETBursts is analogous to installing any standard python
package. The python interpreter needs to be installed, preferentially
through a scientific python distribution which conveniently includes
all the major scientific libraries.
For new python users we suggest installing
\href{https://store.continuum.io/cshop/anaconda/}{Continuum Anaconda}
python distribution and then install (or update) FRETBursts with the command:
\begin{verbatim}
conda install fretbursts -c tritemio
\end{verbatim}
For more information on different installation methods refer to the
\href{http://fretbursts.readthedocs.org/en/latest/getting_started.html}{Getting Started}
section in the FRETBursts documentation.
FRETBursts depends on a standard set of scientific
python libraries, namely, \href{http://www.numpy.org/}{numpy}/\href{http://www.scipy.org/}{scipy} for numerical computations,
\href{http://matplotlib.org/}{matplotlib} and \href{http://stanford.edu/~mwaskom/software/seaborn/}{seaborn} for plotting. Non-mandatory dependencies include \href{http://cython.org/}{cython} (used to speed up the execution of a few core functions)
and \href{http://ipython.org/notebook.html}{Jupyter Notebook} that can be used
to execute the tutorials.
A complete list of dependencies can be found in the
\href{http://fretbursts.readthedocs.org/en/latest/getting_started.html}{Getting Started}
section in the FRETBursts documentation.
\subsection{Loading FRETBursts}
\label{sec:import}
In this article, we assume that FRETBursts is loaded using the following
import line:
\begin{verbatim}
from fretbursts import *
\end{verbatim}
After this import, all the FRETBursts functions and objects will be accessible.
The previous line will also import \verb|numpy| and \verb|matplotlib.pyplot|
respectively as \verb|np| and \verb|plt|.
The previous import is also used in the FRETBursts tutorials.
