Metadata-Version: 2.4
Name: rinpy
Version: 0.2.1
Summary: Residue Interaction Network
Author-email: Zehra Sarica <zehraacar559@gmail.com>, Zehra Sarica <sarica16@itu.edu.tr>
License-Expression: MIT
Project-URL: Homepage, https://github.com/zehrasarica/rinpy
Project-URL: Documentation, https://github.com/zehrasarica/rinpy
Project-URL: Source, https://github.com/zehrasarica/rinpy
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: <3.14,>=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3.0,>=1.26
Requires-Dist: scipy<2.0,>=1.12
Requires-Dist: pandas<3.0,>=2.0
Requires-Dist: networkx<4.0,>=3.4
Requires-Dist: matplotlib<4.0,>=3.7
Requires-Dist: plotly<7.0,>=5.18
Requires-Dist: seaborn<1.0,>=0.13
Requires-Dist: openpyxl<4.0,>=3.1
Requires-Dist: biopandas<0.6,>=0.5.1
Requires-Dist: scikit-learn<2.0,>=1.3
Dynamic: license-file

<div align="center">
  <table border="0" cellpadding="0" cellspacing="0" style="border: none;">
    <tr>
      <td style="border: none; vertical-align: middle;">
        <img src="assets/RinPy_128x128.png" alt="RinPy logo">
      </td>
      <td style="border: none; vertical-align: middle; padding-left: 25px;">
        <h2 style="margin-top: -12px; margin-left: -40px">
          RinPy – Residue Interaction Network for Protein Structures
        </h2>
      </td>
    </tr>
  </table>
</div>

📖 Description
------------
**RinPy**, a pip-installable Python package, is designed for constructing, visualizing, and analyzing Residue Interaction Networks (RINs). RIN
describes a protein as a network of nodes interconnected by weighted edges. In this network, each node represents a
residue, nucleotide or a ligand at the average coordinate of its atomic coordinates. The edge weight between two nodes
is defined by the local interaction strength between the two residues. The average coordinates of the residues and/or
nucleotides are placed at the Cα atom or P atom, respectively, for protein-RNA/DNA complexes, such as the ribosome. Each node is annotated
with attributes such as Chain ID, Residue Number, Insertion Code, Segment ID, and its Cartesian coordinates.

✨ Features
-------------

- Converts protein complexes to residue interaction networks (RINs).
- Supports weighted edges based on the local interaction strength or affinity.
- Annotates nodes with Chain ID, Residue Number, Insertion Code, and Cartesian coordinates.
- Scalable and reproducible pipeline for single structures, large PDB ensembles, and PDBs from a MD trajectory.
- Cross-platform: compatible with Windows, macOS, and Linux.
- Can be integrated with molecular visualization system such as PyMOL.
- Centrality analysis (betweenness, closeness, and degree) to identify key residues.
- Detects the residues with high centrality scores using a user-defined quantile percentage.
- Frequency of common hub residues across PDB datasets.
- Graph spectral analysis to identify hinge residues and dynamically connected domains.
- Interactive 2D heatmap visualizations for each centrality metrics, residue frequencies, spectral domains and more.
- Interactive 3D visualizations of graph spectral clustering for protein structures.

🖥️ RinPy GUI
--------------
To facilitate ease of use, the RinPy Graphical User Interface (GUI) was developed as a companion to this package for the scientific community. The standalone RinPy GUI can be downloaded from [**here**](https://drive.google.com/drive/folders/1GlLva31y7Ebpmpd8Dk6uQmGHCem2vWfO?usp=drive_link), and the **User Manual** is available [**User Manual**](./assets/RinPy_GUI_User_Manual.pdf). Additionally, the User Manual can be accessed directly within the RinPy GUI application via **Help** > **User Manual**.

⚙️ Installation
-----------------

### 📌 Prerequisites (Important)

- **Python ≥ 3.10** is required.
- RinPy depends on **NetworkX ≥ 3.4**, which requires Python 3.10 or newer.

To ensure reliable management of the Python environment and scientific dependencies, we strongly recommend using *
*Miniconda** or **Anaconda**.

- **Miniconda** (lightweight, recommended):  
  https://docs.conda.io/en/latest/miniconda.html

- **Anaconda** (full distribution):  
  https://www.anaconda.com/products/distribution

---

### 🚀 Installation via PyPI (Recommended)

RinPy is available on **PyPI** ([RinPy](https://pypi.org/project/rinpy/)) and can be installed directly using **pip**.

The following steps demonstrate how to create and activate a conda virtual environment, install RinPy, verify the
installation, and run the program from the command line:

```bash
# Create a conda virtual environment
conda create -n rinpy_env python=3.10 -y

# Activate the environment
conda activate rinpy_env or source activate rinpy_env

# Install RinPy
pip install rinpy

# Check installation
rinpy --help

# Run RinPy
python -m rinpy --input_path INPUT_PATH --output_path OUTPUT_PATH --calculation_option_file path/to/calculation_options.json

or 

rinpy --input_path INPUT_PATH --output_path OUTPUT_PATH --calculation_option_file path/to/calculation_options.json

```

#### Parameters from the terminal

- `--input_path`: Input directory including PDB files
- `--output_path`: Output directory
- `--calculation_option_file`: JSON file containing parameters. To download,
  click [calculation_options.json](./src/rinpy/calculation_options.json).

### 🔧 Installation from Source (Alternative)

If you prefer to install RinPy from source, follow the steps below:

1. **Clone the repository:**

Replace `<username>` with GitHub username:

**Using HTTPS:**
```bash
git clone https://github.com/<username>/rinpy.git
```
**Using SSH (requires GitHub SSH keys):**
```bash
git clone git@github.com:<username>/rinpy.git
```

2. **Make scripts executable (macOS/Linux only):**

```bash
chmod -R +x rinpy
```

3. **Navigate to the project folder:**

```bash
cd rinpy
```

4. **Create a Python virtual environment (strongly recommended):**

**Using conda (strongly recommended):**

```bash
conda create -n rinpy_env python=3.10
conda activate rinpy_env or source activate rinpy_env
```

**Or using venv:**

```bash
python -m venv rinpy_env

# Activate the virtual environment
# On Windows:
rinpy_env\Scripts\activate
# On macOS/Linux:
source rinpy_env/bin/activate
```
5. **Install the package:**

- **Editable (recommended):**

```bash
pip install -e .
```
- **Non-editable:**

```bash
pip install .
```

🚀 Usage
---------
RinPy can be used programmatically via the **`RINProcess`** API within your Python scripts. Create a Python file
named **`main.py`**, insert the content given below, and execute the script via the terminal (python **`main.py`**) or an equivalent environment.

### Basic Example

RinPy uses Python's **`multiprocessing`** module.

When running RinPy from a script on macOS or Windows, make sure your entry point is protected:

```python
from multiprocessing import freeze_support
from rinpy import RINProcess


def main():
    # Define calculation options as a JSON-like dictionary
    calculation_options = {
        'remove_hydrogen': {
            'is_checked': True,
            'value': 0
        },
        'betweenness': {
            'is_checked': True,
            'value': 5
        },
        'closeness': {
            'is_checked': True,
            'value': 100
        },
        'degree': {
            'is_checked': True,
            'value': 100
        },
        'cluster_number': {
            'is_checked': True,
            'value': 3
        },
        'cutoff': {
            'is_checked': True,
            'value': 4.5
        }
    }

    # Initialize RINProcess, 
    #
    # output_path is mandatory.
    # For input, provide ONLY ONE of the following:
    #   - input_path
    #   - pdb_ids
    #   - trajectory_file
    # The system checks inputs in the following order:
    # input_path → pdb_ids → trajectory_file
    #
    # If using pdb_ids, set input_path and trajectory_file to None.

    rin = RINProcess(
        input_path="path/to/input/files",
        output_path="path/to/output",
        pdb_ids=None,  # list of PDB IDs to process if download from protein data bank such ["4OBE", "4DSN"].
        ligand_dict=None,  # optional ligand information
        calculation_options=calculation_options,
        trajectory_file=None,  # "path/to/input/files"
        stride=1  # The default is 1. This parameter is used in conjunction with trajectory_file.
    )

    # Start the process
    rin.start_process()


if __name__ == "__main__":
    freeze_support()
    main()
```

---------------------------------------------------------

📝 Notes
----------
**RinPy** requires output_path and only one of the following: input_path, pdb_ids, or trajectory_file. Providing
multiple
inputs is not allowed; if more than one is given, input_path will take precedence. Input processing order: input_path →
pdb_ids → trajectory_file.

- **output_path**: Folder where processed RINs and results will be saved
- **input_path**: Folder containing your input PDB files
- **pdb_ids**: List of specific PDB IDs to process
- **ligand_dict**: Optional dictionary with ligand information
- **calculation_options**: JSON-like dictionary specifying which calculations to run and their parameters
- **trajectory_file**: The MD trajectory file (pdb format) which contains multiple snaphots from MD.
- **stride**: Default is **1**. This parameter is used in conjunction with trajectory_file parameter.

## 📊 Case Study of RinPy

After setting up a Conda virtual environment and installing **RinPy**, navigate to the **`tests`** folder. It contains
two
Python scripts and their corresponding `.sh` files for running the analyses.
The **`kras_sos1_input`** folder contains KRAS–SOS1 PDB files, whereas **`kras_input`** includes KRAS PDB structures
used in the
case study.

To analyze the MD trajectory PDB files, download the dataset
from [here](https://drive.google.com/file/d/1COAZqgiCGVhkYvCI6DQLv2YzJ5emcvRN/view?usp=drive_link).
You may update the existing a Python script and its corresponding `.sh` file under `tests` directory.

📄 License
------------
MIT License. See [LICENSE](LICENSE) file for details.

📘How to Cite
---------------

If you use this repository, please cite this study as follows:

```bibtex
@article{rinpy,
  title={RinPy, a Python Package for Residue Interaction Network Model to Analyze Protein Structures and Predict Ligand Binding Sites},
  author={Sarica, Z.; Sungur, F. A.; Kurkcuoglu, O.},
  journal={},
  volume={},
  year={},
  publisher={}
}
```

📬 Contact
------------
For questions, contact: zehraacar559@gmail.com, sarica16@itu.edu.tr
