pkaraptor 0.1.2

Protein pKa and environment analysis with an interactive HTML dashboard

pKaRaptor

pKaRaptor is a Python toolkit for the analysis of protein protonation states and residue-level physicochemical environments, with results presented through an interactive HTML dashboard.

The package is intended for structure-based exploration of ionizable residues and their local environments, supporting the inspection of protonation-related features in proteins. It was developed to facilitate the interpretation of pKa-relevant structural descriptors in a practical and accessible format for research workflows.

Overview

Protonation states play an important role in protein structure, stability, dynamics, and function. pKaRaptor was developed as a lightweight toolkit to help researchers inspect protein structures with a focus on ionizable residues and their surrounding physicochemical environments.

The package combines command-line workflows with an interactive dashboard, allowing users to move from structure processing to exploratory analysis in a reproducible and accessible way.

Features

• Analysis of protein protonation states and residue-level physicochemical environments from PDB structures
• Integration of multiple pKa sources, including local and external predictions
• Support for membrane-aware annotation through OPM/PPM-oriented structures
• Interactive HTML dashboard for visual exploration of results
• Export of residue selections from the dashboard in JSON format
• Utilities to apply residue-name selections to structures
• Protonation workflows using OpenMM templates

Installation

Install from PyPI

pip install pkaraptor

Create and activate a dedicated environment (recommended)

Using conda:

conda create -n pkaraptor python=3.10
conda activate pkaraptor
pip install pkaraptor

Using venv:

python -m venv pkaraptor-env
source pkaraptor-env/bin/activate
pip install pkaraptor

Installation from source

git clone https://github.com/jmargaridars/pkaraptor.git
cd pkaraptor
pip install -e .

Requirements

• Python 3.10 or later

Command-line tools

After installation, the following command-line tools should be available:

pkaraptor
pkaraptor-dashboard
pkaraptor-apply-json
pkaraptor-protonate

Main analysis

The main pkaraptor command generates a protonation and environment analysis CSV from a PDB structure using pKa sources and environment descriptors.

pkaraptor --pdb input.pdb

To inspect all available options:

pkaraptor -h

Main options

• --pdb input PDB file
• --ph pH at which protonation fractions are computed
• --out output CSV file name
• --no-propka disable local PROPKA execution
• --pypka-csv PyPka server CSV input
• --deepka-csv DeepKa server CSV input
• --opm-id optional OPM identifier for downstream visualization
• --opm-zmin lower Z boundary of membrane slab in Angstrom
• --opm-zmax upper Z boundary of membrane slab in Angstrom
• --opm-pdb oriented PDB from PPM/OPM for environment feature calculation
• --opm-residues legacy residue ranges without chain identifiers
• --opm-embedded chain-aware embedded residues, repeatable by chain

Example usage

Basic analysis:

pkaraptor --pdb protein.pdb

Analysis at a defined pH with a custom output file:

pkaraptor --pdb protein.pdb --ph 7.4 --out protonation_environment_analysis.csv

Analysis using external pKa predictions:

pkaraptor --pdb protein.pdb --pypka-csv pypka_results.csv --deepka-csv deepka_results.csv

Membrane-aware analysis using an OPM-oriented structure:

pkaraptor --pdb protein.pdb --opm-pdb protein_opm.pdb --opm-zmin -15 --opm-zmax 15

Chain-aware membrane embedded residues:

pkaraptor --pdb protein.pdb --opm-embedded "A:48-66,69,426" --opm-embedded "B:48-66,69,426,461"

Dashboard generation

The pkaraptor-dashboard command builds an interactive protonation dashboard HTML from a PDB structure and a CSV file produced by pkaraptor.

pkaraptor-dashboard --pdb protein.pdb --csv protonation_environment_analysis.csv --out dashboard.html

To inspect all available options:

pkaraptor-dashboard -h

Dashboard options

• --pdb input PDB file
• --csv CSV file produced by pkaraptor
• --ph pH used for the analysis, displayed in the dashboard title
• --out output HTML file

Apply dashboard selections to a PDB

The pkaraptor-apply-json command applies residue-name selections exported from the dashboard to a PDB by renaming residue names.

pkaraptor-apply-json --json selections.json --pdb protein.pdb --out renamed_structure.pdb

To inspect all available options:

pkaraptor-apply-json -h

Apply-json options

• --json selections JSON exported from the dashboard
• --pdb input PDB file, overriding the JSON pdb field if provided
• --out output protonated or renamed PDB file
• --no-validate-allowed disable validation that selected_resname is present in allowed_resnames

Protonate a structure from dashboard selections

The pkaraptor-protonate command applies selections exported from the dashboard to a PDB and adds hydrogens using OpenMM templates.

pkaraptor-protonate --json selections.json --pdb protein.pdb --out protonated_structure.pdb

To inspect all available options:

pkaraptor-protonate -h

Protonation options

• --json selections JSON exported from the dashboard
• --pdb input PDB file, overriding the JSON pdb field if provided
• --out output PDB file with hydrogens
• --strip-ppm remove PPM/OPM dummy atoms (DUM/DU)
• --no-validate-allowed do not validate that selected_resname is present in allowed_resnames
• --ph pH used by OpenMM to place hydrogens
• --forcefield OpenMM ForceField XML file, repeatable; default is amber14-all.xml
• --remove-heterogens remove heterogens before hydrogenation
• --keep-water when removing heterogens, keep water molecules

Typical workflow

A typical workflow may involve running pkaraptor on a PDB structure to generate a protonation environment analysis CSV, building an interactive dashboard with pkaraptor-dashboard, exporting residue selections from the dashboard as JSON, applying renamed residue selections with pkaraptor-apply-json, and generating a hydrogenated structure with pkaraptor-protonate.

Output

Depending on the selected workflow and inputs, pKaRaptor can generate outputs such as protonation environment analysis CSV files, interactive HTML dashboards, JSON files containing residue selections exported from the dashboard, renamed PDB structures, and protonated PDB structures with hydrogens added through OpenMM.

Use cases

pKaRaptor may be useful for exploratory analysis of ionizable residues in protein structures, inspection of local environments around titratable sites, comparison of protonation-related predictions from different sources, investigation of pH-dependent structural hypotheses, membrane protein analysis with OPM-informed context, preparation and interpretation steps prior to molecular simulation, and educational or methodological demonstrations related to protein protonation analysis.

Repository structure

A typical repository structure includes the files LICENSE, README.md, and pyproject.toml, together with the src/ directory containing the package source code and, when distributions are built locally, a dist/ directory.

Citation

If you use pKaRaptor in academic work, please cite the software repository or the corresponding PyPI release.

A formal software citation will be added once available.

Authorship, Contributions, and Maintenance

Joana Ribeiro da Silva is the author and developer of pKaRaptor. The PyPI maintainers are Joana Ribeiro da Silva, Pedro Alexandrino Fernandes, and Pedro Ferreira. Acknowledged contributions include academic supervision and project support from Pedro Alexandrino Fernandes, and testing, feedback, and scientific discussion from Pedro Ferreira.

Contributing

Contributions, suggestions, and bug reports are welcome. Please use the GitHub issue tracker to report problems or propose improvements.

License

This project is distributed under the BSD 3-Clause License. See the LICENSE file for details.