tmquick 1.0.0__py3-none-any.whl

tmq/core/diff2graph.py

@@ -0,0 +1,75 @@
+""" Render a difference heatmap (A - B) and return the figure
+
+"""
+
+import numpy as np
+import pandas as pd
+import matplotlib.pyplot as plt
+import seaborn as sns
+from matplotlib.ticker import MultipleLocator
+from ..utils.utils import compute_mat_diff
+
+
+
+
+def diff_map(matrix1, matrix2, vmax, residue_start, residue_end):
+
+    D = compute_mat_diff(matrix1, matrix2)
+
+    # Internal style settings
+    x_minor = 20
+    y_major = 50
+    y_minor = 10
+
+    frames = D.shape[1]
+
+    if frames <= 100:
+        x_step = 10
+    elif frames <= 500:
+        x_step = 50
+    else:
+        x_step = 100
+
+    fig, ax = plt.subplots(figsize=(12, 8))
+
+    #handle NAN
+    mask = np.isnan(D)
+
+    sns.heatmap(D, cmap="bwr", center=0, vmin=-vmax, vmax=vmax, mask=mask, cbar=False)
+
+    xticks = np.arange(0, frames + 1, x_step)
+    ax.set_xticks(xticks)
+    ax.set_xticklabels(xticks, rotation=0, fontsize=14)
+    ax.xaxis.set_minor_locator(MultipleLocator(x_minor))
+
+    for tick in ax.get_xticklabels():
+        tick.set_fontweight("bold")
+
+    # Y ticks
+    residues = D.shape[0]
+    ax.set_yticks(np.arange(0, residues, y_major))
+    ax.set_yticklabels(np.arange(residue_start, residue_end, y_major), fontsize=14)
+    ax.yaxis.set_minor_locator(MultipleLocator(y_minor))
+
+    for tick in ax.get_yticklabels():
+        tick.set_fontweight("bold")
+
+    ax.invert_yaxis()
+
+    # Labels
+    ax.set_title("Difference Map", fontsize=20, fontweight="bold")
+    ax.set_ylabel("Residue", fontsize=20, fontweight="bold")
+    ax.set_xlabel("Frames", fontsize=20, fontweight="bold")
+
+    # Colorbar
+    im = ax.collections[0]
+    cbar = fig.colorbar(im, fraction=0.029, pad=0.028)
+    cbar.set_label("Shift (Å)", fontsize=14, fontweight="bold")
+
+    for t in cbar.ax.get_yticklabels():
+        t.set_fontweight("bold")
+        t.set_fontsize(16)
+
+    plt.tight_layout()
+    plt.close()
+    return fig

tmq/core/hotspot.py

@@ -0,0 +1,164 @@
+""" Core logic for generating shift graphs of detected 
+peak regions of a protein in an automated way
+
+"""
+
+import numpy as np
+import pandas as pd
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.ticker import MultipleLocator
+from ..utils.utils import detect, extract_region_submatrices, slice_matrix2shift, auto_limits
+
+
+def detect_shifts(matrix, window, mindist, hotspot):
+    regions, mean_shift, smooth = detect(
+        matrix=matrix,
+        window=window,
+        mindist=mindist,
+        hotspot=hotspot,)
+    return mean_shift, smooth, regions
+
+def create_submatrices(matrix, window, mindist, hotspot):
+    regions, mean_shift, smooth = detect(
+        matrix=matrix,
+        window=window,
+        mindist=mindist,
+        hotspot=hotspot)
+    
+    regions_only = [(start, end) for (start, peak, end) in regions]
+    submatrices = extract_region_submatrices(matrix, regions_only)
+    return submatrices, regions, mean_shift, smooth
+
+def plot_shift_regions(shift_data, start_residue, end_residue, color="blue", window=10, title=None):
+    df = pd.DataFrame(shift_data)
+    roll = df.rolling(window, center=True, min_periods=1).mean()
+    x_min, x_max, y_min, y_max = auto_limits(df)
+
+    fig, ax = plt.subplots(figsize=(10, 6))
+    ax.plot(df, linewidth=0.3, color=color,
+            label=f"residues {start_residue}-{end_residue}")
+    ax.plot(roll, linewidth=3.0, color=color)
+    ax.legend(loc='upper left', fancybox=True, shadow=True,
+              prop={'size': 14, 'weight': 'bold'})
+
+    ax.set_xlim(x_min, x_max)
+    ax.set_ylim(y_min, y_max)
+    x_range = x_max - x_min
+    if x_range <= 500:
+        x_step = 50
+    elif x_range <= 1000:
+        x_step = 100
+    else:
+        x_step = 200
+    ax.set_xticks(np.arange(x_min, x_max + 1, x_step))
+    ax.tick_params(axis='x', labelsize=16)
+    y_range = y_max - y_min
+    if y_range <= 2:
+        y_step = 0.2
+    elif y_range <= 5:
+        y_step = 0.5
+    elif y_range <= 10:
+        y_step = 1
+    else:
+        y_step = 5
+    ax.set_yticks(np.arange(y_min, y_max + 0.5, y_step))
+    ax.tick_params(axis='y', labelsize=16)
+    ax.set_yticklabels([f"{y:.2f}" for y in ax.get_yticks()])
+    for tick in ax.get_xticklabels():
+        tick.set_fontweight("bold")
+    for tick in ax.get_yticklabels():
+        tick.set_fontweight("bold")
+    ax.set_title(title if title else f"Shift Graph {start_residue}-{end_residue}",
+                 fontsize=20, fontweight="bold")
+    ax.set_xlabel("Frames", fontsize=20, fontweight="bold")
+    ax.set_ylabel("Shift / Å", fontsize=20, fontweight="bold")
+    ax.xaxis.set_minor_locator(MultipleLocator((x_max - x_min) / 50))
+    fig.tight_layout()
+    plt.close(fig)
+    return fig
+
+
+def slice_shifts(matrix, window, mindist, hotspot):
+    regions, mean_shift, smooth = detect(
+        matrix=matrix,
+        window=window,
+        mindist=mindist,
+        hotspot=hotspot)
+
+    regions_only = [(start, end) for (start, peak, end) in regions]
+    submatrices = extract_region_submatrices(matrix, regions_only)
+    results = []
+
+    for start, end, submatrix in submatrices:
+        params = [0, submatrix.shape[0] - 1, 0, submatrix.shape[1] - 1]
+        shift_data = slice_matrix2shift(submatrix, params)
+        shift_data = shift_data[2:]
+        results.append((start, end, shift_data))
+    return results
+
+
+def plot_slice_regions(shift_data, start, end):
+    return plot_shift_regions(
+        shift_data=shift_data,
+        start_residue=start,
+        end_residue=end,
+        title=f"Region {start}-{end}" )
+
+
+def plot_hotspot_regions(mean_shift, smooth, regions, title="Residue Shift Hotspots"):
+    residues = np.arange(len(mean_shift))
+    df = pd.DataFrame(mean_shift)
+    x_min, x_max, y_min, y_max = auto_limits(df)
+
+    fig, ax = plt.subplots(figsize=(10, 6))
+    ax.plot(residues, mean_shift, color="gray", alpha=0.4, linewidth=0.8, label="Mean shift")
+    ax.plot(residues, smooth, color="blue", linewidth=3.5, label="Smoothed")
+
+    for (start, peak, end) in regions:
+        ax.axvspan(start, end, color="white", alpha=0.7)
+        ax.plot(peak, smooth[peak], "ro")
+        ax.text(peak, smooth[peak], f" {peak}", color="red", fontsize=9, fontweight="bold")
+
+    ax.legend(loc='upper left', fancybox=True, shadow=True,
+              prop={'size': 8, 'weight': 'bold'})
+    ax.set_xlim(x_min, x_max)
+    ax.set_ylim(y_min, y_max)
+    x_range = x_max - x_min
+    if x_range <= 200:
+        x_step = 25
+    elif x_range <= 500:
+        x_step = 50
+    elif x_range <= 1000:
+        x_step = 100
+    else:
+        x_step = 200
+    ax.set_xticks(np.arange(x_min, x_max + 1, x_step))
+    ax.tick_params(axis='x', labelsize=12)
+
+    y_range = y_max - y_min
+    if y_range <= 2:
+        y_step = 0.2
+    elif y_range <= 5:
+        y_step = 0.5
+    elif y_range <= 10:
+        y_step = 1
+    else:
+        y_step = 5
+    ax.set_yticks(np.arange(y_min, y_max + 0.5, y_step))
+    ax.tick_params(axis='y', labelsize=12)
+    for tick in ax.get_xticklabels():
+        tick.set_fontweight("bold")
+    for tick in ax.get_yticklabels():
+        tick.set_fontweight("bold")
+
+    ax.set_title(title, fontsize=18, fontweight="bold")
+    ax.set_xlabel("Residue index", fontsize=16, fontweight="bold")
+    ax.set_ylabel("Mean shift / Å", fontsize=16, fontweight="bold")
+    ax.xaxis.set_minor_locator(MultipleLocator((x_max - x_min) / 50))
+    ax.yaxis.set_minor_locator(MultipleLocator((y_max - y_min) / 50))
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+    plt.close(fig)
+    return fig

tmq/core/pdb2csv.py

@@ -0,0 +1,53 @@
+""" This module loops over the Multi-model pdb and 
+compute residual fluctuations across the frames
+
+"""
+
+import pandas as pd
+import numpy as np
+from ..utils.utils import (load_pdb_models, build_residue_lookup, get_ca_coord, get_backbone_com, distance)
+
+
+def pdb2csv(pdb_file, residue_start, residue_end, mode):
+    weights = {"N": 14.0, "CA": 12.0, "C": 12.0, "O": 16.0}
+    residue_numbers = list(range(residue_start, residue_end + 1))
+
+    models = load_pdb_models(pdb_file)
+    n_frames = len(models)
+
+    ref_lookup = build_residue_lookup(models[0])
+
+    ref_coords = {}
+    for resnum in residue_numbers:
+        if resnum in ref_lookup:
+            residue = ref_lookup[resnum]
+            if mode == "ca":
+                ref_coords[resnum] = get_ca_coord(residue)
+            else:
+                ref_coords[resnum] = get_backbone_com(residue, weights)
+        else:
+            ref_coords[resnum] = np.zeros(3)
+
+    matrix = pd.DataFrame(0.0, index=residue_numbers, columns=range(n_frames))
+
+    """ Compute distances for frames 1..N-1
+    """
+
+    for t in range(1, n_frames):
+        lookup = build_residue_lookup(models[t])
+
+        for resnum in residue_numbers:
+            ref = ref_coords[resnum]
+
+            if resnum in lookup:
+                residue = lookup[resnum]
+                if mode == "ca":
+                    cur = get_ca_coord(residue)
+                else:
+                    cur = get_backbone_com(residue, weights)
+            else:
+                cur = np.zeros(3)
+
+            matrix.loc[resnum, t] = distance(cur, ref)
+
+    return matrix

tmq/core/shift2graph.py

@@ -0,0 +1,63 @@
+""" Core logic for making the shift plot
+
+"""
+
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from matplotlib.ticker import MultipleLocator
+from ..utils.utils import auto_limits, rolling_average
+
+
+def shift2graph(df, residue_label, window=10):
+    roll_df = rolling_average(df, window)
+    x_min, x_max, y_min, y_max = auto_limits(df)
+    color = "blue"
+    fig, ax = plt.subplots(figsize=(10, 6))
+
+    ax.plot(df, linewidth=0.3, color=color, label=f"residues {residue_label}")
+    ax.plot(roll_df, linewidth=3.0, color=color)
+    ax.legend(loc='upper left', fancybox=True, shadow=True,
+              prop={'size': 14, 'weight': 'bold'})
+
+    ax.set_xlim(x_min, x_max)
+    ax.set_ylim(y_min, y_max)
+    x_range = x_max - x_min
+    if x_range <= 100:
+        x_step = 10
+    elif x_range <= 500:
+        x_step = 50
+    elif x_range <= 1000:
+        x_step = 100
+    else:
+        x_step = 200
+    ax.set_xticks(np.arange(x_min, x_max + 1, x_step))
+    ax.tick_params(axis='x', labelsize=14)
+
+    y_range = y_max - y_min
+    if y_range <= 2:
+        y_step = 0.2
+    elif y_range <= 5:
+        y_step = 0.5
+    elif y_range <= 10:
+        y_step = 1
+    else:
+        y_step = 5
+    ax.set_yticks(np.arange(y_min, y_max + 0.5, y_step))
+    ax.tick_params(axis='y', labelsize=14)
+    ax.set_yticklabels([f"{y:.2f}" for y in ax.get_yticks()])
+    for tick in ax.get_xticklabels():
+        tick.set_fontweight("bold")
+    for tick in ax.get_yticklabels():
+        tick.set_fontweight("bold")
+
+    ax.set_title("Shift Graph", fontsize=20, fontweight="bold")
+    ax.set_xlabel("Frames", fontsize=18, fontweight="bold")
+    ax.set_ylabel("Shift / Å", fontsize=18, fontweight="bold")
+
+    ax.yaxis.set_minor_locator(MultipleLocator((y_max - y_min) / 10))
+    fig.tight_layout()
+    plt.close(fig)
+    return fig

tmq/core/traj2pdb.py

@@ -0,0 +1,12 @@
+""" This is the engine for the conversion of trajectory files into multi-model PDB
+
+"""
+
+from ..utils.utils import (load_traj, select_backbone, align_to_first_frame)
+
+
+def traj2pdb(topology, trajectory, stride):
+    traj = load_traj(topology, trajectory, stride)
+    traj = select_backbone(traj)
+    traj = align_to_first_frame(traj)
+    return traj

tmq/core/trajmap.py

@@ -0,0 +1,52 @@
+""" This module instantiates the trajectory map plot 
+for the residue range specified by the user
+
+"""
+
+import numpy as np
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import matplotlib.pyplot as plt
+from matplotlib.ticker import MultipleLocator
+from ..utils.utils import choose_cmap, choose_aspect
+
+
+def trajmap(matrix, residue_start, residue_end, vmax):
+    x_minor = 20
+    y_major = 50
+    y_minor = 10
+    vmin = matrix.iloc[:, 1:].values.min()
+    cmap = choose_cmap('viridis_capped')
+    aspect = choose_aspect('auto')
+    frames = matrix.shape[1]
+    if frames <= 100:
+        x_step = 10
+    elif frames <= 500:
+        x_step = 50
+    else:
+        x_step = 100
+
+    fig, ax = plt.subplots(figsize=(12, 8))
+    im = ax.imshow(matrix, cmap=cmap, vmin=vmin, vmax=vmax, aspect=aspect)
+    ax.invert_yaxis()
+
+    ax.set_xticks(np.arange(0, frames + 1, step=x_step))
+    ax.tick_params(axis='x', labelsize=14)
+    ax.set_yticks(np.arange(residue_start, residue_end, step=y_major),)
+    ax.tick_params(axis='y', labelsize=14)
+    ax.yaxis.set_minor_locator(MultipleLocator(y_minor))
+    ax.xaxis.set_minor_locator(MultipleLocator(x_minor))
+    for tick in ax.get_xticklabels():
+        tick.set_fontweight("bold")
+    for tick in ax.get_yticklabels():
+        tick.set_fontweight("bold")
+
+    ax.set_title("Trajectory Map", fontsize=20, fontweight="bold")
+    ax.set_ylabel("Residue", fontsize=18, fontweight="bold")
+    ax.set_xlabel("Frames", fontsize=18, fontweight="bold")
+    cbar = fig.colorbar(im, fraction=0.029, pad=0.028)
+    cbar.set_label("Shift / Å", fontsize=12, fontweight="bold")
+    fig.tight_layout()
+    plt.close(fig)
+    return fig

tmq/utils/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "1.0"
+

tmq/utils/utils.py

@@ -0,0 +1,233 @@
+""" This contains all the utility functions used in the core modules and CLI wrappers
+
+"""
+
+import numpy as np
+import pandas as pd
+import mdtraj as mdt
+from Bio.PDB import PDBParser
+
+
+
+def ensure_pdb_extension(name):
+    return name if name.endswith(".pdb") else name + ".pdb"
+
+def load_traj(topology, trajectories, stride):
+    return mdt.load(trajectories, top=topology, stride=stride)
+
+def select_backbone(traj):
+    idx = traj.topology.select("backbone")
+    return traj.atom_slice(idx)
+
+def align_to_first_frame(traj):
+    return traj.superpose(traj, 0)
+
+
+def load_pdb_models(file):
+    parser = PDBParser(QUIET=True)
+    structure = parser.get_structure("prot", file)
+    return list(structure.get_models())
+
+def build_residue_lookup(model):
+    lookup = {}
+    for residue in model.get_residues():
+        het, resnum, icode = residue.get_id()
+        if het == " ":
+            lookup[resnum] = residue
+    return lookup
+
+
+def get_ca_coord(residue):
+    if "CA" in residue:
+        return np.array(residue["CA"].coord, dtype=float)
+    return np.zeros(3)
+
+def get_backbone_com(residue, weights):
+    coords = []
+    w = []
+    for atom_name in ["N", "CA", "C", "O"]:
+        if atom_name in residue:
+            atom = residue[atom_name]
+            coords.append(atom.coord * weights[atom_name])
+            w.append(weights[atom_name])
+    if coords:
+        return np.sum(coords, axis=0) / np.sum(w)
+    return np.zeros(3)
+
+def distance(a, b):
+    return np.linalg.norm(a - b)
+
+def ensure_csv_extension(name):
+    return name if name.endswith(".csv") else name + ".csv"
+
+
+def csv2matrix(csv_file):
+    matrix = pd.read_csv(csv_file, index_col=0)
+    return matrix
+
+
+def matrix2shift(matrix, params):
+
+    matrix_array = np.array(matrix)
+
+    res1 = params[0]
+    res2 = params[1]
+    time1 = params[2]
+    time2 = params[3]
+
+    output = pd.DataFrame(data=np.arange(time1, time2, 1, dtype=float))
+
+    if res1 == res2:
+        output = matrix_array[res1]
+    else:
+        y = matrix_array[res1:res2, time1:time2]
+
+        i = 0
+        while i < len(output):
+            output.iloc[i] = np.average(y[:, i])
+            i = i + 1
+
+    return output
+
+
+def csv2matrix(file):
+    return pd.read_csv(file, index_col=None)
+
+def choose_cmap(cmap_choice):
+    if cmap_choice == 0:
+        return "magma"
+    elif cmap_choice == 1:
+        return "seismic"
+    elif cmap_choice == 5:
+        return "Greys"
+    elif cmap_choice == 6:
+        return "turbo"
+    return "viridis"
+
+def choose_aspect(aspect):
+    if aspect == 0:
+        return "auto"
+    elif aspect == 1:
+        return "equal"
+    return "auto"
+
+def ensure_png_extension(name):
+    return name if name.endswith(".png") else name + ".png"
+
+
+def shift_to_dataframe(shift_data):
+    df = pd.read_csv(shift_data, header=None)
+    df = df.astype(float)
+    df = df.iloc[2:].reset_index(drop=True)
+    return df
+
+def rolling_average(df, window):
+    return df.rolling(window).mean()
+
+def auto_limits(df):
+    col = df.iloc[:, 0]
+    y_min = float(col.min())
+    y_max = float(col.max() + 0.5)
+    x_min = 0
+    x_max = len(df) - 1
+    return x_min, x_max, y_min, y_max
+
+
+
+def parse_range(s):
+    """
+    Parse a residue range string like '110-125' into (110, 125).
+    """
+    try:
+        start, end = map(int, s.split("-"))
+        return start, end
+    except Exception:
+        raise ValueError("Residue range must be in the form start-end, e.g., 110-125")
+
+
+import numpy as np
+import pandas as pd
+from scipy.signal import find_peaks
+
+def detect(matrix, window, mindist, hotspot):
+    return extract_residue_shift_regions(
+        matrix,
+        window,
+        mindist,
+        hotspot,
+    )
+
+
+def extract_residue_shift_regions(matrix, window, min_distance, top_n):
+
+    mat = np.array(matrix, dtype=float)
+
+    mean_shift = mat.mean(axis=1)
+
+    smooth = pd.Series(mean_shift).rolling(window, center=True).mean()
+    smooth = smooth.bfill().ffill()
+
+    peaks, props = find_peaks(smooth, distance=min_distance, prominence=0.1)
+
+    if len(peaks) == 0:
+        return []
+
+    prominences = props["prominences"]
+    ranked = np.argsort(prominences)[::-1]
+    top_peaks = peaks[ranked][:top_n]
+
+    regions = []
+    for p in top_peaks:
+        left = p
+        while left > 0 and smooth[left] > smooth[p] * 0.5:
+            left -= 1
+
+        right = p
+        while right < len(smooth)-1 and smooth[right] > smooth[p] * 0.5:
+            right += 1
+
+        regions.append((left, p, right))
+
+    return regions, mean_shift, smooth
+
+
+def extract_region_submatrices(matrix, regions_only):
+    mat = matrix.values
+    submatrices = []
+    for start, end in regions_only:
+        sub = mat[start:end+1, :]  
+        submatrices.append((start, end, sub))
+    return submatrices
+
+
+def slice_matrix2shift(matrix, params):
+
+    matrix_array = np.array(matrix)
+
+    res1 = params[0]
+    res2 = params[1]
+    time1 = params[2]
+    time2 = params[3]
+
+    output = np.zeros(time2 - time1)
+
+    if res1 == res2:
+        output[:] = matrix_array[res1, time1:time2]
+    else:
+        y = matrix_array[res1:res2+1, time1:time2]
+        for i in range(output.shape[0]):
+            output[i] = np.mean(y[:, i])
+
+    return output
+
+
+
+def load_matrix_4_diff_map(csv_path):
+    """Load a CSV file into a numeric matrix."""
+    return pd.read_csv(csv_path, header=None).values
+
+def compute_mat_diff(A, B):
+    """Compute A - B with NaN mask."""
+    if A.shape != B.shape:
+        raise ValueError(f"Matrix shapes do not match: {A.shape} vs {B.shape}")
+    return A - B

tmquick-1.0.0.dist-info/METADATA

@@ -0,0 +1,23 @@
+Metadata-Version: 2.4
+Name: tmquick
+Version: 1.0.0
+Summary: TrajMapQuick: Towards Fast Trajectory Map Analysis and Visualization
+Author: Wande M. Oluyemi (PhD), Adeniyi T. Adewumi (PhD), Shadrach C. Eze, Stephen C. Nnemolisa,  @ Research Laboratory for Rational Design of Drugs and Biomaterials (ResLaR Labs), Afe Babalola University, Ado-Ekiti Nigeria
+Project-URL: Homepage, https://github.com/SHEDOOMTC/TrajMapQuick.git
+Project-URL: Documentation, https://github.com/SHEDOOMTC/TrajMapQuick/blob/7997b0076a6c31bd725dba3ccdca4349b43250d4/README.md
+Project-URL: DOI, https://github.com/SHEDOOMTC/TrajMapQuick.git
+Requires-Python: >=3.9
+License-File: LICENSE.md
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: matplotlib
+Requires-Dist: seaborn
+Requires-Dist: tqdm
+Requires-Dist: biopython
+Requires-Dist: scipy
+Requires-Dist: netcdf4
+Requires-Dist: colorama
+Provides-Extra: md
+Requires-Dist: mdtraj; extra == "md"
+Dynamic: license-file
+Dynamic: requires-python