certaraiq 2.2.3__py3-none-any.whl

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/_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/_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/_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

certaraiq/_helper/create_map.py

@@ -0,0 +1,180 @@
+import tabeline as tl
+
+from .._labelset import LabelSet
+from .nested_map import NestedMap
+from .parameter import Parameter
+
+
+def create_parameters_map(df: tl.DataFrame, parameter_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+
+    param_map = NestedMap()
+
+    for i, lb in enumerate(labels):
+        param_map.set_value(
+            # if the label does not exist it is wildcard.
+            # Add the parameter column to the list of columns to be used as keys for the last layer and
+            # it is guaranteed that it is not wildcard
+            [lb.labels.get(k, "*") for k in [*parameter_label_columns, "parameter"]],
+            {df[i, "parameter"]: Parameter(value=df[i, "value"], unit=df[i, "unit"])},
+        )
+
+    return param_map
+
+
+def create_fitting_parameters_map(df: tl.DataFrame, parameter_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+
+    param_map = NestedMap()
+
+    for i, lb in enumerate(labels):
+        parameter_i = {
+            "parameter": df[i, "parameter"],
+            "value": df[i, "value"],
+            "unit": df[i, "unit"],
+            "is_fit": df[i, "is_fit"],
+            "lower_bound": df[i, "lower_bound"],
+            "upper_bound": df[i, "upper_bound"],
+            "global_parameter_name": df[i, "global_parameter_name"],
+        }
+
+        if "prior_distribution" in df.column_names:
+            parameter_i["prior_distribution"] = df[i, "prior_distribution"]
+        if "location" in df.column_names:
+            parameter_i["location"] = df[i, "location"]
+        if "scale" in df.column_names:
+            parameter_i["scale"] = df[i, "scale"]
+
+        param_map.set_value(
+            # if the label does not exist it is wildcard.
+            # Add the parameter column to the list of columns to be used as keys for the last layer and
+            # it is guaranteed that it is not wildcard
+            [lb.labels.get(k, "*") for k in [*parameter_label_columns, "parameter"]],
+            {df[i, "parameter"]: parameter_i},
+        )
+
+    return param_map
+
+
+def create_doses_map(df: tl.DataFrame, dose_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+    dose_map = NestedMap()
+    has_amounts = "amounts" in df.column_names
+    has_durations = "durations" in df.column_names
+
+    for i, lb in enumerate(labels):
+        schedule_i = {
+            "route": df[i, "route"],
+            "times": df[i, "times"],
+            "time_unit": df[i, "time_unit"],
+        }
+        if has_amounts:
+            schedule_i.update({"amounts": df[i, "amounts"], "amount_unit": df[i, "amount_unit"]})
+        if has_durations:
+            schedule_i.update({"durations": df[i, "durations"], "duration_unit": df[i, "duration_unit"]})
+        # if the label does not exist it is wildcard.
+        # Add the route column to the list of columns to be used as keys for the last layer and
+        # it is guaranteed that it is not wildcard
+        dose_map.set_value(
+            [lb.labels.get(k, "*") for k in [*dose_label_columns, "route"]], {df[i, "route"]: schedule_i}
+        )
+
+    return dose_map
+
+
+def create_models_map(df: tl.DataFrame, model_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+    model_map = NestedMap()
+
+    for i, lb in enumerate(labels):
+        # if the label does not exist it is wildcard.
+        # Add the route column to the list of columns to be used as keys for the last layer and
+        # it is guaranteed that it is not wildcard
+        model_map.set_value(
+            [lb.labels.get(k, "*") for k in [*model_label_columns, "model"]],
+            {df[i, "model"]: {"model": df[i, "model"]}},
+        )
+
+    return model_map
+
+
+def create_times_map(df: tl.DataFrame, time_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+    time_map = NestedMap()
+
+    for i, lb in enumerate(labels):
+        # if the label does not exist it is wildcard.
+        # Add the index to the list of columns to be used as keys for the last layer
+        # for times duplication is fine
+        time_map.set_value(
+            [lb.labels.get(k, "*") for k in time_label_columns] + [f"{i}"],
+            {"times": df[i, "times"], "times_unit": df[i, "times_unit"]},
+        )
+
+    return time_map
+
+
+def create_measurements_map(df: tl.DataFrame, measurement_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+    measurement_map = NestedMap()
+
+    has_exponential_error = "exponential_error" in df.column_names
+    has_constant_error = "constant_error" in df.column_names
+    has_proportional_error = "proportional_error" in df.column_names
+
+    for i, lb in enumerate(labels):
+        measurement_i = {
+            "time": df[i, "time"],
+            "time_unit": df[i, "time_unit"],
+            "output": df[i, "output"],
+            "measurement": df[i, "measurement"],
+            "measurement_unit": df[i, "measurement_unit"],
+        }
+        if has_exponential_error:
+            measurement_i.update({"exponential_error": df[i, "exponential_error"]})
+        if has_constant_error:
+            measurement_i.update({"constant_error": df[i, "constant_error"]})
+        if has_proportional_error:
+            measurement_i.update({"proportional_error": df[i, "proportional_error"]})
+
+        # if the label does not exist it is wildcard.
+        # Add the index to the list of columns to be used as keys for the last layer
+        # for measurements duplication is fine
+        measurement_map.set_value([lb.labels.get(k, "*") for k in measurement_label_columns] + [f"{i}"], measurement_i)
+
+    return measurement_map
+
+
+def create_distributions_map(df: tl.DataFrame, distribution_label_columns: list[str]) -> NestedMap:
+    labels = LabelSet.from_df(df)  # This is necessary because labels need to be standardized
+    distribution_map = NestedMap()
+
+    has_histogram_cols = "bin_edges" in df.column_names
+    has_mvn_cols = "covariance" in df.column_names
+
+    for i, lb in enumerate(labels):
+        distribution_i = {
+            "time": df[i, "time"],
+            "time_unit": df[i, "time_unit"],
+            "target": df[i, "target"],
+            "distribution": df[i, "distribution"],
+            "distribution_unit": df[i, "distribution_unit"],
+        }
+        if has_histogram_cols:
+            distribution_i.update({"bin_edges": df[i, "bin_edges"]})
+            distribution_i.update({"bin_probabilities": df[i, "bin_probabilities"]})
+            distribution_i.update({"smoothness": df[i, "smoothness"]})
+
+        if has_mvn_cols:
+            distribution_i.update({"measurements": df[i, "measurements"]})
+            distribution_i.update({"measurements_unit": df[i, "measurements_unit"]})
+            distribution_i.update({"variance": df[i, "covariance"]})  # TODO: yes, this is stupid
+
+        # if the label does not exist it is wildcard.
+        # Add the index to the list of columns to be used as keys for the last layer
+        # for measurements duplication is fine
+        distribution_map.set_value(
+            [lb.labels.get(k, "*") for k in distribution_label_columns] + [f"{i}"], distribution_i
+        )
+
+    return distribution_map

certaraiq/_helper/display.py

@@ -0,0 +1,24 @@
+__all__ = ["Display"]
+
+from dataclasses import dataclass
+from uuid import uuid4
+
+from IPython import get_ipython
+from IPython.display import DisplayObject, display, update_display
+
+
+@dataclass(kw_only=True, slots=True)
+class Display:
+    display_id: str | None = None
+
+    def display(self, display_object: DisplayObject) -> None:
+        if get_ipython() is None:
+            message = display_object.data
+        else:
+            message = display_object
+
+        if self.display_id is None:
+            self.display_id = str(uuid4())
+            display(message, display_id=self.display_id)
+        else:
+            update_display(message, display_id=self.display_id)

certaraiq/_helper/get_dose_schedules.py

@@ -0,0 +1,32 @@
+from pathlib import Path
+
+import pandas as pd
+import tabeline as tl
+
+from certaraiq._sdk.data_frame import DataFrame
+from certaraiq._sdk.reaction_model import Schedule
+
+from .helper import find_duplicate_keys
+from .parse_schedule import parse_schedule
+
+DataFrameLike = pd.DataFrame | tl.DataFrame | DataFrame
+PathLike = str | Path
+
+
+def get_dose_schedules(
+    doses: list[dict[str, dict[str, int | float | str]]], labels: dict[str, str | float | int | bool]
+) -> dict[str, Schedule]:
+    duplicate_routes = find_duplicate_keys(doses)
+    if len(duplicate_routes) > 0:
+        if len(labels) > 0:
+            raise ValueError(
+                "Duplicate routes found for label(s)"
+                f" {', '.join([f'{key}={value}' for key, value in labels.items()])}:"
+                f" {', '.join(duplicate_routes)}"
+            )
+        else:
+            raise ValueError(f"Duplicate routes found: {', '.join(duplicate_routes)}")
+
+    route_schedules_i = {r: parse_schedule(d) for dose in doses for r, d in dose.items()}
+
+    return route_schedules_i