Package: pycofitness
Aboutpycofitnesspycofitnessis a Python implementation forin silicomutagenesis of a target protein or RNA sequence, given as input a multiple sequence alignment (MSA) of    homologs to the target. It employs apseudolikelihood maximizationdirect coupling analysis (DCA) algorithm to infer a coevolutionary energy and then uses it to predict the impact of all single-site mutations in the target.The input file forpycofitnessmust be an MSA  in FASTA format, with the first sequence representing the target sequence to mutate. The output consists of a txt file reporting the change of fitness for all single-site variants of the target.More information about pycofitness can be found in theassociated paper. When using pycofitness, please cite F. Pucci, M. Zerihun, M. Rooman, A. Schug,"pycofitness---Evaluating the fitness landscape of RNA and protein sequences", Bioinformatics, submitted (2023).Prerequisitespycofitnessis implemented mainly in Python, with the pseudolikelihood maximization parameter inference part implemented using C++ backend to enable parallelization. It requires:Python 3C++ compiler that supports C++11, e.g., the GNU compiler collection (GCC)Optionally, OpenMP for multithreading supportInstallingpycofitnesscan be installed from PyPI or from this repository. To install the current version ofpycofitnessfrom PyPI, run:$pipinstallpycofitnessThe alternative way is to clone this repository and install pycofitness as:$gitclonehttps://github.com/KIT-MBS/pycofitness/
$cdpycofitness
$pythonsetup.pyinstallRunningpycofitnessfrom the command lineWhenpycofitnessis installed, it provides thepycofitnesscommand  that can be executed from the command line.
For example:$pycofitness<biomolecule><msa_file>[--optional_arguments]where<biomolecule>can take the values "protein" or "RNA" (case insensitive), and<msa_file>is the MSA file in  fasta format.
The optional arguments of pycofitness input are:-h, --help:Shows  command line information.--seqid SEQID:Cut-off value of sequence similarity, above which sequences are lumped together in the calculation of frequencies.--lambda_h LAMBDA_h:Value of the penalizing constant for L2 regularization of fields in the pseudolikelyhood maximization DCA inference step (seeherefor  details).--lambda_J LAMBDA_J:Value of the penalizing constant for L2 regularization of couplings in the pseudolikelyhood maximization DCA inference step (seeherefor  details).--max_iterations MAX_ITERATIONS:Maximum number of iterations for the gradient descent in the negative pseudolikelihood minimization step.--num_threads NUM_THREADS:Number of threads used in the computation.--output_dir OUTPUT_DIR:Directory path to which output results are written. If the directory is not existing, it is created. If this path is not provided, an output directory is created using the base name of the MSA file, with the "output_" prefix added to it.--verbose:Show logging information on the terminal.Usingpycofitnessas a Python libraryAfter installation,pycofitnesscan be imported into other Python source codes, and used. For example,frompycofitness.mutationimportPointMutationpoint_mutation=PointMutation(msa_file,biomolecule)deltas=point_mutation.delphi_epistatic()#Print the values of delta_dict by iteration over sites and bases/residuesforiinrange(len(deltas)):forresindeltas[i]:print(i+1,res,deltas[i][res])#Note: we added 1 to i to count sites starting from one instead of zero.It is also possble to pass parameters (e.g., the number of iterations or the number of threads for parallel execution)  as
keyword arguments to thePointMutationconstructor:point_mutation=PointMutation(msa_file,biomolecule,max_iterations=1000,num_threads=4,seqid=0.9,lambda_J=10.0,lambda_h=5.0,verbose=True)wheremax_iterationsis the number of maximum iterations for gradient descent,num_threadsis the number of
threads for parallel execution,seqidis the sequence identity threshold value (if sequences have a higher similarity  than this value, they are regarded as identical),lambda_Jandlambda_hare penalizing constants for L2 regularization. Ifverboseis set toTrue,logging information is given.Preprocessing input MSAsThe input data for pycofitness is an MSA file in FASTA format. We chose not to include tools to generate MSA in pycofitness because, in this way, users can employ
their favorite MSA alignment and curation methods. There is only one compulsory adjustment within the input MSA: the sequence
to mutate (the target sequence) has to be positioned as the first one in the MSA. Note that pycofitness automatically removes MSA columns containing non-standard residues and gaps with respect to the target sequence.Results interpretationHere is a few-line example of a pycofitness output file:#site	reference	alternative	score1	M	A	-0.141	M	C	-3.541	M	D	-5.121	M	E	-7.64........The first column is the position in the target sequence, the second column is the wild-type amino acid or nucleic acid base, and the third column is the substituted amino acid or nucleic acid base. In the last column, the pycofitness score is provided. Negative values of this score correspond to variants that are less fit than the wild type, and  positive values mean variants that  are  fitter than wild type.