### Install PROPKA 3 from source

Source: https://github.com/jensengroup/propka/blob/master/docs/source/installation.md

Install PROPKA 3 by cloning the repository or unpacking a source archive and running this command in the source directory.

```bash
pip install .
```

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

### Install PROPKA from Source

Source: https://github.com/jensengroup/propka/blob/master/README.md

Commands for installing from a local source directory, including an editable mode for development.

```bash
pip install .
```

```bash
pip install -e .
```

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

### Install PROPKA via PIP

Source: https://github.com/jensengroup/propka/blob/master/README.md

Standard installation command for the PROPKA Python module and executable.

```bash
pip install propka
```

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

### Install PROPKA 3 using pip

Source: https://github.com/jensengroup/propka/blob/master/docs/source/installation.md

Use this command to install the latest release of PROPKA 3 from PyPI. This method installs the Python module and the propka3 executable.

```bash
pip install --upgrade propka
```

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

### Install PROPKA as a Module

Source: https://github.com/jensengroup/propka/blob/master/tests/README.md

Use this command to install PROPKA in editable mode, allowing for code changes to be reflected immediately. Ensure you are in the top-level directory of the PROPKA source.

```bash
pip install -e .
```

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

### PROPKA Python API: propka.run.single() Basic Usage

Source: https://context7.com/jensengroup/propka/llms.txt

Programmatically run PROPKA calculations using the single() function. This basic example calculates pKa values and writes an output file.

```python
import propka.run

# Basic usage - calculate pKa values and write output file
mol = propka.run.single("protein.pdb")

# Access predicted pKa values
for conformation_name in mol.conformation_names:
    conformation = mol.conformations[conformation_name]
    for group in conformation.get_titratable_groups():
        print(f"{group.label}: pKa = {group.pka_value:.2f}")
```

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

### Get Titratable Groups

Source: https://context7.com/jensengroup/propka/llms.txt

Retrieves all titratable groups within a specific protein conformation, providing access to individual residue pKa values and determinants. Requires accessing the desired conformation from the molecule's conformations dictionary.

```python
import propka.run

mol = propka.run.single("protein.pdb", write_pka=False)

# Access titratable groups in average conformation
conf = mol.conformations['AVR']
titratable_groups = conf.get_titratable_groups()

for group in titratable_groups:
    print(f"\n{group.label}:")
    print(f"  Residue type: {group.residue_type}")
    print(f"  pKa value: {group.pka_value:.2f}")
    print(f"  Model pKa: {group.model_pka:.2f}")
    print(f"  Buried: {group.buried:.0f}%")
    print(f"  Charge: {group.charge}")

    # Access determinants
    for det_type in ['sidechain', 'backbone', 'coulomb']:
        dets = group.determinants[det_type]
        if dets:
            print(f"  {det_type.capitalize()} determinants:")
            for det in dets[:3]:  # Show first 3
                print(f"    {det.group.label}: {det.value:+.2f}")
```

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

### Build Documentation Locally

Source: https://github.com/jensengroup/propka/wiki/Style-Guide

Command to generate the project documentation using Sphinx.

```bash
python setup.py build_sphinx
```

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

### Access PROPKA Help

Source: https://github.com/jensengroup/propka/blob/master/README.md

Commands to display usage information and available options.

```bash
propka3
```

```bash
propka3 --help
```

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

### propka.lib.loadOptions()

Source: https://context7.com/jensengroup/propka/llms.txt

Parses command-line arguments and returns an Options object.

```APIDOC
## propka.lib.loadOptions()

### Description
Parses command-line arguments and returns an Options object that controls PROPKA calculation behavior.

### Parameters
#### Method Parameters
- **args** (list) - Required - A list of command-line argument strings.
```

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

### Complete Workflow Analysis

Source: https://context7.com/jensengroup/propka/llms.txt

Demonstrates the full workflow from loading a PDB file to calculating stability profiles and isoelectric points.

```APIDOC
## CLASS MolecularContainer

### Description
Main container for protein data and pKa calculation results.

### Methods
- **get_folding_profile()**: Returns the folding profile including optimal pH and stability range.
- **get_pi()**: Returns the isoelectric point for folded and unfolded states.
- **calculate_pka()**: Performs the pKa calculation on the loaded molecule.
- **get_titratable_groups()**: Returns a list of titratable groups within a conformation.
```

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

### propka.run.main() - Command-Line Style Processing

Source: https://context7.com/jensengroup/propka/llms.txt

Provides an entry point for command-line style processing of multiple PDB files. It handles argument parsing and processes all specified input files.

```APIDOC
## POST /api/run/main

### Description
Executes PROPKA calculations in a manner similar to command-line execution, processing one or more PDB files with specified options.

### Method
POST

### Endpoint
/api/run/main

### Parameters
#### Request Body
- **args** (list of strings) - Required - A list of arguments, mimicking command-line arguments. Example: `["protein.pdb", "--quiet", "--pH", "6.5"]`.

### Request Example
```json
{
  "args": ["protein1.pdb", "-f", "protein2.pdb", "--quiet"]
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the processing is complete.

#### Response Example
```json
{
  "message": "Processing complete."
}
```
```

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

### Load configuration parameters

Source: https://context7.com/jensengroup/propka/llms.txt

Read pKa calculation settings from a configuration file.

```python
from propka.input import read_parameter_file
from propka.parameters import Parameters
from pathlib import Path

# Load default parameters
params = Parameters()
params = read_parameter_file(Path("propka.cfg"), params)

# Access parameter values
print(f"Version: {params.version}")
print(f"Acid residues: {params.acid_list}")
print(f"Ignore residues: {params.ignore_residues}")
```

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

### Process PDB files via command-line style interface

Source: https://context7.com/jensengroup/propka/llms.txt

Use the main entry point to process one or multiple PDB files with optional arguments.

```python
import propka.run

# Process single file
propka.run.main(["protein.pdb"])

# Process multiple files
propka.run.main(["protein1.pdb", "-f", "protein2.pdb", "-f", "protein3.pdb"])

# With additional options
propka.run.main(["protein.pdb", "--quiet", "--pH", "6.5"])
```

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

### Command Line Interface (CLI)

Source: https://context7.com/jensengroup/propka/llms.txt

The propka3 command-line tool allows for pKa prediction from PDB files with various options for chain selection, titration filtering, and pH settings.

```APIDOC
## CLI Usage

### Description
The `propka3` command is the primary interface for running pKa predictions on PDB files.

### Parameters
- **--chain** (string) - Optional - Filter calculations to specific protein chains.
- **--titrate_only** (string) - Optional - Restrict calculations to specific residues (e.g., "A:25,A:29").
- **--pH** (float) - Optional - Set specific pH for stability calculations.
- **--window** (list) - Optional - Customize pH window for stability profiles (min, max, step).
- **--grid** (list) - Optional - Customize pH grid for calculations.
- **--reference** (string) - Optional - Set reference state (e.g., "low-pH").
- **--display-coupled-residues** (flag) - Optional - Show detailed coupling information.
- **--quiet** (flag) - Optional - Suppress non-warning messages.
- **--log-level** (string) - Optional - Set logging level (DEBUG, WARNING).
- **--parameters** (string) - Optional - Path to custom parameter file.
```

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

### propka.input.read_parameter_file() - Loading Parameters

Source: https://context7.com/jensengroup/propka/llms.txt

Loads PROPKA configuration parameters from a file, controlling pKa calculation behavior.

```APIDOC
## POST /api/input/read_parameter_file

### Description
Loads PROPKA configuration parameters from a specified file. These parameters influence the pKa calculation process.

### Method
POST

### Endpoint
/api/input/read_parameter_file

### Parameters
#### Request Body
- **parameter_filepath** (string) - Required - The path to the parameter configuration file (e.g., `propka.cfg`).
- **parameters_object** (object) - Required - An existing `Parameters` object to load the configuration into.

### Request Example
```json
{
  "parameter_filepath": "propka.cfg",
  "parameters_object": { ... Parameters object ... }
}
```

### Response
#### Success Response (200)
- **parameters_object** (object) - The `Parameters` object populated with data from the configuration file.

#### Response Example
```json
{
  "parameters_object": { ... Populated Parameters object ... }
}
```
```

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

### Run PROPKA on a PDB File

Source: https://github.com/jensengroup/propka/blob/master/README.md

Standard execution command providing a PDB file as an argument.

```bash
propka3 1hpx.pdb
```

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

### PROPKA pH and Stability Settings

Source: https://context7.com/jensengroup/propka/llms.txt

Control pH values for stability and charge calculations. Options include setting a specific pH, defining a pH window, or using a custom pH grid.

```bash
propka3 --pH 6.5 protein.pdb
```

```bash
propka3 --window 0.0 14.0 0.5 protein.pdb
```

```bash
propka3 --grid 0.0 14.0 0.2 protein.pdb
```

```bash
propka3 --reference low-pH protein.pdb
```

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

### Run PROPKA using the propka3 script

Source: https://github.com/jensengroup/propka/blob/master/docs/source/quickstart.md

Use this command to run PROPKA from the terminal. Replace FILENAME with the path to your input file.

```bash
propka3  FILENAME
```

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

### Invoke PROPKA

Source: https://github.com/jensengroup/propka/blob/master/README.md

Methods for running the PROPKA tool from the command line.

```bash
propka3
```

```bash
python -m propka
```

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

### Run PROPKA as a Python module

Source: https://github.com/jensengroup/propka/blob/master/docs/source/quickstart.md

Execute PROPKA as a Python module using the 'python -m propka' command. Specify the input filename after the module name.

```bash
python -m propka FILENAME
```

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

### Basic PROPKA Command Line Usage

Source: https://context7.com/jensengroup/propka/llms.txt

Predict pKa values for a protein structure using the default command-line interface. This is the most basic way to run PROPKA.

```bash
propka3 1hpx.pdb
```

```bash
python -m propka 1hpx.pdb
```

```bash
propka3 --help
```

```bash
propka3 --version
```

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

### Run PROPKA with file-like objects

Source: https://context7.com/jensengroup/propka/llms.txt

Process PDB data directly from a stream instead of a file path.

```python
from io import StringIO

pdb_content = """ATOM      1  N   ALA A   1       0.000   0.000   0.000  1.00  0.00           N
ATOM      2  CA  ALA A   1       1.458   0.000   0.000  1.00  0.00           C
...
"""
stream = StringIO(pdb_content)
mol = propka.run.single("input.pdb", stream=stream)
```

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

### PROPKA Custom Parameters

Source: https://context7.com/jensengroup/propka/llms.txt

Specify a custom parameter configuration file using the --parameters option for specialized calculation settings.

```bash
propka3 --parameters custom_propka.cfg protein.pdb
```

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

### Propka3 Output - Summary of Predictions

Source: https://github.com/jensengroup/propka/blob/master/docs/source/quickstart.md

This section provides a concise summary of the predicted pKa values for various groups, comparing the calculated pKa with a model-pKa and indicating the ligand atom type. This is useful for a quick overview of the results.

```text
SUMMARY OF THIS PREDICTION
       Group      pKa  model-pKa   ligand atom-type
   ASP  25 A     5.07       3.80
   ASP  29 A     3.11       3.80
   ASP  30 A     4.62       3.80
   ASP  60 A     2.55       3.80
   ASP  25 B     9.28       3.80
   ASP  29 B     1.78       3.80
   ASP  30 B     4.91       3.80
   ASP  60 B     2.13       3.80
   GLU  21 A     4.78       4.50
   GLU  34 A     3.93       4.50
   GLU  35 A     3.65       4.50
   GLU  65 A     3.89       4.50
   GLU  21 B     4.73       4.50
   GLU  34 B     3.36       4.50
   GLU  35 B     4.07       4.50
   GLU  65 B     3.70       4.50

```

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

### Parse PROPKA Options

Source: https://context7.com/jensengroup/propka/llms.txt

Parses command-line arguments to create an Options object that configures PROPKA calculation behavior. Useful for setting input files, pH values, and logging levels programmatically.

```python
from propka.lib import loadOptions

# Parse options from argument list
options = loadOptions(["protein.pdb", "--pH", "6.5", "--quiet"])

# Access option values
print(f"Input file: {options.input_pdb}")
print(f"pH value: {options.pH}")
print(f"Log level: {options.log_level}")
print(f"pH window: {options.window}")
print(f"pH grid: {options.grid}")
print(f"Keep protons: {options.keep_protons}")
print(f"Display coupled: {options.display_coupled_residues}")
```

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

### Execute complete pKa analysis workflow

Source: https://context7.com/jensengroup/propka/llms.txt

Perform pKa predictions, stability analysis, and isoelectric point calculations using either the high-level single() function or manual step-by-step configuration.

```python
import propka.run
from propka.lib import loadOptions
from propka.input import read_parameter_file, read_molecule_file
from propka.parameters import Parameters
from propka.molecular_container import MolecularContainer

# Method 1: Simple approach using single()
mol = propka.run.single("1hpx.pdb", write_pka=False)

# Print summary of pKa predictions
print("=" * 60)
print("pKa Predictions Summary")
print("=" * 60)

conf = mol.conformations['AVR']
for group in sorted(conf.get_titratable_groups(),
                    key=lambda g: g.pka_value):
    shift = group.pka_value - group.model_pka
    print(f"{group.label}: pKa={group.pka_value:5.2f} "
          f"(model={group.model_pka:.2f}, shift={shift:+.2f})")

# Analyze stability
print("\n" + "=" * 60)
print("Stability Analysis")
print("=" * 60)

profile, (ph_opt, dg_opt), _, (ph_min, ph_max) = mol.get_folding_profile()
print(f"Optimal stability pH: {ph_opt:.1f}")
print(f"Stability range: pH {ph_min:.1f} - {ph_max:.1f}")

# Isoelectric point
pi_folded, pi_unfolded = mol.get_pi()
print(f"Isoelectric point (folded): {pi_folded:.2f}")
print(f"Isoelectric point (unfolded): {pi_unfolded:.2f}")

# Method 2: Manual step-by-step approach for more control
options = loadOptions(["1hpx.pdb"])
parameters = read_parameter_file(options.parameters, Parameters())

mol2 = MolecularContainer(parameters, options)
mol2 = read_molecule_file("1hpx.pdb", mol2)
mol2.calculate_pka()

# Custom analysis on specific residues
print("\n" + "=" * 60)
print("Active Site Residues Analysis")
print("=" * 60)

for group in conf.get_titratable_groups():
    if group.residue_type == 'ASP' and group.atom.res_num == 25:
        print(f"\nCatalytic ASP 25:")
        print(f"  pKa: {group.pka_value:.2f}")
        print(f"  Buried: {group.buried:.0f}%")
        print(f"  Desolvation energy: {group.energy_volume:.2f}")
```

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

### propka.input.read_molecule_file() - Reading PDB Files

Source: https://context7.com/jensengroup/propka/llms.txt

Parses PDB files and populates a MolecularContainer with structural data. It handles conformations, chains, and ligands.

```APIDOC
## POST /api/input/read_molecule_file

### Description
Reads and parses a PDB file, populating a `MolecularContainer` object with the structural information.

### Method
POST

### Endpoint
/api/input/read_molecule_file

### Parameters
#### Request Body
- **pdb_filepath** (string) - Required - The path to the PDB file to be read.
- **molecular_container** (object) - Required - An existing `MolecularContainer` object to populate.

### Request Example
```json
{
  "pdb_filepath": "protein.pdb",
  "molecular_container": { ... MolecularContainer object ... }
}
```

### Response
#### Success Response (200)
- **molecular_container** (object) - The updated `MolecularContainer` object with data from the PDB file.

#### Response Example
```json
{
  "molecular_container": { ... Updated MolecularContainer object ... }
}
```
```

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

### propka.output.write_pka()

Source: https://context7.com/jensengroup/propka/llms.txt

Provides low-level control over pKa file generation, allowing users to specify conformations and reference states.

```APIDOC
## FUNCTION propka.output.write_pka()

### Description
Writes pKa prediction results to a file with specific control over conformation and reference states.

### Parameters
- **protein** (MolecularContainer) - Required - The molecular container object containing pKa results.
- **parameters** (Parameters) - Required - The parameter set used for calculation.
- **filename** (str) - Required - The path to the output file.
- **conformation** (str) - Optional - The specific conformation name to write.
- **reference** (str) - Optional - The reference state (e.g., 'neutral').
- **verbose** (bool) - Optional - Enable verbose output.
```

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

### Working with StringIO Streams

Source: https://context7.com/jensengroup/propka/llms.txt

Enables processing of PDB data directly from memory using file-like objects, suitable for web services.

```APIDOC
## METHOD propka.run.single()

### Description
Processes PDB data from a stream instead of a physical file.

### Parameters
- **filename** (str) - Required - Used for naming output and determining file type.
- **stream** (io.StringIO) - Required - The file-like object containing PDB content.
- **write_pka** (bool) - Optional - Whether to write the output file to disk.
```

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

### PROPKA Python API: Passing Command-Line Options

Source: https://context7.com/jensengroup/propka/llms.txt

Pass command-line arguments programmatically to the single() function using the optargs parameter for custom calculations.

```python
import propka.run

# Pass command-line options programmatically
mol = propka.run.single("protein.pdb",
                        optargs=["--pH=7.2", "--titrate_only=A:25,A:29"])
```

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

### Write pKa results to file

Source: https://context7.com/jensengroup/propka/llms.txt

Export calculation results to a .pka file with optional custom naming and reference states.

```python
import propka.run

# Calculate and write to default filename (protein.pka)
mol = propka.run.single("protein.pdb")

# Or manually control output
mol = propka.run.single("protein.pdb", write_pka=False)
mol.write_pka()  # Writes to protein.pka

# Custom filename
mol.write_pka(filename="custom_output.pka")

# Different reference state
mol.write_pka(filename="lowph_output.pka", reference="low-pH")
```

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

### Parse PDB files into a MolecularContainer

Source: https://context7.com/jensengroup/propka/llms.txt

Manually load structural data and parameters into a container for custom analysis.

```python
from propka.input import read_molecule_file, read_parameter_file
from propka.parameters import Parameters
from propka.molecular_container import MolecularContainer
from propka.lib import loadOptions

# Set up parameters and options
options = loadOptions(["protein.pdb"])
parameters = read_parameter_file(options.parameters, Parameters())

# Create molecular container and read PDB file
mol = MolecularContainer(parameters, options)
mol = read_molecule_file("protein.pdb", mol)

# Access parsed structural data
print(f"Molecule: {mol.name}")
print(f"Conformations: {mol.conformation_names}")
for name in mol.conformation_names:
    conf = mol.conformations[name]
    print(f"  {name}: {len(conf.atoms)} atoms, {len(conf.groups)} groups")
```

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

### propka.run.single() - Single Molecule Processing

Source: https://context7.com/jensengroup/propka/llms.txt

Processes a single PDB file, including reading the structure and performing pKa calculations. Can optionally write results to a .pka file.

```APIDOC
## POST /api/run/single

### Description
Processes a single PDB file and calculates pKa values for titratable groups. This function can also write the results to a .pka file.

### Method
POST

### Endpoint
/api/run/single

### Parameters
#### Query Parameters
- **input.pdb** (string) - Required - Path to the input PDB file.
- **stream** (file-like object) - Optional - A file-like object containing PDB content.
- **write_pka** (boolean) - Optional - If true, writes results to a .pka file (default: true).

### Request Body
```json
{
  "input_pdb": "path/to/your/protein.pdb",
  "stream": null, // or a file-like object representation
  "write_pka": true
}
```

### Response
#### Success Response (200)
- **mol** (object) - The processed MolecularContainer object containing pKa calculation results.

#### Response Example
```json
{
  "mol": { ... MolecularContainer object ... }
}
```
```

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

### Run PROPKA Tests

Source: https://github.com/jensengroup/propka/blob/master/tests/README.md

Execute the PROPKA test suite using pytest. This command can be run from the top-level directory or the 'tests' subdirectory.

```bash
python -m pytest tests
```

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

### Python API: propka.run.single()

Source: https://context7.com/jensengroup/propka/llms.txt

The programmatic interface for running PROPKA calculations within Python scripts, returning a MolecularContainer object.

```APIDOC
## Python API: propka.run.single()

### Description
Executes a pKa calculation on a given PDB file and returns a `MolecularContainer` object containing the results.

### Parameters
- **filename** (string) - Required - Path to the PDB file.
- **write_pka** (boolean) - Optional - Whether to write the .pka output file.
- **optargs** (list) - Optional - List of command-line style arguments (e.g., ["--pH=7.2"]).

### Response
- **MolecularContainer** (object) - Contains conformations and titratable group data.
```

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

### MolecularContainer.write_pka() - Writing pKa Results

Source: https://context7.com/jensengroup/propka/llms.txt

Outputs the pKa calculation results to a .pka file, including detailed determinant, summary, folding, and charge profiles.

```APIDOC
## POST /api/molecular_container/write_pka

### Description
Writes the computed pKa values and associated analysis data to a file.

### Method
POST

### Endpoint
/api/molecular_container/write_pka

### Parameters
#### Request Body
- **molecular_container** (object) - Required - The `MolecularContainer` object containing the pKa calculation results.
- **filename** (string) - Optional - The desired name for the output file (defaults to `[molecule_name].pka`).
- **reference** (string) - Optional - The reference state for the calculation (e.g., 'neutral', 'low-pH'). Defaults to 'neutral'.

### Request Example
```json
{
  "molecular_container": { ... MolecularContainer with pKa results ... },
  "filename": "custom_output.pka",
  "reference": "low-pH"
}
```

### Response
#### Success Response (200)
- **message** (string) - A confirmation message indicating the results have been written.

#### Response Example
```json
{
  "message": "pKa results written to custom_output.pka"
}
```
```

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

### Generate pKa files with write_pka()

Source: https://context7.com/jensengroup/propka/llms.txt

Use write_pka to generate custom pKa output files for specific conformations and reference states. Requires a processed MolecularContainer object.

```python
from propka.output import write_pka
import propka.run

mol = propka.run.single("protein.pdb", write_pka=False)

# Write pKa file with full control
write_pka(
    protein=mol,
    parameters=mol.version.parameters,
    filename="detailed_output.pka",
    conformation='AVR',
    reference='neutral',
    verbose=True
)

# Write for specific conformation
for conf_name in mol.conformation_names:
    if conf_name != 'AVR':
        write_pka(
            protein=mol,
            parameters=mol.version.parameters,
            filename=f"output_{conf_name}.pka",
            conformation=conf_name,
            reference='neutral'
        )
```

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

### Propka3 Output - Detailed pKa Calculations

Source: https://github.com/jensengroup/propka/blob/master/docs/source/quickstart.md

This table presents detailed pKa calculations for each residue, including the predicted pKa, burial percentage, desolvation effects, and contributions from sidechain and backbone hydrogen bonds, and Coulombic interactions. Residues marked with an asterisk (*) indicate coupled residues that may require re-running with a specific option for more detail.

```text
---------  -----   ------   ---------------------	       DESOLVATION  EFFECTS       SIDECHAIN	      BACKBONE        COULOMBIC
 RESIDUE    pKa    BURIED     REGULAR      RE	        HYDROGEN BOND     HYDROGEN BOND	       INTERACTION
---------  -----   ------   ---------	   ---------	    --------------    --------------    --------------

 ASP  25 A   5.07*	 100 %	    4.30  617 	   0.19	    0   -0.85 KNI  O4 B	   -0.63 GLY  27 A	    0.07 ASP  29 A
 ASP  25 A	                                           -0.85 KNI  O2 B	   -0.09 ALA  28 A	    0.00 XXX   0 X
 ASP  25 A	                                           -0.84 ASP  25 B	   -0.04 GLY  27 B	    0.00 XXX   0 X

 ASP  29 A   3.11	    50 %	    1.20  420 	   0.13	    0   -0.68 ARG  87 A	    0.00 XXX   0 X	   -0.04 LYS  45 A
 ASP  29 A	                                           -0.28 ARG   8 B	    0.00 XXX   0 X	   -0.47 ARG  87 A
 ASP  29 A	                                            0.00 XXX   0 X	    0.00 XXX   0 X	   -0.54 ARG   8 B

 ASP  30 A   4.62	    59 %	    1.30  446 	   0.00	    0   -0.11 LYS  45 A	    0.00 XXX   0 X	   -0.07 ARG  87 A
 ASP  30 A	                                            0.00 XXX   0 X	    0.00 XXX   0 X	   -0.01 ARG   8 B
 ASP  30 A	                                            0.00 XXX   0 X	    0.00 XXX   0 X	    0.29 ASP  29 A
 ASP  30 A	                                            0.00 XXX   0 X	    0.00 XXX   0 X	   -0.57 LYS  45 A

 ASP  60 A   2.55	     0 %	    0.41  249 	   0.00	    0   -0.40 THR  74 A	    0.00 XXX   0 X	   -0.02 LYS  45 A
 ASP  60 A	                                           -0.85 LYS  43 A	    0.00 XXX   0 X	   -0.38 LYS  43 A
...
...
...
 ARG  87 B  12.28	    45 %	   -1.40  407 	   0.00	    0    0.77 ASP  29 B	    0.00 XXX   0 X	    0.10 ASP  30 B
 ARG  87 B	                                            0.00 XXX   0 X	    0.00 XXX   0 X	   -0.19 ARG   8 A
 ARG  87 B	                                            0.00 XXX   0 X	    0.00 XXX   0 X	    0.50 ASP  29 B

 N+    1 B   8.96	     0 %	   -0.39  235 	   0.00	    0    0.85 C-   99 A	    0.00 XXX   0 X	    0.07 CYS  67 B
 N+    1 B	                                            0.00 XXX   0 X	    0.00 XXX   0 X	    0.04 CYS  95 B
 N+    1 B	                                            0.00 XXX   0 X	    0.00 XXX   0 X	    0.38 C-   99 A

 KNI  N1 B   4.60	     0 %	   -0.36  273 	   0.00	    0    0.00 XXX   0 X	    0.00 XXX   0 X	   -0.03 ARG   8 A

Coupled residues (marked *) were detected.Please rerun PropKa with the --display-coupled-residues
or -d option for detailed information.

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

```

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

### PROPKA Coupled Residues Analysis

Source: https://context7.com/jensengroup/propka/llms.txt

Display detailed information about energetically coupled residues using the --display-coupled-residues option. The short form is -d.

```bash
propka3 --display-coupled-residues 1hpx.pdb
```

```bash
propka3 -d 1hpx.pdb
```

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

### Calculate Protein Charge Profile

Source: https://context7.com/jensengroup/propka/llms.txt

Calculates the total protein charge as a function of pH for both folded and unfolded states. Requires importing the propka.run module.

```python
import propka.run

mol = propka.run.single("protein.pdb", write_pka=False)

# Get charge profile
charge_profile = mol.get_charge_profile(conformation='AVR', grid=(0., 14., 0.5))

print("pH\tUnfolded\tFolded")
for ph, q_unfolded, q_folded in charge_profile:
    print(f"{ph:.1f}\t{q_unfolded:+.2f}\t\t{q_folded:+.2f}")
```

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

### MolecularContainer.calculate_pka() - pKa Calculation

Source: https://context7.com/jensengroup/propka/llms.txt

Performs the core pKa calculation on a prepared molecular structure, considering desolvation, hydrogen bonding, and Coulombic contributions.

```APIDOC
## POST /api/molecular_container/calculate_pka

### Description
Initiates the pKa calculation for all titratable groups within a `MolecularContainer`.

### Method
POST

### Endpoint
/api/molecular_container/calculate_pka

### Parameters
#### Request Body
- **molecular_container** (object) - Required - The `MolecularContainer` object containing the molecular structure and parameters.

### Request Example
```json
{
  "molecular_container": { ... MolecularContainer object ... }
}
```

### Response
#### Success Response (200)
- **molecular_container** (object) - The `MolecularContainer` object with pKa calculation results populated within its conformations.

#### Response Example
```json
{
  "molecular_container": { ... MolecularContainer with pKa results ... }
}
```
```

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

### Process PDB data from memory streams

Source: https://context7.com/jensengroup/propka/llms.txt

Process PDB content directly from strings or file-like objects using StringIO to avoid filesystem dependencies.

```python
import propka.run
from io import StringIO

# PDB content as string (typically from database or web service)
pdb_content = open("protein.pdb").read()

# Create StringIO stream
stream = StringIO(pdb_content)

# Process without filesystem access
mol = propka.run.single(
    "protein.pdb",  # Used for naming output and determining file type
    stream=stream,
    write_pka=False
)

# Access results
for group in mol.conformations['AVR'].get_titratable_groups():
    print(f"{group.label}: {group.pka_value:.2f}")
```

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

### Calculate protein folding profile

Source: https://context7.com/jensengroup/propka/llms.txt

Compute the free energy of folding across a pH range.

```python
import propka.run

mol = propka.run.single("protein.pdb", write_pka=False)

# Get folding profile with default settings
profile, optimum, range_80pct, stability_range = mol.get_folding_profile()

# profile: list of (pH, delta_G) tuples
# optimum: (pH, delta_G) at minimum energy
# range_80pct: (pH_min, pH_max) within 80% of optimum
# stability_range: (pH_min, pH_max) where delta_G < 0

print(f"Optimal pH: {optimum[0]:.1f}")
print(f"Optimal folding energy: {optimum[1]:.2f} kcal/mol")
print(f"Stability range: pH {stability_range[0]:.1f} - {stability_range[1]:.1f}")

# Custom pH grid
profile, opt, r80, stable = mol.get_folding_profile(
    conformation='AVR',
    reference='neutral',
    grid=(4.0, 10.0, 0.1)
)

# Print profile
for ph, dg in profile:
    print(f"pH {ph:.1f}: {dg:+.2f} kcal/mol")
```

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

### PROPKA Chain Selection

Source: https://context7.com/jensengroup/propka/llms.txt

Filter pKa calculations to specific protein chains using the --chain option. This is useful for analyzing multi-chain complexes.

```bash
propka3 --chain A 1hpx.pdb
```

```bash
propka3 --chain A --chain B 1hpx.pdb
```

```bash
propka3 --chain " " protein.pdb
```

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

### PROPKA Python API: Running without Output File

Source: https://context7.com/jensengroup/propka/llms.txt

Execute PROPKA calculations programmatically without generating an output file by setting write_pka=False in the single() function.

```python
import propka.run

# Calculate without writing output file
mol = propka.run.single("protein.pdb", write_pka=False)
```

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

### Access pKa calculation results

Source: https://context7.com/jensengroup/propka/llms.txt

Retrieve calculated pKa values and group properties from the molecular container.

```python
import propka.run

# Calculate pKa values
mol = propka.run.single("protein.pdb", write_pka=False)

# pKa calculation is performed automatically by single()
# Access results through conformations
avr_conf = mol.conformations['AVR']  # Average conformation
for group in avr_conf.get_titratable_groups():
    print(f"{group.residue_type} {group.atom.res_num} {group.atom.chain_id}:")
    print(f"  pKa: {group.pka_value:.2f}")
    print(f"  Model pKa: {group.model_pka:.2f}")
    print(f"  Buried: {group.buried:.0f}%")
```

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

### Propka3 Output - Group Identification

Source: https://github.com/jensengroup/propka/blob/master/docs/source/quickstart.md

This section of the output identifies titratable groups found in the input PDB file, including their residue, atom type, and coordinates. It helps in understanding which groups Propka3 is analyzing.

```text
propka3.2                                                                                    2020-06-19
...
...
Found NAR group:  1530-  N1   900-KNI (B) [   7.907    1.459    5.427] N
Found O3  group:  1531-  O1   900-KNI (B) [   5.235    3.791    9.082] O
Found O2  group:  1532-  O3   900-KNI (B) [   3.327    4.297   11.852] O
Found NAM group:  1533-  N2   900-KNI (B) [   3.955    2.384   10.893] N
Found O2  group:  1539-  O6   900-KNI (B) [   3.758   -0.629   12.111] O
Found NAM group:  1541-  N3   900-KNI (B) [   4.496    0.982   13.492] N
Found O2  group:  1542-  O4   900-KNI (B) [   6.324   -1.234   17.045] O
Found OH  group:  1548-  O2   900-KNI (B) [   4.949    0.934   16.427] O
Found O2  group:  1559-  O5   900-KNI (B) [   6.746   -3.574   14.588] O
Found NAM group:  1560-  N5   900-KNI (B) [   7.637   -4.575   16.403] N
-------------------------------------------------------------------------------------------------------


Calculating pKas for Conformation container 1A with 1878 atoms and 480 groups
-------------------------------------------------------------------------------------------------------

```

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

### propka3 Command Usage

Source: https://github.com/jensengroup/propka/blob/master/docs/source/command.md

The propka3 command predicts pKa values of ionizable groups in proteins and protein-ligand complexes based on their 3D structure. It accepts a PDB file as input and offers numerous options for customization.

```APIDOC
## propka3 Command

### Description
Predicts the pKa values of ionizable groups in proteins and protein-ligand complexes based on the 3D structure.

### Method
Command-line execution

### Endpoint
N/A (Command-line tool)

### Parameters
#### Path Parameters
- **input_pdb** (file) - Required - Path to the input PDB file.

#### Query Parameters
- **-h, --help** (flag) - Optional - Show this help message and exit.
- **-f FILENAMES, --file FILENAMES** (list of files) - Optional - Read data from specified files. Each filename is added to the arguments. (default: [])
- **-r REFERENCE, --reference REFERENCE** (string) - Optional - Setting which reference to use for stability calculations. Options: [neutral/low-pH]. (default: neutral)
- **-c CHAINS, --chain CHAINS** (string) - Optional - Creating the protein with only a specified chain. Specify " " for chains without ID [all]. (default: None)
- **-i TITRATE_ONLY, --titrate_only TITRATE_ONLY** (string) - Optional - Treat only the specified residues as titratable. Value should be a comma-separated list of "chain:resnum" values; for example: `-i "A:10,A:11"`. (default: None)
- **--version** (flag) - Optional - Show program’s version number and exit.
- **-p PARAMETERS, --parameters PARAMETERS** (file) - Optional - Set the parameter file. (default: <installation_directory>/propka/propka/propka.cfg)
- **--log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}** (string) - Optional - Logging level verbosity. (default: INFO)
- **-o PH, --pH PH** (float) - Optional - Setting pH-value used in e.g. stability calculations. (default: 7.0)
- **-w WINDOW WINDOW WINDOW, --window WINDOW WINDOW WINDOW** (tuple of floats) - Optional - Setting the pH-window to show e.g. stability profiles. (default: (0.0, 14.0, 1.0))
- **-g GRID GRID GRID, --grid GRID GRID GRID** (tuple of floats) - Optional - Setting the pH-grid to calculate e.g. stability related properties. (default: (0.0, 14.0, 0.1))
- **-d, --display-coupled-residues** (flag) - Optional - Displays alternative pKa values due to coupling of titratable groups. (default: False)
- **-l, --reuse-ligand-mol2-files** (flag) - Optional - Reuses the ligand mol2 files allowing the user to alter ligand bond orders. (default: False)
- **-k, --keep-protons** (flag) - Optional - Keep protons in input file. (default: False)
- **-q, --quiet** (flag) - Optional - Suppress non-warning messages. (default: None)
- **--protonate-all** (flag) - Optional - Protonate all atoms (will not influence pKa calculation). (default: False)

### Request Example
```bash
propka3 input.pdb -o 7.4 -c A
```

### Response
N/A (Command-line tool output is typically printed to standard output or files.)

### Error Handling
- The command will exit with an error if the input PDB file is not found or is malformed.
- Help messages are displayed with the `-h` or `--help` flags.
```

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

### MolecularContainer.get_folding_profile() - Folding Profile Analysis

Source: https://context7.com/jensengroup/propka/llms.txt

Calculates the protein folding free energy as a function of pH, revealing the pH range of maximum stability.

```APIDOC
## POST /api/molecular_container/get_folding_profile

### Description
Computes the folding free energy profile of the protein across a range of pH values.

### Method
POST

### Endpoint
/api/molecular_container/get_folding_profile

### Parameters
#### Request Body
- **molecular_container** (object) - Required - The `MolecularContainer` object with pKa calculations performed.
- **conformation** (string) - Optional - The specific conformation to use for the calculation (default: 'AVR').
- **reference** (string) - Optional - The reference state for the calculation (default: 'neutral').
- **grid** (tuple of floats) - Optional - A tuple defining the pH grid (min_pH, max_pH, step). Example: `(4.0, 10.0, 0.1)`.

### Request Example
```json
{
  "molecular_container": { ... MolecularContainer with pKa results ... },
  "conformation": "AVR",
  "grid": [4.0, 10.0, 0.1]
}
```

### Response
#### Success Response (200)
- **profile** (list of tuples) - A list of (pH, delta_G) tuples representing the folding energy at different pH values.
- **optimum** (tuple) - A tuple `(pH, delta_G)` indicating the pH of optimal folding stability.
- **range_80pct** (tuple) - A tuple `(pH_min, pH_max)` representing the pH range within 80% of the optimal folding energy.
- **stability_range** (tuple) - A tuple `(pH_min, pH_max)` indicating the pH range where the protein is stable (delta_G < 0).

#### Response Example
```json
{
  "profile": [[4.0, -1.5], [4.1, -1.6], ...],
  "optimum": [7.2, -2.1],
  "range_80pct": [6.5, 7.9],
  "stability_range": [5.0, 9.0]
}
```
```

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

### PROPKA Logging and Output Control

Source: https://context7.com/jensengroup/propka/llms.txt

Control the verbosity of PROPKA output using --quiet mode to suppress messages or --log-level to set specific logging levels like WARNING or DEBUG.

```bash
propka3 --quiet protein.pdb
```

```bash
propka3 --log-level WARNING protein.pdb
```

```bash
propka3 --log-level DEBUG protein.pdb
```

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

### ConformationContainer.calculate_folding_energy()

Source: https://context7.com/jensengroup/propka/llms.txt

Computes the free energy difference between folded and unfolded states at a given pH.

```APIDOC
## ConformationContainer.calculate_folding_energy()

### Description
Computes the free energy difference (ddG) between folded and unfolded states at a given pH.

### Parameters
#### Method Parameters
- **ph** (float) - Required - The pH value.
- **reference** (string) - Optional - The reference state (e.g., 'neutral').
```

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

### PROPKA Titration Filtering

Source: https://context7.com/jensengroup/propka/llms.txt

Restrict pKa calculations to specified residues using the --titrate_only option. This can improve performance and focus output.

```bash
propka3 --titrate_only "A:25,A:29,A:30" 1hpx.pdb
```

```bash
propka3 --titrate_only "E:17,E:18,E:19,E:29,E:44,E:45,E:46,E:118,E:119,E:120,E:139" 3sgb.pdb
```

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

### MolecularContainer.get_charge_profile()

Source: https://context7.com/jensengroup/propka/llms.txt

Calculates the total protein charge as a function of pH for both folded and unfolded states.

```APIDOC
## MolecularContainer.get_charge_profile()

### Description
Calculates the total protein charge as a function of pH for both folded and unfolded states.

### Parameters
#### Method Parameters
- **conformation** (string) - Required - The conformation identifier (e.g., 'AVR').
- **grid** (tuple) - Optional - A tuple defining the pH range and step size (start, end, step).
```