mutate2test takes an input model structure and an optional open reading frame and then outputs a set of disrupting and restoring mutations that can be used to test the model. This is a python program available in scripts/.

USAGE: python3 mutate2test.py <ct file> [options]

example: python3 /home/username/RNAstructure/scripts/mutate2test /home/username/mutate_to_test_files/bmorivector.ct

Required parameters:

Options that do not require added values:

Options that require added values:

Notes:

Paths: The path to mutate2test.py and to the input .ct or .dot file need to be provided as absolute paths, i.e. starting with "/".

Output files: The output folder will be in the same directory as the input CT file. Please make sure the ORF fasta file, if used, is in the same directory as the input CT file.

mutate2test provides detailed reports on selected mutations. Ranked Mutations are outputted in the same directory as the inputput ct file. Each report file is in a space-delimited .txt format.
* Using the NED objective function, mutations are ranked in a descending order based on disrupting NED. Mutations with the same disruption NED are ranked further in an ascending order using restoring NED. We also output another report file where we rank mutations in a descending order based on the total number of disrupted nucleotides in each disrupting mutation.
* Similarly, using the probability objective function, we rank mutations based on disrupting probability in an ascending order and for groups with the same disrupting probability, we rank them further using restoring probability in a descending order.

mutate2test outputs structure drawings for the top ranked mutation for each file report in the topHitDrawings folder created in the same directory as the input ct file. For each mutation pair we draw the following structures:
* disrupting mutant predicted maximum expected accuracy structure (e.g. 1topDisruption_MEA.ps where the number represents the number of codons changed for disruption).
* disrupting mutant used to draw the model structure color-annotated using the base-pairing probabilites calculated using the mutant sequence (e.g. 1topDisruption_bpProbEffectOnModelStruct.ps where the number represents the number of codons changed for disruption).
* restoring mutantpredicted maximum expected accuracy structure (e.g. 1topRestoration_MEA.ps where the number represents the number of codons changed for disruption).
* restoring mutant used to draw the model structure color-annotated using the base-pairing probabilites calculated using the mutant sequence (e.g. 1topRestoration_bpProbEffectOnModelStruct.ps where the number represents the number of codons changed for disruption).

When using the NED function, there will be 2 subfolders in topHitDrawings:
* totalNEDrank: this shows the top ranked mutation structure drawings based on the total disrupting NED.
* nt-NEDrank: this shows the top ranked mutation structure drawings based on the number of disrupted nucleotides.

Required Libraries: mutate2test requires installation of the following Python libraries: biopython, tqdm, and blosum (the 2.0.2 release). A package manager can be used to install them. For example, pip can be used using the following command: pip install biopython .

Set up RNAstructure: mutate2test calls components of the RNAstructure package. Make sure to add the RNAstructure executables to your global path. The following steps show how to do so in Linux:
1- Use a command line-based text editor like nano to open up the bash profile in the users home directory. For example, use "nano ~/.bashrc"
2- Add this line to the file: export PATH=/path/to/RNAstructure/exe/:${PATH}
3- Add this line to the file: export DATAPATH=/path/to/RNAstructure/data_tables
4- Save changes and source the changed bashrc profile. You can use: source ~/.bashrc
On Apple OS, the steps are the same, but edit the file ~/.zshrc .
See Thermodynamics.html .

Execution time and setting parameters: The execution time and the number of mutations outputted by each metric might vary when using NED or Probability as the objective functions, therefore, it is important to adjust Accepting/Rejecting Mutation thresholds to best fit the your needs. Depending on the number of mutations outputted, the user may increase or decrease the disrupting and the restoring thresholds as needed.
* The NED disruption threshold ensures that the disrupting mutations are selected such that their NED has to be greater than or equal to the sum of the model NED and the disruption threshold.
* The NED restoration threshold means that the restoring mutations are only accepted if they have an NED lower than or equal to the sum of the model NED and the restoration threshold.
* The recommended start NED values are an NED disruption increase threshold of 0.15 and an NED restoration difference threshold of 0.05.

* The probability disruption threshold ensures that the disrupting mutations are only accepted if they have a probability lower than or equal to the model probability multiplied by the disruption factor.
* The probability restoration threshold determines that the restoring mutations are to be accepted only if they have a probability greater than or equal to the model probability divided by the restoration factor.
* I recommend starting with a probability factor threshold of 100 and a restoration factor threshold of 3.

Evaluating mutations: There are two modes where mutatet2test can used to evaluate user-inputted mutations.
1- The exact base-paring mode (using -c, -C, --Calc) ensures that if a model includes a pair that cannot base pair because the mutated nucleotides do not allow pairing, the structure probability will be 0. This can be used to evaluate wildtype sequence and restoring mutants.
2- The flexible mode (using -f, -F, --flexible) allows flexibility in base pairing. This indicates that the probability will be calculated after any base pairs no longer pairing given the sequence are eliminated. This can be used to evaluate disrupting mutants where the sequence may have been mutated to eliminate base pairs in the model.

References:

1. Reuter, J.S. and Mathews, D.H.
   "RNAstructure: software for RNA secondary structure prediction and analysis."
   BMC Bioinformatics, 11:129. (2010).
2. Mathews, D.H., Disney, M.D., Childs, J.L., Schroeder, S.J., Zuker, M. and Turner, D.H.
   "Incorporating chemical modification constraints into a dynamic programming algorithm for prediction of RNA secondary structure."
   Proc. Natl. Acad. Sci. USA, 101:7287-7292. (2004).
3. Zadeh, J.N., Wolfe, B.R., and Pierce, N.A.
   "Nucleic acid sequence design via efficient ensemble defect optimization."
   J. Comput. Chem., 32: 439-452. (2011).