ABCount is an extended cheminformatics package to work with acidic and basic groups in molecules. The package includes the following functionalities:
ABCounter: SMARTS-based matcher to determine the number of acidic and basic groups in molecules.ABClassBuilder: Converter that accepts a dictionary of pKa numerical values and yields anABClassDataobject with their corresponding classes such asSTRONG,WEAK, andNONE.IonMatcher: Matcher that accepts anABClassDataobject and yields anIonDefinitioncontaining information about the major species at pH 7.4 and its corresponding ionic class and explanation.pIPredictor: Predictor based on the Henderson–Hasselbalch equation for calculating the pI of molecules. It accepts a dictionary of pKa values and calculates the pI using either the bisect method or value bounds. Note that the bisect method may yield results that are in disagreement with discrete charge methods: e.g., for a molecule with a weak acid [pKa == 10] and a weak base [pKb == 2], you would expect to find a zero charge as soon as pH moves from 2 towards basic values (pI == pH == ~2.1); however, this implementation calculates charges as fractional, hence for weak groups they leak shifting the pI towards the average [pH ~= 6].
ABCount can be installed from pypi (https://pypi.org/project/abcount).
pip install abcountfrom rdkit import Chem
from abcount import ABCounter
# Use the tool out of the box with default definitions.
mol = Chem.MolFromSmiles("[nH]1nnnc1-c3c2[nH]ncc2ccc3")
abc = ABCounter()
abc.count_acid_and_bases(mol){'acid': 2, 'base': 2}from rdkit import Chem
from abcount import ABCounter
# Point the tool to using your own definitions.
# The format is JSON and attributes must be consistent to those in
# acid_definitions.json and base_definitions.json in abcount/data.
mol = Chem.MolFromSmiles("[nH]1nnnc1-c3c2[nH]ncc2ccc3")
abc = ABCounter(acid_defs_filepath="/my/path/acid_defs.json", base_defs_filepath="/my/path/base_defs.json")
abc.acid_matcher.definitions_fpPosixPath('/my/path/acid_defs.json')from abcount import ABClassBuilder
abcb = ABClassBuilder()
# The builder expects two acidic and two basic groups with these key names.
predictions = {"pka_acid1": 3.5, "pka_acid2": None, "pka_base1": 9.785, "pka_base2": None}
abcb.build(predictions)ABClassData(acid_1_class=<AcidType.STRONG: 'strong_acid'>, acid_2_class=<AcidType.NONE: 'no_acid'>, base_1_class=<BaseType.STRONG: 'strong_base'>, base_2_class=<BaseType.NONE: 'no_base'>)# to_dict() can be used to obtain a dictionary containing a mix of objects.
# Alternatively, the output can also be serialised using to_json()
abcb.build(predictions).to_json()'{"acid_1_class": "strong_acid", "acid_2_class": "no_acid", "base_1_class": "strong_base", "base_2_class": "no_base"}'from abcount import ABClassBuilder, PKaClassBuilder
abcb = ABClassBuilder()
# Custom names can be passed but these need to be
# configured in a `CustomPKaAttribute` class.
predictions = {"my_pka_acid1": 3.5, "my_pka_acid2": None, "my_pka_base1": 9.785, "my_pka_base2": None}
CustomPKaAttribute = PKaClassBuilder.build(ACID_1="my_pka_acid1", BASE_1="my_pka_base1", ACID_2="my_pka_acid2", BASE_2="my_pka_base2")
# The `CustomPKaAttribute` can then be passed to the builder
# which will map the new data to the rules.
abcb.build(predictions, CustomPKaAttribute)ABClassData(acid_1_class=<AcidType.STRONG: 'strong_acid'>, acid_2_class=<AcidType.NONE: 'no_acid'>, base_1_class=<BaseType.STRONG: 'strong_base'>, base_2_class=<BaseType.NONE: 'no_base'>)from abcount import ABClassBuilder
abcb = ABClassBuilder()
# It is possible to work with fewer acidic or basic groups
# These can be set as arguments in the builder
predictions = {"pka_acid1": 3.5, "pka_acid2": 7.5, "pka_base1": 9.785}
abcb.build(predictions, num_acids=2, num_bases=1)# Note that despite passing only one basic group, the builder still
# returns `base_2_class` but associating that with a None instead of BaseType.NONE.
ABClassData(acid_1_class=<AcidType.STRONG: 'strong_acid'>, acid_2_class=<AcidType.NONE: 'no_acid'>, base_1_class=<BaseType.STRONG: 'strong_base'>, base_2_class=None)from abcount import ABClassBuilder, IonMatcher
abcb = ABClassBuilder()
predictions = {"pka_acid1": 3.5, "pka_acid2": 7.5, "pka_base1": 9.785}
abcd = abcb.build(predictions, num_acids=2, num_bases=1)
ion_matcher = IonMatcher()
ion_matcher.match_class_data(abcd)# Note that IonMatcher ignores AcidType.NONE and BaseType.NONE - treats them as None.
IonDefinition(class_data=ABClassData(acid_1_class=<AcidType.STRONG: 'strong_acid'>, acid_2_class=None, base_1_class=<BaseType.STRONG: 'strong_base'>, base_2_class=None), major_species_ph74_class='zwitterion', ion_class='zwitterion', explanation='acid_1_class: strong_acid, base_1_class: strong_base')# to_json() can also be applied to `IonDefinition`
# to yield a fully serialised representation.
# Alternatively, to_dict() can be used to obtain
# a dictionary containing a mix of objects.
ion_matcher.match_class_data(abcd).to_dict(){'class_data': {'acid_1_class': <AcidType.STRONG: 'strong_acid'>, 'acid_2_class': None, 'base_1_class': <BaseType.STRONG: 'strong_base'>, 'base_2_class': None}, 'major_species_ph74_class': 'zwitterion', 'ion_class': 'zwitterion', 'explanation': 'acid_1_class: strong_acid, base_1_class: strong_base'}
from abcount import pIPredictor
predictions = {
"pka_acid1": 3,
"pka_acid2": None,
"pka_base1": 12,
"pka_base2": 8.5,
}
pIPredictor.predict_input(predictions)10.25
from abcount import PKaClassBuilder
from abcount.components.isoelectric import pIPredictor
CustomPKaAttribute = PKaClassBuilder.build(ACID_1="my_pka_acid1", BASE_1="my_pka_base1", ACID_2="my_pka_acid2", BASE_2="my_pka_base2")
predictions = {
"my_pka_acid1": 3,
"my_pka_base1": 5.5,
"my_pka_acid2": 12,
"my_pka_base2": 8.5,
}
pIPredictor.predict_input(predictions, CustomPKaAttribute)7.0
The SMARTS patterns used in this project were obtained from the following sources. Note that definitions are not deduplicated, hence require curation to avoid redundant matching.
- Pan, X.; Wang, H.; Li, C.; Zhang, J. Z. H.; Ji, C., MolGpka: A Web Server for Small Molecule pKa Prediction Using a Graph-Convolutional Neural Network Journal of Chemical Information and Modeling 2021, 61 (7), 3159–3165. DOI: 10.1021/acs.jcim.1c00075
- Wu, J.; Wan, Y.; Wu, Z.; Zhang, S.; Cao, D.; Hsieh, C.-Y.; Hou, T., MF-SuP-pKa: Multi-fidelity modeling with subgraph pooling mechanism for pKa prediction Acta Pharmaceutica Sinica B 2023, 13 (6). DOI: 10.26434/chemrxiv-2022-t6q61
- Some manually curated definitions.
- Generate acidic and basic definitions from aggregated data:
python abcount/_definitions.py. A follow up on how definitions can be curated will be provided. - Run tests:
pytest -vss tests/test.py - Run validation:
cd tests && validation.py. This will also generate four CSV files listing out false positives and negatives for the test data.
- The package was created using
uv(https://docs.astral.sh/uv/). - The package can be installed from the wheel in the
dist/folder. When a new version needs to be released, a new wheel must be built. That can be done by changing the version of the package insidepyproject.tomlthen callinguv buildwhich will create a new build. - The code can be automatically tested using
pytest -vss tests/test.pywhich requirespytestto be installed. - The
Makefilecan also be used for building (make build) or testing (make test). - Before committing new code, please always check that the style and syntax are compliant using
pre-commit.
The pyproject.toml already contains the optional dependencies needed for development. Follow these steps to set up the environment.
# Make sure you have got Python >= 3.10
python --version
> Python 3.12.7
# Installs `abcount` in editable mode and with dev dependencies
pip install -e .[dev]
> ...
> Successfully installed abcount ...
# Setup pre-commit hooks
pre-commit install
> pre-commit installed at .git/hooks/pre-commit