Metadata-Version: 2.4
Name: viennaptm-pymol
Version: 0.1.0
Summary: PyMOL plugin for ViennaPTM post-translational modification library
Author-email: Sophie Margreitter <sophie.margreitter@gmail.com>, Christian Margreitter <christian.margreitter@gmail.com>
Maintainer-email: Sophie Margreitter <sophie.margreitter@gmail.com>, Christian Margreitter <christian.margreitter@gmail.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://viennaptm.univie.ac.at
Project-URL: Repository, https://github.com/viennaptm/viennaptm_pymol
Keywords: Post-translational modifications,python,python-packages,semantic-versions,pymol
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: viennaptm>=0.2.0
Provides-Extra: test
Requires-Dist: pytest>=8.4.0; extra == "test"
Provides-Extra: build
Requires-Dist: twine; extra == "build"
Requires-Dist: build; extra == "build"
Dynamic: license-file

# ViennaPTM `PyMOL` plugin
[![PyPI version](https://badge.fury.io/py/viennaptm-pymol.svg)](https://pypi.org/project/viennaptm-pymol/)  
[![License](https://img.shields.io/github/license/viennaptm_pymol/viennaptm-pymol.svg)](LICENSE)  
[![Python Version](https://img.shields.io/badge/python-3.9%2B-green.svg)](https://www.python.org)

---

This plugin is used for applying [ViennaPTM](https://github.com/viennaptm/viennaptm) post-translational modifications to protein side-chains directly inside `PyMOL`.
It should be compatible with both the [proprietary](https://www.pymol.org) and the [open-source](https://github.com/schrodinger/pymol-open-source) version of `PyMOL`.

## Installation

There are two different ways to install the plugin, either via direct installation of the library or by importing a `zip` file from the plugin manager dialog within `PyMOL`.

### Using a dedicated `conda` environment (recommended)

```bash
# create an environment and install the version of PyMOL you need
# here, it uses the open-source iteration
conda create --name viennaptm_pymol python=3.11
conda activate viennaptm_pymol
conda install -c conda-forge "pymol-open-source>=3.1.0" "numpy<2"

# install the plugin from the pypi server, it will register itself directly
pip install viennaptm-pymol
```

In order for the plugin to show up, you need to restart `PyMOL` if it was open at the time of installation.

Troubleshoot: If the plugin does not load automatically, try to execute teh installation manually.
```bash
viennaptm-pymol-install
```

### Using a `zip` file

Install the dependencies first (the following only registers the plugin with `PyMOL`):

```bash
pip install viennaptm-pymol
```

Then:

1. Download **`viennaptm-<version>.zip`** from the [GitHub Releases](https://github.com/viennaptm/viennaptm_pymol/releases/latest) page.
2. In `PyMOL`, open **Plugin -> Plugin Manager -> Install** and select the ZIP file.
3. Restart `PyMOL`.

### Developer's notice: Locations of `PyMOL` plugins

Open-source `PyMOL` scans `**$PYMOL_DATA/startup/**`. The install tries to copy the startup wrapper there when that directory is writable (typical for `conda` envs). Otherwise it falls back to `~/.pymol/startup/` and registers that path with `PyMOL`.

## Usage

1. Launch `PyMOL`. If you are using a dedicated environment, first activate it:

   ```bash
   conda activate viennaptm_pymol
   pymol
   ```

2. Load a protein structure.
3. Select a residue (click an atom or `select resi 50 and chain A`).

<p align="center">
  <img src="assets/sequence_select.png" alt="Select a residue." width="6000"/>
</p>

4. Open **Plugin -> ViennaPTM -> Modify selected residue…**

<p align="center">
  <img src="assets/menu_overlay.png" alt="Plugin position in top menu." width="360"/>
</p>

<p align="center">
  <img src="assets/selection_menu.png" alt="Select available modification from dialog." width="360"/>
</p>

5. Choose a modification and click **Apply modification**.
6. The structure is updated in place, or a new object is created if **Make copy** is checked.
7. Save or export the structure as needed.

<p align="center">
  <img src="assets/modification_structure.png" alt="Example of result: GLN → QME." width="600"/>
</p>

If multiple residues are selected, a separate picker dialog lets you choose one residue to modify.

## Authors / Contributors

- **Sophie Margreitter** - [GitHub](https://github.com/SMargreitter)
- **Christian Margreitter** - [GitHub](https://github.com/CMargreitter)
