Site

Protonation site data structures and state calculations.

This module defines the core data structures for protonation sites, including state enumerations, pKa data, and site information. Each class has clear responsibilities and comprehensive validation.

PKaDatum(idx_site, mean, stdev)

Data structure for pKa information at a specific site.

Contains the site index, mean pKa value, and standard deviation for calculating protonation states at different pH values.

Initialize pKa data with validation.

PARAMETER	DESCRIPTION
idx_atom	Site index (non-negative integer)
mean	Mean pKa value (bounded 0-20 for realistic range) TYPE: float
stdev	Standard deviation (non-negative, bounded 0-5) TYPE: float

idx_site = idx_site

Index of the atom we would protonate in the SMARTS substructure pattern

mean = float(mean)

stdev = float(stdev)

get_state(ph_min, ph_max, precision)

Calculate protonation state for given pH range and precision.

PARAMETER	DESCRIPTION
ph_min	Minimum pH value (bounded 0-14) TYPE: float
ph_max	Maximum pH value (bounded 0-14, greater than ph_min) TYPE: float
precision	Precision factor for pKa calculation (positive) TYPE: float

RETURNS	DESCRIPTION
ProtonationState	ProtonationState based on pH range and pKa statistics

ProtonationSite(mol, idxs_match, pkas, smarts, name)

Data structure for detected protonation site information.

Contains atom indices and associated substructure data for a specific protonation site in a molecule.

idxs_match

Atom indices of substructure match

mol

RDKit Mol object that this protonation site was detected

name

Name of identified protonation site.

pkas

Observed pKas of this site.

smarts

SMARTS used to detect the protonation site.

get_states(ph_min, ph_max, precision)

Generate protonation states for all pKa data at this site.

PARAMETER	DESCRIPTION
ph_min	Minimum pH value TYPE: float
ph_max	Maximum pH value TYPE: float
precision	Precision factor for pKa calculation TYPE: float

YIELDS	DESCRIPTION
tuple[int, ProtonationState]	Atom index of Mol and ProtonationState for each pKa datum at this site

get_unique_states(ph_min, ph_max, precision)

Get protonation states as a list for easier handling.

PARAMETER	DESCRIPTION
ph_min	Minimum pH value (bounded 0-14) TYPE: float
ph_max	Maximum pH value (bounded 0-14, greater than ph_min) TYPE: float
precision	Precision factor for pKa calculation (positive) TYPE: float

RETURNS	DESCRIPTION
tuple[tuple[int, ProtonationState], ...]	List of ProtonationState objects for this site

is_valid()

ProtonationState

Bases: Enum

Enumeration of possible protonation states for a site.

Values are explicitly assigned for clarity and debugging.

BOTH = 3

DEPROTONATED = 1

PROTONATED = 2

UNKNOWN = 0

get_charges()

Get the formal charges associated with this protonation state.

RETURNS	DESCRIPTION
list[int]	List of integer formal charges for this state

to_str()

Convert protonation state to string representation.

RETURNS	DESCRIPTION
str	String representation of the protonation state

SubstructureDatum(name='', smarts='', mol=None, pkas=list())

Data structure for substructure pattern matching information.

Contains the pattern name, SMARTS string, RDKit mol object, and associated pKa data for protonation site detection.

mol = None

name = ''

pkas = field(default_factory=list)

smarts = ''

__post_init__()

Validate substructure data after initialization.

get_pka_count()

Get the number of pKa data points for this substructure.

RETURNS	DESCRIPTION
int	Number of pKa data entries

has_pka_data()

Check if substructure has pKa data available.

RETURNS	DESCRIPTION
bool	True if pKa data list is non-empty

has_valid_pattern()

Check if substructure has a valid molecular pattern.

RETURNS	DESCRIPTION
bool	True if mol object exists and is valid

is_valid_for_matching()

Check if substructure is valid for pattern matching.

RETURNS	DESCRIPTION
bool	True if both pattern and pKa data are available

create_pka_datum_safe(idx_site, mean, stdev)

Create PKaDatum with error handling.

PARAMETER	DESCRIPTION
idx_site	Site index TYPE: int
mean	Mean pKa value TYPE: float
stdev	Standard deviation TYPE: float

RETURNS	DESCRIPTION
PKaDatum | None	PKaDatum object or None if parameters are invalid

create_protonation_site_safe(mol, idxs_match, substructure=None)

Create ProtonationSite with error handling.

PARAMETER	DESCRIPTION
mol	RDKit Mol object we are creating a protonation site for. TYPE: Mol
idxs_match	Atom indices of substructure match. TYPE: tuple[int, ...]
substructure	Substructure data TYPE: SubstructureDatum | None DEFAULT: None

RETURNS	DESCRIPTION
ProtonationSite | None	ProtonationSite object or None if parameters are invalid

validate_ph_range(ph_min, ph_max)

Validate pH range parameters.

PARAMETER	DESCRIPTION
ph_min	Minimum pH value TYPE: float
ph_max	Maximum pH value TYPE: float

RETURNS	DESCRIPTION
bool	True if pH range is valid