Skip to content

Trial Placement

Trial placement strategies for adaptive psychophysical experiments.

Package Overview


trial_placement

trial_placement

Trial placement that does not depend on the posterior.

This module is untested and still in development.

  • GridPlacement: proposes the points of a fixed grid, in order.
  • SobolPlacement: proposes quasi-random points that fill the stimulus space evenly.

Both take a posterior argument in propose and ignore it. psyphy does not yet place trials adaptively, from the posterior.

Examples:

1
2
3
4
5
>>> # Fixed grid design: walks through the grid in order
>>> from psyphy.trial_placement import GridPlacement
>>> grid = [[x0, x1] for x0 in (-1.0, 0.0, 1.0) for x1 in (-1.0, 0.0, 1.0)]  # 9 points
>>> placement = GridPlacement(grid_points=grid)
>>> trials = placement.propose(posterior=None, batch_size=5)
1
2
3
4
>>> # Quasi-random exploration
>>> from psyphy.trial_placement import SobolPlacement
>>> placement = SobolPlacement(dim=2, bounds=[[-1, 1], [-1, 1]])
>>> trials = placement.propose(posterior=None, batch_size=8)

Classes:

Name Description
GridPlacement

Fixed grid placement.

SobolPlacement

Sobol quasi-random placement.

GridPlacement

GridPlacement(grid_points)

Fixed grid placement.

Parameters:

Name Type Description Default
grid_points list of (ref, probe)

Predefined set of trial stimuli.

required
Notes
  • grid = your set of allowable trials; this class simply walks through that set.

Methods:

Name Description
propose

Return the next batch of trials from the grid.

Attributes:

Name Type Description
grid_points
Source code in src/psyphy/trial_placement/grid.py
def __init__(self, grid_points):
    self.grid_points = list(grid_points)
    self._index = 0

grid_points

grid_points = list(grid_points)

propose

propose(posterior, batch_size: int) -> TrialBatch

Return the next batch of trials from the grid.

Parameters:

Name Type Description Default
posterior Posterior
required
batch_size int

Number of trials to return.

required

Returns:

Type Description
TrialBatch

Fixed batch of (ref, probe).

Source code in src/psyphy/trial_placement/grid.py
def propose(self, posterior, batch_size: int) -> TrialBatch:
    """
    Return the next batch of trials from the grid.

    Parameters
    ----------
    posterior : Posterior
    batch_size : int
        Number of trials to return.

    Returns
    -------
    TrialBatch
        Fixed batch of (ref, probe).
    """
    start, end = self._index, self._index + batch_size
    batch = self.grid_points[start:end]
    self._index = end
    return TrialBatch.from_stimuli(batch)

SobolPlacement

SobolPlacement(dim: int, bounds, seed: int = 0)

Sobol quasi-random placement.

Parameters:

Name Type Description Default
dim int

Dimensionality of stimulus space.

required
bounds list of (low, high)

Bounds per dimension.

required
seed int

RNG seed.

0
Notes

TrialBatch stores stimuli as list[tuple[Any, Any]], and the reference vector is fixed at zero.

Methods:

Name Description
propose

Propose Sobol points (ignores posterior).

Attributes:

Name Type Description
bounds
engine
Source code in src/psyphy/trial_placement/sobol.py
def __init__(self, dim: int, bounds, seed: int = 0):
    self.engine = Sobol(d=dim, scramble=True, seed=seed)
    self.bounds = bounds

bounds

bounds = bounds

engine

engine = Sobol(d=dim, scramble=True, seed=seed)

propose

propose(posterior, batch_size: int) -> TrialBatch

Propose Sobol points (ignores posterior).

Parameters:

Name Type Description Default
posterior Posterior

Ignored.

required
batch_size int

Number of trials to return.

required

Returns:

Type Description
TrialBatch

Candidate trials from Sobol sequence.

Source code in src/psyphy/trial_placement/sobol.py
def propose(self, posterior, batch_size: int) -> TrialBatch:
    """
    Propose Sobol points (ignores posterior).

    Parameters
    ----------
    posterior : Posterior
        Ignored.
    batch_size : int
        Number of trials to return.

    Returns
    -------
    TrialBatch
        Candidate trials from Sobol sequence.

    """
    raw = self.engine.random(batch_size)
    scaled = [
        low + (high - low) * raw[:, i] for i, (low, high) in enumerate(self.bounds)
    ]
    # Convert column-wise scaled arrays into list of probe vectors
    comparisons = [tuple(vals) for vals in zip(*scaled)]
    # reference is always a zero vector of matching dimension
    dim = len(self.bounds)
    zero_ref = 0.0 if dim == 1 else tuple(0.0 for _ in range(dim))
    trials = [(zero_ref, p) for p in comparisons]
    return TrialBatch.from_stimuli(trials)

Grid


grid

grid.py

Grid-based placement strategy.

Full WPPM mode: - Could refine the grid adaptively around regions of high posterior uncertainty.

Classes:

Name Description
GridPlacement

Fixed grid placement.

GridPlacement

GridPlacement(grid_points)

Fixed grid placement.

Parameters:

Name Type Description Default
grid_points list of (ref, probe)

Predefined set of trial stimuli.

required
Notes
  • grid = your set of allowable trials; this class simply walks through that set.

Methods:

Name Description
propose

Return the next batch of trials from the grid.

Attributes:

Name Type Description
grid_points
Source code in src/psyphy/trial_placement/grid.py
def __init__(self, grid_points):
    self.grid_points = list(grid_points)
    self._index = 0

grid_points

grid_points = list(grid_points)

propose

propose(posterior, batch_size: int) -> TrialBatch

Return the next batch of trials from the grid.

Parameters:

Name Type Description Default
posterior Posterior
required
batch_size int

Number of trials to return.

required

Returns:

Type Description
TrialBatch

Fixed batch of (ref, probe).

Source code in src/psyphy/trial_placement/grid.py
def propose(self, posterior, batch_size: int) -> TrialBatch:
    """
    Return the next batch of trials from the grid.

    Parameters
    ----------
    posterior : Posterior
    batch_size : int
        Number of trials to return.

    Returns
    -------
    TrialBatch
        Fixed batch of (ref, probe).
    """
    start, end = self._index, self._index + batch_size
    batch = self.grid_points[start:end]
    self._index = end
    return TrialBatch.from_stimuli(batch)

Sobol


sobol

sobol.py

Sobol quasi-random placement.

What it does: - Uses a Sobol engine to generate low-discrepancy points. - Ignores the posterior (pure exploration).

Levaraging WPPM's posterior: - Could combine Sobol exploration (early) with posterior-aware exploitation (later).

Classes:

Name Description
SobolPlacement

Sobol quasi-random placement.

SobolPlacement

SobolPlacement(dim: int, bounds, seed: int = 0)

Sobol quasi-random placement.

Parameters:

Name Type Description Default
dim int

Dimensionality of stimulus space.

required
bounds list of (low, high)

Bounds per dimension.

required
seed int

RNG seed.

0
Notes

TrialBatch stores stimuli as list[tuple[Any, Any]], and the reference vector is fixed at zero.

Methods:

Name Description
propose

Propose Sobol points (ignores posterior).

Attributes:

Name Type Description
bounds
engine
Source code in src/psyphy/trial_placement/sobol.py
def __init__(self, dim: int, bounds, seed: int = 0):
    self.engine = Sobol(d=dim, scramble=True, seed=seed)
    self.bounds = bounds

bounds

bounds = bounds

engine

engine = Sobol(d=dim, scramble=True, seed=seed)

propose

propose(posterior, batch_size: int) -> TrialBatch

Propose Sobol points (ignores posterior).

Parameters:

Name Type Description Default
posterior Posterior

Ignored.

required
batch_size int

Number of trials to return.

required

Returns:

Type Description
TrialBatch

Candidate trials from Sobol sequence.

Source code in src/psyphy/trial_placement/sobol.py
def propose(self, posterior, batch_size: int) -> TrialBatch:
    """
    Propose Sobol points (ignores posterior).

    Parameters
    ----------
    posterior : Posterior
        Ignored.
    batch_size : int
        Number of trials to return.

    Returns
    -------
    TrialBatch
        Candidate trials from Sobol sequence.

    """
    raw = self.engine.random(batch_size)
    scaled = [
        low + (high - low) * raw[:, i] for i, (low, high) in enumerate(self.bounds)
    ]
    # Convert column-wise scaled arrays into list of probe vectors
    comparisons = [tuple(vals) for vals in zip(*scaled)]
    # reference is always a zero vector of matching dimension
    dim = len(self.bounds)
    zero_ref = 0.0 if dim == 1 else tuple(0.0 for _ in range(dim))
    trials = [(zero_ref, p) for p in comparisons]
    return TrialBatch.from_stimuli(trials)