Multiarrangement - Video, Image, and Audio Similarity Arrangement Toolkit

Multiarrangement is an open-source toolkit for collecting human similarity judgments by arranging video, image, or audio stimuli on a 2D canvas. The package supports fixed-batch set-cover experiments and adaptive Lift-the-Weakest (LTW) experiments, then fuses trial-level layouts into representational dissimilarity matrices (RDMs) for downstream analysis.

Distances are computed between stimulus token centers. In the hosted web implementation, submitted center coordinates are interpreted relative to the arena center and scaled by the arena radius before RDM estimation, so equivalent layouts have the same geometry across screen sizes while exact raw coordinates remain available for trial reconstruction.

Repository layout

• multiarrangement/ and coverlib/: desktop package source, demos, bundled media, and covering-design utilities
• server/: FastAPI backend for hosted studies
• web/: Next.js frontend for setup, participation, results, and admin flows
• paper/: manuscript sources, figures, and compiled reference PDFs
• tests/ and server/tests/: regression tests for the package and hosted stack
• multiarrangement/examples/: runnable example scripts

The schedule generator uses a monotonic candidate portfolio: certified constructions, residual exact repair, cyclic/one-rotational search, and bounded local search are compared with the existing LJCR and balanced-cache schedules. The nondominated frontier is shared by the desktop package and server. See CERTIFIED_SCHEDULING.md for the guarantees and objective order.

The current certified audit improves 66 of the 745 historical cache parameter pairs in at least one mode (30 compact, 66 balanced), without deleting any valid prior candidate.

Quick demo

Bundled package assets include:

• videos: multiarrangement/15videos/*
• images: multiarrangement/15images/*
• audio: multiarrangement/15audios/*, multiarrangement/sample_audio/*
• instruction clips: multiarrangement/demovids/*
• cached covering designs: multiarrangement/ljcr_cache/*.txt
• certified runtime frontier: multiarrangement/frontier_cache/index.json

Install

From PyPI:

python -m pip install multiarrangement

Or from the repository root:

python -m pip install .

Requirements:

• Python 3.8 or newer
• NumPy 1.20+
• pandas 1.3+
• pygame 2.0+
• opencv-python 4.5+
• matplotlib 3.4+
• openpyxl 3.0+

Python API quickstart

Set-cover demo with bundled media:

import multiarrangement as ma

ma.demo()

Adaptive LTW demo with bundled media:

import multiarrangement as ma

ma.demo_adaptive()

Minimal set-cover experiment:

import multiarrangement as ma

input_dir = "path/to/input"
output_dir = "path/to/output"

batches = ma.create_batches(ma.auto_detect_stimuli(input_dir), 8)
results = ma.multiarrangement(input_dir, batches, output_dir)
results.vis()
results.savefig(f"{output_dir}/rdm_setcover.png", title="Set-cover RDM")

Fixed-batch schedules are ordered for balanced early prefixes by default. Group studies can additionally request deterministic isomorphic schedules that spread repeated-pair bias across participants:

batches = ma.create_batches(
    58,
    8,
    counterbalance=True,
    participant_index=participant_number,
    counterbalance_family_size=16,
)

Minimal adaptive LTW experiment:

import multiarrangement as ma

input_dir = "path/to/input"
output_dir = "path/to/output"

results = ma.multiarrangement_adaptive(input_dir, output_dir)
results.vis()
results.savefig(f"{output_dir}/rdm_adaptive.png", title="Adaptive LTW RDM")

Pass skip_initial=True (or the skip_first=True alias) to begin directly with an LTW-selected subset instead of the all-item orientation trial.

Example scripts are included under multiarrangement/examples/.

Outputs

Typical outputs include:

• fused RDMs
• per-trial logs
• schedule metadata
• evidence matrices for adaptive runs
• JSON, CSV, XLSX, and NumPy exports, depending on the workflow

Citation and support

Please cite the software using CITATION.cff. Archival metadata for Zenodo is included in .zenodo.json.

Source code, releases, documentation updates, and issue tracking are available at:

https://github.com/UYildiz12/Multiarrangement-for-videos

License

MIT License. See LICENSE.