openpkflow 0.1.2__py3-none-any.whl

openpkflow/__init__.py

@@ -0,0 +1,10 @@
+"""OpenPKFlow -- Python-first pharmacometrics and dissolution toolkit."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+__author__ = "Priyam Thakar"
+__email__ = "priyamthakar1@gmail.com"
+__license__ = "MIT"
+
+__all__ = ["__version__"]

openpkflow/bayes/__init__.py

@@ -0,0 +1 @@
+"""Bayesian PK module -- planned for v0.8.0."""

openpkflow/cli.py

@@ -0,0 +1,123 @@
+"""OpenPKFlow CLI - command-line interface built with Typer."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import typer
+
+from openpkflow import __version__
+from openpkflow.dissolution.loader import DissolutionCSVConfig
+from openpkflow.dissolution.similarity import f1, f2
+from openpkflow.dissolution.study import DissolutionStudy
+
+app = typer.Typer(
+    name="openpkflow",
+    help="OpenPKFlow - Python-first pharmacometrics toolkit.",
+    add_completion=False,
+)
+
+dissolution_app = typer.Typer(help="Dissolution similarity commands.")
+app.add_typer(dissolution_app, name="dissolution")
+
+
+@app.command("version")
+def version_command() -> None:
+    """Print the installed version of openpkflow."""
+    typer.echo(f"openpkflow {__version__}")
+
+
+@app.command("similarity")
+def similarity_command(
+    reference: str = typer.Option(
+        ...,
+        "--reference",
+        help="Comma-separated reference dissolution profile (percent released per time point).",
+    ),
+    test: str = typer.Option(
+        ...,
+        "--test",
+        help="Comma-separated test dissolution profile (percent released per time point).",
+    ),
+) -> None:
+    """Compute f1 and f2 from two comma-separated dissolution profiles.
+
+    Example
+    -------
+    openpkflow similarity --reference "20,40,60,80,90" --test "21,39,61,79,88"
+    """
+    try:
+        ref_vals = [float(v.strip()) for v in reference.split(",")]
+        tst_vals = [float(v.strip()) for v in test.split(",")]
+        f1_val = f1(ref_vals, tst_vals)
+        f2_val = f2(ref_vals, tst_vals)
+    except ValueError as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(f"f1 = {f1_val:.3f}")
+    typer.echo(f"f2 = {f2_val:.2f}")
+    interpretation = (
+        "f2 >= 50: profiles are similar."
+        if f2_val >= 50.0
+        else "f2 < 50: profiles are not similar."
+    )
+    typer.echo(f"Interpretation: {interpretation}")
+
+
+@dissolution_app.command("compare")
+def dissolution_compare(
+    csv_path: Path = typer.Argument(
+        ...,
+        help="Path to dissolution CSV file.",
+        exists=True,
+        file_okay=True,
+        dir_okay=False,
+        readable=True,
+    ),
+    reference: str = typer.Option(
+        ...,
+        "--reference",
+        help="Label of the reference formulation.",
+    ),
+    test: str = typer.Option(
+        ...,
+        "--test",
+        help="Label of the test formulation.",
+    ),
+    formulation_col: str = typer.Option("formulation", help="Formulation column name."),
+    batch_col: str = typer.Option("batch", help="Batch column name."),
+    time_col: str = typer.Option("time", help="Time column name."),
+    percent_released_col: str = typer.Option(
+        "percent_released", help="Percent released column name."
+    ),
+    report: Optional[Path] = typer.Option(
+        None,
+        "--report",
+        help="Write an HTML or Markdown report to this path (format inferred from extension).",
+    ),
+) -> None:
+    """Compare two formulations in a dissolution CSV using f1 and f2."""
+    config = DissolutionCSVConfig(
+        formulation_col=formulation_col,
+        batch_col=batch_col,
+        time_col=time_col,
+        percent_released_col=percent_released_col,
+    )
+    try:
+        study = DissolutionStudy.from_csv(csv_path, config)
+        result = study.compare(reference, test)
+    except (FileNotFoundError, ValueError) as exc:
+        typer.echo(f"Error: {exc}", err=True)
+        raise typer.Exit(1)
+
+    typer.echo(result.summary())
+
+    if report is not None:
+        fmt = "markdown" if str(report).endswith((".md", ".markdown")) else "html"
+        try:
+            result.report(report, format=fmt)
+            typer.echo(f"\nReport written to: {report}")
+        except Exception as exc:  # noqa: BLE001
+            typer.echo(f"Warning: could not write report: {exc}", err=True)

openpkflow/datasets/__init__.py

@@ -0,0 +1,26 @@
+"""Example datasets for OpenPKFlow."""
+from __future__ import annotations
+
+from importlib.resources import files
+
+
+def _dataset_path(name: str) -> str:
+    return str(files("openpkflow.datasets").joinpath(name))
+
+
+def example_dissolution_path() -> str:
+    """Path to the borderline-similar example dataset (f2 approx 57)."""
+    return _dataset_path("example_dissolution.csv")
+
+
+def example_similar_path() -> str:
+    """Path to the clearly-similar example dataset (f2 approx 80)."""
+    return _dataset_path("example_similar.csv")
+
+
+def example_not_similar_path() -> str:
+    """Path to the not-similar example dataset (f2 approx 38)."""
+    return _dataset_path("example_not_similar.csv")
+
+
+__all__ = ["example_dissolution_path", "example_similar_path", "example_not_similar_path"]

openpkflow/datasets/example_dissolution.csv

@@ -0,0 +1,37 @@
+formulation,batch,time,percent_released
+reference,R1,5,14.2
+reference,R1,10,29.1
+reference,R1,15,47.3
+reference,R1,20,61.4
+reference,R1,30,77.6
+reference,R1,45,89.5
+reference,R2,5,15.8
+reference,R2,10,31.2
+reference,R2,15,48.9
+reference,R2,20,62.7
+reference,R2,30,78.4
+reference,R2,45,90.6
+reference,R3,5,15.0
+reference,R3,10,29.7
+reference,R3,15,47.8
+reference,R3,20,62.0
+reference,R3,30,78.0
+reference,R3,45,90.0
+test,T1,5,11.5
+test,T1,10,23.4
+test,T1,15,39.2
+test,T1,20,54.3
+test,T1,30,69.7
+test,T1,45,81.8
+test,T2,5,12.8
+test,T2,10,24.9
+test,T2,15,40.8
+test,T2,20,55.6
+test,T2,30,70.5
+test,T2,45,82.4
+test,T3,5,11.9
+test,T3,10,23.8
+test,T3,15,40.0
+test,T3,20,55.0
+test,T3,30,70.0
+test,T3,45,82.0

openpkflow/datasets/example_not_similar.csv

@@ -0,0 +1,37 @@
+formulation,batch,time,percent_released
+reference,R1,5,19.0
+reference,R1,10,37.0
+reference,R1,15,54.0
+reference,R1,20,67.0
+reference,R1,30,81.0
+reference,R1,45,92.0
+reference,R2,5,21.0
+reference,R2,10,39.0
+reference,R2,15,56.0
+reference,R2,20,69.0
+reference,R2,30,83.0
+reference,R2,45,94.0
+reference,R3,5,20.0
+reference,R3,10,38.0
+reference,R3,15,55.0
+reference,R3,20,68.0
+reference,R3,30,82.0
+reference,R3,45,93.0
+test,T1,5,11.0
+test,T1,10,24.0
+test,T1,15,37.0
+test,T1,20,51.0
+test,T1,30,67.0
+test,T1,45,79.0
+test,T2,5,13.0
+test,T2,10,26.0
+test,T2,15,39.0
+test,T2,20,53.0
+test,T2,30,69.0
+test,T2,45,81.0
+test,T3,5,12.0
+test,T3,10,25.0
+test,T3,15,38.0
+test,T3,20,52.0
+test,T3,30,68.0
+test,T3,45,80.0

openpkflow/datasets/example_similar.csv

@@ -0,0 +1,37 @@
+formulation,batch,time,percent_released
+reference,R1,5,19.0
+reference,R1,10,37.0
+reference,R1,15,54.0
+reference,R1,20,67.0
+reference,R1,30,81.0
+reference,R1,45,92.0
+reference,R2,5,21.0
+reference,R2,10,39.0
+reference,R2,15,56.0
+reference,R2,20,69.0
+reference,R2,30,83.0
+reference,R2,45,94.0
+reference,R3,5,20.0
+reference,R3,10,38.0
+reference,R3,15,55.0
+reference,R3,20,68.0
+reference,R3,30,82.0
+reference,R3,45,93.0
+test,T1,5,20.0
+test,T1,10,36.0
+test,T1,15,53.0
+test,T1,20,68.0
+test,T1,30,80.0
+test,T1,45,91.0
+test,T2,5,22.0
+test,T2,10,38.0
+test,T2,15,55.0
+test,T2,20,70.0
+test,T2,30,82.0
+test,T2,45,93.0
+test,T3,5,21.0
+test,T3,10,37.0
+test,T3,15,54.0
+test,T3,20,69.0
+test,T3,30,81.0
+test,T3,45,92.0

openpkflow/dissolution/__init__.py

@@ -0,0 +1,18 @@
+from __future__ import annotations
+
+from .bootstrap import BootstrapF2Result, bootstrap_f2
+from .loader import DissolutionCSVConfig, get_formulation_means, load_dissolution_csv
+from .similarity import f1, f2
+from .study import ComparisonResult, DissolutionStudy
+
+__all__ = [
+    "f1",
+    "f2",
+    "bootstrap_f2",
+    "BootstrapF2Result",
+    "DissolutionCSVConfig",
+    "load_dissolution_csv",
+    "get_formulation_means",
+    "DissolutionStudy",
+    "ComparisonResult",
+]

openpkflow/dissolution/bootstrap.py

@@ -0,0 +1,161 @@
+"""Bootstrap f2 confidence interval for dissolution similarity.
+
+References:
+    Shah VP et al. (1998) In vitro dissolution profile comparison —
+    statistics and analysis of the similarity factor, f2.
+    Pharm Res, 15(6):889–896.
+
+    Davit BM et al. (2013) Comparing dissolution profiles —
+    recommendations for regulatory discussions.
+    AAPS J, 15(4):1150–1157.
+"""
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass
+
+import numpy as np
+
+from .similarity import f2 as _f2
+
+
+@dataclass(frozen=True)
+class BootstrapF2Result:
+    """Result of a bootstrap f2 analysis."""
+
+    f2_observed: float
+    ci_lower: float
+    ci_upper: float
+    n_replicates: int
+    confidence_level: float
+    n_timepoints: int
+    n_reference_vessels: int
+    n_test_vessels: int
+
+    @property
+    def is_similar(self) -> bool:
+        """True if lower bound of CI >= 50."""
+        return self.ci_lower >= 50.0
+
+    def summary(self) -> str:
+        """Return a human-readable summary of the bootstrap f2 result.
+
+        Returns
+        -------
+        str
+            Multi-line summary string.
+        """
+        pct = int(self.confidence_level * 100)
+        verdict = "SIMILAR" if self.is_similar else "NOT SIMILAR"
+        lines = [
+            f"Bootstrap f2 Analysis",
+            f"  Observed f2:       {self.f2_observed:.2f}",
+            f"  {pct}% CI:             [{self.ci_lower:.2f}, {self.ci_upper:.2f}]",
+            (
+                f"  Verdict:           {verdict} (CI lower bound >= 50)"
+                if self.is_similar
+                else f"  Verdict:           {verdict} (CI lower bound < 50)"
+            ),
+            f"  Replicates:        {self.n_replicates}",
+            f"  Timepoints:        {self.n_timepoints}",
+            f"  Reference vessels: {self.n_reference_vessels}",
+            f"  Test vessels:      {self.n_test_vessels}",
+            "",
+            "Note: Bootstrap f2 is suitable when <12 vessels are available.",
+            "Regulatory acceptance requires expert interpretation.",
+        ]
+        return "\n".join(lines)
+
+
+def bootstrap_f2(
+    reference: np.ndarray,
+    test: np.ndarray,
+    *,
+    n_replicates: int = 5000,
+    confidence_level: float = 0.90,
+    seed: int | None = None,
+) -> BootstrapF2Result:
+    """Compute bootstrap f2 confidence interval.
+
+    Parameters
+    ----------
+    reference : np.ndarray
+        2-D array of shape (n_vessels, n_timepoints). Each row is one vessel.
+    test : np.ndarray
+        2-D array of shape (n_vessels, n_timepoints). Each row is one vessel.
+    n_replicates : int
+        Number of bootstrap replicates. Default 5000.
+    confidence_level : float
+        CI level, e.g. 0.90 for 90% CI. Default 0.90.
+    seed : int or None
+        Random seed for reproducibility.
+
+    Returns
+    -------
+    BootstrapF2Result
+        Observed f2, CI bounds, and metadata.
+
+    Raises
+    ------
+    ValueError
+        If arrays are not 2-D, have mismatched timepoints, fewer than 3 timepoints,
+        or fewer than 2 vessels in either group.
+    """
+    reference = np.asarray(reference, dtype=float)
+    test = np.asarray(test, dtype=float)
+
+    if reference.ndim != 2:
+        raise ValueError("reference must be a 2-D array (n_vessels, n_timepoints)")
+    if test.ndim != 2:
+        raise ValueError("test must be a 2-D array (n_vessels, n_timepoints)")
+    if reference.shape[1] != test.shape[1]:
+        raise ValueError(
+            f"reference and test must have the same number of timepoints, "
+            f"got {reference.shape[1]} and {test.shape[1]}"
+        )
+
+    n_ref, n_tp = reference.shape
+    n_tst = test.shape[0]
+
+    if n_tp < 3:
+        raise ValueError("At least 3 timepoints are required for f2 calculation.")
+    if n_ref < 2:
+        raise ValueError("At least 2 reference vessels are required for bootstrap.")
+    if n_tst < 2:
+        raise ValueError("At least 2 test vessels are required for bootstrap.")
+
+    if n_ref >= 12 or n_tst >= 12:
+        warnings.warn(
+            "Bootstrap f2 is designed for small samples (<12 vessels). "
+            "With n>=12, the regulatory single-point f2 is preferred.",
+            UserWarning,
+            stacklevel=2,
+        )
+
+    # Compute observed f2 from column means
+    ref_mean = reference.mean(axis=0)
+    tst_mean = test.mean(axis=0)
+    f2_observed = _f2(ref_mean.tolist(), tst_mean.tolist())
+
+    rng = np.random.default_rng(seed)
+    f2_boots = np.empty(n_replicates)
+
+    for i in range(n_replicates):
+        ref_boot = reference[rng.integers(0, n_ref, size=n_ref)].mean(axis=0)
+        tst_boot = test[rng.integers(0, n_tst, size=n_tst)].mean(axis=0)
+        f2_boots[i] = _f2(ref_boot.tolist(), tst_boot.tolist())
+
+    alpha = 1.0 - confidence_level
+    ci_lower = float(np.percentile(f2_boots, 100 * alpha / 2))
+    ci_upper = float(np.percentile(f2_boots, 100 * (1 - alpha / 2)))
+
+    return BootstrapF2Result(
+        f2_observed=f2_observed,
+        ci_lower=ci_lower,
+        ci_upper=ci_upper,
+        n_replicates=n_replicates,
+        confidence_level=confidence_level,
+        n_timepoints=n_tp,
+        n_reference_vessels=n_ref,
+        n_test_vessels=n_tst,
+    )

openpkflow/dissolution/loader.py

@@ -0,0 +1,159 @@
+"""CSV loader for dissolution data."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pandas as pd
+from pydantic import BaseModel
+
+
+class DissolutionCSVConfig(BaseModel):
+    """Column name configuration for dissolution CSV files."""
+
+    formulation_col: str = "formulation"
+    batch_col: str = "batch"
+    time_col: str = "time"
+    percent_released_col: str = "percent_released"
+
+
+def load_dissolution_csv(
+    path: str | Path,
+    config: DissolutionCSVConfig | None = None,
+) -> pd.DataFrame:
+    """Load and validate a dissolution CSV file.
+
+    Parameters
+    ----------
+    path : str | Path
+        Path to CSV file.
+    config : DissolutionCSVConfig | None, optional
+        Column name configuration. Uses defaults if None.
+
+    Returns
+    -------
+    pd.DataFrame
+        Validated DataFrame with standardized columns: formulation (str),
+        batch (str), time (float), percent_released (float).
+
+    Raises
+    ------
+    FileNotFoundError
+        If path does not exist.
+    ValueError
+        If required columns are missing or data fails validation.
+    """
+    path = Path(path)
+    if not path.exists():
+        raise FileNotFoundError(f"Dissolution CSV not found: {path}")
+
+    cfg = config or DissolutionCSVConfig()
+
+    df = pd.read_csv(path)
+
+    required = {
+        cfg.formulation_col,
+        cfg.batch_col,
+        cfg.time_col,
+        cfg.percent_released_col,
+    }
+    missing = required - set(df.columns)
+    if missing:
+        raise ValueError(
+            f"Required columns missing from '{path.name}': {sorted(missing)}"
+        )
+
+    form_col = cfg.formulation_col
+    batch_col = cfg.batch_col
+    time_col = cfg.time_col
+    pct_col = cfg.percent_released_col
+
+    for col in [form_col, batch_col, time_col, pct_col]:
+        n_null = df[col].isna().sum()
+        if n_null > 0:
+            raise ValueError(
+                f"Column '{col}' contains {n_null} NaN value(s). "
+                "All required columns must be complete."
+            )
+
+    df[time_col] = pd.to_numeric(df[time_col], errors="coerce")
+    if df[time_col].isna().any():
+        raise ValueError(
+            f"Column '{time_col}' contains non-numeric values. "
+            "Time must be numeric."
+        )
+    if (df[time_col] < 0).any():
+        raise ValueError(
+            f"Column '{time_col}' contains negative values. "
+            "Time must be non-negative."
+        )
+
+    df[pct_col] = pd.to_numeric(df[pct_col], errors="coerce")
+    if df[pct_col].isna().any():
+        raise ValueError(
+            f"Column '{pct_col}' contains non-numeric values. "
+            "Percent released must be numeric."
+        )
+    out_of_range = df[(df[pct_col] < 0) | (df[pct_col] > 100)]
+    if not out_of_range.empty:
+        bad_vals = out_of_range[pct_col].tolist()
+        raise ValueError(
+            f"Column '{pct_col}' contains values outside [0, 100]: {bad_vals}"
+        )
+
+    formulations = df[form_col].unique()
+    empty_formulations = [
+        str(f) for f in formulations if df[df[form_col] == f].shape[0] == 0
+    ]
+    if empty_formulations:
+        raise ValueError(
+            f"The following formulations have no rows: {empty_formulations}"
+        )
+
+    result = pd.DataFrame(
+        {
+            "formulation": df[form_col].astype(str),
+            "batch": df[batch_col].astype(str),
+            "time": df[time_col].astype(float),
+            "percent_released": df[pct_col].astype(float),
+        }
+    )
+    return result
+
+
+def get_formulation_means(
+    df: pd.DataFrame,
+    formulation: str,
+    time_col: str = "time",
+    pct_col: str = "percent_released",
+    formulation_col: str = "formulation",
+) -> tuple[list[float], list[float]]:
+    """Return mean dissolution profile for a given formulation, averaged across batches.
+
+    Parameters
+    ----------
+    df : pd.DataFrame
+        Dissolution DataFrame (as returned by load_dissolution_csv).
+    formulation : str
+        Formulation label to filter on.
+    time_col : str, optional
+        Name of the time column. Defaults to "time".
+    pct_col : str, optional
+        Name of the percent released column. Defaults to "percent_released".
+    formulation_col : str, optional
+        Name of the formulation column. Defaults to "formulation".
+
+    Returns
+    -------
+    tuple[list[float], list[float]]
+        A tuple of (time_points, mean_percent_released), each sorted by time.
+    """
+    subset = df[df[formulation_col] == formulation]
+    means = (
+        subset.groupby(time_col, sort=True)[pct_col]
+        .mean()
+        .reset_index()
+    )
+    time_points = means[time_col].tolist()
+    mean_pct = means[pct_col].tolist()
+    return time_points, mean_pct

openpkflow/dissolution/plotting.py

@@ -0,0 +1,68 @@
+"""Dissolution profile plot — reference vs test mean with error bars."""
+from __future__ import annotations
+
+import base64
+import io
+
+import numpy as np
+
+
+def dissolution_profile_plot_b64(
+    time_points: list[float],
+    reference_mean: list[float],
+    test_mean: list[float],
+    reference_label: str = "Reference",
+    test_label: str = "Test",
+) -> str:
+    """Return a base64-encoded PNG of the dissolution profile comparison.
+
+    Embeds cleanly as <img src="data:image/png;base64,..."> in HTML reports.
+    Uses matplotlib with a non-interactive backend (Agg) — safe in headless environments.
+
+    Parameters
+    ----------
+    time_points :
+        Shared time points used in the comparison.
+    reference_mean :
+        Mean percent dissolved for the reference formulation at each time point.
+    test_mean :
+        Mean percent dissolved for the test formulation at each time point.
+    reference_label :
+        Legend label for the reference profile.
+    test_label :
+        Legend label for the test profile.
+
+    Returns
+    -------
+    str
+        ASCII base64-encoded PNG image string.
+    """
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=(7, 4), dpi=110)
+
+    tp = np.array(time_points)
+    ref = np.array(reference_mean)
+    tst = np.array(test_mean)
+
+    ax.plot(tp, ref, "o-", color="#003366", linewidth=2, markersize=6,
+            label=reference_label)
+    ax.plot(tp, tst, "s--", color="#cc3300", linewidth=2, markersize=6,
+            label=test_label)
+
+    ax.set_xlabel("Time (min)", fontsize=11)
+    ax.set_ylabel("Mean % Dissolved", fontsize=11)
+    ax.set_title("Dissolution Profile Comparison", fontsize=12, fontweight="bold")
+    ax.set_ylim(0, 105)
+    ax.axhline(85, color="#888888", linestyle=":", linewidth=1, label="85% threshold")
+    ax.legend(fontsize=10)
+    ax.grid(True, alpha=0.3)
+    fig.tight_layout()
+
+    buf = io.BytesIO()
+    fig.savefig(buf, format="png", bbox_inches="tight")
+    plt.close(fig)
+    buf.seek(0)
+    return base64.b64encode(buf.read()).decode("ascii")