Chrisjurich/feature new mutation submodule

[chrisjurich]

This branch represents a re-write of the mutation submodule. The base unit of the new mutation submodule is the Mutation namedtuple. Mutation describes a desired mutation for a given protein and below is a summary of the attributes as seen in the docstring found in enzy_htp/mutation/mutation:

 Attributes:
         orig: the one-letter code of the original amino acid. Can be in [ "A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, U, V, W, Y"] or "X".
         target: the one-letter code of the target mutation. Can be in [ "A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, U, V, W, Y"] or "X".
         chain_id: a single capital letter.
         res_num: the 1-indexed int() of the residue to Mutate

The Mutation namedtuple is critical for modeling mutations across a full enzyme system as it allows for convenient mapping of the full space in a manner that can be sampled efficiently. The full mutational space of an enzyme contains Nx19 Mutation namedtuples where N is the number of canonical residues in the sequence. In python this can be represented as a dict() where each (key, value) pair is (residue number, list() of Mutation namedtuple's). This modeling approach is convenient for both applying restrictions and randomly selecting residues.

Mutation restrictions are now represented and encoded via the MutationRestrictions() object. The source for this object is found in enzy_htp/mutation/mutation_restrictions.py. This object is at its core a list of dict objects each with same keys. One dict exists for each residue and it stores information on whether 1) the residue can be mutated at all or 2) what mutations may be restricted. Potential restrictions include changes to size or charge in specific directions. MutationRestrictions() as a class is compatible with the mapping of a protein's mutation space such that this space is effectively reduced by this object. When a residue is to be locked completely from mutation, the position is removed from the mutation dict and other incompatible Mutation obejcts are removed.

The user facing function in this module is mutate_pdb(). This function combines the previous two concepts as well as random selection from the mutational space and final mutation deployment. For a given protein, the function first creates all possible Mutations in the aforementioned dict layout. Next, the restrictions (if present) are applied to reduce the possible space. Lastly, the final list of Mutation namedtuple's is selected by randomly choosing an available/eligible position in the structure and then randomly choosing a Mutation from the respective list. After a mutation is chosen fromo a specific position, it is removed from the mutation dict. As a result, positions cannot be mutated twice and selection speed is drastically improved. Lastly, the desired mutations are deployed thorugh an implementation engine. Currently the only engine is Amber's tleap program.

Tests for all of the above functionality is contained within test/mutation/

[shaoqx]

Can you change it to merging into develop_refactor?

[shaoqx]

Great job! More review will be in a new pr of my edit