rinpy 0.2.1

Residue Interaction Network

RinPy – Residue Interaction Network for Protein Structures

📖 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, and the User Manual is available User Manual. 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) 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:

# 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.

🔧 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:

git clone https://github.com/<username>/rinpy.git

Using SSH (requires GitHub SSH keys):

git clone [e-mail]:<username>/rinpy.git

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

chmod -R +x rinpy

3. Navigate to the project folder:

cd rinpy

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

Using conda (strongly recommended):

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

Or using venv:

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):

pip install -e .

• Non-editable:

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:

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. You may update the existing a Python script and its corresponding .sh file under tests directory.

📄 License

MIT License. See LICENSE file for details.

📘How to Cite

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

@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: [e-mail], [e-mail]