%% Generated by Sphinx.
\def\sphinxdocclass{report}
\documentclass[letterpaper,10pt,english]{sphinxmanual}
\ifdefined\pdfpxdimen
   \let\sphinxpxdimen\pdfpxdimen\else\newdimen\sphinxpxdimen
\fi \sphinxpxdimen=.75bp\relax
\ifdefined\pdfimageresolution
    \pdfimageresolution= \numexpr \dimexpr1in\relax/\sphinxpxdimen\relax
\fi
%% let collapsible pdf bookmarks panel have high depth per default
\PassOptionsToPackage{bookmarksdepth=5}{hyperref}

\PassOptionsToPackage{booktabs}{sphinx}
\PassOptionsToPackage{colorrows}{sphinx}

\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{tgtermes}
\usepackage{tgheros}
\renewcommand{\ttdefault}{txtt}



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

\fvset{fontsize=auto}
\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{Jun 08, 2023}
\release{1.3.0}
\author{Mustafa Tekpinar}
\newcommand{\sphinxlogo}{\vbox{}}
\renewcommand{\releasename}{Release}
\makeindex
\begin{document}

\ifdefined\shorthandoff
  \ifnum\catcode`\=\string=\active\shorthandoff{=}\fi
  \ifnum\catcode`\"=\active\shorthandoff{"}\fi
\fi

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


\sphinxstepscope


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

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

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

\sphinxAtStartPar
Let’s start our favorite terminal app.

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

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


\section{Getting the example input data}
\label{\detokenize{docker:getting-the-example-input-data}}
\sphinxAtStartPar
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\PYG{+w}{ }http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/blob/master/data/aliBLAT.fasta
\end{sphinxVerbatim}

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

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

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

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

\begin{sphinxVerbatim}[commandchars=\\\{\}]
wget\PYG{+w}{ }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}}
\sphinxAtStartPar
In order to make sure that the docker is installed:

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

\sphinxAtStartPar
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\PYG{+w}{ }docker\PYG{+w}{ }run\PYG{+w}{ }\PYGZhy{}ti\PYG{+w}{ }\PYGZhy{}\PYGZhy{}rm\PYG{+w}{ }\PYGZhy{}\PYGZhy{}mount\PYG{+w}{ }\PYG{n+nv}{type}\PYG{o}{=}bind,source\PYG{o}{=}\PYG{n+nv}{\PYGZdl{}PWD},target\PYG{o}{=}/home/tekpinar/research/myexample\PYG{+w}{ }\PYG{l+s+se}{\PYGZbs{}}
tekpinar/esgemme\PYGZhy{}docker:v1.3.0
\end{sphinxVerbatim}

\sphinxAtStartPar
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}\PYG{+w}{ }../myexample/
\end{sphinxVerbatim}

\sphinxAtStartPar
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}}
\sphinxAtStartPar
In this step, we will use only evolutionary information from an MSA file:

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

\sphinxAtStartPar
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.

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

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


\subsection{Predicting the effect of a subset of single point mutations}
\label{\detokenize{docker:predicting-the-effect-of-a-subset-of-single-point-mutations}}
\sphinxAtStartPar
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\PYG{+w}{ }http://gitlab.lcqb.upmc.fr/tekpinar/ESGEMME/raw/master/data/Stiffler\PYGZus{}2015\PYGZus{}BLAT\PYGZus{}ECOLX.mut
\end{sphinxVerbatim}

\sphinxAtStartPar
Similar to the previous step, there are two possible ways to do the calculations: with or without
structural information. First, let’s do it without structural information:

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

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

\sphinxAtStartPar
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}

\sphinxAtStartPar
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}}
\sphinxAtStartPar
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}

\sphinxAtStartPar
The first line of the text file is impact of a double mutation 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}}
\sphinxstepscope


\chapter{Analyzing and Modifying the ESGEMME Output}
\label{\detokenize{analysis:analyzing-and-modifying-the-esgemme-output}}\label{\detokenize{analysis::doc}}

\section{Raw ESGEMME Scores and Their Interpretation}
\label{\detokenize{analysis:raw-esgemme-scores-and-their-interpretation}}
\sphinxAtStartPar
There is not a hardcoded limit for raw ESGEMME scores. However, the values
range between {[}\sphinxhyphen{}12, 2{]} generally. The lower values mean the mutations is impactful,
while values close to 0 means the mutation does not have any significant impact.

\sphinxAtStartPar
We should note that most of the ‘impactful’ mutations are deleterious but
it is not always the case.


\section{Entire Single Point Mutation Landscape Calculations}
\label{\detokenize{analysis:entire-single-point-mutation-landscape-calculations}}
\sphinxAtStartPar
By default, ESGEMME will only output the combined (independent
and epistatic) scores*:

\sphinxAtStartPar
There are three output files:
\begin{enumerate}
\sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}%
\item {} 
\sphinxAtStartPar
myProt\_normPred\_evolCombi.txt
\begin{quote}

\sphinxAtStartPar
myProt is the short name in the MSA file for your protein. The
‘myProt\_normPred\_evolCombi.txt’ file contains 20 rows (for 20 amino acids
in alphabetical order) and L columns, where L is the number of amino acids
in your protein of interest. Since this file is horizontal, it is easy to
read it in R or Python but difficult to find the mutations you are interested.
\end{quote}

\item {} 
\sphinxAtStartPar
myProt\_normPred\_evolCombiTransposed.txt
\begin{quote}

\sphinxAtStartPar
As the name implies, this is the transposed version of the combined results.
It is easier to find the mutations you are interested in this file. Just
check the row corresponding to the mutation.
\end{quote}

\item {} 
\sphinxAtStartPar
myProt\_normPred\_evolCombi.Preparing
\begin{quote}

\sphinxAtStartPar
This is the image file of the combined results. It selects ‘Oranges\_r’
matplotlib color map by default. You can change it by adding ‘\textendash{}colormap turbo\_r’
for a more fancy look during the esgemme call. It \textendash{}colormap argument accepts
all the color maps in matplotlib.
\end{quote}

\end{enumerate}

\sphinxAtStartPar
Note*: If you want to see epistatic and independent contributions as well,
you should add ‘\textendash{}verbose true’ argument while calling esgemme.


\section{Selected Single Point or Multiple Point Mutation Calculations}
\label{\detokenize{analysis:selected-single-point-or-multiple-point-mutation-calculations}}
\sphinxAtStartPar
Since you used a mutation file to predict mutations, you will have your combined (epistatic+independent)
results in the same format, such as :
\begin{description}
\sphinxlineitem{{\color{red}\bfseries{}*}. myProt\_normPred\_evolCombi.txt:}
\sphinxAtStartPar
A2C \sphinxhyphen{}6.23
A2D \sphinxhyphen{}1.23
.
.
.
D286F \sphinxhyphen{}0.23

\end{description}

\sphinxstepscope


\chapter{Preparing Your Own Input}
\label{\detokenize{input-preparation:preparing-your-own-input}}\label{\detokenize{input-preparation::doc}}

\section{Preparing Your Input MSA and PDB with Colabfold}
\label{\detokenize{input-preparation:preparing-your-input-msa-and-pdb-with-colabfold}}
\sphinxAtStartPar
You have a fasta file for your protein of interest and you want to understand
impact of (certain) mutations.
Before starting, please make sure that your fasta file does not contain a gap.
The quickest method to obtain both multiple sequence alignment and a protein
structure is to use Colabfold. Let’s do this step by step:
\begin{enumerate}
\sphinxsetlistlabels{\arabic}{enumi}{enumii}{}{.}%
\item {} 
\sphinxAtStartPar
Let’s go the Colabfold web site:

\sphinxAtStartPar
\sphinxurl{https://colab.research.google.com/github/sokrypton/ColabFold/blob/main/AlphaFold2.ipynb}

\sphinxAtStartPar
Sign in using your gmail account.

\item {} 
\sphinxAtStartPar
Click on the ‘Connect’ button on the top right hand side.

\item {} 
\sphinxAtStartPar
Clean ‘query\_sequence’ box and paste your sequence to the ‘query\_sequence’ box.
For me, I selected adenylate kinase (AKE) as my example fasta sequence
(\sphinxurl{https://www.rcsb.org/fasta/entry/4AKE/display}).

\item {} 
\sphinxAtStartPar
Change the ‘jobname’ to something that makes more sense to you.

\item {} 
\sphinxAtStartPar
Go to the menu bar of your ‘AlphaFold2.ipynb’ notebook, where ‘File, Edit,
View, Insert, Runtime, Tools, Help’ are listed. Click on the Runtime and
select ‘Run all’.

\item {} 
\sphinxAtStartPar
This process make take from a few minutes to a few hours depending on your
protein size. It will give you an a3m file and up to 5 PDB models. Put these
files in a clean folder and change the directory to that folder in your
terminal.

\item {} 
\sphinxAtStartPar
Unfortunately, a3m file is not in fasta format and it contains gap columns.
We have to clean those gaps. We can do that with a GUI program like Ugene
or Jalview. However, it is a labor intensive procedure. Here, I will use a
small tool that I developed and added to the ESGEMME docker image that I created.

\item {} 
\sphinxAtStartPar
Start the docker image with the following command:

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

\item {} 
\sphinxAtStartPar
Now, change the directory to myexample folder.

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

\sphinxAtStartPar
We are supposed to see our a3m and pdb files in this folder.

\item {} 
\sphinxAtStartPar
Let’s use a small script from hhsuite to convert a3m file to fasta format.

\begin{sphinxVerbatim}[commandchars=\\\{\}]
reformat.pl\PYG{+w}{ }a3m\PYG{+w}{ }fas\PYG{+w}{ }AKE.a3m\PYG{+w}{ }AKE.fasta
\end{sphinxVerbatim}

\item {} 
\sphinxAtStartPar
Final step and we are there:

\begin{sphinxVerbatim}[commandchars=\\\{\}]
demust\PYG{+w}{ }removegaps\PYG{+w}{ }\PYGZhy{}i\PYG{+w}{ }AKE.fasta\PYG{+w}{ }\PYGZhy{}o\PYG{+w}{ }AKE\PYGZus{}nogaps.fasta
\end{sphinxVerbatim}

\end{enumerate}

\sphinxAtStartPar
Congratulations! Now, you have all the input files required for ESGEMME:
I. An input MSA: AKE\_nogaps.fasta
II. An input PDB: myprotein.pdb

\sphinxstepscope


\chapter{Installation}
\label{\detokenize{installation:installation}}\label{\detokenize{installation::doc}}
\sphinxAtStartPar
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}}
\sphinxAtStartPar
ESGEMME has the following external dependencies:
\begin{itemize}
\item {} 
\sphinxAtStartPar
Joint Evolutionary Trees: \sphinxurl{http://www.lcqb.upmc.fr/JET2/} and its dependencies:
\begin{itemize}
\item {} 
\sphinxAtStartPar
java

\item {} 
\sphinxAtStartPar
naccess: \sphinxurl{http://www.bioinf.manchester.ac.uk/naccess/}

\item {} 
\sphinxAtStartPar
muscle: \sphinxurl{https://www.drive5.com/muscle/}

\end{itemize}

\item {} 
\sphinxAtStartPar
seqinr R package: \sphinxurl{https://cran.r-project.org/web/packages/seqinr/index.html}

\item {} 
\sphinxAtStartPar
dssp for secondary structure prediction.

\end{itemize}

\sphinxAtStartPar
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}}
\sphinxAtStartPar
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{+w}{ }\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}}
\sphinxAtStartPar
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 {} 
\sphinxAtStartPar
\DUrole{xref,std,std-ref}{genindex}

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

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

\end{itemize}



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