Skip to content

Data

Package

data

psyphy.data

submodule for handling psychophysical experiment data.

Includes: - dataset: ResponseData, TrialBatch, loaders - transforms: color/model space conversions - io: save/load datasets

Classes:

Name Description
ResponseData

Container for psychophysical trial data.
TrialBatch

Container for a proposed batch of trials

ResponseData 

ResponseData()

Container for psychophysical trial data.

Attributes:

Name Type Description
refs List[Any]

List of reference stimuli.
probes List[Any]

List of probe stimuli.
responses List[int]

List of subject responses (e.g., 0/1 or categorical).

Methods:

Name Description
add_batch

Append responses for a batch of trials.
add_trial

append a single trial.
to_numpy

Return refs, probes, responses as numpy arrays.
Source code in src/psyphy/data/dataset.py 
40
41
42
43
def __init__(self) -> None:
    self.refs: List[Any] = []
    self.probes: List[Any] = []
    self.responses: List[int] = []

probes 

probes: List[Any] = []

refs 

refs: List[Any] = []

responses 

responses: List[int] = []

add_batch 

add_batch(
    responses: List[int], trial_batch: TrialBatch
) -> None

Append responses for a batch of trials.

Parameters:

Name Type Description Default
responses List[int]

Responses corresponding to each (ref, probe) in the trial batch.

 required
trial_batch TrialBatch

The batch of proposed trials.

 required
Source code in src/psyphy/data/dataset.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
def add_batch(self, responses: List[int], trial_batch: TrialBatch) -> None:
    """
    Append responses for a batch of trials.

    Parameters
    ----------
    responses : List[int]
        Responses corresponding to each (ref, probe) in the trial batch.
    trial_batch : TrialBatch
        The batch of proposed trials.
    """
    for (ref, probe), resp in zip(trial_batch.stimuli, responses):
        self.add_trial(ref, probe, resp)

add_trial 

add_trial(ref: Any, probe: Any, resp: int) -> None

append a single trial.

Parameters:

Name Type Description Default
ref Any

Reference stimulus (numpy array, list, etc.)

 required
probe Any

Probe stimulus

 required
resp int

Subject response (binary or categorical)

 required
Source code in src/psyphy/data/dataset.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def add_trial(self, ref: Any, probe: Any, resp: int) -> None:
    """
    append a single trial.

    Parameters
    ----------
    ref : Any
        Reference stimulus (numpy array, list, etc.)
    probe : Any
        Probe stimulus
    resp : int
        Subject response (binary or categorical)
    """
    self.refs.append(ref)
    self.probes.append(probe)
    self.responses.append(resp)

to_numpy 

to_numpy() -> Tuple[ndarray, ndarray, ndarray]

Return refs, probes, responses as numpy arrays.

Returns:

Name Type Description
refs ndarray
probes ndarray
responses ndarray
Source code in src/psyphy/data/dataset.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def to_numpy(self) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    """
    Return refs, probes, responses as numpy arrays.

    Returns
    -------
    refs : np.ndarray
    probes : np.ndarray
    responses : np.ndarray
    """
    return (
        np.array(self.refs),
        np.array(self.probes),
        np.array(self.responses),
    )

TrialBatch 

TrialBatch(stimuli: List[Tuple[Any, Any]])

Container for a proposed batch of trials

Attributes:

Name Type Description
stimuli List[Tuple[Any, Any]]

Each trial is a (reference, probe) tuple.

Methods:

Name Description
from_stimuli

Construct a TrialBatch from a list of stimuli (ref, probe) pairs.
Source code in src/psyphy/data/dataset.py 
103
104
def __init__(self, stimuli: List[Tuple[Any, Any]]) -> None:
    self.stimuli = list(stimuli)

stimuli 

stimuli = list(stimuli)

from_stimuli 

from_stimuli(pairs: List[Tuple[Any, Any]]) -> TrialBatch

Construct a TrialBatch from a list of stimuli (ref, probe) pairs.

Source code in src/psyphy/data/dataset.py 
106
107
108
109
110
111
@classmethod
def from_stimuli(cls, pairs: List[Tuple[Any, Any]]) -> TrialBatch:
    """
    Construct a TrialBatch from a list of stimuli (ref, probe) pairs.
    """
    return cls(pairs)

Data Containers for Response Data and Proposed Next Trials

dataset

dataset.py

Core data containers for psyphy.

defines: - ResponseData: container for psychophysical trial data - TrialBatch: container for a proposed batch of trials

Notes
  • Data is stored in standard NumPy (mutable!) arrays or Python lists.
  • Use numpy for I/O and analysis.
  • Convert to jax.numpy (jnp) (immutable!) arrays only when passing into WPPM or inference engines that require JAX/Optax.

Classes:

Name Description
ResponseData

Container for psychophysical trial data.
TrialBatch

Container for a proposed batch of trials

ResponseData 

ResponseData()

Container for psychophysical trial data.

Attributes:

Name Type Description
refs List[Any]

List of reference stimuli.
probes List[Any]

List of probe stimuli.
responses List[int]

List of subject responses (e.g., 0/1 or categorical).

Methods:

Name Description
add_batch

Append responses for a batch of trials.
add_trial

append a single trial.
to_numpy

Return refs, probes, responses as numpy arrays.
Source code in src/psyphy/data/dataset.py 
40
41
42
43
def __init__(self) -> None:
    self.refs: List[Any] = []
    self.probes: List[Any] = []
    self.responses: List[int] = []

probes 

probes: List[Any] = []

refs 

refs: List[Any] = []

responses 

responses: List[int] = []

add_batch 

add_batch(
    responses: List[int], trial_batch: TrialBatch
) -> None

Append responses for a batch of trials.

Parameters:

Name Type Description Default
responses List[int]

Responses corresponding to each (ref, probe) in the trial batch.

 required
trial_batch TrialBatch

The batch of proposed trials.

 required
Source code in src/psyphy/data/dataset.py 
62
63
64
65
66
67
68
69
70
71
72
73
74
def add_batch(self, responses: List[int], trial_batch: TrialBatch) -> None:
    """
    Append responses for a batch of trials.

    Parameters
    ----------
    responses : List[int]
        Responses corresponding to each (ref, probe) in the trial batch.
    trial_batch : TrialBatch
        The batch of proposed trials.
    """
    for (ref, probe), resp in zip(trial_batch.stimuli, responses):
        self.add_trial(ref, probe, resp)

add_trial 

add_trial(ref: Any, probe: Any, resp: int) -> None

append a single trial.

Parameters:

Name Type Description Default
ref Any

Reference stimulus (numpy array, list, etc.)

 required
probe Any

Probe stimulus

 required
resp int

Subject response (binary or categorical)

 required
Source code in src/psyphy/data/dataset.py 
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
def add_trial(self, ref: Any, probe: Any, resp: int) -> None:
    """
    append a single trial.

    Parameters
    ----------
    ref : Any
        Reference stimulus (numpy array, list, etc.)
    probe : Any
        Probe stimulus
    resp : int
        Subject response (binary or categorical)
    """
    self.refs.append(ref)
    self.probes.append(probe)
    self.responses.append(resp)

to_numpy 

to_numpy() -> Tuple[ndarray, ndarray, ndarray]

Return refs, probes, responses as numpy arrays.

Returns:

Name Type Description
refs ndarray
probes ndarray
responses ndarray
Source code in src/psyphy/data/dataset.py 
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def to_numpy(self) -> Tuple[np.ndarray, np.ndarray, np.ndarray]:
    """
    Return refs, probes, responses as numpy arrays.

    Returns
    -------
    refs : np.ndarray
    probes : np.ndarray
    responses : np.ndarray
    """
    return (
        np.array(self.refs),
        np.array(self.probes),
        np.array(self.responses),
    )

TrialBatch 

TrialBatch(stimuli: List[Tuple[Any, Any]])

Container for a proposed batch of trials

Attributes:

Name Type Description
stimuli List[Tuple[Any, Any]]

Each trial is a (reference, probe) tuple.

Methods:

Name Description
from_stimuli

Construct a TrialBatch from a list of stimuli (ref, probe) pairs.
Source code in src/psyphy/data/dataset.py 
103
104
def __init__(self, stimuli: List[Tuple[Any, Any]]) -> None:
    self.stimuli = list(stimuli)

stimuli 

stimuli = list(stimuli)

from_stimuli 

from_stimuli(pairs: List[Tuple[Any, Any]]) -> TrialBatch

Construct a TrialBatch from a list of stimuli (ref, probe) pairs.

Source code in src/psyphy/data/dataset.py 
106
107
108
109
110
111
@classmethod
def from_stimuli(cls, pairs: List[Tuple[Any, Any]]) -> TrialBatch:
    """
    Construct a TrialBatch from a list of stimuli (ref, probe) pairs.
    """
    return cls(pairs)

Transforms (e.g., from RGB to model space)

transforms

transforms.py

color space transformations.

functions (MVP stubs): - to_model_space(rgb): map RGB stimulus values into model space - to_rgb(model_coords): map from model space back to RGB

Future extensions: - other color spaces

Functions:

Name Description
model_to_stimuli

Map from model space coordinates to RGB values.
stimuli_to_model_space

Map RGB stimulus values to model space coordinates.

Attributes:

Name Type Description
ArrayLike

ArrayLike 

ArrayLike = Union[Sequence[float], ndarray]

model_to_stimuli 

model_to_stimuli(model_coords: ArrayLike) -> ndarray

Map from model space coordinates to RGB values.

Parameters:

Name Type Description Default
model_coords array - like

Model space coordinates.

 required

Returns:

Type Description
ndarray

RGB values (MVP: identical to input).
Source code in src/psyphy/data/transforms.py 
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
def model_to_stimuli(model_coords: ArrayLike) -> np.ndarray:
    """
    Map from model space coordinates to RGB values.

    Parameters
    ----------
    model_coords : array-like
        Model space coordinates.

    Returns
    -------
    np.ndarray
        RGB values (MVP: identical to input).
    """
    return np.array(model_coords)

stimuli_to_model_space 

stimuli_to_model_space(rgb: ArrayLike) -> ndarray

Map RGB stimulus values to model space coordinates.

Parameters:

Name Type Description Default
rgb array - like

RGB values, shape (3,) or similar.

 required

Returns:

Type Description
ndarray

Model-space coordinates (MVP: identical to input).
Source code in src/psyphy/data/transforms.py 
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
def stimuli_to_model_space(rgb: ArrayLike) -> np.ndarray:
    """
    Map RGB stimulus values to model space coordinates.

    Parameters
    ----------
    rgb : array-like
        RGB values, shape (3,) or similar.

    Returns
    -------
    np.ndarray
        Model-space coordinates (MVP: identical to input).
    """
    return np.array(rgb)

I/O

io

io.py

I/O utilities for saving and loading psyphy data.

Supports: - CSV for human-readable trial logs - Pickle (.pkl) for Posterior and ResponseData checkpoints?

Notes
  • Data is stored in NumPy arrays (via ResponseData.to_numpy()).
  • Convert to jax.numpy when passing into models.

Functions:

Name Description
load_posterior

Load a Posterior object from pickle.
load_responses_csv

Load ResponseData from a CSV file.
save_posterior

Save a Posterior object to disk using pickle.
save_responses_csv

Save ResponseData to a CSV file.

Attributes:

Name Type Description
PathLike

PathLike 

PathLike = Union[str, Path]

load_posterior 

load_posterior(path: PathLike) -> object

Load a Posterior object from pickle.

Source code in src/psyphy/data/io.py 
78
79
80
81
82
83
def load_posterior(path: PathLike) -> object:
    """
    Load a Posterior object from pickle.
    """
    with open(path, "rb") as f:
        return pickle.load(f)

load_responses_csv 

load_responses_csv(path: PathLike) -> ResponseData

Load ResponseData from a CSV file.

Parameters:

Name Type Description Default
path str or Path
required

Returns:

Type Description
ResponseData
Source code in src/psyphy/data/io.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def load_responses_csv(path: PathLike) -> ResponseData:
    """
    Load ResponseData from a CSV file.

    Parameters
    ----------
    path : str or Path

    Returns
    -------
    ResponseData
    """
    data = ResponseData()
    with open(path) as f:
        reader = csv.DictReader(f)
        for row in reader:
            ref = ast.literal_eval(row["ref"])
            probe = ast.literal_eval(row["probe"])
            resp = int(row["response"])
            data.add_trial(ref, probe, resp)
    return data

save_posterior 

save_posterior(posterior: object, path: PathLike) -> None

Save a Posterior object to disk using pickle.

Source code in src/psyphy/data/io.py 
70
71
72
73
74
75
def save_posterior(posterior: object, path: PathLike) -> None:
    """
    Save a Posterior object to disk using pickle.
    """
    with open(path, "wb") as f:
        pickle.dump(posterior, f)

save_responses_csv 

save_responses_csv(
    data: ResponseData, path: PathLike
) -> None

Save ResponseData to a CSV file.

Parameters:

Name Type Description Default
data ResponseData
required
path str or Path
required
Source code in src/psyphy/data/io.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
def save_responses_csv(data: ResponseData, path: PathLike) -> None:
    """
    Save ResponseData to a CSV file.

    Parameters
    ----------
    data : ResponseData
    path : str or Path
    """
    refs, probes, resps = data.to_numpy()
    with open(path, "w", newline="") as f:
        writer = csv.writer(f)
        writer.writerow(["ref", "probe", "response"])
        for r, p, y in zip(refs, probes, resps):
            writer.writerow([r.tolist(), p.tolist(), int(y)])