certaraiq 2.2.3__tar.gz

certaraiq-2.2.3/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.3
+Name: certaraiq
+Version: 2.2.3
+Summary: A Python client for the Certara IQ platform
+Author: Certara IQ Support
+Author-email: Certara IQ Support <iq-support@certara.com>
+License: Proprietary
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Classifier: Operating System :: POSIX
+Requires-Dist: httpx>=0.28
+Requires-Dist: ipython>=9.10
+Requires-Dist: numpy>=2.4,<3
+Requires-Dist: ordered-set>=4.1,<5
+Requires-Dist: pandas>=2.3,<3
+Requires-Dist: parsita>=2.2,<2.3
+Requires-Dist: pint>=0.25,<0.26
+Requires-Dist: prettytable>=3.17,<4
+Requires-Dist: scipy>=1.17,<2
+Requires-Dist: serialite>=0.5,<0.6
+Requires-Dist: tabeline[pandas,polars]>=0.6,<0.7
+Requires-Python: >=3.12
+Project-URL: Repository, https://github.com/certara/certara-iq-v2
+Description-Content-Type: text/markdown
+
+# Certara IQ Python client
+
+This is a Python client for the Certara IQ platform. It is useless alone and must be
+installed in an environment with a valid access token to a deployed Certara IQ server.
+
+## Configuration
+
+The client searches the following paths for a configuration file:
+
+```
+${XDG_CONFIG_HOME:-~/.config}/certaraiq/client.toml
+
+/etc/certaraiq/client.toml
+```
+
+Example configuration file:
+
+```toml
+api_origin = 'https://dev01.dev-abm.com'
+auth_token_path = '/home/jovyan/.jupyterhub/services-blue/auth_token'
+```
+
+- `api_origin`: The protocol and host for the Certara IQ server API. All requests will be made against this API. By
+  default, the client will request against `http://localhost:5100`
+- `auth_token_path`: Path to a file containing a bearer token that will be used to authenticate
+  requests. By default, the client will attempt requests with no authentication.
+
+The search stops at the first configuration file found. If no configuration file is found, the defaults for
+all values are used.

certaraiq-2.2.3/README.md

@@ -0,0 +1,29 @@
+# Certara IQ Python client
+
+This is a Python client for the Certara IQ platform. It is useless alone and must be
+installed in an environment with a valid access token to a deployed Certara IQ server.
+
+## Configuration
+
+The client searches the following paths for a configuration file:
+
+```
+${XDG_CONFIG_HOME:-~/.config}/certaraiq/client.toml
+
+/etc/certaraiq/client.toml
+```
+
+Example configuration file:
+
+```toml
+api_origin = 'https://dev01.dev-abm.com'
+auth_token_path = '/home/jovyan/.jupyterhub/services-blue/auth_token'
+```
+
+- `api_origin`: The protocol and host for the Certara IQ server API. All requests will be made against this API. By
+  default, the client will request against `http://localhost:5100`
+- `auth_token_path`: Path to a file containing a bearer token that will be used to authenticate
+  requests. By default, the client will attempt requests with no authentication.
+
+The search stops at the first configuration file found. If no configuration file is found, the defaults for
+all values are used.

certaraiq-2.2.3/pyproject.toml

@@ -0,0 +1,116 @@
+[project]
+name = "certaraiq"
+version = "2.2.3"
+description = "A Python client for the Certara IQ platform"
+authors = [{ name = "Certara IQ Support", email = "iq-support@certara.com" }]
+license = { text = "Proprietary" }
+readme = "README.md"
+requires-python = ">=3.12"
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Operating System :: POSIX",
+]
+dependencies = [
+    "httpx >=0.28",
+    "ipython >=9.10",
+    "numpy >=2.4,<3",
+    "ordered-set >=4.1,<5",
+    "pandas >=2.3,<3",
+    "parsita >=2.2,<2.3",
+    "pint >=0.25,<0.26",
+    "prettytable >=3.17,<4",
+    "scipy >=1.17,<2",
+    "serialite >=0.5,<0.6",
+    "tabeline[pandas,polars] >=0.6,<0.7",
+]
+
+[project.urls]
+Repository = "https://github.com/certara/certara-iq-v2"
+
+[dependency-groups]
+dev = [
+    "nox >=2026.2.9",
+    "nox-uv >=0.7.1",
+
+    # Test
+    "coverage[toml] >=7.13",
+    "filelock >= 3.25",
+    "pytest >=9.0",
+    "pytest-cov >=7.0",
+    "pytest-xdist >=3.8",
+
+    # Docs
+    "mkdocs >=1.6",
+    "mkdocs-material >=9.7",
+    "mkdocstrings[python] >=1.0",
+    "pygments >=2.19",
+    "pytkdocs[numpy-style] >=0.16",
+
+    # Linting and formatting
+    "ruff >=0.15",
+]
+
+[build-system]
+requires = ["uv-build"]
+build-backend = "uv_build"
+
+[tool.uv]
+python-preference = "only-managed"
+
+[tool.coverage.run]
+branch = true
+
+[tool.coverage.report]
+exclude_lines = [
+    "pragma: no cover",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "if TYPE_CHECKING:",
+]
+
+[tool.coverage.paths]
+source = [
+    "src/",
+    ".nox/test*/lib/python*/site-packages/",
+    ".nox/test*/Lib/site-packages/",
+]
+
+[tool.ruff]
+src = ["src"]
+line-length = 120
+target-version = "py312"
+
+[tool.ruff.lint]
+extend-select = [
+    "I", # isort
+    "N", # pep8-naming
+    "RUF", # ruff
+    "B", # flake8-bugbear
+    "C4", # flake8-comprehensions
+    "PIE", # flake8-pie
+    "PT", # flake8-pytest-style
+    "PTH", # flake8-use-pathlib
+    "ERA", # flake8-eradicate
+]
+
+# B006, B008 and RUF009: disable function calls and mutable data structures in defaults
+# N802, N803, N806: Uppercase variables are fine in science
+# RUF003: Backticks are fine in docstrings
+# ERA001: Too many false positives about commented-out code
+extend-ignore = [
+    "B006",
+    "B008",
+    "RUF009",
+    "N802",
+    "N803",
+    "N806",
+    "RUF003",
+    "ERA001",
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Allow unused imports and star imports in __init__.py files
+"__init__.py" = ["F401", "F403"]
+"./src/certaraiq/_units/*.py" = ["F403", "F405"]

certaraiq-2.2.3/src/certaraiq/__init__.py

@@ -0,0 +1,8 @@
+from ._exports import *
+from ._helper.helper import linspace, logspace
+from ._helper.initialize_parameter_table import initialize_parameter_table
+from ._optimize import optimize
+from ._scan import fold_scan, value_scan
+from ._sdk.data_pipe_builder import concatenate_columns, concatenate_rows
+from ._simulate import simulate
+from ._vpop import virtual_population

certaraiq-2.2.3/src/certaraiq/_exports.py

@@ -0,0 +1,8 @@
+__all__ = ["client_version", "list_contracts", "server_version"]
+
+
+from ._sdk import client
+
+client_version = client.client_version
+list_contracts = client.list_contracts
+server_version = client.server_version

certaraiq-2.2.3/src/certaraiq/_helper/argument_parser.py

@@ -0,0 +1,157 @@
+from dataclasses import dataclass
+from inspect import Parameter
+from typing import Any, Generic
+
+from parsita import Parser, lit, reg
+from parsita.state import Continue, Output, Reader, State
+
+
+@dataclass(frozen=True, slots=True)
+class ArgumentParserParameter(Generic[Output]):
+    name: str
+    parser: Parser[str, Output]
+    default: Output = Parameter.empty
+
+    def __repr__(self):
+        if self.default == Parameter.empty:
+            return f"{self.__class__.__name__}({self.name}, {self.parser.name_or_repr()})"
+        else:
+            return f"{self.__class__.__name__}({self.name}, {self.parser.name_or_repr()}, {self.default})"
+
+
+class ArgumentParser(Parser[str, dict[str, Any]]):
+    def __init__(
+        self,
+        positional_only: list[ArgumentParserParameter] = [],
+        keyword_only: list[ArgumentParserParameter] = [],
+        *,
+        keyword: Parser = reg(r"[A-Za-z_][A-Za-z_0-9]*"),
+        separator: Parser = lit(","),
+        equals: Parser = lit("="),
+    ):
+        super().__init__()
+        self.positional_only = positional_only
+        self.keyword_only = keyword_only
+        self.separator = separator
+        self.equals = equals
+        self.keyword = keyword
+        self.keyword_only_by_name = {parameter.name: parameter for parameter in keyword_only}
+
+    def _consume(self, state: State, reader: Reader[str]):
+        output_positional = {}
+        output_keyword = {}
+        remainder = reader
+
+        #  no argument
+        if len(self.keyword_only) == 0 and len(self.positional_only) == 0:
+            return Continue(remainder, {})
+
+        # positional arguments
+        for param in self.positional_only:
+            status = param.parser.consume(state, remainder)
+            if isinstance(status, Continue):
+                remainder = status.remainder
+            else:
+                break
+
+            output_positional[param.name] = status.value
+
+            status = self.separator.consume(state, remainder)
+            if isinstance(status, Continue):
+                remainder = status.remainder
+            else:
+                break
+
+        # keyword arguments
+        if len(self.keyword_only) > 0:
+            while True:
+                # if keywords are following by positional, the comma after positional is not optional anymore
+                if len(self.positional_only) > 0 and status is None:
+                    break
+                status = self.keyword.consume(state, remainder)
+                if isinstance(status, Continue):
+                    keyword_name = status.value
+                    if keyword_name not in self.keyword_only_by_name.keys():
+                        break
+                    remainder = status.remainder
+                else:
+                    break
+
+                status = self.equals.consume(state, remainder)
+                if isinstance(status, Continue):
+                    remainder = status.remainder
+                else:
+                    break
+
+                status = self.keyword_only_by_name[keyword_name].parser.consume(state, remainder)
+                if isinstance(status, Continue):
+                    remainder = status.remainder
+                else:
+                    break
+
+                output_keyword[keyword_name] = status.value
+
+                status = self.separator.consume(state, remainder)
+                if isinstance(status, Continue):
+                    remainder = status.remainder
+                else:
+                    break
+
+        must_positional_argument = {
+            parameter.name for parameter in self.positional_only if parameter.default is Parameter.empty
+        }
+        provided_positional_argument = set(output_positional.keys())
+
+        must_keyword_arguments = {
+            parameter.name for parameter in self.keyword_only if parameter.default is Parameter.empty
+        }
+        provided_keyword_arguments = set(output_keyword.keys())
+
+        if not must_positional_argument.issubset(provided_positional_argument):
+            state.register_failure(
+                f"{must_positional_argument} positional arguments but {provided_positional_argument} are provided",
+                reader,
+            )
+            return None
+
+        if not must_keyword_arguments.issubset(provided_keyword_arguments):
+            state.register_failure(
+                f"{must_keyword_arguments} keyword arguments but {provided_keyword_arguments} are provided", reader
+            )
+            return None
+
+        for i, param in enumerate(self.positional_only):
+            if param.name not in provided_positional_argument:
+                output_positional[param] = self.positional_only[i].default
+
+        for key in self.keyword_only_by_name.keys():
+            if key not in provided_keyword_arguments:
+                output_keyword[key] = self.keyword_only_by_name[key].default
+
+        output = output_positional | output_keyword
+
+        return Continue(remainder, output)
+
+    def __repr__(self):
+        keyword_list = [param.__repr__() for param in self.keyword_only]
+        positional_list = [param.__repr__() for param in self.positional_only]
+        keyword_arg_strings = f"keyword_only=[{', '.join(keyword_list)}]" if len(keyword_list) > 0 else ""
+        positional_arg_strings = f"positional_only=[{', '.join(positional_list)}]" if len(positional_list) > 0 else ""
+        return self.name_or_nothing() + f"arguments({','.join([keyword_arg_strings, positional_arg_strings])})"
+
+
+def arguments(
+    positional_only: list[ArgumentParserParameter] = [],
+    keyword_only: list[ArgumentParserParameter] = [],
+    *,
+    keyword: Parser = reg(r"[A-Za-z_][A-Za-z_0-9]*"),
+    separator: Parser = lit(","),
+    equals: Parser = lit("="),
+):
+    return ArgumentParser(
+        positional_only,
+        keyword_only,
+        keyword=keyword,
+        separator=separator,
+        equals=equals,
+    )

certaraiq-2.2.3/src/certaraiq/_helper/covariance_matrix.py

@@ -0,0 +1,174 @@
+__all__ = ["AnnotatedFisherRow", "confidence_intervals"]
+
+from dataclasses import dataclass
+
+import numpy as np
+
+from .._sdk.data_frame import DataFrame
+from .._sdk.ode_optimization_result import UnittedValue
+from .._sdk.scenario import Prior
+from .helper import scale_parameter, unscale_parameter
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AnnotatedFisherRow:
+    """A row of the Fisher information matrix along with the corresponding parameter value and prior."""
+
+    parameter_value: float
+    parameter_prior: Prior
+    values: dict[str, UnittedValue]
+
+
+def _theta(annotated_matrix: dict[str, AnnotatedFisherRow]) -> np.ndarray:
+    return np.asarray([row.parameter_value for row in annotated_matrix.values()])
+
+
+def _theta_is_logscale(annotated_matrix: dict[str, AnnotatedFisherRow]) -> list[bool]:
+    return [row.parameter_prior.is_logscaled for row in annotated_matrix.values()]
+
+
+def _information_unit(annotated_matrix: dict[str, AnnotatedFisherRow]):
+    return np.asarray([[val.unit for val in row.values.values()] for row in annotated_matrix.values()])
+
+
+def _information_matrix(annotated_matrix: dict[str, AnnotatedFisherRow]) -> list[list[float]]:
+    return [[val.value for val in row.values.values()] for row in annotated_matrix.values()]
+
+
+def covariance_matrix(
+    annotated_fisher_information: dict[str, AnnotatedFisherRow],
+    uncertainty_ceiling: float = float("inf"),
+) -> list[list[float]]:
+    """Transform information matrix into covariance intervals.
+
+    Parameters
+    ----------
+    fisher_information: dict[str, AnnotatedFisherRow]
+    uncertainty_ceiling : float, default = inf
+        If some parameters are numerically non-identifiable, the information
+        on those parameters is very low and the uncertainties very high. In
+        this situation, inverting the information matrix is numerically
+        unstable, which can result in a bunch of junk for the covariance
+        matrix. A value like 1e8 is a good
+        number to try if the scenario appears to be non-identifiable.
+
+    Returns
+    -------
+    List[List[float]]
+    """
+
+    eigenvalue_threshold = 1.0 / uncertainty_ceiling**2
+
+    information_matrix_values = np.asarray(_information_matrix(annotated_fisher_information))
+    theta = _theta(annotated_fisher_information)
+    theta_is_logscale = _theta_is_logscale(annotated_fisher_information)
+    theta_array = np.where(theta_is_logscale, theta, 1.0)
+
+    information_matrix = np.einsum("i,ij,j->ij", theta_array, information_matrix_values, theta_array)
+
+    modified_covariance = fisher_information_inverse(information_matrix, eigenvalue_threshold)
+
+    return modified_covariance
+
+
+def confidence_intervals(
+    annotated_fisher_information: dict[str, AnnotatedFisherRow],
+    fraction: float,
+    uncertainty_ceiling: float = float("inf"),
+) -> DataFrame:
+    """Transform information matrix into confidence intervals.
+
+    Parameters
+    ----------
+    annotated_fisher_information: dict[str, AnnotatedFisherRow]
+    fraction : float
+        The fraction of the distribution to contain within the CI. Use 0.95
+        for 95% confidence intervals.
+    uncertainty_ceiling : float, default = inf
+        If some parameters are numerically non-identifiable, the information
+        on those parameters is very low and the uncertainties very high. In
+        this situation, inverting the information matrix is numerically
+        unstable, which can result in a bunch of junk for the confidence
+        intervals. Choosing a ceiling will prevent uncertainties from going
+        larger than that, which can prevent large uncertainties from
+        polluting the rest of the uncertainties. A value like 1e8 is a good
+        number to try if the scenario appears to be non-identifiable.
+
+    Returns
+    -------
+    DataFrame with columns:
+        parameter: str
+        value: float
+        unit: str
+        scale: "linear" | "log"
+        lower: float
+        upper: float
+    """
+
+    from scipy import stats
+
+    if uncertainty_ceiling <= 0.0:
+        raise ValueError("Argument 'uncertainty_ceiling' must be positive.")
+
+    modified_covariance = covariance_matrix(annotated_fisher_information, uncertainty_ceiling)
+
+    sigma = np.sqrt(np.diag(modified_covariance))
+    lower = []
+    upper = []
+    theta = _theta(annotated_fisher_information)
+    theta_is_logscale = _theta_is_logscale(annotated_fisher_information)
+
+    for t, maybe_scaled_sigma, is_log in zip(theta, sigma, theta_is_logscale, strict=True):
+        scaled_mean = scale_parameter(is_log, t)
+        scaled_lower, scaled_upper = stats.norm.interval(fraction, scaled_mean, maybe_scaled_sigma)
+        lower.append(unscale_parameter(is_log, scaled_lower))
+        upper.append(unscale_parameter(is_log, scaled_upper))
+
+    # These units are ugly and also different (in terms of formatting) from what _optimize returns. This
+    # should be fixed in the future when Renan's work for diagnostics is in.
+    parameter_units = [f"(1/({unit}))^0.5" for unit in np.diag(_information_unit(annotated_fisher_information))]
+
+    return DataFrame(
+        parameter=list(annotated_fisher_information.keys()),
+        value=theta.tolist(),
+        unit=parameter_units,
+        scale=["log" if is_log else "linear" for is_log in theta_is_logscale],
+        lower=lower,
+        upper=upper,
+    )
+
+
+def fisher_information_inverse(F: np.ndarray, eigenvalue_threshold: float = 0.0) -> np.ndarray:
+    # for stable inversion of Fisher information matrix; used in confidence_intervals() below
+
+    # locate inf/-inf on diag
+    finite_indices = ~np.isinf(np.diag(F))
+
+    # cut out zero/inf indices before inversion
+    F_finite = F[np.ix_(finite_indices, finite_indices)]
+    L, Q = np.linalg.eigh(F_finite)
+
+    # floor small eigenvalues at threshold
+    L[L < eigenvalue_threshold] = eigenvalue_threshold
+
+    # identify indices of exactly zero eigenvalues
+    zero_eigs = L == 0.0
+
+    # invert floored eigenvalues, compose modified inverse
+    Finv_finite = Q[:, ~zero_eigs] @ np.diag(1.0 / L[~zero_eigs]) @ Q[:, ~zero_eigs].T
+
+    # For exactly zero eigenvalues after flooring, examine entries of corresponding eigenvectors.  Nonzero (> Qthresh)
+    # eigenvector entries correspond to columns of F_finite which are nontrivial contributions to this kernel.  Such
+    # columns/rows of Finv are set to zero with inf on diagonal.
+    Qthresh = F_finite.shape[0] * np.finfo("float").eps
+    kernel_cols = np.any(np.abs(Q[:, zero_eigs]) > Qthresh, axis=1)
+    Finv_finite[kernel_cols, :] = 0.0
+    Finv_finite[:, kernel_cols] = 0.0
+    Finv_finite[kernel_cols, kernel_cols] = np.inf
+
+    # Initialize full output, fill in modified inverse
+    # (Note inf on diag(A) -> 0 on corresponding row/col of inverse).
+    Finv_out = np.zeros(F.shape)
+    Finv_out[np.ix_(finite_indices, finite_indices)] = Finv_finite
+
+    return Finv_out