voiage.schema module

Core data structures for voiage.

These structures are designed to hold and manage data used in Value of Information analyses. They leverage Python’s dataclasses for type hinting and validation where appropriate, and are intended to work seamlessly with NumPy and Pandas/xarray.

class voiage.schema.ValueArray(dataset: Dataset)[source]

Bases: object

Container for probabilistic sensitivity analysis net-benefit samples.

dataset

Dataset with n_samples and n_strategies dimensions and a net_benefit data variable.

Type:: xarray.Dataset

Examples

>>> import numpy as np
>>> from voiage.schema import ValueArray
>>> values = np.array([[10.0, 12.0], [11.0, 9.5]])
>>> va = ValueArray.from_numpy(values, ["A", "B"])
>>> va.n_samples, va.n_strategies
(2, 2)

dataset: Dataset

__post_init__() → None[source]: Validate the dataset.

property values: DataArray: Return the net benefit values as an xarray DataArray.

property numpy_values: ndarray: Return the net benefit values as a NumPy array.

property jax_values: Array | None: Return the net benefit values as a JAX array.

property n_samples: int: Return the number of samples.

property n_strategies: int: Return the number of strategies.

property strategy_names: list[str]: Return the names of the strategies.

copy() → ValueArray[source]: Return a deep copy of the ValueArray.

get_strategy_index(strategy_name: str) → int[source]: Return the integer index for a strategy name.

slice_by_strategies(strategy_names: Sequence[str]) → ValueArray[source]: Return a new ValueArray containing only the requested strategies.

__eq__(other: object) → bool[source]: Compare ValueArray instances by dataset contents and coordinates.

classmethod from_numpy(values: ndarray | Array, strategy_names: list[str] | None = None) → ValueArray[source]

Create a ValueArray from a numpy or JAX array.

Parameters:

values – A 2D array of shape (n_samples, n_strategies). Supports both NumPy and JAX arrays.
strategy_names – Optional list of strategy names

Returns:

ValueArray

Return type:

A new ValueArray instance

classmethod from_numpy_perspectives(values: ndarray | Array, strategy_names: list[str] | None = None, perspective_names: list[str] | None = None) → ValueArray[source]

Create a multi-perspective ValueArray from a 3D array.

Parameters:

values (numpy.ndarray or jax.numpy.ndarray) – Net-benefit values with shape (n_samples, n_strategies, n_perspectives).
strategy_names (list[str], optional) – Strategy labels aligned to the second dimension.
perspective_names (list[str], optional) – Perspective labels aligned to the third dimension.

Returns:

ValueArray with a perspective dimension.

Return type:

ValueArray

property perspective_names: list[str] | None: Return perspective labels when present.

classmethod from_jax(values: Array, strategy_names: list[str] | None = None) → ValueArray[source]

Create a ValueArray from a JAX array.

Parameters:

values – A 2D JAX array of shape (n_samples, n_strategies)
strategy_names – Optional list of strategy names

Returns:

ValueArray

Return type:

A new ValueArray instance

class voiage.schema.ParameterSet(dataset: Dataset)[source]

Bases: object

Container for parameter samples from a probabilistic sensitivity analysis.

dataset

Dataset with n_samples as the sample dimension and one data variable per parameter.

Type:: xarray.Dataset

Examples

>>> import numpy as np
>>> from voiage.schema import ParameterSet
>>> params = ParameterSet.from_numpy_or_dict({"cost": np.array([1.0, 2.0])})
>>> params.parameter_names
['cost']

dataset: Dataset

__post_init__() → None[source]: Validate the dataset.

property parameters: dict[str, ndarray]: Return the parameter samples.

property jax_parameters: dict[str, Array] | None: Return the parameter samples as JAX arrays.

property n_samples: int: Return the number of samples.

property parameter_names: list[str]: Return the names of the parameters.

copy() → ParameterSet[source]: Return a deep copy of the ParameterSet.

subset_by_parameters(parameter_names: Sequence[str]) → ParameterSet[source]: Return a new ParameterSet containing only the requested parameters.

__eq__(other: object) → bool[source]: Compare ParameterSet instances by dataset contents and coordinates.

classmethod from_numpy_or_dict(parameters: ndarray | dict[str, ndarray] | Array | dict[str, Array]) → ParameterSet[source]

Create a ParameterSet from a numpy/JAX array or dictionary.

Parameters:: parameters – Either a 2D array of shape (n_samples, n_parameters) or a dictionary mapping parameter names to 1D arrays. Supports both NumPy and JAX arrays.
Returns:: ParameterSet
Return type:: A new ParameterSet instance

classmethod from_jax(parameters: Array | dict[str, Array]) → ParameterSet[source]

Create a ParameterSet from a JAX array or dictionary.

Parameters:: parameters – Either a 2D JAX array of shape (n_samples, n_parameters) or a dictionary mapping parameter names to 1D JAX arrays
Returns:: ParameterSet
Return type:: A new ParameterSet instance

class voiage.schema.DecisionOption(name: str, sample_size: int)[source]

Bases: object

Represents a single arm in a clinical trial design.

name

The name of the trial arm (e.g., “Treatment A”, “Placebo”).

Type:: str

sample_size

The number of subjects to be allocated to this arm.

Type:: int

Examples

>>> from voiage.schema import DecisionOption
>>> arm = DecisionOption(name="Standard care", sample_size=100)
>>> arm.to_dict()
{'name': 'Standard care', 'sample_size': 100}

Raises:: InputError – If name is not a non-empty string or sample_size is not a positive integer.

name: str

sample_size: int

__post_init__() → None[source]: Validate the decision option.

to_dict() → dict[str, object][source]: Serialize the decision option to a dictionary.

classmethod from_dict(data: object) → DecisionOption[source]: Deserialize a decision option from a dictionary.

class voiage.schema.TrialDesign(arms: list[DecisionOption])[source]

Bases: object

Specifies the design of a proposed trial for EVSI calculations.

arms

A list of DecisionOption objects that together define the trial.

Type:: List[DecisionOption]

Examples

>>> from voiage.schema import DecisionOption, TrialDesign
>>> design = TrialDesign([DecisionOption("A", 50), DecisionOption("B", 50)])
>>> design.total_sample_size
100

Raises:: InputError – If arms is not a non-empty list of DecisionOption objects, or if any of the arm names are duplicated.

arms: list[DecisionOption]

__post_init__() → None[source]: Validate the trial design.

to_dict() → dict[str, object][source]: Serialize the trial design to a dictionary.

classmethod from_dict(data: object) → TrialDesign[source]: Deserialize a trial design from a dictionary.

property total_sample_size: int: Return the total sample size across all arms.

class voiage.schema.PortfolioStudy(name: str, design: TrialDesign, cost: float)[source]

Bases: object

Represents a single candidate study within a research portfolio.

name

The name of the candidate study.

Type:: str

design

The TrialDesign object specifying the study’s design.

Type:: TrialDesign

cost

The estimated cost of conducting this study.

Type:: float

Examples

>>> from voiage.schema import DecisionOption, PortfolioStudy, TrialDesign
>>> study = PortfolioStudy("Trial 1", TrialDesign([DecisionOption("A", 10)]), 1000.0)
>>> study.cost
1000.0

Raises:: InputError – If inputs are of the wrong type or cost is negative.

name: str

design: TrialDesign

cost: float

__post_init__() → None[source]: Validate the portfolio study.

class voiage.schema.PortfolioSpec(studies: list[PortfolioStudy], budget_constraint: float | None = None)[source]

Bases: object

Defines a portfolio of candidate research studies for optimization.

studies

A list of PortfolioStudy objects representing the candidate studies.

Type:: List[PortfolioStudy]

budget_constraint

The overall budget limit for the portfolio. Defaults to None.

Type:: Optional[float], optional

Examples

>>> from voiage.schema import DecisionOption, PortfolioSpec, PortfolioStudy, TrialDesign
>>> study = PortfolioStudy("Trial 1", TrialDesign([DecisionOption("A", 10)]), 1000.0)
>>> spec = PortfolioSpec([study], budget_constraint=2000.0)
>>> spec.budget_constraint
2000.0

Raises:: InputError – If studies is not a non-empty list of PortfolioStudy objects, if study names are duplicated, or if budget_constraint is negative.

studies: list[PortfolioStudy]

budget_constraint: float | None = None

__post_init__() → None[source]: Validate the portfolio spec.

class voiage.schema.DynamicSpec(time_steps: Sequence[float])[source]

Bases: object

Specification for dynamic or sequential VOI analyses.

time_steps

A sequence of time points (e.g., years from present) at which decisions or data accrual occur.

Type:: Sequence[float]

Examples

>>> from voiage.schema import DynamicSpec
>>> spec = DynamicSpec([0.0, 1.0, 2.0])
>>> list(spec.time_steps)
[0.0, 1.0, 2.0]

Raises:: InputError – If time_steps is not a non-empty sequence of numbers.

time_steps: Sequence[float]

__post_init__() → None[source]: Validate the dynamic spec.