Initial commit

README.md

@@ -1,14 +1,72 @@
----
-title: SoluProtMutDemo
-emoji: 📈
-colorFrom: yellow
-colorTo: purple
-sdk: gradio
-sdk_version: 5.46.0
-app_file: app.py
-pinned: false
-license: bsd-3-clause
-short_description: Predictor of a protein solubility change given a mutation
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Installation
+
+Clone the repository `???`.  
+Then, extract the [FoldX](https://foldxsuite.crg.eu/products#foldx) distribution for your operating system into `external/foldx` in the cloned project folder, _make sure_ the binary is named `foldx`.  
+Finally, install the dependencies and check the installation works:  
+```bash
+pip install -r requirements.in
+python -m tests.inference
+```
+
+If the installation *fails*, or the application *crashes*, try to install *pinned dependencies* instead: `pip install -r requirements.txt`. Also check the table below.
+
+#### Tested configurations:
+
+| OS    | Python | PyTorch | Engine    | Project version                |
+|-------|--------|---------|-----------|--------------------------------|
+| Win 10 | 3.8.18 | 2.1.2   | CPU       | January 16, 2024               |
+| Linux | 3.9.19 | 2.1.2   | CPU       | January 16, 2024               | 
+| Linux | 3.8.13 | 1.10.0  | CUDA 11.3 | January 16, 2024                               | 
+
+### Usage
+
+```
+wrapper.py [-h] [-v] pdb-code [chain] wild-type location mutation
+
+Solubility change preditor:
+  Predicts the change in the solubility of a given protein variant
+
+positional arguments:
+  pdb-code       PDB code
+  chain          target chain          character; default=A
+  wild-type      wild-type residue(s)  amino-acid[n]
+  location       mutated position(s)   integer[n]
+  mutation       1 or n substituents   amino-acid|amino-acid[n]
+
+optional arguments:
+  -h, --help     show this help message and exit
+  -v, --verbose
+
+Amino acids can be specified by both 1- or 3-letter code.
+```
+
+Example usage (double-point mutant in [erythropoietin](https://www.rcsb.org/sequence/1EER))`and its outpus:
+```bash
+./wrapper.py 1EER F,R 48,150 D --verbose
+```
+
+```
+Predicted solubility change: 5.000398e-01 (solubilizing)
+```
+
+## Development
+
+### Reproducible environment
+
+`requirements.in` – project (direct) dependencies required for *inference*. Keep the PyTorch version specified here in sync with the link for the *pyg* wheels specified ibidem.
+
+`requirements.txt` – _resolved_ and _pinned_ dependencies based on the file above, a result of `pip install -r requirements.in && pip freeze` in a fresh Python environment.  
+note: `pip-compile` of pip-tools does not seem to work with complex PyTorch ecosystem 
+
+### Style guide
+#### Indentation
+Use tabs `\t` for an indentation, spaces (after tabs) for an alignment ([reasoning](https://stackoverflow.com/a/5048130/1908192), [reasoning2](https://www.reddit.com/r/javascript/comments/c8drjo/nobody_talks_about_the_real_reason_to_use_tabs/
+))
+
+#### Naming conventions (PEP8-based)
+module_name, CONSTANT_NAME, ClassName (capitalize first letters of words), subroutine_name, variable_name
+
+ClassName, function_name: keep acronyms in their original case: GetPDB, get_PDB
+
+ 
+

app.py

@@ -0,0 +1,90 @@
+import gradio as gr
+from wrapper import *
+
+# --- Helper functions from wrapper.py ---
+def parse_amino_acid(value):
+	value = value.upper()
+	if len(value) == 1:
+		try:
+			value = AA.one_to_three(value)
+		except Exception:
+			pass
+	if not AA.is_aa(value):
+		raise ValueError(f"'{value}' is not a valid amino acid")
+	return AA.three_to_one(value.upper())
+
+def predict_solubility(pdb_code, chain, orig, loc, mut, version=None):
+	try:
+		from code.predictor import EnsemblePredictor # expensive import left for after the argument check
+		
+		pdb_code, pdb_path = Type_PDB(pdb_code)
+		orig_list = parseList(orig, parse_amino_acid)
+		loc_list = parseList(loc, int)
+		mut_list = parseList(mut, parse_amino_acid)
+
+		if len(loc_list) != len(mut_list):
+			if len(mut_list) == 1:
+				mut_list *= len(loc_list)
+			else:
+				return "Error: Inconsistent multi-point mutant specification"
+
+		predictor = EnsemblePredictor(version=version)
+		assessment, prediction = predictor.predict_change(pdb_path, chain, orig_list, loc_list, mut_list)
+		assessment_str = {'+': 'solubilizing', 'N': 'neutral', '-': 'desolubilizing'}[assessment]
+		
+		ORANGE = (255, 165, 0)
+		BLUESH = (100, 100, 255)
+		# ternary gradient orange-black-blue
+		color = tuple((o*max(0, 1-prediction*2) + b*max(0, (2*prediction)**2-1) for o, b in zip(ORANGE, BLUESH)))
+		return f"Predicted solubility change: {prediction:.3f} <span style='color: rgb{color}'>({assessment_str})</span>"
+	except Exception as e:
+		return f"Error: {str(e)}"		
+
+
+# --- Gradio Interface ---
+with gr.Blocks(
+	title="SoluProtMut", css="""
+		.gradio-container {
+			max-width: 900px !important
+		} blockquote {
+			margin: 1em !important
+		}
+	""") as demo:
+	gr.Markdown("""
+	## SoluProtMut: prediction of a mutational effect on protein solubility
+	specify the mutation in the protein of interest:""")
+
+	with gr.Row():
+		pdb_code = gr.Textbox(label="PDB Code",
+			placeholder="1EER",
+			max_length=4 # 12 # new PDB identifier has a shape of: pdb_00001abc https://proteopedia.org/w/PDB_code
+		)
+		chain = gr.Textbox(label="Chain", value="A", max_length=1, max_lines=1, scale=0)
+
+	with gr.Row():
+		loc = gr.Textbox(label="Mutation position(s)", placeholder="48,150")
+		orig = gr.Textbox(label="Wild-type residue(s)", placeholder="F,R", scale=0)
+		mut = gr.Textbox(label="Mutant residue(s)", placeholder="D[,A]", scale=0)
+
+	# with gr.Row():
+		# verbose = gr.Checkbox(label="Verbose Output")
+		# version = gr.Textbox(label="Model Version (optional)", placeholder="v1.0")
+
+	output = gr.HTML()
+
+	predict_btn = gr.Button("Predict solubility effect", variant='primary', size='lg', scale=0)
+	# predict_btn.style(full_width=False)
+	predict_btn.click(fn=predict_solubility,
+					  inputs=[pdb_code, chain, orig, loc, mut],
+					  outputs=[output])
+					  
+	gr.Markdown(value="""
+	<br/>
+	
+	**Acknowledgement**. Please, use the following citation to acknowledge the use of our tool:  
+	> Velecký, J., Faldynová H., Hermosilla, P., Sandlerová, N., Dörr, M., Egersdorfová, S., Bornscheuer, U., Prokop, Z., Damborský, J., Mazurenko, S., 2025:
+	> SoluProtMut: Siamese Deep Learning for Solubility Effect Prediction in Protein Mutations and Experimental Validation.
+	> *In preparation.*
+    """)
+
+	demo.launch()

code/VHSE.csv

@@ -0,0 +1,21 @@
+AA,VHSE1,VHSE2,VHSE3,VHSE4,VHSE5,VHSE6,VHSE7,VHSE8
+A,0.15,-1.11,-1.35,-0.92,0.02,-0.91,0.36,-0.48
+C,0.18,-1.67,-0.46,-0.21,0,1.2,-1.61,-0.19
+D,-1.15,0.67,-0.41,-0.01,-2.68,1.31,0.03,0.56
+E,-1.18,0.4,0.1,0.36,-2.16,-0.17,0.91,0.02
+F,1.52,0.61,0.96,-0.16,0.25,0.28,-1.33,-0.2
+G,-0.2,-1.53,-2.63,2.28,-0.53,-1.18,2.01,-1.34
+H,-0.43,-0.25,0.37,0.19,0.51,1.28,0.93,0.65
+I,1.27,-0.14,0.3,-1.8,0.3,-1.61,-0.16,-0.13
+K,-1.17,0.7,0.7,0.8,1.64,0.67,1.63,0.13
+L,1.36,0.07,0.36,-0.8,0.22,-1.37,0.08,-0.62
+M,1.01,-0.53,0.43,0,0.23,0.1,-0.86,-0.68
+N,-0.99,0,-0.37,0.69,-0.55,0.85,0.73,-0.8
+P,0.22,-0.17,-0.5,0.05,-0.01,-1.34,-0.19,3.56
+Q,-0.96,0.12,0.18,0.16,0.09,0.42,-0.2,-0.41
+R,-1.47,1.45,1.24,1.27,1.55,1.47,1.3,0.83
+S,-0.67,-0.86,-1.07,-0.41,-0.32,0.27,-0.64,0.11
+T,-0.34,-0.51,-0.55,-1.06,-0.06,-0.01,-0.79,0.39
+V,0.76,-0.92,-0.17,-1.91,0.22,-1.4,-0.24,-0.03
+W,1.5,2.06,1.79,0.75,0.75,-0.13,-1.01,-0.85
+Y,0.61,1.6,1.17,0.73,0.53,0.25,-0.96,-0.52

code/data_loader.py

@@ -0,0 +1,194 @@
+import os
+import math
+
+import numpy as np
+
+from Bio.PDB.Polypeptide import one_to_index
+
+import torch
+from torch.utils.data import Dataset
+
+class Collate_Protein_Batch():
+
+	@staticmethod
+	def collate(p_batch):
+		batch_names    = []
+		batch_aas      = []
+		batch_coords   = []
+		batch_seq_pos  = []
+		batch_axes     = []
+		batch_instance = []
+		batch_labels   = []
+		batch_weights  = []
+		
+		cur_iter = 0
+		for protA, protB, label, w in p_batch:
+			for chain in (protA, protB):
+				if chain:
+					batch_names.append(chain[0])
+					batch_aas.append(chain[1])
+					batch_coords.append(chain[2])
+					batch_seq_pos.append(chain[3])
+					batch_axes.append(chain[4])
+					batch_instance.append(np.ones_like(chain[1])*cur_iter)
+					cur_iter += 1
+			batch_labels.append(label)
+			batch_weights.append(w)
+		
+		batch_labels = list(filter(lambda l: l is not None, batch_labels))
+		
+		return batch_names,\
+			torch.as_tensor(np.concatenate(batch_aas, axis=0)),\
+			torch.as_tensor(np.concatenate(batch_coords, axis=0)),\
+			torch.as_tensor(np.concatenate(batch_seq_pos, axis=0)),\
+			torch.as_tensor(np.concatenate(batch_axes, axis=0)),\
+			torch.as_tensor(np.concatenate(batch_instance, axis=0)).to(torch.int32),\
+			torch.as_tensor(batch_weights),\
+			torch.as_tensor(batch_labels)
+
+
+# AA Letter to id
+AA1 = "ACDEFGHIKLMNPQRSTVWYX"
+AA_TO_ID = {}
+for i in range(0, 21):
+	AA_TO_ID[AA1[i]] = i
+
+def create_datapoint(pdb_code: str, seq: str, coords, w: float = 1):
+	return (
+		(
+			pdb_code,
+			[AA_TO_ID[aa] for aa in seq],
+			coords,
+			list(range(len(seq))),
+			[],
+			[]
+		), None, None, w
+	)
+	
+def collate_batch(p_batch):
+	return Collate_Protein_Batch.collate(p_batch)
+
+
+class EnzymeClassDataset(Dataset):
+
+	def __init__(
+		self,
+		p_path = 'data',
+		p_data_path = 'chains',
+		p_dataset = 'training',
+		p_fastafile = 'chain_list_pdb.fasta',
+		p_random_seed = None,
+		p_fold: str = None,        # particular fold from 1 to N
+		p_train_mode = False, # to select all but the given fold (for training)
+		p_data_aug = False,
+		p_batch_pairs = False,
+		p_load_data = False
+	):
+		if p_fold is not None and int(p_fold) < 1:
+			raise Exception("Fold for CV should be a positive integer! Got: " + str(p_fold))
+		
+		# Random state.
+		self.random_state_ = np.random.RandomState(p_random_seed)
+
+		# Save the data augmentation parameters.
+		self.data_augment_ = p_data_aug
+		self.batch_pairs_  = p_batch_pairs
+	
+		# Get the paths.
+		self.pdb_folder_ = os.path.join(os.path.join(p_path, p_data_path))
+		pdb_fasta_file = os.path.join(p_path, p_fastafile)
+
+		# Load the sequences from the fasta file
+		self.list_chains_ = {}
+		def process_fasta_file(fasta_file, folder):
+			with open(fasta_file, 'r') as my_fasta_file:
+				chain_name = ''
+				for cur_line in my_fasta_file.readlines():
+					if cur_line.startswith('>'):
+						chain_name = cur_line.rstrip()[1:]
+					else:
+						cur_chain = cur_line.rstrip()
+						cur_chain_ids = []
+						for cur_aa in cur_chain:
+							cur_chain_ids.append(AA_TO_ID[cur_aa])
+						self.list_chains_[chain_name] = (np.array(cur_chain_ids), folder)
+
+		process_fasta_file(pdb_fasta_file, self.pdb_folder_)
+			
+		# load datapoints
+		self.datapoints_ = []
+		with open(os.path.join(p_path, p_dataset+'.csv'), 'r') as labels_map_file:
+			for cur_line in labels_map_file:
+				line_split = cur_line.rstrip().split(',')
+				line_split[2] = float(line_split[2])
+				line_split[3] = float(line_split[3]) if line_split[3] else 1 # set default weight if not available
+				# Cross-validation row selection
+				if p_fold and (line_split[4] == p_fold) == p_train_mode:
+					continue # do not include this fold
+				self.datapoints_.append(line_split[:4]) # orig_pdb, mut_pdb, label, weight
+
+		if p_load_data:
+			self.data_ = []
+			print()
+			for cur_iter, cur_chain in enumerate(self.list_chains_):
+				cur_path = os.path.join(cur_chain[2], cur_chain[0]+".npy")
+				cur_pos_seq_path = os.path.join(cur_chain[2], cur_chain[0]+"_seq_pos.npy") 
+				# cur_axes_path = os.path.join(cur_chain[2], cur_chain[0]+"_axes.npy")
+				cur_aces_path = []
+				self.data_.append((np.load(cur_path), np.load(cur_pos_seq_path), np.load(cur_axes_path)))
+				if cur_iter%100==0:
+					print("\r Loading {:6d}/{:6d}".format(cur_iter, len(self.list_chains_)), end ="")
+			print()
+		else:
+			self.data_ = None
+
+
+	def __len__(self):
+		return len(self.datapoints_)
+
+	def __getitem__(self, idx):
+		orig_pdb, mut_pdb, label, weight = self.datapoints_[idx]
+		
+		orig_path = os.path.join(self.list_chains_[orig_pdb][1], orig_pdb +".npy")
+		mut_path = os.path.join(self.list_chains_[mut_pdb][1], mut_pdb + ".npy")
+		# cur_pos_seq_path = os.path.join(self.list_chains_[idx][2], self.list_chains_[idx][0]+"_seq_pos.npy")
+		# cur_axes_path = os.path.join(self.list_chains_[idx][2], self.list_chains_[idx][0]+"_axes.npy")
+		cur_axes_path = []
+		
+		noise = None
+		
+		def get_pdb(idx, cur_path, label: int):
+			nonlocal noise
+			
+			cur_aa_ids = self.list_chains_[idx][0]
+			if self.data_ is None:
+				cur_pos = np.load(cur_path)
+				# cur_seq_pos = np.load(cur_pos_seq_path)
+				cur_seq_pos = list(range(len(cur_aa_ids)))
+				cur_axes = []
+			else:
+				cur_pos = self.data_[idx][0]
+				cur_seq_pos = self.data_[idx][1]
+				cur_axes = self.data_[idx][2]
+
+			cur_min = np.amin(cur_pos, axis=0, keepdims=True)
+			cur_max = np.amax(cur_pos, axis=0, keepdims=True)
+			center = (cur_max + cur_min)*0.5
+			cur_pos = cur_pos - center
+			
+			if self.data_augment_:
+				if noise is None or not self.batch_pairs_:
+					noise = self.random_state_.normal(0.0, 0.05, cur_pos.shape)
+				
+				assert cur_pos.shape == noise.shape
+				# print(cur_pos)
+				cur_pos = cur_pos + noise
+				# print(cur_pos)
+
+			return idx, cur_aa_ids, cur_pos, cur_seq_pos, cur_axes
+		
+		return get_pdb(orig_pdb, orig_path, label), get_pdb(mut_pdb, mut_path, label), label, weight
+
+		
+		
+		

code/data_preprocessing/__init__.py

@@ -0,0 +1,7 @@
+TMPDIR = "tmp/"
+
+class PreprocessError(Exception):
+	pass
+
+from .process import process_pdb, mutate_seq
+from .model import FoldX, get_PDB

code/data_preprocessing/model.py

@@ -0,0 +1,113 @@
+import os.path, sys
+
+from . import TMPDIR, PreprocessError
+os.makedirs(TMPDIR, exist_ok=True)
+
+FILEDIR = os.path.dirname(__file__)
+FOLDX_DIR      = FILEDIR + "/../../external/foldx/"
+FOLDX_BINARY   = FOLDX_DIR + "foldx"
+# if sys.platform == "win32":
+	# FOLDX_BINARY   = FOLDX_DIR + "foldx-32"
+FOLDX_ROTAFILE = os.path.relpath(FOLDX_DIR) + "/rotabase.txt"
+# os.environ["FOLDX_BINARY"] = os.path.dirname(__file__) + "/external/foldx/foldx-32.exe"
+
+# verbosity of logs
+VERBOSE_IMPORTANT = 0
+VERBOSE_VERBOSE = 1
+VERBOSE_LEVEL = VERBOSE_IMPORTANT
+
+def echo(txt="", level=VERBOSE_VERBOSE):
+	if(level <= VERBOSE_LEVEL):
+		print(txt)
+
+def echoStage(name, exe = None):
+	echo()
+	name = " %s " % name
+	TEXT = "predictor:----------------------------------------------------------------------"
+	hyphen_len = int((len(TEXT) - len(name)) / 2)
+	TEXT = TEXT[0:hyphen_len] + name + TEXT[-hyphen_len:]
+	echo(TEXT)
+	if exe:
+		echo("Running: %s" % exe)
+	else:
+		echo()
+
+def get_PDB(pdb_code: str, force: bool = False):
+	# todo: make filename small
+	from urllib import request, error
+	global TMPDIR
+
+	pdb_filename = pdb_code + ".pdb"
+	pdb_filepath = TMPDIR + pdb_filename
+	if force or not os.path.isfile(pdb_filepath):
+		try:
+			request.urlretrieve('https://files.rcsb.org/download/' + pdb_filename, pdb_filepath)
+		except error.HTTPError as e:
+			if e.code == 404:
+				raise PreprocessError("PDB file not available online – '%s': %s" % (pdb_code, e.url))
+			raise
+
+	return pdb_filepath
+
+    
+def exec(cmd, level=VERBOSE_VERBOSE, **args):
+	import subprocess
+	print(cmd)
+	
+	pipe = None if level <= VERBOSE_LEVEL else subprocess.DEVNULL
+	return subprocess.call(cmd, shell=True, stdout=pipe, **args)
+
+def FoldX(file,
+	chain: str = None,
+	wildtype: list = None,
+	location: list = None, 
+	mutation: list = None,
+	force: bool=False
+):
+	global TMPDIR, FOLDX_BINARY, FOLDX_ROTAFILE
+	
+	if(exec("\"%s\" -h" % FOLDX_BINARY)):
+		raise PreprocessError("FoldX is not installed or has expired!")
+	
+	dname = os.path.dirname(file) or '.'
+	fname = os.path.basename(file)
+
+	# prepare PDB structure for run in FoldX
+	rname = "_Repair".join(os.path.splitext(fname)) # repaired PDB filename
+	rpath = TMPDIR + rname
+	if force or not os.path.isfile(rpath):
+		print(TMPDIR)
+		exe = "\"%s\" --command=RepairPDB --pdb-dir=\"%s\" --pdb=\"%s\" --rotabaseLocation=\"%s\" --output-dir=\"%s\"" % \
+			(FOLDX_BINARY, dname, fname, FOLDX_ROTAFILE, TMPDIR)
+		echoStage("EXECUTING FOLDX AS MUTATION ENGINE", exe)
+		# Repair PDB
+		exit_code = exec(exe)
+		if exit_code:
+			raise PreprocessError("FoldX optimization failed with code: %i" % (exit_code))
+			return None, None
+
+	if not mutation:
+		return rpath, None
+
+	# prepare mutation list for FoldX
+	ifile = TMPDIR + 'individual_list.txt'
+	muts = []
+	for w,l,m in zip(wildtype, location, mutation):
+		muts.append("%s%s%s%s" % (w,chain,l,m))
+	with open(ifile, 'w') as individuals:
+		individuals.write(','.join(muts) + ';')
+
+	# Create mutants
+	# --numberOfRuns=5 does not seems to change structure a lot, does not influence the backbone
+	exe = "\"%s\" --command=BuildModel --pdb-dir=\"%s\" --pdb=\"%s\" --rotabaseLocation=\"%s\" --output-dir=\"%s\" --mutant-file=\"%s\"" % \
+		(FOLDX_BINARY, TMPDIR, rname, FOLDX_ROTAFILE, TMPDIR, ifile)
+	exit_code = exec(exe)
+	# exit_code = 0
+	if exit_code:
+		raise PreprocessError("FoldX mutation failed with code: %i" % (exit_code))
+		return rpath, None
+
+	mname = TMPDIR + "_1".join(os.path.splitext(rname)) # 1st mutant of inidivudals file has "_Repair_1" suffix
+	
+	# name of optimized original file, name of mutated file
+	return rpath, mname

code/data_preprocessing/process.py

@@ -0,0 +1,136 @@
+# author: Jan Velecky, adapted from Pedro
+import os
+import numpy as np
+import gzip
+import pickle
+
+ROOT_DIR    = os.path.dirname(__file__) + '/../../'
+RAW_DIR  = ROOT_DIR + '/data_raw/pdbs/'
+OPTIMS_DIR  = ROOT_DIR + '/data_temp/optimized-pdbs/'
+MUTANTS_DIR = ROOT_DIR + '/data_temp/mutated-pdbs/'
+
+PREPRO_DIR  = ROOT_DIR + '/data_preprocessed/'
+CHAINS_DIR  = PREPRO_DIR + '/chains/'
+
+# should not contain multi-chains
+# should deal with partial residues
+# mutated residues should be in the structure
+
+import warnings
+warnings.filterwarnings("ignore")
+
+from Bio.PDB.PDBParser import PDBParser
+from Bio.PDB.Polypeptide import is_aa, three_to_one
+
+parser = PDBParser(PERMISSIVE=1)
+
+# a dict of {pos: aa} with some str compability
+class Type_Seq(dict):
+	def __init__(self, *arg, **kw):
+		super().__init__(*arg, **kw)
+	
+	def __str__(self): # directly convertible to amino-acid sequence string
+		return ''.join(self.values())
+	
+	def __repr__(self):
+		return str(dict(self))
+	
+	def __iter__(self): # dict default is over the keys
+		yield from self.values()
+	
+	# def __getitem__(self, subscript): # slicing would be nice to have, but should it slice by indexes or as sequence? Who knows.
+		# if isinstance(subscript, slice):
+			# return self.items() print(subscript.start, subscript.stop, subscript.step)
+		# else:
+			# return dict[subscript]
+	
+	def copy(self): # sing super's (dict's) copy would create another dict, not a Type_Seq
+		return Type_Seq(dict(self))
+
+
+def _process_pdb(filepath, gap_detect=True):
+	structure_name = filepath.split('/')[-1][:-4]
+
+	with open(filepath, 'rt') as ifh:
+		structure = parser.get_structure(structure_name, ifh)
+
+		for chain in structure[0]:
+			res_aas = {} # sequence from the pdb
+			res_pos = [] # positions of Cα
+			seqid1 = None
+			for residue in chain:
+				if is_aa(residue.get_resname()):
+					if 'CA' in residue:
+						_, seqid, _ = residue.id
+						if(gap_detect):
+							if seqid1:
+								gap = seqid - seqid1
+								if gap > 8:
+									print("Gap of %i AAs detected at %s" % (gap, str(residue.full_id)))
+							seqid1 = seqid
+
+						try: # std amino acids
+							res_aas[seqid] = three_to_one(residue.get_resname())
+						except KeyError as e:
+							res_aas[seqid] = 'X'
+						atom_ca = residue['CA']
+						res_pos.append(atom_ca.get_coord())
+
+			res_pos = np.array(res_pos)
+			
+			yield chain.id, Type_Seq(res_aas), res_pos
+
+
+def process_pdb(filepath, chain: str = None):
+	chains = _process_pdb(filepath)
+	if not chain: # return generator (for all chains)
+		return chains
+		
+	for ch in chains: # return the specified chain
+		if ch[0] == chain:
+			return ch[1:]
+
+
+def mutate_seq(res_aas: Type_Seq, wildtype: list, location: list, mutation: list) -> Type_Seq:
+	res_aas = res_aas.copy()
+	
+	for w,l,m in zip(wildtype, location, mutation):
+		if res_aas[l] != w:
+			raise ValueError("Wildtype residue mismatch: %s is actually %s" % (''.join((w,str(l),m)), res_aas[l]))
+		res_aas[l] = m
+	
+	return res_aas
+
+
+if __name__ == "__main__":
+
+	list_pdbs = []
+	set_pdbs = set()
+	# process all PDBs
+	for pdb_path in [OPTIMS_DIR, RAW_DIR, MUTANTS_DIR]:
+		# use RAW structure if optimized not found
+		pdbs = {f for f in os.listdir(pdb_path) if os.path.isfile(os.path.join(pdb_path, f))}
+		pdbs -= set_pdbs
+		set_pdbs |= pdbs # merge sets
+		list_pdbs += [os.path.join(pdb_path, f) for f in pdbs]
+
+	total_chains = 0
+	os.makedirs(CHAINS_DIR, exist_ok=True) # folders for preprocessed data
+	
+	with open(PREPRO_DIR+"chain_list_pdb.fasta", 'w') as chain_list_file:
+		for cur_iter, cur_pdb in enumerate(list_pdbs):
+			structure_name = cur_pdb.split('/')[-1][:-4].lower()
+			
+			if cur_iter% 100 == 0:
+				print("%i/%i %s" % (cur_iter, len(list_pdbs), structure_name))
+			
+			for chain_id, seq, res_pos in process_pdb(cur_pdb): # todo: _process_pdb(cur_pdb, gap_detect=False)
+				if len(seq) > 10:
+					total_chains += 1
+
+					chain_list_file.write(">"+structure_name+"."+chain_id+"\n")
+					chain_list_file.write(seq+"\n")
+				
+					np.save(CHAINS_DIR+structure_name+"."+chain_id, res_pos)
+
+	print("Total chains:", total_chains)

code/model_py/__init__.py

@@ -0,0 +1,14 @@
+from .v21_2 import PlaNNet, MutPred, Ensemble, conf_dict, feed
+
+# Print number of parameters.
+def get_n_params(model):
+	pp=0
+	for p in model.parameters():
+		nn=1
+		for s in list(p.size()):
+			nn = nn*s
+		pp += nn
+	return pp
+
+def print_n_params(model, out_f = print):
+	out_f("Number of parameters: ", get_n_params(model))

code/model_py/utils.py

@@ -0,0 +1,67 @@
+from time import time
+
+import torch
+
+_current_milli_time = lambda: time() * 1000.0
+
+# feeds batch to the predictor
+def feed(model, cur_batch):
+	start_time = _current_milli_time()
+	chain_name, chain, chain_pos, chain_seq_pos, chain_axes, batch_ids = cur_batch
+
+	dev = next(model.parameters()).device
+	# move the batch to the same device as model is in
+	chain         =         chain.to(dev, torch.int64)
+	chain_pos     =     chain_pos.to(dev, torch.float32)
+	chain_seq_pos = chain_seq_pos.to(dev, torch.int64)
+	chain_axes    =    chain_axes.to(dev, torch.float32)
+	batch_ids     =     batch_ids.to(dev)
+
+	time_data = _current_milli_time() - start_time
+
+	logits = model( # [batch_size] of residues each:
+		chain,         # AA type (index)
+		chain_pos,     # coordinates in 3D (of a-Carbon?)
+		chain_seq_pos, # seqential index
+		chain_axes,    # ??? axes (orthonormal) between consecutive residues
+		batch_ids      # chain ID mask
+	)
+	
+	return logits, time_data
+
+class Feeder:
+	# enables feeding models with batches in objective way: model.feed(batch) instead of imperative feed(model, batch)
+	# simplifies imports...
+	def feed(self, *args):
+		return feed(self, *args)
+
+
+class _Ensemble(torch.nn.Module, Feeder):
+
+	def __init__(self,
+		paths_or_n,
+		base_nn: torch.nn.Module,
+		mut_nn:  torch.nn.Module,
+	):
+		super().__init__()
+		models = []
+
+		if type(paths_or_n) is int:
+			for i in range(paths_or_n):
+				models.append(mut_nn(base_nn('avg', True, False))) # todo: this should not be hardcoded
+		else:
+			for path in paths_or_n:
+				conf_dict = torch.load(path)
+				model = mut_nn(
+					base_nn(conf_dict['gl_pooling'], bool(conf_dict['embed_aa']), conf_dict['embed_aa'] == 'learn'))
+				model.load_state_dict(conf_dict["state_dict_prot_enc"])
+				model.eval()
+				models.append(model)
+		# all modules has to be properly registered as modules to be visible for PyTorch
+		self.models = torch.nn.ModuleList(
+			models)  # jit.trace would not work without this with a crpytic message: RuntimeError: "Cannot insert a Tensor that requires grad as a constant"
+
+	def forward(self, *args):
+		preds = [m(*args) for m in self.models]
+		preds = torch.cat(preds)
+		return torch.mean(preds)

code/model_py/v21_2.py

@@ -0,0 +1,503 @@
+import signal
+
+# RUN CONFIGURATION
+VERSION = "21.2-mutpred"
+VERSION_DESC = "VERSION_DESC..." # DEPRECATED?
+conf_dict = {
+	# model configuration
+	'embed_aa': True,    # True (VHSE) | False (1-Hot) | 'learn'
+	'gl_pool': 'avg',    # both|avg
+	'L1_features': 128,  # e.g.: 128,256,...
+	'cl_features': 1024, # classifier hidden neurons count
+	'conv_features': 8,  # convolution features (32 in the IEConv paper)
+}
+
+import numpy as np
+import torch
+from torch.utils.tensorboard import SummaryWriter
+
+from torch_geometric.nn import radius_graph as ball_query
+from torch_geometric.nn import global_add_pool, global_mean_pool, global_max_pool, InstanceNorm, BatchNorm
+from torch_geometric.nn.conv import GCNConv
+from torch_geometric.nn.pool import avg_pool_x
+from torch_geometric.data import Data
+from torch_geometric.transforms import Distance
+from torch.nn.functional import one_hot
+from torch.nn import Embedding, Linear, Sequential, ReLU, Sigmoid
+from torch.nn import Dropout3d as Dropout # Dropout2d, Dropdout, 3d and Dropout1d are calling the same function underneath (the last one available since PyTorch 1.12)
+from torch_scatter import scatter
+from sklearn.metrics import balanced_accuracy_score as BA_score
+
+from torch.utils.data import DataLoader
+
+from .utils import feed, Feeder, _Ensemble # feed for backward compatibility (import from this module)
+
+EC_CLASSES = 1 # 1 (2) class or regression
+AA_CLASSES = 21 # 20 standard AAs + X
+VHSE_DIM   = 8  # dimension count of VHSE embedding
+CONV_HIDDENS = conf_dict['conv_features']
+MAX_HOPS = 6
+DROPOUT_RATE = 0 # 0.2
+DROPOUT_CL_RATE = 0.5
+
+# some PyTorch Geometric function does not respect batch_mask
+def batch_clusters(cluster, batch_mask, safe_margin=2):
+	return cluster + (int(cluster.max()) + 8) // 8 * 8 * batch_mask
+	#                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+	#      pseudocode: (cluster.max() + 8) >> 3 << 3
+	#                  each offset is a multiply of cluster.max()+1 rounded up to 8s in binary (0..7 --> 8, 8..15 -> 16, etc.)
+	#      note: retyping to int() to get rid of an irrelevant PyTorch 1 warning: UserWarning: __floordiv__ is deprecated...
+	#      this is not good, because it would require to move data back and forth between CPU and GPU
+	# mask would depend on the largest protein
+
+class BatchAwareDropout(torch.nn.Module):
+	r"""A placeholder identity operator that is argument-insensitive.
+
+	Args:
+		args: any argument (unused)
+		kwargs: any keyword argument (unused)
+
+	Shape:
+		- Input: :math:`(*)`, where :math:`*` means any number of dimensions.
+		- Output: :math:`(*)`, same shape as the input.
+
+	Examples::
+
+		>>> m = nn.Identity(54, unused_argument1=0.1, unused_argument2=False)
+		>>> input = torch.randn(128, 20)
+		>>> output = m(input)
+		>>> print(output.size())
+		torch.Size([128, 20])
+
+	"""
+	def __init__(self, p: float = 0.5) -> None:
+		super().__init__()
+		self.p = p
+
+	def forward(self, input: torch.Tensor) -> torch.Tensor:
+		if(self.p and self.training):
+			feature_shape = input[0].shape
+			mask = (
+					input.new_empty(feature_shape).uniform_() # tensor with uniformly distributed random numbers on the same device as input and dimensions as one data instance
+					> self.p                                  # thresholding by dropout rate
+				).float().unsqueeze(0) / (1 - self.p)         # normalization to keep similar "weight sum"
+			
+			input = input.mul(mask)
+		return input
+Dropout = BatchAwareDropout
+
+class Print(torch.nn.Module):
+	def __init__(self):
+		super(Print, self).__init__()
+
+	def forward(self, x):
+		# print(x[0:20])
+		return x
+
+# Double Layer Perceptron
+# with droupouts + batch norm. and ReLU for the hidden layer
+class DLP(torch.nn.Module):
+	def __init__(self, inputs, hiddens, outputs=1): # number of the input, hidden and ouput neurons
+		super().__init__()
+
+		self.hid = Sequential(
+			Dropout(DROPOUT_CL_RATE),
+			Linear(inputs, hiddens),
+			BatchNorm(hiddens),
+			ReLU()
+		)
+		self.out = Sequential(
+			Dropout(DROPOUT_CL_RATE),
+			Linear(hiddens, outputs)
+		)
+
+	def forward(self, x):
+		# batch norm
+		# dropout 0.5
+		# relu
+		# hidden layer
+		x = self.hid(x)
+		# batch norm
+		# dropout 0.5
+		# output layer
+		x = self.out(x)
+		return x
+
+# Intrinsci-extrinsic convolution layer
+class IEConv(torch.nn.Module):
+	def __init__(self, inputs, outputs, distance):
+		super().__init__()
+
+		self.distance = distance
+		self.inputs = inputs   # input features
+		self.outputs = outputs # output features
+		
+		self.intr_dist = Distance(max_value = MAX_HOPS)
+		self.extr_dist = Distance(max_value = self.distance)
+
+		self.slp1 = Sequential(
+			Linear(2, CONV_HIDDENS), # 2 types of distance
+			ReLU()
+		)
+		self.slp2 = Sequential(
+			# Dropout(DROPOUT_CL_RATE),
+			Linear(CONV_HIDDENS*inputs, outputs) # largest gradient matrix: [8,I] 
+		)
+		# effectively implements the following but more frugally in terms of gradient (intermediate) tensor size (8*I << I*O):
+		# self.gcl = Sequential(
+		#     DLP(2, 8, inputs*outputs), # [8,I*O] matrix size
+		#     # ReLU()
+		# )
+
+		self.norm = BatchNorm(outputs)
+	
+	def forward(self,
+		graphs: Data, # AAs connected to neighbouring AAs, position: sequential, node features
+		coords,       # 3D cartesian coordinates
+	):
+		neighbors = graphs.edge_index
+
+		# 1st edge feature = intrinsic distance (along bonds)
+		graphs = self.intr_dist(graphs) # max_value is used just for nomalization in the step above
+		graphs.edge_attr = graphs.edge_attr.clamp(max=1.0) # get values into interval <0,1> for numerical stability
+		# NOTE: this way, information about long bond distance is lost (longer than MAX_HOPS)
+		
+		# 2nd edge feature = extrinsic distance (euclidean)
+		graphs.pos = coords
+		graphs = self.extr_dist(graphs)
+
+		# batch norm, dropout 0.2, relu
+
+		# get weights from the convolution kernel
+		w = self.slp1(graphs.edge_attr)                       # (|edges|, 8)
+		w = torch.reshape(w, (-1, 1, CONV_HIDDENS))           # (|edges|, 1, 8)
+		# get input features and project them on the edges
+		h = graphs.x[neighbors[0]]                            # (|edges|, input_features)
+		h = torch.reshape(h, (-1, self.inputs, 1))            # (|edges|, input_features, 1)
+		# widen weights 
+		h = w*h#torch.matmul(w, h)                            # (|edges|, 8, input_features)
+		h = torch.reshape(h, (-1, CONV_HIDDENS*self.inputs))  # (|edges|, 8*input_features)
+		assert_test(h)
+		# compute the new features factors (per edge)
+		# print(h)
+		h = self.slp2(h)                                      # (|edges|, output_features)
+		assert_test(h)
+		# np.savetxt('h_before_scattered.txt', h.detach().cpu().numpy())
+		# finish convolution (sum vertex-wise the new features projected on the edges)
+		h = scatter(h, neighbors[1], dim=0, dim_size = graphs.num_nodes, reduce='add') # dim_size required - solitary AA may be in PDB (at the end of the sequence)
+		# print(h.shape)
+		# np.savetxt('h_scattered.txt', h.detach().cpu().numpy())
+		assert_test(h)
+		h = self.norm(h)
+		h = h.relu()
+
+		return h
+
+
+
+# like IEConv but employing ResNets
+class ResNet(torch.nn.Module):
+	def __init__(self, inputs, outputs, distance):
+		super().__init__()
+		self.distance = distance
+
+		self.ldown = self.SLP(inputs, inputs//4)
+		self.conv  = IEConv(inputs//4, inputs, distance)
+		self.lup   = self.SLP(inputs, outputs)
+		
+		self.lside = self.SLP(inputs, outputs) # side channel for passing the features of the node itself
+
+	def forward(self, graph, coords):
+		h = graph.x
+
+		graph.x = self.ldown(h)
+		x = self.conv(graph, coords)
+		x = self.lup(x)
+		
+		h = self.lside(h)
+
+		return x+h                            # combine features of the node and features of its neighbours
+	
+	# Single Layer Perceptron with batch norm., dropout and ReLU
+	class SLP(torch.nn.Module):
+		def __init__(self, inputs, outputs):
+			super().__init__()
+
+			self.l = Sequential(
+				Print(),
+				Dropout(DROPOUT_RATE),
+				Print(),
+				Linear(inputs, outputs),
+				BatchNorm(outputs),
+				ReLU()
+			)
+			self.norm = BatchNorm(outputs)
+			
+		def forward(self, x):
+			# batch norm, dropout 0.2, relu
+			# x = x.dropout(DROPOUT_RATE)
+			x = self.l(x)
+			# x = self.norm(x).relu()
+			return x
+
+
+
+
+
+class PlaNNet(torch.nn.Module):
+	"""possible names:
+		PCNN – Protein/Peptide/Polyamino-acid Convolutional NN. BUT: "Pulse Coupled NN"
+		CCNN - Conformation Convolutional NN. BUT: Constrained Convolutional NN
+		ACNN - polyAmino-acid Convolutional NN. BUT: Anatomically Constrained NN
+		PLN - Protein Learning (neural) Network
+		ACN (AACCNN) - Amino-Acid Chain-Convolutional NN
+		NNfP = NN for Proteins
+		PLearner = Protein Learner
+		PlaNNet /ˈplænet/ = Protein Learning Neural NETwork
+	"""
+	class EncodeAA:
+		def __call__(self, AAs):
+			return one_hot(AAs, AA_CLASSES).to(torch.float32)
+	class EmbedAA(torch.nn.Module):
+		_norm = None
+		
+		def __init__(self, precomputed: bool = True):
+			super().__init__()
+			self._precomputed = precomputed
+			if precomputed:
+				vhse_coeffs = np.genfromtxt("code/VHSE.csv", delimiter=',', skip_header=1, usecols=range(1, VHSE_DIM+1))
+				vhse_coeffs = np.vstack([
+					vhse_coeffs,
+					np.zeros(vhse_coeffs.shape[1]) # 0s as the vector for 'X' AA
+				])
+				vhse_coeffs = torch.from_numpy(vhse_coeffs)
+				self.emb = Embedding.from_pretrained(vhse_coeffs)
+			else:
+				self.emb = Embedding(AA_CLASSES, VHSE_DIM) # embedding + batch_norm
+				self._norm = BatchNorm(VHSE_DIM)
+		
+		def __call__(self, AAs):
+			emb = self.emb(AAs)
+			if self._norm:
+				self._norm(emb)
+			return emb
+	
+	def __init__(self,
+		gl_pool:     str  = conf_dict['gl_pool'],
+		embed_aa:    bool = bool(conf_dict['embed_aa']),      # embedding (otherwise 1hot encoding)
+		embed_learn: bool = conf_dict['embed_aa'] == 'learn', # learn embedding (or precomputed VHSE)
+		L1_features: int  = conf_dict['L1_features'],
+		cl_features: int  = conf_dict['cl_features'],
+	**_):
+		super().__init__()
+		
+		# MODEL HYPERPARAMETERS
+		# hidden layers features
+		L1C_FEATURES = L1_features
+		L2C_FEATURES = L1C_FEATURES*2
+		L3C_FEATURES = L2C_FEATURES*2
+		self.LF__FEATURES = L3C_FEATURES + (L3C_FEATURES if gl_pool == 'both' else 0) # avg (+ max)
+		
+		self._gl_pool = gl_pool
+		torch.manual_seed(42)
+		
+		self.AAenc = self.EmbedAA(not embed_learn) if embed_aa else self.EncodeAA()
+
+		# MODEL LAYERS
+		# don't do batch norm, ReLU - parameters
+		self.gcl3 = IEConv(VHSE_DIM if embed_aa else AA_CLASSES, L1C_FEATURES, 8)
+		# no pooling
+		self.gcl3_ = ResNet(L1C_FEATURES, L1C_FEATURES, 8)
+		# no pooling
+		self.gcl3__ = ResNet(L1C_FEATURES, L1C_FEATURES, 8)
+		# pooling
+		self.gcl4 = ResNet(L1C_FEATURES, L2C_FEATURES, 12)
+		# no pooling
+		self.gcl4_ = ResNet(L2C_FEATURES, L2C_FEATURES, 12)
+		# pooling
+		self.gcl5 = ResNet(L2C_FEATURES, L3C_FEATURES, 16)
+		# no pooling
+		self.gcl5_ = ResNet(L3C_FEATURES, L3C_FEATURES, 16)
+		# pooling
+
+		self.classifier = DLP(self.LF__FEATURES, cl_features, EC_CLASSES)
+		
+	def forward(self,
+		AA_type,
+		coordinate,
+		seq_position,
+		axes,
+		batch_mask
+	):
+		batch_mask = batch_mask.to(torch.int64)
+		#print(AA_type)
+		AA_type = self.AAenc(AA_type).to(torch.float32)
+		# print(AA_type)
+		assert_test(AA_type)
+		# print(coordinate)
+		# print(batch_mask.shape, seq_position.shape, coordinate.shape)
+		seq_position = torch.reshape(seq_position.to(torch.float32), (-1,1))
+		# print(seq_position.view(-1))
+		assert_test(seq_position)
+
+		# 1st convolutional layer (AA level; 8-Å radius)
+		# print("ball query:", coordinate, coordinate.size, batch_mask)
+		neighbors = ball_query(coordinate, self.gcl3.distance, batch_mask) # [[tos] [froms]], e.g. [to0, to2, ...], [from1, from1, from2, ...]
+		# print(neighbors)
+		graphs = Data(
+			x = AA_type.to(torch.float32),
+			edge_index = neighbors,
+			pos = seq_position
+		)
+
+		assert_test(neighbors)
+		assert_test(coordinate)
+		# print(AA_type.shape )
+		h = self.gcl3(graphs.clone(), coordinate)
+		assert_test(h)
+		# print(h.shape)
+		graphs.x = h
+		h = self.gcl3_(graphs.clone(), coordinate)
+		# input() # DEBUG
+		self.act3 = h
+		graphs.x = h
+		h = self.gcl3__(graphs, coordinate)
+		self.act3 = h
+		#print(neighbors)
+		#h = self.gconv3(AA_type.to(torch.float32), neighbors)
+		# pooling
+		clusters = torch.div(seq_position.flatten(), 2, rounding_mode = "trunc")
+		#print(clusters)
+		clusters = batch_clusters(clusters, batch_mask)
+		#print(clusters)
+		#print(h.shape, coordinate.shape)
+		#print(batch_mask)
+		#print(coordinate)
+		coordinate, _        = avg_pool_x(clusters, coordinate, batch_mask)
+		h, _                 = avg_pool_x(clusters, h, batch_mask)
+		clusters, batch_mask = avg_pool_x(clusters, clusters, batch_mask)
+		#print(coordinate)
+		#print(clusters, batch_mask)
+		#print(h.shape, coordinate.shape)
+
+		# 2nd convolutional layer (2 AAs level; 12-Å radius)
+		neighbors = ball_query(coordinate, self.gcl4.distance, batch_mask)
+		graphs = Data(
+			x = h,
+			edge_index = neighbors,
+			pos = torch.reshape(clusters, (-1,1))
+		)
+
+		h = self.gcl4(graphs.clone(), coordinate)
+		graphs.x = h
+		h = self.gcl4_(graphs, coordinate)
+		self.act4 = h
+		# h = self.gconv4(h, neighbors)
+		clusters = torch.div(clusters, 2, rounding_mode = "trunc")
+		# print(clusters)
+		clusters = batch_clusters(clusters, batch_mask)
+		
+		coordinate, _        = avg_pool_x(clusters, coordinate, batch_mask)
+		h, _                 = avg_pool_x(clusters, h, batch_mask)
+		clusters, batch_mask = avg_pool_x(clusters, clusters, batch_mask)
+		# print(clusters, batch_mask, clusters.shape)
+		# print(h.shape)
+
+		# 3rd convolutional layer (4 AAs level; 16-Å radius)
+		neighbors = ball_query(coordinate, self.gcl5.distance, batch_mask)
+		graphs = Data(
+			x = h,
+			edge_index = neighbors,
+			pos = torch.reshape(clusters, (-1,1))
+		)
+
+		h = self.gcl5(graphs.clone(), coordinate)
+		graphs.x = h
+		h = self.gcl5_(graphs, coordinate)
+		self.act5 = h
+		# h = self.gconv5(h, neighbors)
+		assert_test(h)
+		
+		# global pooling
+		g = global_mean_pool(h, batch_mask)
+		if self._gl_pool == "both":
+			g2 = global_max_pool(h, batch_mask)
+			g = torch.stack([g, g2], 1)
+		g = torch.reshape(
+			g,
+			(-1, self.LF__FEATURES)
+		)
+		#print(h, h.shape)
+		#activations = self.act(h)
+		#print(activations)
+		assert_test(g)
+		# print('cl:', self.classifier(g))
+
+		return self.classifier(g)
+
+class MutPred(torch.nn.Module):
+	def __init__(self,
+		base_nn: torch.nn.Module
+	):
+		super().__init__()
+		self.base_nn = base_nn
+		
+	def forward(self,
+		AA_type,
+		coordinate,
+		seq_position,
+		axes,
+		batch_mask
+	):
+		base_pred = self.base_nn(AA_type, coordinate, seq_position, axes, batch_mask)
+		LOG(base_pred.view(-1), sep='\n')
+		pred = base_pred[1::2] - base_pred[0::2] # MUT - WT predictions
+		LOG(pred.sigmoid().view(-1))
+		return pred.sigmoid()
+
+
+# log after a keyboard event (CTRL+BREAK on Windows)
+class LOG:
+	def __init__(self):
+		LOG.on = False
+		return # TODO: signal.SIGQUIT does not exist on Windows Python 3.8
+		signal.signal(signal.SIGQUIT, self.signal_handler) # CTRL+\ on Linux (normally kills the process)
+		
+	def __call__(self, *args, sep=' '):
+		if LOG.on is not False:
+			LOG.on = None
+			print(*args, sep=sep)
+	
+	def signal_handler(*args):
+		print()
+		LOG.on = True
+	
+	@staticmethod
+	def iter():
+		LOG.on = not not LOG.on
+
+
+def assert_test(tensor, mask = None):
+	if not mask:
+		# l = int(len(tensor) / conf_dict['norm_size']/2)
+		l = int(len(tensor) / 2)
+		# print(l)
+		# equal won't go well with small inaccuracies after ~7 significant digits
+		# assert torch.allclose(tensor[0:l], tensor[l:]), (tensor[0:l], tensor[l:])
+
+
+def Ensemble(paths_or_n): # Ensemble consisting of this-version models
+	return _Ensemble(paths_or_n, PlaNNet, MutPred)
+
+
+# online logging
+LOG = LOG()
+# LOG.on = True
+
+
+
+
+
+
+
+

code/predictor.py

@@ -0,0 +1,60 @@
+import torch
+
+from code.data_preprocessing import process_pdb, mutate_seq
+from code.data_loader import create_datapoint, collate_batch
+
+
+class EnsemblePredictor:
+	
+	def __init__(self,
+		weights: str = "model_weights.pth", # trained model
+		version: str = None,                # model version: '21_1'|...
+	):
+		conf_dict = torch.load(weights)
+		
+		if version is None: # default model
+			from code.model_py import Ensemble
+		elif version == '21_2':
+			from code.model_py.v21_2 import Ensemble
+		elif version == '21_1':
+			from code.model_py.v21_1 import Ensemble
+		else:
+			raise 'Non-existing version!'
+		
+		pred_model = Ensemble(5)
+		pred_model.load_state_dict(conf_dict)
+		pred_model.eval()
+		
+		self._model = pred_model
+
+	def predict_change(self,
+		PDB_path: str,
+		chain: str,
+		aa_from: list,
+		locs: list,
+		aa_to: list
+	):
+		assert len(aa_from) == len(locs) == len(aa_to)
+		
+		print("Processing structure...")
+		orig_seq, coords = process_pdb(PDB_path, chain)
+		mut_seq = mutate_seq(orig_seq, aa_from, locs, aa_to)
+		
+		print("Calculating prediction...")
+		protein = create_datapoint(
+			'wt',
+			orig_seq,
+			coords
+		)
+		mutant = create_datapoint(
+			'mut',
+			mut_seq,
+			coords
+		)
+		
+		data = collate_batch([protein, mutant])[:-2]
+		prediction = float(self._model.feed(data)[0])
+		prediction_cl = 'N' if round(prediction, 2) == 0.5 else\
+					'+' if prediction > 0.5 else '-'
+		
+		return prediction_cl, prediction

model_weights.pth

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7247bd1e89766a138815d96120f72bc03d77f0be1935886db44a8464683175dc
+size 53058100

requirements.in

@@ -0,0 +1,8 @@
+--find-links "https://data.pyg.org/whl/torch-2.1.0+cpu.html"
+biopython == 1.79  # < 1.82 # 1.82 removed three_to_one function https://github.com/biopython/biopython/pull/4508, 1.80 added the deprecation warning, TODO: internalize three_to_one function
+tensorboard
+torch ~= 2.1.0
+torch-geometric
+torch_scatter
+torch_cluster
+packaging         # required by tensorboard but not properly specified in its requirements (probably due to being preinstalled from some version of pip)

requirements.txt

@@ -0,0 +1,47 @@
+# Working configuration of Python 3.8 on Win10 with PyTorch 2.1 on CPU
+--find-links "https://data.pyg.org/whl/torch-2.1.0+cpu.html"
+absl-py==2.0.0
+biopython==1.81
+cachetools==5.3.2
+certifi==2023.11.17
+charset-normalizer==3.3.2
+colorama==0.4.6
+filelock==3.13.1
+fsspec==2023.12.2
+google-auth==2.26.2
+google-auth-oauthlib==1.0.0
+grpcio==1.60.0
+idna==3.6
+importlib-metadata==7.0.1
+Jinja2==3.1.3
+joblib==1.3.2
+Markdown==3.5.2
+MarkupSafe==2.1.3
+mpmath==1.3.0
+networkx==3.1
+numpy==1.24.4
+oauthlib==3.2.2
+packaging==23.2
+protobuf==4.25.2
+psutil==5.9.7
+pyasn1==0.5.1
+pyasn1-modules==0.3.0
+pyparsing==3.1.1
+requests==2.31.0
+requests-oauthlib==1.3.1
+rsa==4.9
+scikit-learn==1.3.2
+scipy==1.10.1
+sympy==1.12
+tensorboard==2.14.0
+tensorboard-data-server==0.7.2
+threadpoolctl==3.2.0
+torch==2.1.2
+torch-cluster==1.6.3+pt21cpu
+torch-scatter==2.1.2+pt21cpu
+torch_geometric==2.4.0
+tqdm==4.66.1
+typing_extensions==4.9.0
+urllib3==2.1.0
+Werkzeug==3.0.1
+zipp==3.17.0

wrapper.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+#---------------------------------------------------------------------
+#---   Predictor of a protein solubility change given a mutation   ---
+#---           by Jan Velecky velda@mail.muni.cz                   ---
+#---              Loschmidt Laboratories, 2023-24                  ---
+#---       example use:      python3 wrapper.py -h                 ---
+#---------------------------------------------------------------------
+import argparse
+from functools import partial
+
+import Bio.PDB.Polypeptide as AA
+from code.data_preprocessing import get_PDB
+
+# ---------------------------------------- DATA TYPES FOR ARGPARSE ----------------------------------------
+def Check_nonNegative(value):
+	ivalue = int(value)
+	if ivalue < 0:
+		return False
+	return ivalue
+
+# non-negative integer datatype
+def Type_nonNegative(value):
+	ivalue = int(value)
+	if ivalue < 0:
+		raise argparse.ArgumentTypeError("%s is not a non-negative integer" % value)
+	return ivalue
+
+def Type_char(value):
+	if len(value) != 1:
+		raise argparse.ArgumentTypeError("'%s' is not a character" % value)
+	return value
+
+def Type_aminoAcid(value):
+	orig = value
+	value = str.upper(value)
+	if len(value) == 1:
+		try:
+			value = AA.one_to_three(value)
+		except:
+			pass
+	if not AA.is_aa(value):
+		raise argparse.ArgumentTypeError("'%s' is not a valid amino-acid" % orig)
+	return str.upper(AA.three_to_one(value))
+
+def parseList(s, type):
+	return [type(i) for i in s.split(',')]
+
+def Type_listOf(basetype):
+	return partial(parseList, type=basetype)
+
+def Type_PDB(pdb_code):
+	try:
+		pdb_path = get_PDB(pdb_code.lower())
+	except Exception as e:
+		raise argparse.ArgumentTypeError(e)
+	return pdb_code, pdb_path
+
+
+# ----------------------------------------------END OF DATA TYPES ------------------------------------------
+
+argParser = argparse.ArgumentParser(add_help = True,
+	description=
+"""Solubility change preditor:
+  Predicts the change in the solubility of a given protein variant
+
+
+""", epilog="""
+Amino acids can be specified by both 1- or 3-letter code.
+
+example of use: ./wrapper.py 1EER F,R 48,150 D --verbose
+""",conflict_handler='resolve', # overwrite conflicts
+	formatter_class=argparse.RawTextHelpFormatter,
+	prefix_chars="+-",
+	# exit_on_error=False # would be nice to use it for prompting a user for required params, but was implemented buggy: https://bugs.python.org/issue41255
+)
+argParser.add_argument(
+	'input',
+	metavar='pdb-code',
+	type=Type_PDB,
+	help="PDB code"
+)
+argParser.add_argument( # we only process one chain in the end
+	'chain', nargs="?",
+	default='A',
+	type=Type_char,
+	help="target chain          character; default=A"
+)
+argParser.add_argument(
+	'orig',
+	metavar='wild-type',
+	type=Type_listOf(Type_aminoAcid),
+	help="wild-type residue(s)  amino-acid[n]"
+)
+argParser.add_argument(
+	'loc',
+	metavar='location',
+	type=Type_listOf(int),
+	help="mutated position(s)   integer[n]"
+)
+argParser.add_argument(
+	'mut',
+	metavar='mutation',
+	type=Type_listOf(Type_aminoAcid),
+	help="1 or n substituents   amino-acid|amino-acid[n]"
+)
+argParser.add_argument(
+	'-v', '--verbose',
+	action="store_true",
+	#help="show ouputs from the underlaying tools"
+)
+
+argParser.add_argument('--ver', default=None, help=argparse.SUPPRESS)
+
+
+
+
+
+
+if __name__ == '__main__':
+	# ---------------------------------------- ARGUMENTS PROCESSING ----------------------------------------
+	args = argParser.parse_args()
+
+	# positional arguments parsing (argparse can't cope with nested positional arguments)
+	if len(args.loc) != len(args.mut):
+		if len(args.mut) == 1: # same target AA on all specified positions
+			args.mut = args.mut * len(args.loc)
+		else:
+			argParser.error("Inconsistent multi-point mutant specification")
+	pdb_code, pdb_path = args.input
+	chain = args.chain
+
+	# import code.data_preprocessing.model as modeling
+	# if(args.verbose):
+		# modeling.VERBOSE_LEVEL = modeling.VERBOSE_VERBOSE
+
+	# ------------------------------------- PREPROCESSING & INFERENCE --------------------------------------
+	from code.predictor import EnsemblePredictor # expensive import left for after the argument check
+
+	pred_model = EnsemblePredictor(version=args.ver)
+
+	assesment, prediction = pred_model.predict_change(pdb_path, chain, args.orig, args.loc, args.mut)
+	assesment = {'+': 'solubilizing', 'N': 'neutral', '-': 'desolubilizing'}[assesment]
+	print()
+	print("Predicted solubility change: %g (%s)" % (prediction, assesment))