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

A container for net benefit values from a PSA.

dataset: Dataset

__post_init__()[source]: Validate the dataset.

property values: ndarray: Return the net benefit values.

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.

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

A container for parameter samples from a PSA.

dataset: Dataset

__post_init__()[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.

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

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__()[source]: Validate the decision option.

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]

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__()[source]: Validate the trial design.

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

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

name: str

design: TrialDesign

cost: float

__post_init__()[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

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__()[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]

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

time_steps: Sequence[float]

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