Initial commit

Author: finlayclark

.github/workflows/CI.yaml

@@ -0,0 +1,62 @@
+name: CI
+
+on:
+  # GitHub has started calling new repo's first branch "main" https://github.com/github/renaming
+  # The cookiecutter uses the "--initial-branch" flag when it runs git-init
+  push:
+    branches:
+      - "main"
+  pull_request:
+    branches:
+      - "main"
+  schedule:
+    # Weekly tests run on main by default:
+    #   Scheduled workflows run on the latest commit on the default or base branch.
+    #   (from https://help.github.com/en/actions/reference/events-that-trigger-workflows#scheduled-events-schedule)
+    - cron: "0 0 * * 0"
+
+jobs:
+  test:
+    name: Test on ${{ matrix.os }}, Python ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.9', '3.10', '3.11']
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Additional info about the build
+        shell: bash
+        run: |
+          uname -a
+          df -h
+          ulimit -a
+
+      - uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: env.yaml
+          environment-name: test
+          create-args: >- # beware the >- instead of |, we don't split on newlines but on spaces
+            python=${{ matrix.python-version }}
+
+      - name: Install package
+        # conda setup requires this special shell
+        shell: bash -l {0}
+        run: |
+          python -m pip install . 
+          micromamba list
+
+      - name: Run tests
+        # conda setup requires this special shell
+        shell: bash -l {0}
+        run: |
+          pytest -v --cov=K2DG --cov-report=xml --color=yes tests/
+
+      - name: Upload coverage reports to Codecov
+        uses: codecov/codecov-action@v3
+        with:
+          file: ./coverage.xml
+          flags: unittests
+          name: codecov-${{ matrix.os }}-py${{ matrix.python-version }}

README.md

@@ -0,0 +1,3 @@
+# k2dg
+
+A command line tool to convert between dissociation constants and free energies.

env.yml

@@ -0,0 +1,6 @@
+name: k2dg
+channels:
+  - conda-forge
+  - defaults
+dependencies:
+  - python

k2dg/__init__.py

@@ -0,0 +1,6 @@
+from pint import UnitRegistry
+
+ureg = UnitRegistry()
+Q_ = ureg.Quantity
+
+from .conversion import *

k2dg/__main__.py

@@ -0,0 +1,9 @@
+from k2dg._cli import run_cli
+
+
+def main():
+    run_cli()
+
+
+if __name__ == "__main__":
+    main()

k2dg/_cli.py

@@ -0,0 +1,82 @@
+"""Command line interface for k2dg."""
+
+import argparse
+from . import ureg, Q_
+from .conversion import dg0_to_kd0 as _dg0_to_kd0, kd0_to_dg0 as _kd0_to_dg0
+from ._parse import (
+    _parse_dg_units,
+    _parse_k_units,
+    _parse_temperature,
+    K_UNITS,
+    DG_UNITS,
+)
+from ._print import _print_dg0, _print_kd0
+
+
+def run_cli() -> None:
+    """Run the command line interface."""
+
+    global_parser = argparse.ArgumentParser(prog="k2dg")
+    global_parser.add_argument(
+        "-v", "--version", action="version", version="%(prog)s 0.1.0"
+    )
+    subparsers = global_parser.add_subparsers(
+        title="subcommands",
+        help="Converters from dissociation constants to free energies of binding and vice versa.",
+    )
+
+    # Add subparsers to handle conversion in each direction
+    to_dg_parser = subparsers.add_parser(
+        "2dg", help="Convert a dissociation constant to a free energy of binding."
+    )
+    to_kd_parser = subparsers.add_parser(
+        "2kd", help="Convert a free energy of binding to a dissociation constant."
+    )
+
+    subparser_dict = {
+        to_dg_parser: {
+            "units": K_UNITS,
+            "value": "kd",
+            "func": _kd0_to_dg0,
+            "parse_func": _parse_k_units,
+            "print_func": _print_dg0,
+        },
+        to_kd_parser: {
+            "units": DG_UNITS,
+            "value": "dg",
+            "func": _dg0_to_kd0,
+            "parse_func": _parse_dg_units,
+            "print_func": _print_kd0,
+        },
+    }
+
+    for subparser in subparser_dict:
+        subparser.add_argument(
+            "value",
+            type=float,
+            help=f"The value of {subparser_dict[subparser]['value']}.",
+        )
+        subparser.add_argument(
+            "units",
+            type=str,
+            help=f"The units of the value. Must be one of {list(subparser_dict[subparser]['units'].keys())}.",
+        )
+        subparser.add_argument(
+            "-t",
+            "--temperature",
+            type=float,
+            help="The temperature (in Kelvin) at which the dissociation constant was measured.",
+            default=298.15,
+        )
+        subparser.set_defaults(func=subparser_dict[subparser]["func"])
+        subparser.set_defaults(parse_func=subparser_dict[subparser]["parse_func"])
+        subparser.set_defaults(print_func=subparser_dict[subparser]["print_func"])
+
+    args = global_parser.parse_args()
+    # Check that a subparser was selected
+    if not hasattr(args, "func"):
+        global_parser.print_help()
+        return
+    units = args.parse_func(args.units)
+    temperature = _parse_temperature(args.temperature)
+    args.print_func(args.func(args.value * units, temperature))

k2dg/_parse.py

@@ -0,0 +1,43 @@
+"""Functions for parsing units from the command line input."""
+
+from . import Q_
+
+from pint import Quantity
+
+K_UNITS = {"pM": 1e-12, "nM": 1e-9, "uM": 1e-6, "mM": 1e-3, "M": 1}
+DG_UNITS = {"kcal/mol": Q_(1, "kcal/mol"), "kJ/mol": Q_(1, "kJ/mol")}
+
+
+def _parse_k_units(units: str) -> float:
+    """
+    Parse a string of units (for the dissociation constant) into a float. Note
+    that there is an implcit conversion from the dissociation constant to the
+    standard dissociation constant.
+    """
+    lower_case_units = {k.lower(): v for k, v in K_UNITS.items()}
+    try:
+        return lower_case_units[units.lower()]
+    except KeyError:
+        raise ValueError(
+            f"Units {units} not recognized. Please use one of {K_UNITS.keys()}."
+        )
+
+
+def _parse_dg_units(units: str) -> Quantity:
+    """Parse a string of units (for the free energy of binding) into a float."""
+    lower_case_units = {k.lower(): v for k, v in DG_UNITS.items()}
+    try:
+        return lower_case_units[units.lower()]
+    except KeyError:
+        raise ValueError(
+            f"Units {units} not recognized. Please use one of {DG_UNITS.keys()}."
+        )
+
+
+def _parse_temperature(temperature: float) -> Quantity:
+    """Parse a temperature in Kelvin."""
+    if temperature < 100:
+        raise ValueError(
+            "Temperature must be in Kelvin. The supplied value is likely in Celsius."
+        )
+    return Q_(temperature, "K")

k2dg/_print.py

@@ -0,0 +1,26 @@
+"""Functions for printing results to the command line."""
+
+from pint import Quantity
+from ._parse import K_UNITS
+
+
+def _print_dg0(dg0: Quantity) -> None:
+    """Print the free energy of binding in kcal/mol."""
+    print(f"{dg0.to('kcal/mol').magnitude:#.3g} kcal/mol")
+
+
+def _print_kd0(kd0: float) -> None:
+    """
+    Print the dissociation constant with an appropriate prefix. Note that there
+    is an implicit conversion from the standard dissociation constant to the
+    dissociation constant.
+    """
+    # The appropriate prefix is the one that gives a value between 0.1 and 100
+    # (i.e. between 1e-1 and 1e2)
+    kd = kd0.magnitude
+    for prefix, value in K_UNITS.items():
+        if 1e-1 < kd / value < 1e2:
+            print(f"{kd / value:#.3g} {prefix}")
+            break
+    # The value is less than 0.1 pM
+    print(f"{kd / 1e-12:#.3g} pM")

k2dg/conversion.py

@@ -0,0 +1,29 @@
+"""Functions to convert between standard dissociation constants and free energies of binding."""
+
+import numpy as np
+from pint import Quantity
+from scipy import constants
+
+from . import ureg
+
+__all__ = ["get_kbT", "kd0_to_dg0", "dg0_to_kd0"]
+
+
+@ureg.check("[temperature]")
+def get_kbT(temperature: Quantity) -> Quantity:
+    """Return the value of k_b * T at a given temperature."""
+    k = constants.k * ureg.J / ureg.K
+    na = constants.N_A / ureg.mol
+    return k * temperature * na
+
+
+# @ureg.check("[None]", "[temperature]")  # None is not accepted TODO: Find a work around
+def kd0_to_dg0(kd0: float, temperature: Quantity) -> Quantity:
+    """Convert an standard dissociation constant a standard free energy of binding."""
+    return -get_kbT(temperature) * np.log(1 / kd0)
+
+
+@ureg.check("[energy] / [substance]", "[temperature]")
+def dg0_to_kd0(dg0: Quantity, temperature: Quantity) -> float:
+    """Convert a standard free energy of binding to a standard dissociation constant."""
+    return 1 / np.exp(-dg0 / get_kbT(temperature))

pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "k2dg"
+version = "0.1.0"
+description = "A simple command line app to interconvert dissociation constants and free energies of binding."
+authors = [{name = "Finlay Clark"}]
+readme = "README.md"
+requires-python = ">=3.9.0"
+dependencies = ["numpy", "scipy", "pint", "pytest"]
+
+[build-system]
+requires = ["setuptools>=64.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project.scripts]
+k2dg = "k2dg.__main__:main"
+

tests/__init__.py

@@ -0,0 +1,39 @@
+"""Test the conversion functions."""
+
+import numpy as np
+from k2dg import conversion
+from k2dg import Q_
+
+
+def test_get_kbT():
+    temperature = Q_(298.15, "K")
+    expected_kbT = Q_(0.592483, "kcal/mol")
+    assert np.isclose(
+        conversion.get_kbT(temperature).to("kcal/mol").magnitude,
+        expected_kbT.magnitude,
+        rtol=1e-5,
+    )
+
+
+def test_kd0_to_dg0():
+    temperature = Q_(298.15, "K")
+    kd0 = 0.347e-6
+    expected_dg0 = Q_(-8.812586, "kcal/mol")
+    print(conversion.kd0_to_dg0(kd0, temperature).to("kcal/mol").magnitude)
+    assert np.isclose(
+        conversion.kd0_to_dg0(kd0, temperature).to("kcal/mol").magnitude,
+        expected_dg0.magnitude,
+        rtol=1e-3,
+    )
+
+
+def test_dg0_to_kd0():
+    temperature = Q_(298.15, "K")
+    dg0 = Q_(-8.812586, "kcal/mol")
+    expected_kd0 = 0.347e-6
+    print(conversion.dg0_to_kd0(dg0, temperature))
+    assert np.isclose(
+        conversion.dg0_to_kd0(dg0, temperature),
+        expected_kd0,
+        rtol=1e-3,
+    )

tests/test_conversion.py

@@ -0,0 +1,34 @@
+"""Tests for the parse module."""
+from k2dg._parse import _parse_k_units, _parse_dg_units, _parse_temperature
+
+import pytest
+
+from k2dg import Q_
+
+
+def test_parse_k_units():
+    assert _parse_k_units("nM") == 1e-9
+    assert _parse_k_units("M") == 1
+    assert _parse_k_units("mM") == 1e-3
+    assert _parse_k_units("uM") == 1e-6
+    assert _parse_k_units("pM") == 1e-12
+    with pytest.raises(ValueError) as e:
+        _parse_k_units("foo")
+    assert (
+        str(e.value)
+        == "Units foo not recognized. Please use one of dict_keys(['pM', 'nM', 'uM', 'mM', 'M'])."
+    )
+
+
+def test_parse_dg_units():
+    assert _parse_dg_units("kcal/mol") == Q_(1, "kcal/mol")
+    assert _parse_dg_units("kJ/mol") == Q_(1, "kJ/mol")
+    with pytest.raises(ValueError):
+        _parse_dg_units("foo")
+
+
+def test_parse_temperature():
+    assert _parse_temperature(273.15) == Q_(273.15, "K")
+    assert _parse_temperature(300) == Q_(300, "K")
+    with pytest.raises(ValueError):
+        _parse_temperature(37)