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 – Labels of response variables in the task (e.g., choice, rt).

  • name – Name of the task.

Examples

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

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

property designs

Labels for design variables of the task.

property responses

Labels of response variables in 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.

extract_responses(data)

Extract response 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 response variables.

class adopy.base.Model(task, params, func=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 – Labels of model parameters in the model.

  • func (function, optional) – A function to compute the log likelihood given a model, denoted as \(L(\mathbf{x} | \mathbf{d}, \mathbf{\theta})\), where \(\mathbf{x}\) is a response vector, \(\mathbf{d}\) is a design vector, and \(\mathbf{\theta}\) is a parameter vector. Note that the function arguments should include all design, parameter, and response variables.

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

Examples

>>> task = Task(name='Task A', designs=['x1', 'x2'], responses=['y'])
>>> def calculate_log_lik(y, x1, x2, b0, b1, b2):
...     import numpy as np
...     from scipy.stats import bernoulli
...     logit = b0 + b1 * x1 + b2 * x2
...     p = np.divide(1, 1 + np.exp(-logit))
...     return bernoulli.logpmf(y, p)
>>> model = Model(name='Model X', task=task, params=['b0', 'b1', 'b2'],
...               func=calculate_log_lik)
>>> model.name
>>> model.task
>>> model.params
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.

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 log likelihood of obtaining responses with given designs and model parameters. If the likelihood function is not given for the model, it returns a random log probability.

Deprecated since version 0.4.0: As the Model class get modified to contain a function for log likelihood in 0.4.0, we recommend you to use model.compute_log_lik() function instead so to make it clear what the function calculates.

compute_log_lik(*args, **kargs)

Compute log likelihood of obtaining responses with given designs and model parameters. If the likelihood function is not given for the model, it returns a random log probability.

class adopy.base.Engine(task, model, grid_design, grid_param, grid_response, dtype=<class 'numpy.float32'>)

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 grid_design

Grids for a design space.

property grid_param

Grids for a parameter space.

property grid_response

Grids for a response space.

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 dtype

Datatype for internal grid objects.

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 (Dict[str, any]) – 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