bindtools 0.2.3__tar.gz → 0.3.1__tar.gz

{bindtools-0.2.3 → bindtools-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: bindtools
-Version: 0.2.3
+Version: 0.3.1
 Keywords: chemistry,analytical chemistry,binding constants,supramolecular
 Author: Martin Peeks
 Author-email: Martin Peeks <martinp23@googlemail.com>, m.peeks@unsw.edu.au
@@ -51,11 +51,26 @@ Description-Content-Type: text/markdown
   - Handles various experimental data including NMR integrations, chemical shifts (NMR `deltaH`/`deltaF`), and linear concentration-weighted observables (UV-vis / fluorescence).
 - **Bayesian Inference & Uncertainty Quantification**:
   - Uses `emcee` for Markov Chain Monte Carlo (MCMC) sampling.
-  - Generates trace/chain convergence plots and corner plots using `corner` and `arviz`.
+  - Generates trace/chain convergence plots and corner plots using `corner` and `matplotlib`.
   - MCMC runs can be serialized and stored as HDF5 files for future analysis.
 
 ---
 
+## Package Architecture
+
+`bindtools` is organized into modular scientific domain subpackages:
+
+- **`bindtools.speciation`**: Chemical equilibrium solvers (Numba JIT Newton-Raphson and vectorized cubic analytical solutions for 1:1, 1:2, and 2:1 systems).
+- **`bindtools.observables`**: Physical measurement transforms (`ObsType`, NMR chemical shifts, integrals, and UV-vis / fluorescence linear absorption).
+- **`bindtools.models`**: Model definition (`bindingModel`), simulation helpers, and optimization engine.
+- **`bindtools.mcmc`**: Bayesian parameter estimation (`MCMC`), priors, likelihoods, and HDF5 serialization.
+- **`bindtools.plotting`**: Visualizations for speciation, fit residuals, and MCMC trace/corner diagnostics.
+- **`bindtools.io`**: Data export utilities (`saveFitCSV`).
+
+Core symbols can be imported directly from the top level (`import bindtools as bt`), while legacy imports (`from bindtools import binding as bd`) remain fully supported for backwards compatibility.
+
+---
+
 ## Installation
 
 `bindtools` is available on PyPI. You can install it directly using `pip`:
@@ -90,7 +105,7 @@ You can compute the equilibrium concentration of free species (components and co
 
 ```python
 import numpy as np
-from bindtools import binding as bd
+import bindtools as bt
 
 # Define total concentrations: 50 data points of Host (1e-3 M) and Guest (0 to 1e-2 M)
 component_concs = np.zeros((50, 2))
@@ -113,13 +128,51 @@ logK = np.array([0, 0, 4])
 # Solve for concentrations at each point
 results = []
 for total_concs in component_concs:
-    spec_concs = bd.getConcs(eq_mat, total_concs, logK)
+    spec_concs = bt.getConcs(eq_mat, total_concs, logK)
     results.append(spec_concs)
 
 results = np.array(results)
 print("First point [H, G, HG]:", results[0])
 ```
 
+### 2. Model Fitting (`bindingModel`)
+
+Fit binding models to experimental observables (integrals, chemical shifts, or absorbance):
+
+```python
+import bindtools as bt
+
+# Initialize model with stoichiometry, component names, and data
+model = bt.bindingModel(
+    eqMat=eq_mat,
+    compNames=["H", "G"],
+    speciesList=["H", "G", "HG"],
+    colToComp=col_to_comp,
+    rawData=raw_data,
+)
+
+# Prepare parameters and fit
+model.prepModel()
+model.runModel(skip_col=2, method="least_squares")
+
+print("Fitted logK:", model.miniResult.params["logHG"].value)
+```
+
+### 3. Bayesian MCMC & Uncertainty Estimation
+
+Quantify parameter uncertainties with MCMC sampling and generate corner plots:
+
+```python
+obs = [bt.ObsType("concMeas")]
+mcmc = bt.MCMC(model, obs, walkers=25, samples=2000)
+sampler, bm = mcmc.run(thin=10)
+
+# Diagnostics & plots
+mcmc.plot_chain()
+mcmc.plot_corner()
+mcmc.save("fit_results.hdf")
+```
+
 ---
 
 ## License

{bindtools-0.2.3 → bindtools-0.3.1}/README.md

@@ -18,11 +18,26 @@
   - Handles various experimental data including NMR integrations, chemical shifts (NMR `deltaH`/`deltaF`), and linear concentration-weighted observables (UV-vis / fluorescence).
 - **Bayesian Inference & Uncertainty Quantification**:
   - Uses `emcee` for Markov Chain Monte Carlo (MCMC) sampling.
-  - Generates trace/chain convergence plots and corner plots using `corner` and `arviz`.
+  - Generates trace/chain convergence plots and corner plots using `corner` and `matplotlib`.
   - MCMC runs can be serialized and stored as HDF5 files for future analysis.
 
 ---
 
+## Package Architecture
+
+`bindtools` is organized into modular scientific domain subpackages:
+
+- **`bindtools.speciation`**: Chemical equilibrium solvers (Numba JIT Newton-Raphson and vectorized cubic analytical solutions for 1:1, 1:2, and 2:1 systems).
+- **`bindtools.observables`**: Physical measurement transforms (`ObsType`, NMR chemical shifts, integrals, and UV-vis / fluorescence linear absorption).
+- **`bindtools.models`**: Model definition (`bindingModel`), simulation helpers, and optimization engine.
+- **`bindtools.mcmc`**: Bayesian parameter estimation (`MCMC`), priors, likelihoods, and HDF5 serialization.
+- **`bindtools.plotting`**: Visualizations for speciation, fit residuals, and MCMC trace/corner diagnostics.
+- **`bindtools.io`**: Data export utilities (`saveFitCSV`).
+
+Core symbols can be imported directly from the top level (`import bindtools as bt`), while legacy imports (`from bindtools import binding as bd`) remain fully supported for backwards compatibility.
+
+---
+
 ## Installation
 
 `bindtools` is available on PyPI. You can install it directly using `pip`:
@@ -57,7 +72,7 @@ You can compute the equilibrium concentration of free species (components and co
 
 ```python
 import numpy as np
-from bindtools import binding as bd
+import bindtools as bt
 
 # Define total concentrations: 50 data points of Host (1e-3 M) and Guest (0 to 1e-2 M)
 component_concs = np.zeros((50, 2))
@@ -80,13 +95,51 @@ logK = np.array([0, 0, 4])
 # Solve for concentrations at each point
 results = []
 for total_concs in component_concs:
-    spec_concs = bd.getConcs(eq_mat, total_concs, logK)
+    spec_concs = bt.getConcs(eq_mat, total_concs, logK)
     results.append(spec_concs)
 
 results = np.array(results)
 print("First point [H, G, HG]:", results[0])
 ```
 
+### 2. Model Fitting (`bindingModel`)
+
+Fit binding models to experimental observables (integrals, chemical shifts, or absorbance):
+
+```python
+import bindtools as bt
+
+# Initialize model with stoichiometry, component names, and data
+model = bt.bindingModel(
+    eqMat=eq_mat,
+    compNames=["H", "G"],
+    speciesList=["H", "G", "HG"],
+    colToComp=col_to_comp,
+    rawData=raw_data,
+)
+
+# Prepare parameters and fit
+model.prepModel()
+model.runModel(skip_col=2, method="least_squares")
+
+print("Fitted logK:", model.miniResult.params["logHG"].value)
+```
+
+### 3. Bayesian MCMC & Uncertainty Estimation
+
+Quantify parameter uncertainties with MCMC sampling and generate corner plots:
+
+```python
+obs = [bt.ObsType("concMeas")]
+mcmc = bt.MCMC(model, obs, walkers=25, samples=2000)
+sampler, bm = mcmc.run(thin=10)
+
+# Diagnostics & plots
+mcmc.plot_chain()
+mcmc.plot_corner()
+mcmc.save("fit_results.hdf")
+```
+
 ---
 
 ## License

bindtools-0.3.1/pyproject.toml

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["uv_build"]
+build-backend = "uv_build"
+
+[project]
+name = "bindtools"
+version = "0.3.1"
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+requires-python = ">=3.12"
+keywords = [
+    "chemistry",
+    "analytical chemistry",
+    "binding constants",
+    "supramolecular",
+]
+dependencies = [
+    "corner==2.2.3",
+    "emcee==3.1.6",
+    "h5py>=3.14.0",
+    "latex2mathml>=3.81.0",
+    "lmfit==1.3.4",
+    "matplotlib==3.11.0",
+    "numba>=0.66",
+    "numpy>=2.3.4",
+    "openpyxl>=3.1.5",
+    "pandas>=2.3.3",
+    "scipy==1.18.0",
+    "tqdm==4.68.3",
+    "uncertainties==3.2.3",
+]
+
+[[project.authors]]
+name = "Martin Peeks"
+email = "martinp23@googlemail.com"
+
+[[project.authors]]
+email = "m.peeks@unsw.edu.au"
+
+[project.urls]
+Homepage = "https://github.com/martinp23/bindtools"
+Documentation = "https://readthedocs.org"
+Repository = "https://github.com/martinp23/bindtools.git"
+Issues = "https://github.com/martinp23/bindtools/issues"
+
+[tool.ruff]
+exclude = [
+    ".bzr",
+    ".direnv",
+    ".eggs",
+    ".git",
+    ".git-rewrite",
+    ".hg",
+    ".ipynb_checkpoints",
+    ".mypy_cache",
+    ".nox",
+    ".pants.d",
+    ".pyenv",
+    ".pytest_cache",
+    ".pytype",
+    ".ruff_cache",
+    ".svn",
+    ".tox",
+    ".venv",
+    ".vscode",
+    "__pypackages__",
+    "_build",
+    "buck-out",
+    "build",
+    "dist",
+    "node_modules",
+    "site-packages",
+    "venv",
+]
+line-length = 120
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    "E4",
+    "E7",
+    "E9",
+    "F",
+]
+ignore = []
+fixable = ["ALL"]
+unfixable = []
+dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+docstring-code-format = false
+docstring-code-line-length = "dynamic"
+
+[dependency-groups]
+dev = [
+    "ipykernel>=7.3.0",
+    "pytest>=9.1.0",
+    "ruff>=0.15.18",
+]

bindtools-0.2.3/pyproject.toml → bindtools-0.3.1/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "bindtools"
-version = "0.2.3"
+version = "0.3.1"
 readme = "README.md"
 classifiers = [
   # How mature is this project? Common values are

bindtools-0.3.1/src/bindtools/__init__.py

@@ -0,0 +1,49 @@
+"""bindtools: Python library for supramolecular chemistry modeling, fitting, and speciation.
+"""
+
+from bindtools.exceptions import EquilibriumError
+from bindtools.speciation import (
+    getConcs,
+    getConcsScipy,
+    calc_analytical_speciation,
+)
+from bindtools.observables import (
+    ObsType,
+    concToObservable,
+    concToDelta,
+    concToLinearObs,
+)
+from bindtools.models import (
+    bindingModel,
+    simulateModel,
+    getCalcData,
+)
+from bindtools.mcmc import (
+    MCMC,
+)
+from bindtools.plotting import (
+    makeFitResidPlot,
+)
+from bindtools.io import (
+    saveFitCSV,
+)
+from bindtools import binding
+
+__all__ = [
+    "binding",
+    "EquilibriumError",
+    "getConcs",
+    "getConcsScipy",
+    "calc_analytical_speciation",
+    "ObsType",
+    "concToObservable",
+    "concToDelta",
+    "concToLinearObs",
+    "bindingModel",
+    "simulateModel",
+    "getCalcData",
+    "MCMC",
+    "makeFitResidPlot",
+    "saveFitCSV",
+]
+

bindtools-0.3.1/src/bindtools/binding.py

@@ -0,0 +1,95 @@
+"""Compatibility façade re-exporting all public and internal symbols from modular subpackages.
+
+This module preserves 100% backwards compatibility with historical code and downstream packages
+(e.g., `import bindtools.binding as bd` or `from bindtools.binding import bindingModel, getConcs`).
+"""
+
+from bindtools.exceptions import EquilibriumError
+from bindtools.speciation import (
+    apply_along_axis_0,
+    _apply_along_axis_0,
+    specCalc,
+    _specJac,
+    specJac,
+    specObj,
+    DoNR,
+    getConcs,
+    getConcsScipy,
+    _solve_cubic_vectorized,
+    calc_analytical_speciation,
+    _infer_simple_fast_exchange_topology,
+)
+from bindtools.observables import (
+    ObsType,
+    sigmaMapping,
+    deltaToConc,
+    concToDelta,
+    concToLinearObs,
+    concToObservable,
+)
+from bindtools.models import (
+    fitfun,
+    bindingModel,
+    simulateModel,
+    getCalcData,
+)
+from bindtools.mcmc import (
+    calclnprob,
+    log_prob,
+    log_prior,
+    MCMC,
+    doMCMC,
+    getTau,
+    makeMCMCLabels,
+    mcmchelper,
+)
+from bindtools.plotting import (
+    makeFitResidPlot,
+    plotMCMC,
+    plotCorner,
+)
+from bindtools.io import saveFitCSV
+
+__all__ = [
+    # Exceptions
+    "EquilibriumError",
+    # Speciation
+    "apply_along_axis_0",
+    "_apply_along_axis_0",
+    "specCalc",
+    "_specJac",
+    "specJac",
+    "specObj",
+    "DoNR",
+    "getConcs",
+    "getConcsScipy",
+    "_solve_cubic_vectorized",
+    "calc_analytical_speciation",
+    "_infer_simple_fast_exchange_topology",
+    # Observables
+    "ObsType",
+    "sigmaMapping",
+    "deltaToConc",
+    "concToDelta",
+    "concToLinearObs",
+    "concToObservable",
+    # Models & Simulation
+    "fitfun",
+    "bindingModel",
+    "simulateModel",
+    "getCalcData",
+    # Visualization & IO
+    "makeFitResidPlot",
+    "plotMCMC",
+    "plotCorner",
+    "saveFitCSV",
+    # MCMC
+    "calclnprob",
+    "log_prob",
+    "log_prior",
+    "MCMC",
+    "doMCMC",
+    "getTau",
+    "makeMCMCLabels",
+    "mcmchelper",
+]

bindtools-0.3.1/src/bindtools/exceptions.py

@@ -0,0 +1,6 @@
+class EquilibriumError(Exception):
+    def __init__(self, message, val, params):
+        super().__init__(message)
+        self.val = val
+        self.params = params
+

bindtools-0.3.1/src/bindtools/io/__init__.py

@@ -0,0 +1,4 @@
+from bindtools.io.export import saveFitCSV
+
+__all__ = ["saveFitCSV"]
+

bindtools-0.3.1/src/bindtools/io/export.py

@@ -0,0 +1,29 @@
+import numpy as np
+import pandas as pd
+from bindtools.models.simulation import getCalcData
+
+
+def saveFitCSV(m, mask, filename, xindex=1, xvals=None, xlabel="[G]_tot (M)", labels=None):
+    calcData = getCalcData(m)
+    compConcs = m.compConcs.copy()
+    exptData = m.fcn_opts["exptData"].copy()
+
+    if labels is None:
+        labels = [m.obsList[ii] for ii in mask]
+
+    if mask is not None:
+        calcData = calcData[:, mask]
+        exptData = exptData[:, mask]
+
+    if xvals is None:
+        xvals = compConcs[:, xindex]
+
+    ydata = np.concatenate((exptData, calcData), axis=1)
+    data = np.concatenate((xvals[:, np.newaxis], ydata), axis=1)
+
+    cols = [xlabel, *["expt " + x for x in labels], *["calc " + x for x in labels]]
+    print(cols)
+    dataExport = pd.DataFrame(data, columns=cols)
+
+    dataExport.to_csv(filename, index=False)
+

bindtools-0.3.1/src/bindtools/mcmc/__init__.py

@@ -0,0 +1,19 @@
+from bindtools.mcmc.likelihood import calclnprob, log_prob, log_prior
+from bindtools.mcmc.sampler import MCMC
+from bindtools.mcmc.helpers import (
+    doMCMC,
+    getTau,
+    makeMCMCLabels,
+    mcmchelper,
+)
+
+__all__ = [
+    "calclnprob",
+    "log_prob",
+    "log_prior",
+    "MCMC",
+    "doMCMC",
+    "getTau",
+    "makeMCMCLabels",
+    "mcmchelper",
+]

bindtools-0.3.1/src/bindtools/mcmc/helpers.py

@@ -0,0 +1,71 @@
+from bindtools.mcmc.sampler import MCMC
+from bindtools.observables.types import ObsType
+import emcee
+
+
+def doMCMC(model, obs, samples=1000, variance=0.1, walkers=10):
+    print("Warning: doMCMC() is deprecated. Use the MCMC class and MCMC.run() in future.")
+    mcmcModel = MCMC(model, obs, walkers=walkers, samples=samples, variance=variance)
+    sampler, bm = mcmcModel.run(ret=True)
+    return sampler, bm
+
+
+def getTau(sampler):
+    print("Warning: getTau is deprecated. Use the MCMC class and MCMC.get_tau() in future.")
+
+    try:
+        tau = sampler.get_autocorr_time()
+        print(tau)
+    except emcee.autocorr.AutocorrError as e:
+        print("Warning: Autocorrelation time is likely too short. Check the chain.")
+        print(e.tau)
+
+
+def makeMCMCLabels(model, obs):
+    print("Warning: makeMCMCLabels is deprecated. Use the MCMC class and MCMC.labels in future.")
+
+    params = []
+    for pp in model.params:
+        if model.params[pp].vary:
+            params.append(model.params[pp].name)
+
+    ss = []
+    for pp in obs:
+        ss.append(pp.name)
+
+    ss = list(set(ss))
+    ss = ["lnsigma" + x for x in ss]
+    params += ss
+
+    return params
+
+
+def mcmchelper(
+    model, obsList=None, obs_types=None, walkers=25, samples=10000, variance=0.1, thin=500, figName="out.jpg"
+):
+    """
+    Helper function to run MCMC on a binding model and plot results.
+
+    Parameters:
+    - model: The binding model to run MCMC on.
+    - obsList: List of observable types.
+    - obs_types: Optional list of ObsType instances.
+    - walkers: Number of walkers for MCMC.
+    - samples: Number of samples to draw.
+    - variance: Variance for the MCMC sampling.
+    - thin: Thinning factor for the samples.
+    - figName: Name of the output figure file.
+    """
+    if obs_types is None:
+        if obsList is None:
+            raise ValueError("Either obsList or obs_types must be provided.")
+        obs_types = [ObsType("deltaH")] * len(obsList)
+
+    mcmc = MCMC(model, obs_types, walkers=walkers, samples=samples, variance=variance)
+    mcmc.run(thin=thin)
+
+    mcmc.plot_chain()
+    mcmc.get_tau()
+    ff = mcmc.plot_corner()
+    ff.savefig(figName, dpi=150)
+    return mcmc

bindtools-0.3.1/src/bindtools/mcmc/likelihood.py

@@ -0,0 +1,49 @@
+import math
+import numpy as np
+from numba import jit
+
+from bindtools.models.objective import fitfun
+
+
+@jit(nopython=True, nogil=True, cache=True)
+def calclnprob(r, lnsigma):
+    r = -0.5 * np.sum(np.divide(r, np.exp(lnsigma)) ** 2 + np.log(2 * np.pi) + 2 * lnsigma)
+
+    if math.isnan(r):
+        print("Probability function returned NaN, fudging to -inf.")
+        return -np.inf
+    return r
+
+
+@jit(nopython=True, nogil=True, cache=True)
+def log_prior(val, bounds):
+    for ii in range(len(val)):
+        if not (bounds[ii][0] < val[ii] < bounds[ii][1]):
+            return -np.inf
+    return 0.0
+
+
+def log_prob(params, fcn_opts, bounds):
+    lp = log_prior(params, bounds)
+
+    if not np.isfinite(lp):
+        return -np.inf
+
+    mapping = fcn_opts["sigmaMapping"]
+    lnsigmaVals = params[-(max(mapping) + 1) :]
+    lnsigma = np.array([lnsigmaVals[ii] for ii in mapping])
+
+    pp = np.zeros(
+        len(params) + np.shape(fcn_opts["compConcs"])[1]
+    )  # need extra parameters - for logK=0 - for each component in the eqMat
+
+    pp[-len(params) :] = params
+
+    fcn_opts["ret"] = "residual"
+    r = np.array(fitfun(pp, fcn_opts))
+    if np.isnan(r).any():
+        return -np.inf
+
+    rout = calclnprob(r, lnsigma)
+    return rout
+