PROPKA: Heuristic pKa calculations with ligands

Warnings

• breaking PROPKA 3.5.0 dropped support for Python 3.6 and 3.7. Ensure your environment uses Python 3.10 or higher for the latest versions.
  Fix: Upgrade your Python interpreter to version 3.10 or newer.
• breaking Version 3.4.0 removed the `--generate-propka-input` argument and direct PROPKA input file support. Input should now be provided primarily via PDB files.
  Fix: Provide input directly as PDB files instead of using custom PROPKA input formats or the removed argument.
• breaking The API for `propka` is still evolving and is not guaranteed to be stable between minor releases (e.g., changes between 3.2 and 3.3). This may require adjustments to programmatic integrations.
  Fix: Refer to the latest API documentation and changelog for each minor version update when integrating programmatically. Consider pinning exact minor versions in production if API stability is critical.
• gotcha Older, separate `propka.py` scripts (e.g., for PyMOL integration) exist and are distinct from the `propka` Python package. Using these older scripts can lead to confusion or incompatibility.
  Fix: Always install `propka` via `pip install propka` and refer to the official documentation (jensengroup/propka on GitHub) for Python module usage to ensure you are using the correct and supported library.
• gotcha The command-line tool is `propka3`, not `propka`. When running from the command line, use `propka3 FILENAME.pdb` or `python -m propka FILENAME.pdb`.
  Fix: Use the `propka3` executable or `python -m propka` for command-line invocation.

Install

• pip install propka Install with pip

Imports

• run_propka

  from propka import run

  The primary entry point for programmatic execution is often within the `propka.run` module. You'll typically interact with functions like `run_propka`.
• propka

  import propka

  While `propka` is the package name, direct top-level imports for specific calculation functions are less common. Instead, functions are typically accessed through submodules like `propka.run` or `propka.molecular_container`.

Quickstart

This quickstart demonstrates how to use PROPKA as a Python module to calculate pKa values for a protein structure. It creates a minimal dummy PDB file, runs the `propka.run.run_propka` function, and prints a success message, indicating that detailed results are written to a `.pka` file.

import os
import propka.run

# Example: Create a dummy PDB file for demonstration
# In a real scenario, you would load an existing PDB file.
example_pdb_content = """
ATOM      1  N   ALA A   1       0.000   0.000   0.000  1.00 20.00           N
ATOM      2  CA  ALA A   1       1.458   0.000   0.000  1.00 20.00           C
ATOM      3  C   ALA A   1       2.155   1.234   0.000  1.00 20.00           C
ATOM      4  O   ALA A   1       1.614   2.352   0.000  1.00 20.00           O
ATOM      5  CB  ALA A   1       2.000  -1.200   0.000  1.00 20.00           C
"""

with open("dummy.pdb", "w") as f:
    f.write(example_pdb_content)

# Run PROPKA programmatically
# The output will typically be written to a .pka file
# and potentially to standard output.

try:
    # propka.run.run_propka expects a list of filenames
    pka_results = propka.run.run_propka(["dummy.pdb"])

    # The 'pka_results' object contains detailed pKa information.
    # For a simple print of the summary (similar to command line output):
    print("\nPROPKA Calculation Summary (dummy.pdb):")
    # Note: Accessing results directly from the returned object might require
    # traversing its internal structure, e.g., MolecularContainer.
    # The exact structure depends on the PROPKA version and options.
    # For demonstration, we'll indicate successful execution and refer to the .pka file.
    print("Results written to dummy.pka and available in the returned object.")

    # You can read the generated .pka file for detailed results
    # with open("dummy.pka", "r") as f:
    #     print(f.read())

except Exception as e:
    print(f"An error occurred during PROPKA calculation: {e}")
finally:
    # Clean up the dummy PDB file and output if they exist
    if os.path.exists("dummy.pdb"):
        os.remove("dummy.pdb")
    if os.path.exists("dummy.pka"):
        os.remove("dummy.pka")