tmquick 1.0.0__tar.gz

tmquick-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SHEDOOMTC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tmquick-1.0.0/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include tmq *.py
+

tmquick-1.0.0/PKG-INFO

@@ -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

tmquick-1.0.0/README.md

@@ -0,0 +1,197 @@
+<p align="center">
+  <img src="https://github.com/SHEDOOMTC/TrajMapQuick/blob/main/assets/TrajMapQuick.png" alt="TrajMapQuick Logo" />
+</p>
+
+## **Overview**
+**TrajMapQuick 1.0** is a light tool useful for visualization of trajectory maps and residual shifts within select regions of proteins, across several frames. It is built partially on the codes provided in the original work of Matej Kožić and Branimir Bertoša, 2024 : [**"Trajectory maps: molecular dynamics visualization and analysis"**](https://doi.org/10.1093/nargab/lqad114). **TrajMapQuick** extends the work by reconfiguring how the pdb files are parsed to generate the distance matrix, thereby improving speed dramatically. In addition, **TrajMapQuick** provides a CLI where the user can pass arguments for better throughput and batch processing. 
+We have also extended the code to allow for automatic detection of regions with high residual fluctuations (named **"Hotspots"**) and  generation of the residual shifts of those regions. In addition, a python API has also been provided for python based community. In TrajMapQuick, the user can also choose between the backbone (**backbone**) atoms or the alpha carbon (**CA**) for computing the maps. 
+
+## **Features**
+- **Trajectory Map Visualization:** Generates a trajectory map of residual fluctuations across the select frames chosen by the user.
+- **Residual shift calculation and visualization:** For a select range of residues (region), residual shifts are computed and visualized across select frames
+- **Difference and Average map visualization** This computes the difference and average of two trajectories, respectively and display the resultant trajectory maps.
+- **Hotspot Detection and Plotting:** This automatically probes and detects regions of high fluctuations and computes the residual shift for each region for downstream processing.
+- **Hotspot Annotation:** An RMSF like plot is also generated with the key hotspots highlight for visual confirmation and inspection.
+
+## **Project Structure**
+<pre>
+TrajMapQuick/
+├── README.md                     # Project overview, installation, usage 
+├── requirements.txt              # Python dependencies
+├── setup.py                      # Packaging configuration
+├── environment.yml               # Build config
+├── pyproject.toml                # Build config 
+├── LICENSE                       # MIT license
+├── Manifest.in                   
+├── tmq/                          # Source codes and CLI wrappers lives here
+│   ├── cli.py/                   # Main command line launcher 
+│   ├── __init__.py               # Main launcher for the python API
+│   ├── core/                     # Python package folder
+│   │   ├── __init__.py
+│   │   ├── traj2pdb.py           # Converts trajectory to pdb
+│   │   ├── pdb2csv.py            # Converts pdb to distance matrix
+│   │   ├── trajmap.py            # plots the trajectory map
+│   │   ├── csv2shift.py          # Core shift logic for a given loop
+│   │   ├── shift2graph.py        # Makes shift plots for a given loop
+│   │   ├── hotspot.py            # Automatic detection of regions with peak fluctuations
+│   │   ├── diff2graph.py         # Computes and plot difference map for two trajectories
+│   │   └── average_trajmap.py    # Computes and plot average map for two trajectories
+│   ├── commands/                 # Main wrapper for the CLI
+│   │   ├── __init__.py
+│   │   ├── traj2pdb_cli.py       # CLI wrapper
+│   │   ├── pdb2csv_cli.py        # CLI wrapper
+│   │   ├── trajmap_cli.py        # CLI wrapper
+│   │   ├── csv2shift_cli.py      # CLI wrapper
+│   │   ├── shift2graph_cli.py    # CLI wrapper
+│   │   ├── hotspot_cli.py        # CLI wrapper
+│   │   ├── diff2graph_cli.py     # CLI wrapper
+│   │   └── average_trajmap_cli.py# CLI wrapper
+│   └── utils                     # Holds functions
+│   │   ├── __init__.py
+│   │   └── utils.py              # utility functions
+├── docs/                         # docstrings for the modules
+├── assets/                       # Container for images
+├── Tests/                        # Containers for test trajectories and topologies
+└── Conda/                        # Backup YAML files
+
+
+</pre>
+
+## **Installation**
+```bash
+# Clone the repo
+git clone https://github.com/SHEDOOMTC/TrajMapQuick.git
+cd TrajMapQuick
+
+# In conda environment with pip
+conda create -n tmq python=3.10 
+conda activate tmq
+conda install -c conda-forge mdtraj
+pip install (-e) .
+
+# In conda environment without pip
+conda env create -f environment.yml
+conda activate tmq
+
+Use tmq --help to see the arguments
+```
+## **Commands**
+```bash
+#TrajMapQuick uses a two levell subcommand from the global "tmq" command
+tmq  shift  : Extract matrices, compute residue-residue shifts and make plots: For more, use tmq shift --help
+
+tmq hotspot : Detect hotspots in residue shifts and create plots: For more, use tmq hotspot --help
+
+tmq diff      Computes difference between two matrices and creates the difference map: For more, use tmq diff --help
+
+tmq average   Computes average of n matrices and creates the average map: For more, use tmq average --help
+
+```
+## **Usage (CLI)**
+```bash
+# For tmq shift, arguments are passed into the flags for trajectory, topology etc.
+
+tmq shift --traj traj.pdb --top top.parmtop --str 1 --resr 1-300 --resrs 110-125 --cent backbone --plot --out shift_output
+
+#for tmq hotspot, arguments are passed similiarly, except that the region of shift is not provided
+
+tmq hotspot --traj traj.pdb --top top.parmtop --str 1 --resr 1-300 --cent backbone --out hotspot_output
+```
+## **Usage (Python API)**
+The core modules in the tmq library are clearly demonstrated in the **[Python_API.ipynb](./Notebooks/Python_API.ipynb)** file
+
+```python
+#Typical modules are loaded and then used as explained in the jupyter notebook above:
+
+from tmq.core.traj2pdb import traj2pdb
+from tmq.core.pdb2csv import pdb2csv  
+from tmq.core.trajmap import trajmap
+from tmq.core.csv2shift import shift
+from tmq.core.shift2graph import shift2graph
+from tmq.core.hotspot import detect_shifts
+from tmq.core.hotspot import create_submatrices
+from tmq.core.hotspot import plot_hotspot_regions
+from tmq.core.hotspot import slice_shifts
+from tmq.core.hotspot import plot_slice_regions
+from tmq.core.diff2graph import diff_map
+from tmq.core.average_trajmap import avg_trajmap
+```
+
+```python
+# To run the notebook
+cd ./Notebooks/
+jupyter notebook Python_API.ipynb
+```
+
+## **Requirements**
+- Trajectory processing libraries (mdtraj, biopython)
+
+- Data wrangling tools (numpy, pandas)
+
+- Trajectories must have been preprocessed (strippin water, ions,) before feeding into TrajMapQuick
+
+
+All library requirements are pre-installed installed via pip or conda and are available for use in CLI or via Python API
+
+## **Examples**
+Three trajectories and topologies files are included in the **[Test](./Test)** directory for users to try out the codes. Trajectory 1 has only 125 frames (from apo strucuture of PDB ID: 8EM8 with 789 residues) while others have 250 frames (from apo and bound strucutres of BACE1, with 389 residues). To get the full sized trajectories, see [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20681326.svg)](https://doi.org/10.5281/zenodo.20681326)
+
+
+The Utility of the shift command (using a 500 frame trajectory) was shown by the figure below:
+
+![test_traj_2_shift_graph.png](https://github.com/SHEDOOMTC/TrajMapQuick/blob/main/assets/test_traj_2_shift_graph.png)
+
+
+**And that of the hotspot command by:**
+
+
+![test_traj_2_hotspot_graph.png](https://github.com/SHEDOOMTC/TrajMapQuick/blob/main/assets/test_traj_2_hotspot_graph.png)
+
+
+To reproduce the figures above, download the full length trajectory (500 frames) from Zenodo [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20681326.svg)](https://doi.org/10.5281/zenodo.20681326) and run the codes below on the CLI
+
+```bash
+#The exact codes used to produce the results above
+tmq shift -tr traj_9NSR_500.nc -to topol_9NSR.prmtop -st 1 -rr 1-378 -rs 272-285 -ce backbone -ma 5 -o out
+
+tmq hotspot -tr traj_9NSR_500.nc -to topol_9NSR.prmtop -st 1 -rr 1-378 -ce backbone -o out
+```
+ 
+
+## **Improvements (Speed, Throughput and Reliability)**
+**1.** Batch processing over the CLI and Python API
+
+**2.** A major improvement of TrajMapQuick over TrajMap is the speed across varying **residue lengths** and **number of frames**. We evaluated a 1000 frame trajectory (at 100 frame interval) over 800 residues (at 100 residue interval) in TrajMapQuick for both subcommands (shift & hotspot). The **performance plots below:** 
+
+![performance plots](https://github.com/SHEDOOMTC/TrajMapQuick/blob/main/assets/Performance_shift_hotspot.png?raw=true) 
+
+shows clear scaling with number of residues and frames, with completion time between **2-5 mins**. Compared to TrajMapQuick, a single 500 frame calculations across 800 residues took around **10 minutes** in TrajMap, besides the manual editing of input parameters.
+
+**3.** The choice to select either the CA or backbone for shift calculations.
+
+**4.** Automatic Detection of hotspots using RMSF plots and generation of associated shift plots.
+
+**4.** TrajMapQuick allows you to work on any continous chunk of your protein, say residues 300-360 of a 500-residues protein. This reduces time and allows one to focus.
+
+## **Contributing**
+Contributions are welcome. Please submit a pull request with your changes.
+
+## **License**
+[**MIT License**](../License.md)
+
+## **Contact**
+
+For questions or issues, please contact us @ [Reslar Labs](reslarscience@gmail.com)  **&copy; 2026**, or [Dr. Oluyemi](oluyemiwm@abuad.edu.ng) or [Shadrach Eze](shadrachchinecheremeze@gmail.com).
+
+
+## **Citation**
+
+If you use TrajMapQuick, please cite: SHEDOOMTC. (2026). TrajMapQuick: Towards Fast Trajectory Map Analysis and Visualization (v1.0). Zenodo. https://doi.org/10.5281/zenodo.20681061
+
+**Software:**  
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20681061.svg)](https://doi.org/10.5281/zenodo.20681061)
+
+**Dataset:**  
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20681326.svg)](https://doi.org/10.5281/zenodo.20681326)
+
+

tmquick-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "tmquick"
+version = "1.0.0"
+description = "TrajMapQuick: Towards Fast Trajectory Map Analysis and Visualization"
+authors = [
+    { name = "Wande M. Oluyemi (PhD)" },
+    { name = "Adeniyi T. Adewumi (PhD)" },
+    { name = "Shadrach C. Eze" },
+    { name = "Stephen C. Nnemolisa" },
+    { name = " @ Research Laboratory for Rational Design of Drugs and Biomaterials (ResLaR Labs)"},
+    { name = "Afe Babalola University, Ado-Ekiti Nigeria"}
+]
+
+requires-python = ">=3.9"
+dependencies = [
+    "numpy",
+    "pandas",
+    "matplotlib",
+    "seaborn",
+    "tqdm",
+    "biopython",
+    "scipy",
+    "netcdf4",
+    "colorama"
+]
+
+[project.optional-dependencies]
+md = ["mdtraj"]
+
+[project.urls]
+Homepage = "https://github.com/SHEDOOMTC/TrajMapQuick.git"
+Documentation = "https://github.com/SHEDOOMTC/TrajMapQuick/blob/7997b0076a6c31bd725dba3ccdca4349b43250d4/README.md"
+DOI = "https://github.com/SHEDOOMTC/TrajMapQuick.git"
+
+[project.scripts]
+tmq = "tmq.cli:main"

tmquick-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

tmquick-1.0.0/setup.py

@@ -0,0 +1,30 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="tmq",
+    version="1.0",
+    description = "Trajectory map analysis toolkit",
+    authors = "Wande M. Oluyemi (PhD), Adeniyi Adewumi (PhD), Shadrach Eze @ ResLaR Labs, Afe Babalola University, Nigeria",
+    readme = "README.md",
+    python_requires = ">=3.9",
+    packages=find_packages(include=["tmq", "tmq.*"]),
+    include_package_data=True,
+    extras_require={"md": ["mdtraj"],},
+    install_requires=[
+        "numpy",
+        "pandas",
+        "matplotlib",
+        "seaborn",
+        "tqdm",
+        "biopython",
+        "scipy",
+        "netcdf4",
+        "colorama"
+
+    ],
+    entry_points={
+        "console_scripts": [
+            "tmq=tmq.cli:main",
+        ]
+    },
+)

tmquick-1.0.0/tmq/__init__.py

@@ -0,0 +1,14 @@
+__version__ = "1.0"
+from .core.traj2pdb import traj2pdb
+from .core.pdb2csv import pdb2csv  
+from .core.trajmap import trajmap
+from .core.csv2shift import shift
+from .core.shift2graph import shift2graph
+from .core.hotspot import detect_shifts
+from .core.hotspot import create_submatrices
+from .core.hotspot import plot_shift_regions
+from .core.hotspot import slice_shifts
+from .core.hotspot import plot_slice_regions
+from .core.hotspot import plot_hotspot_regions
+from .core.diff2graph import diff_map
+from .core.average_trajmap import avg_trajmap

tmquick-1.0.0/tmq/cli.py

@@ -0,0 +1,250 @@
+"""Main CLI launcher
+"""
+
+import argparse
+import time
+from .commands.traj2pdb_cli import traj2pdb_cli
+from .commands.pdb2csv_cli import pdb2csv_cli  
+from .commands.trajmap_cli import trajmap_cli
+from .commands.csv2shift_cli import shift_cli
+from .commands.shift2graph_cli import shift2graph_cli
+from .commands.hotspot_cli import detect_shift_cli
+from .commands.hotspot_cli import create_submatrices_cli
+from .commands.hotspot_cli import slice_shifts_cli
+from .commands.hotspot_cli import run_hotspot_cli
+from .commands.diff2graph_cli import diff_map_cli
+from .commands.average_trajmap_cli import avg_trajmap_cli
+from colorama import init, Fore, Style
+init(convert=False)
+
+
+"""Time counter"""
+def print_final_message(total):
+    print(
+        Fore.GREEN +
+        "\nTrajMapQuick analysis complete. \n" +
+        Fore.CYAN +
+        "\nAll tasks completed successfully.\n"+
+        Style.RESET_ALL
+    )
+    print(f"Total computation time: {total:.2f} seconds \n" +
+        Fore.MAGENTA +
+        "\nThank you for using TrajMapQuick 1.0 — ResLaR Labs, Afe Babalola University, Ado-Ekiti Nigeria.\n" +
+        Style.RESET_ALL)
+    
+
+"""Display logo"""
+def main():
+    start_time = time.perf_counter()
+    init()
+    print(Fore.GREEN + r"""
+
+     _______         _ __  __              ____  
+    |__   __|       (_)  \/  |            / __ \ 
+        | |_ __ __ _ _| \  / | __ _ _ __ | |  | |
+        | | '__/ _` | | |\/| |/ _` | '_ \| |  | |
+        | | | | (_| | | |  | | (_| | |_) | |__| |
+        |_|_|  \__,_| |_|  |_|\__,_| .__/ \___\_\
+                   _/ |            | |           
+                  |__/             |_|           
+          
+
+          """ + Style.RESET_ALL)
+    print("========== Welcome to TrajMapQuick 1.0 ==========")
+    print("")
+    print("Authors : " + Fore.BLUE + "Wande M. Oluyemi, Adeniyi T. Adewumi, Shadrach C. Eze & Stephen C. Nnemolisa @ ResLaR Labs, Afe Babalola University, Ado-Ekiti Nigeria" + Style.RESET_ALL)
+    print("")
+    print("")
+
+    parser = argparse.ArgumentParser(
+        prog="tmq",
+        add_help=False,
+        formatter_class=argparse.RawTextHelpFormatter,
+        description="""
+    A command-line toolkit for MD trajectory map analysis:
+    • matrix extraction
+    • shift computation
+    • visualization
+
+    Built on the original work of Kožić & Bertoša, 2024,
+    Trajectory maps: molecular dynamics visualization and analysis,
+    https://doi.org/10.1093/nargab/lqad114
+
+    TrajMapQuick is faster, improves batch processing, and allows
+    automatic shift detection from trajectory maps.
+    """
+    )
+    
+    parser.add_argument(
+    "-h", "--help",
+    action="help",
+    help="Show usage information")
+
+    subparsers = parser.add_subparsers(
+        title="Available subcommands",
+        dest="command",
+        metavar=""
+    )
+
+    """SHIFT SUBCOMMAND"""
+    shift_parser = subparsers.add_parser(
+        "shift",
+        help="Extract matrices, compute residue-residue shifts and make plots: For more, use tmq shift --help",
+        description=(
+            "Converts your trajectory into pdb multimodel form and then to a CSV file, "
+            "extracts a distance matrix from the CSV file and computes "
+            "a shift value between a residue range over a specified frame.\n\n"
+            "Example:\n"
+            "  tmq shift --traj traj.pdb --top top.parmtop --str 1 --resr 1-300 --resrs 110-125 --cent backbone --plot --out shift_output\n\n"
+            "This will compute the shift of the backbone atoms, for residues 110-125, across the trajectory of a protein with residues 1-300, and will generate plots automatically."),
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    shift_parser.add_argument("-tr", "--traj", required=True,
+                              help="Input trajectory, accepts pdb, nc, xtc xtr")
+    shift_parser.add_argument("-to", "--top", required=True,
+                              help="Topology file, accepts parmtop, pdb, gro")
+    shift_parser.add_argument("-st", "--str", type=int, default=1,
+                              help="Stride of the trajectory, (default: 1)")
+    shift_parser.add_argument("-rr", "--resr", type=str, required=True,
+                              help="Residue range of your protein in the form start-end (e.g., 1-300")
+    shift_parser.add_argument("-rs", "--resrs", type=str, required=True,
+                              help="Residue range for shift calculation, in the form start-end (e.g., 110-125")
+    shift_parser.add_argument("-ce", "--cent", type=str, default="backbone", required=True,
+                              help="Centre of calculations, either the backbone " \
+                              "atoms or the ca atoms, (default: backbone)")
+    shift_parser.add_argument("-ma", "--max", type=int, default=5, required=False,
+                              help="Max shift value for color scaling, (default: 5)")
+    shift_parser.add_argument("-o", "--out", type=str, required=True,
+                              help="Basename for all outputs")
+    
+
+    """HOTSPOT SUBCOMMAND"""
+    dehot_parser = subparsers.add_parser(
+        "hotspot",
+        help="Detect hotspots in residue shifts and create plots: For more, use tmq hotspot --help",
+        description=(
+            "Detect hotspots in residue shifts and creates publication-ready plot with trajectory map"
+            "and hotspot regions annotated, and also generates shift graphs for detected hotspot regions.\n\n"
+            "Example:\n"
+            "  tmq hotspot --traj traj.pdb --top top.parmtop --str 1 --resr 1-300 --cent backbone --out hotspot_output\n\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    dehot_parser.add_argument("-tr", "--traj", required=True,
+                              help="Input trajectory, accepts Pdb, nc, xtc xtr")
+    dehot_parser.add_argument("-to", "--top", required=True,
+                              help="Topology file, accepts .parmtop, pdb, gro")
+    dehot_parser.add_argument("-st", "--str", type=int, default=1,
+                              help="Stride of the trajectory, (default: 1)")
+    dehot_parser.add_argument("-rr", "--resr", type=str, required=True,
+                              help="Residue range of your protein in the form start-end (e.g., 1-300")
+    dehot_parser.add_argument("-ce", "--cent", type=str, default="backbone", required=True,
+                              help="Centre of calculations, either the backbone " \
+                              "atoms or the ca atoms, (default: backbone)")
+    dehot_parser.add_argument("-win", "--window", type=int, default=5, required=False,
+                            help="Rolling window size for smoothing, (default: 5) (Not Required)")
+    dehot_parser.add_argument("-md", "--mindist", type=int, default=3, required=False,
+                               help="Minimum distance between peaks, (default: 3) (Not Required)")
+    dehot_parser.add_argument("-hs", "--hot", type=int, default=10, required=False,
+                          help="Number of top peaks to extract, (default: 10) (Not Required)")
+    dehot_parser.add_argument("-ma", "--max", type=int, default=5, required=False,
+                              help="Max shift value for color scaling, (default: 5) (Not Required)")
+    dehot_parser.add_argument("-o", "--out", type=str, required=True,
+                              help="Basename for outputs")
+    
+
+    """DIFFERENCE SUBCOMMAND"""
+    dehot_parser = subparsers.add_parser(
+        "diff",
+        help="Computes difference between two matrices and creates the difference map: For more, use tmq diff --help",
+        description=(
+            "Computes difference between two matrices and creates publication-ready plot with difference map.\n\n"
+            "The input matrices must be supplied by the names of the output of previous 'Shift' runs.\n\n"
+            "A subsequent downstream processing after 'Shift' runs; thus, matrices must have equal lengths.\n\n"
+            "Example:\n"
+            "  tmq diff --mat1 apo --mat2 holo --resr 1-300 --max 8 --out my_diff\n\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    dehot_parser.add_argument("-m1", "--mat1", required=True,
+                              help="First matrix, accepts only the name without extension")
+    dehot_parser.add_argument("-m2", "--mat2", required=True,
+                              help="Second matrix, accepts only the name without extension")
+    dehot_parser.add_argument("-rr", "--resr", type=str, required=True,
+                              help="Residue range of your protein in the form start-end (e.g., 1-300")
+    dehot_parser.add_argument("-ma", "--max", type=int, default=5, required=True,
+                              help="Max shift value for color scaling, (default: 5)")
+    dehot_parser.add_argument("-o", "--out", type=str, required=True,
+                              help="Basename for outputs")
+
+
+
+    """DIFFERENCE SUBCOMMAND"""
+    dehot_parser = subparsers.add_parser(
+        "average",
+        help="Computes average of n matrices and creates the average map: For more, use tmq average --help",
+        description=(
+            "Computes average of n matrices and creates publication-ready plot with average map. \n\n"
+            "The input matrices must be supplied by the names of the output of previous 'Shift' runs as comma separated values.\n\n"
+            "A subsequent downstream processing after 'Shift' runs; thus, matrices must have equal lengths.\n\n"
+            "Example:\n"
+            "  tmq average --mat apo,holo,bound --resr 1-300 --max 8 --out my_avg\n\n"
+        ),
+        formatter_class=argparse.RawTextHelpFormatter
+    )
+
+    dehot_parser.add_argument("-m", "--mat", required=True, type=str,
+                              help="Comma-separated list of matrix names, accepts only the name without extension")
+    dehot_parser.add_argument("-rr", "--resr", type=str, required=True,
+                              help="Residue range of your protein in the form start-end (e.g., 1-300")
+    dehot_parser.add_argument("-ma", "--max", type=int, default=5, required=True,
+                              help="Max shift value for color scaling, (default: 5)")
+    dehot_parser.add_argument("-o", "--out", type=str, required=True,
+                              help="Basename for outputs")
+
+
+    print("")
+    args = parser.parse_args()
+
+    if args.command == "shift":
+        traj2pdb_cli(args)
+        pdb2csv_cli(args)
+        shift_cli(args)
+        trajmap_cli(args)
+        shift2graph_cli(args)
+        end_time = time.perf_counter()
+        total = end_time - start_time    
+        print_final_message(total)
+    elif args.command == "hotspot":
+        traj2pdb_cli(args)
+        pdb2csv_cli(args)
+        trajmap_cli(args)
+        detect_shift_cli(args)
+        create_submatrices_cli(args)
+        run_hotspot_cli(args)  
+        slice_shifts_cli(args)
+        run_hotspot_cli(args)
+        end_time = time.perf_counter()
+        total = end_time - start_time    
+        print_final_message(total)
+
+    elif args.command == "diff":
+        diff_map_cli(args)
+        end_time = time.perf_counter()
+        total = end_time - start_time    
+        print_final_message(total)
+
+    elif args.command == "average":
+        avg_trajmap_cli(args)
+        end_time = time.perf_counter()
+        total = end_time - start_time    
+        print_final_message(total)        
+        
+    else:
+        parser.print_help()
+        print("")
+        print("Cite this as: " + Fore.BLUE + "SHEDOOMTC. (2026). TrajMapQuick: Towards Fast Trajectory Map Analysis and Visualization (v1.0). Zenodo. https://doi.org/10.5281/zenodo.20681061" + Style.RESET_ALL)
+        print("")

tmquick-1.0.0/tmq/commands/__init__.py

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

tmquick-1.0.0/tmq/commands/average_trajmap_cli.py

@@ -0,0 +1,36 @@
+"""Parse input matrices, compute their element-wise average, 
+and save an averaged trajectory map PNG.
+"""
+
+import time
+from ..core.average_trajmap import avg_trajmap
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+from ..utils.utils import ensure_csv_extension, ensure_png_extension, parse_range, load_matrix_4_diff_map, csv2matrix
+
+
+def avg_trajmap_cli(args):
+    start_time = time.perf_counter()
+    print("")
+    print("Plotting Average map...")
+
+    """split the matrix argument to get list of matrices
+    """
+    matrix_names = args.mat.split(",")
+    prefix = "_pdb2csv_"
+    matrices = [csv2matrix(ensure_csv_extension(name + prefix)) for name in matrix_names]
+
+    residue_start, residue_end = parse_range(args.resr)
+
+    """pass the matrices to the core function
+    """
+    fig = avg_trajmap(residue_start, residue_end, args.max, *matrices)
+
+    prefix1 = "_average_map_"
+    savename = ensure_png_extension(args.out + prefix1)
+    fig.savefig(savename, dpi=800, bbox_inches='tight')
+    print(f"Difference map saved to {savename}")
+    plt.close(fig)
+    total = time.perf_counter() - start_time
+    print(f"Time taken to plot Difference map: {total:.2f} seconds")

tmquick-1.0.0/tmq/commands/csv2shift_cli.py

@@ -0,0 +1,27 @@
+"""Load a distance matrix, compute residue-range shifts across frames, and write a shift CSV.
+"""
+
+import time
+from ..core.csv2shift import shift
+from ..utils.utils import csv2matrix, ensure_csv_extension, parse_range
+
+
+def shift_cli(args):
+    start_time = time.perf_counter()
+    print("")
+    prefix = "_pdb2csv_"
+    file = ensure_csv_extension(args.out + prefix)
+    matrix = csv2matrix(file)
+    residue_start, residue_end = parse_range(args.resrs)
+    n_frames = matrix.shape[1]
+    print(f"Calculating shift for residues {residue_start} to {residue_end} "
+          f"across frames 0 to {n_frames - 1}...")
+
+    shifta = shift(matrix, residue_start, residue_end)
+
+    prefix2 = "_shift_"
+    savename = ensure_csv_extension(args.out + prefix2)
+    shifta.to_csv(savename, index=False)
+    print(f"Shift saved to {savename}")
+    total = time.perf_counter() - start_time
+    print(f"Time taken to calculate shift: {total:.2f} seconds")