Metadata-Version: 2.4
Name: multiarrangement
Version: 1.0.1
Summary: Video and audio similarity arrangement toolkit (set-cover and adaptive LTW)
Author: Umur Yildiz
License-Expression: MIT
Project-URL: Homepage, https://github.com/UYildiz12/Multiarrangement-for-videos
Project-URL: Repository, https://github.com/UYildiz12/Multiarrangement-for-videos
Project-URL: Documentation, https://github.com/UYildiz12/Multiarrangement-for-videos#readme
Project-URL: Bug Tracker, https://github.com/UYildiz12/Multiarrangement-for-videos/issues
Keywords: psychology,experiment,video,similarity,multiarrangement,rdm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: pygame>=2.0.0
Requires-Dist: opencv-python>=4.5.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: scipy>=1.9
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: coverlib
Requires-Dist: urllib3; extra == "coverlib"
Requires-Dist: requests; extra == "coverlib"
Dynamic: license-file

# Multiarrangement - Video, Image, and Audio Similarity Arrangement Toolkit

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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`](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

![Multiarrangement Demo](similar_demo.gif)

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:

```bash
python -m pip install multiarrangement
```

Or from the repository root:

```bash
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:

```python
import multiarrangement as ma

ma.demo()
```

Adaptive LTW demo with bundled media:

```python
import multiarrangement as ma

ma.demo_adaptive()
```

Minimal set-cover experiment:

```python
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:

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

Minimal adaptive LTW experiment:

```python
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`.
