%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax

\PassOptionsToPackage{warn}{textcomp}
\usepackage[utf8]{inputenc}
\ifdefined\DeclareUnicodeCharacter
% support both utf8 and utf8x syntaxes
  \ifdefined\DeclareUnicodeCharacterAsOptional
    \def\sphinxDUC#1{\DeclareUnicodeCharacter{"#1}}
  \else
    \let\sphinxDUC\DeclareUnicodeCharacter
  \fi
  \sphinxDUC{00A0}{\nobreakspace}
  \sphinxDUC{2500}{\sphinxunichar{2500}}
  \sphinxDUC{2502}{\sphinxunichar{2502}}
  \sphinxDUC{2514}{\sphinxunichar{2514}}
  \sphinxDUC{251C}{\sphinxunichar{251C}}
  \sphinxDUC{2572}{\textbackslash}
\fi
\usepackage{cmap}
\usepackage[T1]{fontenc}
\usepackage{amsmath,amssymb,amstext}
\usepackage{babel}



\usepackage{times}
\expandafter\ifx\csname T@LGR\endcsname\relax
\else
% LGR was declared as font encoding
  \substitutefont{LGR}{\rmdefault}{cmr}
  \substitutefont{LGR}{\sfdefault}{cmss}
  \substitutefont{LGR}{\ttdefault}{cmtt}
\fi
\expandafter\ifx\csname T@X2\endcsname\relax
  \expandafter\ifx\csname T@T2A\endcsname\relax
  \else
  % T2A was declared as font encoding
    \substitutefont{T2A}{\rmdefault}{cmr}
    \substitutefont{T2A}{\sfdefault}{cmss}
    \substitutefont{T2A}{\ttdefault}{cmtt}
  \fi
\else
% X2 was declared as font encoding
  \substitutefont{X2}{\rmdefault}{cmr}
  \substitutefont{X2}{\sfdefault}{cmss}
  \substitutefont{X2}{\ttdefault}{cmtt}
\fi


\usepackage[Bjarne]{fncychap}
\usepackage{sphinx}

\fvset{fontsize=\small}
\usepackage{geometry}


% Include hyperref last.
\usepackage{hyperref}
% Fix anchor placement for figures with captions.
\usepackage{hypcap}% it must be loaded after hyperref.
% Set up styles of URL: it should be placed after hyperref.
\urlstyle{same}
\addto\captionsenglish{\renewcommand{\contentsname}{Contents:}}

\usepackage{sphinxmessages}
\setcounter{tocdepth}{1}



\title{esgemme}
\date{May 05, 2023}
\release{1.3.0}
\author{Mustafa Tekpinar}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\pagestyle{empty}
\sphinxmaketitle
\pagestyle{plain}
\sphinxtableofcontents
\pagestyle{normal}
\phantomsection\label{\detokenize{index::doc}}



\chapter{Using ESGEMME via Docker}
\label{\detokenize{docker:using-esgemme-via-docker}}\label{\detokenize{docker::doc}}

\section{Requirements}
\label{\detokenize{docker:requirements}}
You need to have docker installed on your machine. You can consult the
following page for this: \sphinxurl{https://docs.docker.com/get-docker/}

I am assuming some basic familiarity with Linux/Unix/MacOS terminal
commands.

Let’s start our favorite terminal app.

You must to create a folder called docker\sphinxhyphen{}tutorial and go to that empty
folder:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
mkdir docker\PYGZhy{}tutorial
\PYG{n+nb}{cd} docker\PYGZhy{}tutorial
\end{sphinxVerbatim}


\section{Getting the input data}
\label{\detokenize{docker:getting-the-input-data}}
Let’s download the sample data provided in the ESGEMME repository for
this exercise. First, we will download the multiple sequence alignment
file in fasta format:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
wget http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/blob/master/data/aliBLAT.fasta
\end{sphinxVerbatim}

If you don’t have wget, you can try the same command with curl:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
curl http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/blob/master/data/aliBLAT.fasta
\end{sphinxVerbatim}

Please verify that the aliBLAT.fasta file is in the folder.

Now, we will download the PDB (Protein Databank) file for BLAT:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
wget http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/blob/master/data/blat\PYGZhy{}af2.pdb
\end{sphinxVerbatim}


\section{Single point mutation calculations}
\label{\detokenize{docker:single-point-mutation-calculations}}
In order to make sure that the docker is installed:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
sudo docker \PYGZhy{}h
\end{sphinxVerbatim}

If it shows you a list of options, you are on a good track. On MacOS,
you may not need ‘sudo’ word before the docker command at all.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
sudo docker run \PYGZhy{}ti \PYGZhy{}\PYGZhy{}rm \PYGZhy{}\PYGZhy{}mount \PYG{n+nv}{type}\PYG{o}{=}bind,source\PYG{o}{=}\PYG{n+nv}{\PYGZdl{}PWD},target\PYG{o}{=}/home/tekpinar/research/myexample \PYG{l+s+se}{\PYGZbs{}}
tekpinar/esgemme\PYGZhy{}docker:v1.3.0
\end{sphinxVerbatim}

You are in the container (your virtual operating system) now. You
created a folder called myexample in your container with the previous
command. Let’s change to that folder.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nb}{cd} ../myexample/
\end{sphinxVerbatim}

When you check the data in that folder with ‘ls’ command, you are
supposed to see aliBLAT.fasta and blat\sphinxhyphen{}af2.pdb files. Basically, your
docker\sphinxhyphen{}tutorial folder on the host system and myexample folder on the
docker container are pointing to the same place.


\subsection{Obtaining the entire single point mutation landscape}
\label{\detokenize{docker:obtaining-the-entire-single-point-mutation-landscape}}
In this step, we will use only evolutionary information from an MSA file:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
python \PYG{n+nv}{\PYGZdl{}ESGEMME\PYGZus{}PATH}/esgemme.py aliBLAT.fasta \PYGZhy{}r input \PYGZhy{}f aliBLAT.fasta
\end{sphinxVerbatim}

After a few minutes of calculation, you must see at least two files named
BLAT\_normPred\_evolCombi.txt and BLAT\_normPred\_evolCombi.png. You have
the entire single point mutational landscape of BLAT protein in these
files.

If you want to utilize structural information (highly recommended) as well as
evolutionary information:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
python \PYG{n+nv}{\PYGZdl{}ESGEMME\PYGZus{}PATH}/esgemme.py aliBLAT.fasta \PYGZhy{}r input \PYGZhy{}f aliBLAT.fasta \PYG{l+s+se}{\PYGZbs{}}
\PYGZhy{}\PYGZhy{}pdbfile blat\PYGZhy{}af2.pdb \PYG{l+s+se}{\PYGZbs{}}
\PYGZhy{}\PYGZhy{}normweightmode sstjetormax
\end{sphinxVerbatim}


\subsection{Obtaining the effect of a subset of single point mutations}
\label{\detokenize{docker:obtaining-the-effect-of-a-subset-of-single-point-mutations}}
If you are interested in only a bunch of single point mutations,
you have to prepare a mut file. The format is a simple text file and
each line contains a single point mutation such as D26A….
Fortunately, we have an example mut in data folder of ESGEMME repository.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
wget http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/raw/master/data/Stiffler\PYGZus{}2015\PYGZus{}BLAT\PYGZus{}ECOLX.mut
\end{sphinxVerbatim}

Similar to the previous step, there are two possible ways to do the calculations: with or without
structural information. First, without structural information:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
python \PYG{n+nv}{\PYGZdl{}ESGEMME\PYGZus{}PATH}/esgemme.py aliBLAT.fasta \PYGZhy{}r input \PYGZhy{}f aliBLAT.fasta \PYG{l+s+se}{\PYGZbs{}}
\PYGZhy{}m Stiffler\PYGZus{}2015\PYGZus{}BLAT\PYGZus{}ECOLX.mut
\end{sphinxVerbatim}

You can include structural information in the following way:
.. code:: bash
\begin{quote}

python \$ESGEMME\_PATH/esgemme.py aliBLAT.fasta \sphinxhyphen{}r input \sphinxhyphen{}f aliBLAT.fasta \textendash{}pdbfile blat\sphinxhyphen{}af2.pdb \textendash{}normweightmode sstjetormax \sphinxhyphen{}m Stiffler\_2015\_BLAT\_ECOLX.mut
\end{quote}

You will have BLAT\_normPred\_evolCombi.txt file in your folder. However, the output
format is completely different from the entire mutational landscape scanning file.
Each line of this file is a mutation and its predicted effect separated by a space.
In addition, you won’t have a png file like in the previous case.


\section{Multiple point mutation calculations}
\label{\detokenize{docker:multiple-point-mutation-calculations}}
Sometimes, we need to see effects of double or triple mutations. ESGEMME can
perform calculations if you provide a mut file. In this case, the mut file must
have the following format:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
E26D:Y44R
E56N:A77F:H94V
\end{sphinxVerbatim}

The first line of the text file is impact of a double mutations and the second
line is the impact of the triple mutations. As you can see, the mutations are
separated by a colon(:) character.
The output file will be in a similar format. Each line will contain the multiple
mutation and its predicted effect, separated by a space.


\section{Running several jobs using docker}
\label{\detokenize{docker:running-several-jobs-using-docker}}

\chapter{Analyzing the ESGEMME output}
\label{\detokenize{analysis:analyzing-the-esgemme-output}}\label{\detokenize{analysis::doc}}
By default, ESGEMME will output the following files: *
myProt\_normPred\_evolEpi.txt * myProt\_normPred\_evolInd.txt *
myProt\_normPred\_evolCombi.txt

The most important output file is \sphinxstylestrong{myProt\_normPred\_evolCombi.txt}. The
values of interest are the normalized predictions (normPred). Each file
contains a 20 x n matrix, where n is the number of positions (columns) in the
query sequence. If the user provides her/his own list of mutations, then
only the global epistatic model will be run and the output file will
contain 2 columns, the first one with the mutations, the second one with
the normalized predicted effects.


\chapter{Installation}
\label{\detokenize{installation:installation}}\label{\detokenize{installation::doc}}
ESGEMME is implemented in Python 3 and R. It has been tested only on
Linux. Since ESGEMME has many dependencies, we recommend using our web
site or our docker image. If you are a determined user, here comes the
steps required to install it from the source.


\section{Installing the dependencies:}
\label{\detokenize{installation:installing-the-dependencies}}
ESGEMME has the following external dependencies: * Joint Evolutionary
Trees: \sphinxurl{http://www.lcqb.upmc.fr/JET2/} and its dependencies: \sphinxhyphen{} naccess:
\sphinxurl{http://www.bioinf.manchester.ac.uk/naccess/} \sphinxhyphen{} muscle:
\sphinxurl{https://www.drive5.com/muscle/} ** * seqinr R package:
\sphinxurl{https://cran.r-project.org/web/packages/seqinr/index.html} * dssp for
secondary structure prediction.

These tools should be installed to be able to use ESGEMME.


\section{Getting the source code and preparing the environment:}
\label{\detokenize{installation:getting-the-source-code-and-preparing-the-environment}}
Download the ESGEMME source code from
\sphinxurl{http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME}. Define and export the
environment variable ESGEMME\_PATH=/path\sphinxhyphen{}to\sphinxhyphen{}ESGEMME\sphinxhyphen{}directory/

\begin{sphinxVerbatim}[commandchars=\\\{\}]
\PYG{n+nb}{export} \PYG{n+nv}{ESGEMME\PYGZus{}PATH}\PYG{o}{=}/path\PYGZhy{}to\PYGZhy{}ESGEMME\PYGZhy{}directory/
\end{sphinxVerbatim}


\section{Configuring default.conf file}
\label{\detokenize{installation:configuring-default-conf-file}}
Inside ESGEMME folder, there is an important file called default.conf.
This file contains essential parameters of ESGEMME, such as paths of
external parts, default internal parameters. etc. You have to correct the Software section of this
file according to your system.


\chapter{Indices and tables}
\label{\detokenize{index:indices-and-tables}}\begin{itemize}
\item {} 
\DUrole{xref,std,std-ref}{genindex}

\item {} 
\DUrole{xref,std,std-ref}{modindex}

\item {} 
\DUrole{xref,std,std-ref}{search}

\end{itemize}



\renewcommand{\indexname}{Index}
\printindex
\end{document}