A Synthetic Benchmark and Real Reference Instance for Educational-Clinical Internship Scheduling with Reciprocal Supervision
Description
This dataset provides a reproducible benchmark for internship scheduling in university psychology clinics, a scheduling problem whose distinctive feature is reciprocal supervision: one student conducts a clinical session while a peer observes, and the roles are later exchanged, with three-way (triadic) observation cycles arising when no directly compatible pair exists. This relational coupling between two trainees, rather than between an actor and a resource, is absent from existing public scheduling and timetabling benchmarks. The dataset contains two components. The first is an anonymized real reference instance migrated from a university psychology clinic (141 students, 12 supervisors, 6 rooms, 4 sequential internship stages, 65 weekly time periods), carrying only synthetic identifier codes and no personally identifiable information. The second is a synthetic suite of 60 instances generated by a parametrized generator calibrated to the real instance, organized into six families that independently vary scale, availability density, temporal clustering, curriculum load, period capacity, and triadic stress (a ring-structured availability pattern that makes binary supervision pairs scarce while keeping triadic cycles feasible). Every instance is released in three interoperable formats generated from the same source: a relational SQLite database, per-table CSV files, and a JSON metadata record, together with a per-instance report. The package also includes the relational schema, the parametrized generator, the socio-academic attribute sampler, and the suite-orchestration script, so that the entire suite can be regenerated bit-for-bit from a single seeded configuration. Each instance is characterized by structural metrics computed directly from its data, independently of any solver: availability density, demand-to-slot ratio, and the pairing feasibility rate, defined as the edge density of a stage-specific temporal-compatibility graph (the fraction of same-stage student pairs whose availability windows intersect), together with triangle counts and triadic-necessity measures for studying triadic supervision. These metrics support research on instance difficulty, operational research and mathematical programming, constraint programming, metaheuristics, and difficulty-aware machine learning. Each student also carries socio-academic attributes (age, active semester, preferred shift, weekly work hours, commuting time, undergraduate-research participation, and prior course and stage failures) that are fully synthetic but calibrated to the marginals and principal correlations of the real cohort; no real student record is reproduced, and a per-student label table is reserved for supervised learning.
Files
Steps to reproduce
The entire synthetic suite and all reported structural metrics can be regenerated bit-for-bit from the files in this dataset. The real reference instance is provided as a frozen artifact and is not regenerated. Requirements: Python 3.10 or later, with the packages listed in code/requirements.txt (install with pip install -r code/requirements.txt). SQLite ships with Python; no database server is needed. 1. Inspect the schema. The relational schema shared by every instance is schema/schema.sql (twelve active tables plus one reserved extension table). It is applied automatically by the generator; no manual step is required. 2. Regenerate the full suite. From the dataset root, run: python code/generate_suite.py --suite config/suite_config.yaml This reads the six-family specification in config/suite_config.yaml, expands it into the individual instance configurations, invokes the generator for each, and writes the 60 instance directories plus the consolidated data/synthetic_suite/suite_summary.csv, suite_report.md, and suite_metadata.json. Because generation is fully seeded, the output is identical on every run. 3. Regenerate a single instance (optional check). The generator can be run directly on any instance configuration: python code/generator_core.py --config <instance_config.yaml> It writes an instance.sqlite, a csv/ folder, a metadata.json, and a per-instance report. 4. Recompute and verify the structural metrics. Each instance's metadata.json records availability density, the demand-to-slot ratio, the per-stage and mean pairing feasibility rate, the triangle counts and triadic-necessity measures, and the composite difficulty index; the consolidated data/synthetic_suite/suite_summary.csv holds the OR-core metrics for all instances. These are recomputed directly from each instance.sqlite during generation, so re-running the suite reproduces every reported value. 5. Verify integrity. Every instance.sqlite passes PRAGMA foreign_key_check with no violations. The real reference instance contains 141 students, 12 supervisors, 6 rooms, 4 stages, and 65 periods, with an availability density of about 0.0655 and a demand-to-slot ratio of about 0.38. Seeds and parameters: every instance records its generating seed and configuration in its metadata.json, so any instance can be reproduced in isolation. The socio-academic attribute sampler uses an independent random stream (seed offset 1,000,003), so enabling the attributes does not perturb the OR-core availability, pairing, or difficulty metrics. Re-running generate_suite.py with the unmodified suite_config.yaml reproduces the published suite exactly, including all availability matrices and derived metrics.
Institutions
- Universidade Estadual Paulista (Unesp)São Paulo, São Paulo