API

class pylater.LATER(
name: str,
mu: float | Distribution,
sigma: float | Distribution,
sigma_e: float | Distribution,
observed_rt_s: ndarray[Any, dtype[float64]] | None = None,
**kwargs: str | float | ndarray[Any, dtype[float64]],
)

A custom PyMC distribution for a LATER model.

Parameters:

  • name (str) – Identifier for the distribution.

  • mu (float | pm.Distribution) – Mean of the primary component.

  • sigma (float | pm.Distribution) – Standard deviation of the primary component.

  • sigma_e (float | pm.Distribution) – Standard deviation of the early component.

  • observed_rt_s (npt.NDArray[np.float64] | None) – Observed reaction times, in units of seconds.

  • **kwargs (str | float | npt.NDArray[np.float64]) – Additional arguments are passed directly to pm.CustomDist.

Returns:

Distribution for use with a PyMC model.

Return type:

pm.CustomDist

Notes

  • The model parameters are in units of promptness (reciprocal of time).

  • Random samples from the model are in units of time.

class pylater.ReciprobitPlot(
fig_ax: tuple[Figure, Axes] | None = None,
min_rt_s: float = 75 / 1000,
max_rt_s: float = 2000 / 1000,
min_p: float = 0.0,
max_p: float = 1.0,
linthresh: float = 0.1 / 100,
linscale: float = 0.05,
axis_position_offset: float = 4,
apply_style: bool = True,
)

Create a Matplotlib figure in reciprobit space.

Parameters:

  • fix_ax – An already-created figure/axes pair.

  • min_rt_s (float) – Minimum and maximum reaction time values, in seconds, for the x axis.

  • max_rt_s (float) – Minimum and maximum reaction time values, in seconds, for the x axis.

  • min_p (float) – Minimum and maximum probability values, for the y axis.

  • max_p (float) – Minimum and maximum probability values, for the y axis.

  • linthresh (float) – The y-axis is on a probit scale between linthresh and 1 - linthresh, and a linear scale otherwise.

  • linscale (float) – The probit range of the y-axis covers 1 - 2 * linscale of the total range.

  • axis_position_offset (float) – The amount, in points, to offset the axes from the plot region.

  • apply_style (bool) – Whether to apply a custom styling to the figure or leave the defaults.

  • fig_ax (tuple[matplotlib.figure.Figure, matplotlib.axes.Axes] | None)

plot_data(
data: Dataset,
plot_type: str = 'step',
n_points: int = 1000,
**kwargs: str | float,
)

Plot an ECDF of data observations.

Parameters:

  • data (Dataset) – Dataset containing the observations.

  • plot_type (str) – Plots the data as a ‘step’ plot (step) or as individual points (scatter).

  • n_points (int) – For ‘step’ plots, how many points to use when evaluating the ECDF.

  • **kwargs (str | float) – Any additional keyword arguments are passed directly to plt.step or plt.scatter.

Returns:

The ReciprobitPlot instance.

Return type:

ReciprobitPlot

plot_model(
idata: InferenceData,
n_points: int = 1000,
ci_range: float = 0.95,
dataset_name: str | None = None,
fill_kwargs: dict[str, Any] | None = None,
line_kwargs: dict[str, Any] | None = None,
)

Plot a summary of model evaluations using parameters from a posterior distribution.

Parameters:

  • idata (InferenceData) – Inference data object containing posterior samples.

  • n_points (int) – How many points to use when evaluating the model.

  • ci_range (float) – Width of the credible interval.

  • dataset_name (Optional[str]) – Name of the dataset to plot. This is used to select a coordinate within a dataset dimension in the posterior samples. If None, assumes that there is only a single coordinate in the dataset dimension.

  • fill_kwargs (Optional[dict[str, Any]]) – Keyword arguments passed directly to plt.fill_between, for the credible interval.

  • line_kwargs (Optional[dict[str, Any]]) – Keyword arguments passed directly to plt.line, for the median.

Returns:

The ReciprobitPlot instance.

Return type:

ReciprobitPlot

plot_predictive(
idata: InferenceData,
predictive_type: str,
observed_var_name: str | None = None,
n_points: int = 1000,
ci_range: float = 0.95,
fill_kwargs: dict[str, Any] | None = None,
line_kwargs: dict[str, Any] | None = None,
)

Plot a summary of draws from a prior or posterior predictive distribution.

Parameters:

  • idata (InferenceData) – Inference data object containing posterior samples.

  • predictive_type (str) – Either prior or posterior.

  • n_points (int) – How many points to use when evaluating the model.

  • ci_range (float) – Width of the credible interval.

  • observed_var_name (Optional[str]) – Name of the observed variable in the predictive samples. If None, assumes that there is only a single variable with observations.

  • fill_kwargs (Optional[dict[str, Any]]) – Keyword arguments passed directly to plt.fill_between, for the credible interval.

  • line_kwargs (Optional[dict[str, Any]]) – Keyword arguments passed directly to plt.line, for the median.

Returns:

The ReciprobitPlot instance.

Return type:

ReciprobitPlot

class pylater.Dataset(
name: str,
rt_s: _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | bool | int | float | complex | str | bytes | _NestedSequence[bool | int | float | complex | str | bytes],
)

Create a dataset from observed reaction times.

Parameters:

  • name (str) – Name of the dataset.

  • rt_s (Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]) – Reaction times, in seconds.

Returns:

The dataset.

Return type:

Dataset

pylater.build_default_model(
datasets: Sequence[Dataset],
share_type: str | None = None,
)

Assemble a LATER model using a default set of priors.

Parameters:

  • datasets (Sequence[Dataset]) – Observed data to model.

  • share_type (Optional[str]) – With multiple datasets, parameters can be shared according to a ‘shift’ or a ‘swivel’ arrangement.

Returns:

The PyMC model.

Return type:

pm.Model

Notes

  • This uses a default set of priors that may not be appropriate for a given use case. A warning is raised to highlight this; it can be silenced using the warnings built-in package.

pylater.combine_multiple_likelihoods(
idata: InferenceData,
combined_var_name: str = 'obs',
var_names: Sequence[str] | None = None,
overwrite: bool = False,
combined_dim_name: str = 'trial',
copy_idata: bool = False,
)

Combine likelihoods from multiple observations into a single variable.

Parameters:

  • idata (InferenceData) – Inference data object containing log-likelihood samples.

  • combined_var_name (str) – Name to call the combined variable.

  • var_names (Optional[Sequence[str]]) – Variable names to include in the combination; if None, include all variables with a likelihood.

  • overwrite (bool) – Whether to overwrite combined_var_name, if it already exists.

  • combined_dim_name (str) – Name of the combined dimension.

  • copy_idata (bool) – Whether to add the new variable to the provided idata or to a copy.

Returns:

Inference data object with the new combined log-likelihood.

Return type:

az.data.inference_data.InferenceData