SKULDORDER / ENGLISH MANUAL / 1.0.0
From stimulus table to reviewed trial orders
SkuldOrder prepares constrained order CSVs locally. This manual uses a fictional 12-word study to show a complete first result.
Prerequisites: A desktop Chrome browser that can open local files, and the extracted SkuldOrder ZIP. No server or account is required. Tested here in Chrome 152 on Linux. Printing uses Chrome Print / Save as PDF. The narrow view is for review and basic control; a desktop width is more comfortable for editing wide tables.
Three steps to a first result
- Extract the buyer ZIP and open
app/SkuldOrder.html. The 12-row fictional words example is already loaded. You can also choose Load fictional example. - Leave maximum consecutive same condition at 2, blocks at 1, 2, seed at skuld-demo-1, and requested orders at 4. Select Generate orders.
- Inspect all four order tabs. Each order has 12 rows, six A and six B, two six-row contiguous blocks, and no condition run longer than two. Select Download order pack.
Figure 1. The actual 12-word example after generation in desktop Chrome.The resulting SkuldOrder-orders.zip contains order_01.csv through order_04.csv, order_index.csv, source_input.csv, settings.json, REVIEW.html and README.txt. Each order CSV has the original columns and one literal source row per trial. The original CSV is never overwritten.
Use your own CSV
Select Import CSV or paste into the editor and select Apply pasted CSV. Both use the same UTF-8 CSV parser. Quoted commas, quotes and newlines in cells are supported. Choose the row ID and condition columns; a block column is optional. The preview helps confirm the mapping. Every row ID must be unique and nonblank, and each condition must be nonblank. Additional stimulus columns are kept as text in exported CSV.
Headers must be unique ASCII names starting with a letter and then letters, digits or underscores, such as item_id or word. This conservative rule avoids headers that the tested PsychoPy importer may reject. Row IDs and block values may not contain commas because the v1 fixed-position and block-order forms use comma separators. Correct invalid input and apply again; an import error leaves the previous valid table intact.
Constraints and reproducibility
| Rule | Meaning |
|---|
| Maximum consecutive same condition | For A, A, B the longest A run is 2. This is checked across block boundaries. |
| Minimum intervening rows | Choose a grouping column. A value of 1 keeps matching values from adjacent positions. Zero turns this rule off. |
| Block order | List each existing block exactly once. Blocks stay contiguous in that order. |
| Fixed positions | Put one row_id,position per line. Positions start at 1 across the whole sequence. |
The seed is visible. Reusing exactly the same source table, mappings, rules, requested count, seed and version produces the same completed orders. Generation uses a deterministic bounded search. It does not sample uniformly or cryptographically. Duplicate complete sequences are detected and do not count toward the request.
A request is complete only when all requested distinct orders are found. A partial result names the number found. Select the valid found orders to include with the export checkboxes; none are selected automatically in a partial result. The settings file records the unmet request and selected export count. “Search budget exhausted” means no result was found within the limit, not proof of impossibility. Use Cancel to stop after the next search yield.
Review, print and export
Each order tab shows position, original columns, condition text and color, condition counts, longest run, gap and fixed-position status. An independent row-by-row validator checks all source IDs, order, blocks and rules before export. Print review prints all generated orders, including later pages; Chrome can save it as PDF. The ZIP also contains a standalone REVIEW.html with all orders. Review content escapes text; experiment CSV keeps literal stimulus values.
Figure 2. Actual 390px Chrome view. Wide CSV columns scroll inside their tables.Spreadsheet safety: SkuldOrder rejects nonnumeric cell text beginning with =, +, - or @ after whitespace. It does not silently prefix apostrophes or claim that CSV quoting prevents formulas. Correct the cell before generating. Treat exported experiment CSV as data; do not enable spreadsheet macros or imported formulas.
Save and reopen work
Save project downloads a JSON file with the source table, mapping, rules, seed, requested count and any generated orders. It also works before generation. Open project validates the file and its stored orders. Editing input, mapping, rules, seed or requested count marks the design unsaved and invalidates current orders; generate again before export. A rejected project leaves the current design, result, selection and unsaved state intact. A ZIP already downloaded remains unchanged.
Use an order in PsychoPy core
The included examples/psychopy_sequential.py demonstrates loading a generated CSV with psychopy.data.importConditions and iterating a TrialHandler(..., method='sequential'). An earlier builder check with PsychoPy core 2026.2.4 and Python 3.11.14 loaded sample CSVs through this API and compared the sample word IDs and text stimuli in sequence. A separate exact-package review repeated the core check on sample, maximum and independently authored inputs. The test is text-only. It does not establish Builder GUI, visual or sound timing, Pavlovia or online compatibility.
CSV text and host values: SkuldOrder writes source cells literally. A consumer may infer types while loading them: a value such as 001 may become numeric 1, and 1e3 may become numeric 1000. The sample core check used word IDs and text stimuli; it does not prove that numeric-looking identifiers survive PsychoPy import as strings. Test your own identifiers and conditions in your experiment host. Keep identifiers text-safe when leading zeros or notation matter.
In a separately installed PsychoPy Builder, the analogous setup is to select one generated CSV as the loop conditions file and choose a sequential loop, then test your own experiment. This is guidance from the official Flow documentation, not a claim that this package was exercised in Builder. Check column types and task-specific needs in your host before collecting data.
Limits and troubleshooting
Maximum: 200 rows, 12 columns, 8 blocks, 20 requested distinct orders, 1 MiB imported CSV, 8 MiB opened project, 10,000 characters per cell, and 20,000 search nodes per order attempt. The search tries a bounded series of seeded attempts. These bounds keep local work manageable, but difficult feasible constraints may remain unresolved.
- Wrong row count or duplicate IDs: correct the CSV; no rows are silently skipped.
- Fixed position conflicts with block: positions count across all blocks. Move the anchor into its block range or change block order.
- Zero or partial orders: inspect rule conflicts, relax a rule explicitly if appropriate, or try a different seed. Exhaustion does not prove impossibility.
- Generation failed: read the displayed error, check the input and rules, then select Generate orders again. Failed partial results cannot be exported; your source and edits remain available.
- Project will not open: use a 1.0.0 SkuldOrder project JSON, not an exported
settings.json from an order ZIP. - Print seems incomplete: choose Print review and let Chrome finish the preview; all orders are included on subsequent pages.
Privacy and uninstall
The app runs from local files, sends no table data to a service and does not save the project in browser storage. Downloads go to the browser's chosen download location. To uninstall, close the tab and delete the extracted app, downloaded projects and order packs that you no longer need.
Documentation sources: PsychoPy installation, PsychoPy data API, PsychoPy Flow. Accessed 2026-10-05.