adopy.base

This module contains three basic classes of ADOpy: Task, Model, and Engine. These classes provide built-in functions for the Adaptive Design Optimization.

Note

Three basic classes are defined in the adopy.base (i.e., adopy.base.Task, adopy.base.Model, and adopy.base.Engine). However, for convinience, users can find it directly as adopy.Task, adopy.Model, and adopy.Engine.

class adopy.base.Task(designs, responses, name=None)

Bases: object

A task object stores information for a specific experimental task, including labels of design variables (designs), possible responses (responses) and its name (name).

Parameters

• designs – Labels of design variables in the task.

• responses – Possible values for the response variable of the task.

• name – Name of the task.

Examples

>>> task = Task(name='Task A', designs=['d1', 'd2'], responses=[0, 1])
>>> task
Task('Task A', designs=['d1', 'd2'], responses=[0, 1])
>>> task.name
'Task A'
>>> task.designs
['d1', 'd2']
>>> task.responses
[0, 1]

property name

Name of the task. If it has no name, returns None.

property designs

Labels for design variables of the task.

property responses

Possible values for the response variable of the task.

extract_designs(data)

Extract design grids from the given data.

Parameters

data – A data object that contains key-value pairs or columns corresponding to design variables.

Returns

ret – An ordered dictionary of grids for design variables.

class adopy.base.Model(task, params, func=None, constraint=None, name=None)

Bases: object

A base class for a model in the ADOpy package.

Parameters

• task (Task) – Task object that this model object is for.

• params (Iterable[str]) – Labels of model parameters in the model.

• func (Optional[Callable]) – A function to calculate the probability of the observation. Currently, it does nothing.

• name (Optional[str]) – Name of the task.

Examples

>>> task = Task(name='Task A', designs=['d1', 'd2'], responses=[0, 1])
>>> model = Model(name='Model X', task=task, params=['m1', 'm2', 'm3'])
>>> model
Model('Model X', params=['m1', 'm2', 'm3'])
>>> model.name
'Model X'
>>> model.task
Task('Task A', designs=['d1', 'd2'], responses=[0, 1])
>>> model.params
['m1', 'm2', 'm3']

property name

Name of the model. If it has no name, returns None.

property task

Task instance for the model.

property params

Labels for model parameters of the model.

property constraint

Contraints on model parameters. This do not work yet.

extract_params(data)

Extract parameter grids from the given data.

Parameters

data – A data object that contains key-value pairs or columns corresponding to design variables.

Returns

ret – An ordered dictionary of grids for model parameters.

compute(*args, **kargs)

Compute the probability of choosing a certain response given values of design variables and model parameters.

class adopy.base.Engine(task, model, grid_design, grid_param, lambda_et=None)

Bases: object

A base class for an ADO engine to compute optimal designs.

property task

Task instance for the engine

property model

Model instance for the engine

property num_design

Number of design grid axes

property num_param

Number of parameter grid axes

property prior

Prior distributions of joint parameter space

property post

Posterior distributions of joint parameter space

property marg_post

Marginal posterior distributions for each parameter

property post_mean

A vector of estimated means for the posterior distribution. Its length is num_params.

property post_cov

An estimated covariance matrix for the posterior distribution. Its shape is (num_grids, num_params).

property post_sd

A vector of estimated standard deviations for the posterior distribution. Its length is num_params.

property lambda_et

Lambda value for eligibility traces. If it equals to None, eligibility traces do not affect choices of the optimal designs.

reset()

Reset the engine as in the initial state.

get_design(kind='optimal')

Choose a design with a given type.

• optimal: an optimal design \(d^*\) that maximizes the mutual information.

• random: a design randomly chosen.

Parameters

kind ({‘optimal’, ‘random’}, optional) – Type of a design to choose

Returns

design (array_like) – A chosen design vector

update(design, response)

Update the posterior \(p(\theta | y_\text{obs}(t), d^*)\) for all discretized values of \(\theta\).

\[p(\theta | y_\text{obs}(t), d^*) = \frac{ p( y_\text{obs}(t) | \theta, d^*) p_t(\theta) } { p( y_\text{obs}(t) | d^* ) }\]

Parameters

• design – Design vector for given response

• response – Any kinds of observed response