chemap - Mapping chemical space

Library for computing molecular fingerprint based similarities as well as dimensionality reduction based chemical space visualizations.

Installation

chemap can be installed using pip.

pip install chemap

Or, to include UMAP computation abilities on either CPU or GPU chose one of the following option:

• CPU version: pip install "chemap[cpu]"
• GPU version (CUDA 12): pip install "chemap[gpu-cu12]"
• GPU version (CUDA 13): pip install "chemap[gpu-cu13]"

Fingerprint computations (choose from RDKit or scikit-fingerprints)

Fingerprints can be computed using generators from RDKit or scikit-fingerprints. This includes popular fingerprint types such as:

Path-based and circular fingerprints

• RDKit fingerprints
• Morgan fingerprints
• FCFP fingerprints
• ...

Predefined substructure fingerprints

• MACCS fingerprints
• PubChem fingerprints
• Klekota-Roth fingerprints
• ...

Topological distance based fingerprints

• Atom pair fingerprints

Fingerprint computations II (implementations in chemap)

Due to some existing limitations with present implementations, chemap also provides some fingerprint generator. Those allow to generate folded as well as unfolded fingerprints, each either as binary or count variant.

• MAP4 fingerprint --> from chemap.fingerprints import MAP4Gen
• Lingo fingerprint --> from chemap.fingerprints import LingoFingerprint

And, not really a fingerprint in the classical sense, but usefull as a baseline for benchmarking tasks (or as an additional component of a fingerprint), chemap provides a simple element count vector/fingerprint. This does nothing more than simply count the number of H's, C's, O's etc.

• ElementCount fingerprint --> from chemap.fingerprints import ElementCountFingerprint

Here a code example:

importnumpyasnpimportscipy.sparseasspfromrdkit.ChemimportrdFingerprintGeneratorfromskfp.fingerprintsimportMAPFingerprint, AtomPairFingerprintfromchemapimportcompute_fingerprints, DatasetLoader, FingerprintConfigds_loader=DatasetLoader()
# Load a single dataset from a local filesmiles=ds_loader.load("tests/data/smiles.csv")
# or load a dataset collection from a DOI based registry (e.g., Zenodo)files=ds_loader.load_collection("10.5281/zenodo.18682050")
# pass one of the absolute file paths from filessmiles=ds_loader.load(files[0])
# ----------------------------# RDKit: Morgan (folded, dense)# ----------------------------morgan=rdFingerprintGenerator.GetMorganGenerator(radius=3, fpSize=4096)
X_morgan=compute_fingerprints(
smiles,
morgan,
config=FingerprintConfig(
count=False,
folded=True,
return_csr=False, # dense numpyinvalid_policy="raise",
),
)
print("RDKit Morgan:", X_morgan.shape, X_morgan.dtype)
# -----------------------------------# RDKit: RDKitFP (folded, CSR sparse)# -----------------------------------rdkitfp=rdFingerprintGenerator.GetRDKitFPGenerator(fpSize=4096)
X_rdkitfp_csr=compute_fingerprints(
smiles,
rdkitfp,
config=FingerprintConfig(
count=False,
folded=True,
return_csr=True, # SciPy CSRinvalid_policy="raise",
),
)
assertsp.issparse(X_rdkitfp_csr)
print("RDKit RDKitFP (CSR):", X_rdkitfp_csr.shape, X_rdkitfp_csr.dtype, "nnz=", X_rdkitfp_csr.nnz)
# --------------------------------------------------# scikit-fingerprints: MAPFingerprint (folded, dense)# --------------------------------------------------# MAPFingerprint is a MinHash-like fingerprint (different from MAP4 lib).map_fp=MAPFingerprint(fp_size=4096, count=False, sparse=False)
X_map=compute_fingerprints(
smiles,
map_fp,
config=FingerprintConfig(
count=False,
folded=True,
return_csr=False,
invalid_policy="raise",
),
)
print("skfp MAPFingerprint:", X_map.shape, X_map.dtype)
# ----------------------------------------------------# scikit-fingerprints: AtomPairFingerprint (folded, CSR)# ----------------------------------------------------atom_pair=AtomPairFingerprint(fp_size=4096, count=False, sparse=False, use_3D=False)
X_ap_csr=compute_fingerprints(
smiles,
atom_pair,
config=FingerprintConfig(
count=False,
folded=True,
return_csr=True,
invalid_policy="raise",
),
)
assertsp.issparse(X_ap_csr)
print("skfp AtomPair (CSR):", X_ap_csr.shape, X_ap_csr.dtype, "nnz=", X_ap_csr.nnz)
# (Optional) convert CSR -> dense if you need a NumPy array downstream:X_ap=X_ap_csr.toarray().astype(np.float32, copy=False)

UMAP Chemical Space Visualization

chemap provides functions to compute UMAP coordinates based on molecular fingerprints. Depending on your system and installation, this can be either via a very fast cuml library by using create_chem_space_umap_gpu, which then only allows to use "cosine" as a metric, as well as folded/fixed sized fingerprints. The alternative is a numba-based variant create_chem_space_umap (so this is still optimized, but much slower than the GPU version). While this is slower, it in return allows to use Tanimoto as a metric and can also handle unfolded fingerprints.

Example:

fromrdkit.ChemimportrdFingerprintGeneratorfromchemap.plottingimportcreate_chem_space_umap, scatter_plot_hierarchical_labelsdata_plot=create_chem_space_umap(
data_compounds, # dataframe with smiles and class/subclass etc. informationcol_smiles="smiles",
inplace=False,
x_col="x",
y_col="y",
fpgen=rdFingerprintGenerator.GetMorganGenerator(radius=9, fpSize=4096),
)
# Plotfig, ax, _, _=scatter_plot_hierarchical_labels(
data_plot,
x_col="x",
y_col="y",
superclass_col="Superclass",
class_col="Class",
low_superclass_thres=2500,
low_class_thres=5000,
max_superclass_size=10_000,