`psp`#

The functions you will use to run a search and read its results. Everything else the package exports is under Advanced.

`PSP`(model, discretize, control[, save, ...])	Partition a model's parameter space by the ordinal patterns it produces.
`PSPLockstep`(model, discretize, controls, *)	Run one independent partitioning per control, sharing one model call per iteration.
`PSPResult`(ordinal_patterns, ordinal_counts, ...)	Container.
`rowwise`(fn, *[, numpy])	A function that adapts parameter space partitioning evaluations from a batched operation to a sequential one.
`read_saved`(path[, extension])	Read the files written by `PSP(save=True, path=path, extension=extension)`.

Running a search#

psp.PSP(model, discretize, control, save=False, path='.', extension='.csv', quiet=False, *, batched=True, device=None, dtype=None, generator=None)[source]#

Partition a model’s parameter space by the ordinal patterns it produces.

A PyTorch implementation of the parameter space partitioning MCMC algorithm of Pitt, Kim, Navarro and Myung (2006). The algorithm:

Evaluate model on every row of control["init"]. The patterns discretize makes of the outputs are the first regions found.
For every pattern with fewer than population parameter sets, propose a new parameter set at random within radius of the last parameter set that produced it, and move it onto the bounds if it crossed them.
Evaluate the model on all proposals in one batch.
Record the patterns found and the parameter sets that produced them, then return to step 1 until every pattern is full or iterations is reached.

Parameters:

model

Maps parameter sets to the model’s continuous outputs. Batched by default: it receives a (n, dimensions) tensor and returns (n, responses). With batched=False it receives one (dimensions,) tensor at a time and returns (responses,), as in R.

discretize

Maps model outputs to an ordinal pattern, a square numeric matrix. Batched by default: (n, responses) in, (n, dimensionality, dimensionality) out. With batched=False, (responses,) in and a matrix out. Two parameter sets produce the same pattern when the matrices are identical, with -0.0 equal to 0.0 and NaN equal to NaN.

control

The settings as a set of control arguments, either a Control or a mapping with the same keys. The required keys are:

init: Starting parameter sets, one per row.
lower, upper: Bounds of each parameter.
radius: Largest step in any one parameter; a single number, or one per parameter.
population: Parameter sets each pattern needs; 0/None for no limit.
iterations: Cap on the number of iterations; 0/None for no cap. At least one of population and iterations must be set.
parameter_names, stimuli_names: Column names of the saved files (optional).
dimensionality, responses: Size of the pattern matrix and length of the model output, checked on every evaluation. Optional: taken from the first evaluation if absent.

save

Write every evaluated parameter set and model output to disk.

path

Prefix of the two files, <path>_parameters<extension> and <path>_continuous<extension>. Each row holds the iteration, the values and the 0-based pattern id.

extension

Extension of the saved files.

quiet

Do not print the iteration number.

batched

Whether model and discretize take the whole batch (default) or one parameter set at a time. Equivalent to wrapping both with psp.rowwise().

device, dtype

Where the search runs and in what precision. Defaults to the device and dtype of control["init"] if it is a tensor, otherwise CPU and float64.

generator

A torch.Generator on device for reproducible proposals. By default the global generator is used, seeded with torch.manual_seed().

Returns:

PSPResult: ordinal_patterns, ordinal_counts and iterations.

Raises:

ValueError: For invalid control settings, and when model or discretize returns something of the wrong type or size. Errors raised by the callbacks propagate.

References

Pitt, M. A., Kim, W., Navarro, D. J., & Myung, J. I. (2006). Global model analysis by parameter space partitioning. Psychological Review, 113(1), 57-83. https://doi.org/10.1037/0033-295X.113.1.57

Examples

>>> import torch
>>> from psp import PSP
>>> torch.manual_seed(1)
<torch._C.Generator object at ...>
>>> model = lambda par: par                       # the outputs are the parameters
>>> discretize = lambda out: (out > 0.5).double().diag_embed()  # which half of each axis
>>> result = PSP(model, discretize, {
...     "init": [[0.5, 0.5]], "lower": [0, 0], "upper": [1, 1],
...     "radius": 0.5, "population": 20, "iterations": 100}, quiet=True)
>>> result.patterns
4

class psp.PSPResult(ordinal_patterns, ordinal_counts, iterations)[source]#

Container. Data class. It holds and validates the results of a PSP() run. It behaves like a mapping and a dataclass.

Attributes:

ordinal_patterns: Every pattern found, shape (patterns, dimensionality, dimensionality), float64, on the CPU. Pattern k is ordinal_patterns[k]; the R package stores the same matrices as ordinal_patterns[, , k + 1].
ordinal_counts: How many evaluated parameter sets produced each pattern, shape (patterns,).
iterations: Number of iterations completed before a stopping rule was reached.

property patterns#: Number of patterns found.

property evaluations#: Number of times the model was evaluated.

psp.PSPLockstep(model, discretize, controls, *, save=False, paths=None, extension='.csv', quiet=False, device=None, dtype=None, generator=None)[source]#

Run one independent partitioning per control, sharing one model call per iteration.

Parameters:

model: Called once per iteration with the proposals of every run that is still going, (n, dimensions), and run, an (n,) int64 tensor giving the index in controls of the run each row belongs to; returns (n, responses).
discretize: As in psp.PSP(): (n, responses) to (n, D, D).
controls: One control mapping per run, with the keys of psp.PSP(). Runs may differ in init, bounds and radius; they must share iterations and population and the number of parameters.
save, paths, extension: Write every evaluation of run r to paths[r] as psp.PSP() does.
quiet: Do not print the iteration number, the number of runs still going and the number of rows evaluated.
device, dtype, generator: As in psp.PSP().

Returns:

list[PSPResult]: One result per control, in order. A run’s iterations is the iteration at which it stopped proposing, or the cap.

Models written for one parameter set#

psp.rowwise(fn, *, numpy=False)[source]#

A function that adapts parameter space partitioning evaluations from a batched operation to a sequential one. This function is here to help users who are porting models from the R package, which is written for one parameter set at a time. Use it with PSP(..., batched=False).

rowwise(fn) calls fn once per row of its input and stacks the results, so a model or discretize written as in the R package, for a single vector, can be handed to psp.PSP(). Each row is passed as a 1-D tensor, or as a NumPy array when numpy=True; fn may return a tensor, an array, a list or a scalar.

Parameters:

fn: Function of a single parameter set (or a single vector of model output).
numpy: Pass each row to fn as a numpy.ndarray instead of a tensor. Useful for models written with NumPy or SciPy.

Examples

>>> import torch
>>> model = rowwise(lambda par: par.cumsum(0))
>>> model(torch.ones(3, 2))
tensor([[1., 2.],
        [1., 2.],
        [1., 2.]])

Reading saved runs#

psp.read_saved(path, extension='.csv')[source]#

Read the files written by PSP(save=True, path=path, extension=extension).

Requires pandas, which is an optional dependency (pip install psp-torch[notebooks]).

Advanced#

The control settings as a class, the types of the callbacks, the pieces of the saved-run reader, and the two steps of a proposal. You need none of them to run a search.

`Control`(init, lower, upper, radius, ...)	Validate control arguments for the parameter space partitioning run.
`UNBOUNDED`	int([x]) -> integer int(x, base=10) -> integer
`Model`
`Discretize`
`LockstepModel`
`SavedRun`(parameters, continuous)	The two tables written by a run with `save=True`, as pandas data frames.
`saved_paths`(path[, extension])	The two files a run with `save=True` writes: parameters and continuous outputs.
`has_pyarrow`()	Whether pyarrow, the optional fast csv writer, is installed.
`hyper_points`(counts, radius, *[, generator])	Random steps of at most `radius` in each parameter, shape `(counts, dimensions)`.
`clamp_parameters`(parameters, lower, upper)	Move every parameter set onto the bounds where it left them.

class psp.Control(init, lower, upper, radius, population, iterations, parameter_names, stimuli_names, dimensionality, responses)[source]#

Validate control arguments for the parameter space partitioning run. It checks that the required keys are present and that the values are of the right type and shape. Use

Control.from_mapping({"lower": [0, 0], "upper": [1, 1], ...}), or pass the mapping to psp.PSP() directly.

Attributes:

init: Starting parameter sets, one per row, shape (starts, dimensions).
lower, upper: Bounds of each parameter, shape (dimensions,). Use -inf/inf for an unbounded parameter.
radius: Largest step the search takes in any one parameter, shape (dimensions,).
population: Number of parameter sets each pattern needs before the search stops proposing from it. 2**63 - 1 when unbounded.
iterations: Cap on the number of iterations. 2**63 - 1 when unbounded.
parameter_names, stimuli_names: Column names of the files written with save=True.
dimensionality: Size of the square matrix discretize returns, or None to take it from the first evaluation.
responses: Length of the vector model returns, or None to take it from the first evaluation.

property dimensions#: Number of free parameters.

classmethod from_mapping(control, *, device=None, dtype=None)[source]#

Validate a control mapping with the expected keys.

Required keys: init, lower, upper, radius, and at least one of population and iterations. Optional keys: parameter_names, stimuli_names, dimensionality, responses.

Raises:

ValueError: If any of the required keys are missing, or if any of the values are of the wrong type or shape.

to_mapping()[source]#: The settings as a plain dict.

psp.UNBOUNDED = 0#

int([x]) -> integer int(x, base=10) -> integer

Convert a number or string to an integer, or return 0 if no arguments are given. If x is a number, return x.__int__(). For floating point numbers, this truncates towards zero.

If x is not a number or if base is given, then x must be a string, bytes, or bytearray instance representing an integer literal in the given base. The literal can be preceded by ‘+’ or ‘-’ and be surrounded by whitespace. The base defaults to 10. Valid bases are 0 and 2-36. Base 0 means to interpret the base from the string as an integer literal. >>> int(‘0b100’, base=0) 4

psp.Model#: alias of Callable[[Tensor], Any]

psp.Discretize#: alias of Callable[[Tensor], Any]

psp.LockstepModel#: alias of Callable[[Tensor, Tensor], Any]

class psp.SavedRun(parameters, continuous)[source]#

The two tables written by a run with save=True, as pandas data frames.

Attributes:

parameters: One row per evaluation: iteration, one column per parameter, pattern.
continuous: One row per evaluation: iteration, one column per model output, pattern.

psp.saved_paths(path, extension='.csv')[source]#: The two files a run with save=True writes: parameters and continuous outputs.

psp.has_pyarrow()[source]#: Whether pyarrow, the optional fast csv writer, is installed.

psp.hyper_points(counts, radius, *, generator=None)[source]#

Random steps of at most radius in each parameter, shape (counts, dimensions).

This is the jumping distribution: a direction picked uniformly on the unit hypersphere (Weisstein, “Hypersphere Point Picking”), scaled in each dimension by a factor drawn uniformly between 0 and that dimension’s radius. The scale factors are drawn once per call and shared by all counts points, as in the C++ implementation.

Parameters:

counts: Number of points.
radius: Radius of each dimension, shape (dimensions,); its device and dtype are used.
generator: Random number generator on the same device as radius.

References

Weisstein, Eric W. “Hypersphere Point Picking.” From MathWorld–A Wolfram Resource. https://mathworld.wolfram.com/HyperspherePointPicking.html

psp.clamp_parameters(parameters, lower, upper)[source]#: Move every parameter set onto the bounds where it left them.

psp#

Running a search#

Models written for one parameter set#

Reading saved runs#

Advanced#

`psp`#