Shuffle: A Tool for Generating Quasi-Randomised Stimulus Lists with Sequential Constraints

Experimental psychologists routinely need to randomise the order of trials across participants while avoiding undesirable sequential patterns, for example, long runs of trials belonging to the same stimulus category, or target items appearing too close together. We present shuffle, a freely available, cross-platform tool for generating quasi-randomised sequences that satisfy user-defined sequential constraints. Input is a plain-text or CSV table whose rows represent trials and whose columns represent categorical variables (\textit{e.g.}, stimulus type, response mapping, condition). Two types of constraint can be imposed on any column: a *maximum-repetition* constraint limits the number of consecutive rows that may share the same label, and a *minimum-gap* constraint requires a minimum number of intervening rows between any two rows sharing the same label. Two algorithms are provided. The *constructive* algorithm builds a valid permutation row by row and is very fast. The *equiprobable* algorithm draws random permutations repeatedly until one satisfies the constraints, guaranteeing an unbiased sample from the set of valid permutations; it is slower but preferable when distributional properties of the randomisation matter. Shuffle-go is implemented in Go and distributed as self-contained binaries for Windows, macOS, and Linux (both x86-64 and ARM64), requiring no runtime installation. It offers a command-line interface, two graphical desktop interfaces, an embeddable Go library, and a Python library. Source code is available at https://github.com/chrplr/shuffle-go under the GPLv3 licence.