Welcome to the GitHub repository for MoCHI: Neural networks to fit interpretable models and quantify energies, energetic couplings, epistasis, and allostery from deep mutational scanning data.
The easiest way to install MoCHI is by using the bioconda package:
conda install -c bioconda pymochi
See the full Installation Instructions for further details and alternative installation options.
You can run a standard MoCHI workflow using the command line tool or a custom analysis by taking advantage of the "pymochi" package in your own python script.
MoCHI requires a plain text model design file containing a table describing the measured phenotypes and how they relate to the underlying additive (biophysical) traits. The table should have the following 4 tab-separated columns (see example here):
trait: One or more additive trait namestransformation: The shape of the global epistatic trend (Linear/ReLU/SiLU/Sigmoid/SumOfSigmoids/TwoStateFractionFolded/ThreeStateFractionBound)phenotype: A unique phenotype name e.g. Abundance, Binding or Kinase Activityfile: Path to DiMSum output (.RData) or plain text file with variant fitness and error estimates for the corresponding phenotype(s) (nucleotide sequence example here, amino acid sequence example here)
Replace MY_MODEL with the path to your model design file (see example here).
run_mochi.py --model_design MY_MODEL
Get help with additional command line parameters:
run_mochi.py -h
Below is an example of a custom MoCHI workflow (written in Python) to infer the underlying free energies of folding and binding from doubledeepPCA data.
#Imports
import pymochi
from pymochi.data import MochiData
from pymochi.models import MochiTask
from pymochi.report import MochiReport
import pandas as pd
from pathlib import Path
#####################
# Step 1: Create a *MochiTask* object with one-hot encoded variant sequences, interaction terms and 10 cross-validation groups
#####################
#Globals
k_folds = 10
abundance_path = str(Path(pymochi.__file__).parent / "data/fitness_abundance.txt") #MoCHI demo data
binding_path = str(Path(pymochi.__file__).parent / "data/fitness_binding.txt") #MoCHI demo data
#Define model
my_model_design = pd.DataFrame({
'phenotype': ['Abundance', 'Binding'],
'transformation': ['TwoStateFractionFolded', 'ThreeStateFractionBound'],
'trait': [['Folding'], ['Folding', 'Binding']],
'file': [abundance_path, binding_path]})
#Create Task
mochi_task = MochiTask(
directory = 'my_task',
data = MochiData(
model_design = my_model_design,
k_folds = k_folds))
#####################
# Step 2: Hyperparameter tuning and model fitting
#####################
#Perform grid search overy hyperparameters
mochi_task.grid_search()
#Fit model using optimal hyperparameters
for i in range(k_folds):
mochi_task.fit_best(fold = i+1)
#####################
# Step 3: Generate report, phenotype predictions, inferred additive trait summaries and save task
#####################
temperature_celcius = 30
mochi_report = MochiReport(
task = mochi_task,
RT = (273+temperature_celcius)*0.001987)
energies = mochi_task.get_additive_trait_weights(
RT = (273+temperature_celcius)*0.001987)
mochi_task.save()
Report plots, predictions and additive trait summaries will be saved to the my_task/report, my_task/predictions and my_task/weights subfolders.
Run the demo to ensure that you have a working MoCHI installation (expected run time <10min):
demo_mochi.py
Comprehensive documentation is coming soon, but in the meantime get more information about specific classes/methods in python e.g.
help(MochiData)
You may submit a bug report here on GitHub as an issue or you could send an email to [email protected].
Please cite the following publication if you use MoCHI:
Faure, A. J. & Lehner, B. MoCHI: neural networks to fit interpretable models and quantify energies, energetic couplings, epistasis, and allostery from deep mutational scanning data. Genome Biol 25, 303 (2024). 10.1186/s13059-024-03444-y
Project based on the Computational Molecular Science Python Cookiecutter version 1.6.
(Vector illustration credit: Vecteezy!)