How to Use OpenScales

OpenScales provides validated psychological scales in a machine-readable format ready to run in multiple contexts. Choose the pathway that best fits your study design.

Creating scales? The PEBL Launcher's built-in ScaleBuilder is the primary tool for authoring OSD-compliant scale definitions — no JSON editing required. See below.

Creating Scales with the PEBL Launcher ScaleBuilder

The PEBL Launcher ships with a graphical ScaleBuilder — a dedicated GUI editor for creating and editing scales in the OpenScale Definition (OSD) format. It is the recommended, authoritative way to author new scales and to edit existing ones. All output is a valid OSD JSON file that can be run immediately by the ScaleRunner (PEBL desktop, peblhub.online, or the browser runner) or exported to any supported format via the Convert tools.

Launching the ScaleBuilder

  1. Download and install PEBL from pebl.sourceforge.net. The Launcher is included with all PEBL installations.
  2. Open the PEBL Launcher application.
  3. Select the Scale Builder tab (or choose New Scale from the File menu to start from scratch, or Open Scale to load an existing {CODE}.json file).

What You Can Edit

Tab / Panel What you configure
Scale Info Name, abbreviation, description, citation, license, version, URL, domain
Items Question text, item IDs, item types (multi, likert, VAS, text, instruction, image), response options and values, item-level coding direction
Scoring Scoring dimensions / subscales, item membership, scoring method (sum, mean, proportion, etc.), correct-answer keys
Norms Interpretation thresholds per dimension (e.g., Minimal / Mild / Moderate / Severe), min/max cutoffs and labels used to annotate score reports
Translations Per-language string overrides for item text, response labels, and instructions; saved as separate {CODE}.{lang}.json files

Saving and Using the Output

Clicking Save writes a fully-validated {CODE}.json definition file (and any translation files) to the location you choose. Place the resulting files in scales/{CODE}/ within the OpenScales repository and rebuild the manifest: 

python3 tools/build_manifest.py

The scale is then immediately available in the browse catalogue and all runner environments.

Tip: Round-Trip Safety

Always use the ScaleBuilder (or a full OSD-aware editor) to modify scale JSON files. Hand-editing the JSON is possible but risks stripping fields that are not yet surfaced in every tool — the Launcher preserves all OSD fields on save, including norms and custom metadata.

Run Scales via PEBL (Desktop)

PEBL (Psychology Experiment Building Language) is a free, cross-platform tool for running behavioral experiments and surveys on Windows, Mac, and Linux. It reads OpenScales definitions directly and saves data locally as CSV — ideal for lab-based or offline data collection.

Setup

  1. Download and install PEBL from pebl.sourceforge.net.
  2. Place (or clone) the OpenScales repository folder next to the PEBL installation, or anywhere accessible on your machine.
  3. Open PEBL, choose File > Open, and navigate to:
    pebl/media/apps/scales/ScaleRunner.pbl
  4. Run the file. A configuration dialog appears before the task starts.

Configuration Parameters

Parameter Description Example
Scale Code The short code identifying the scale to run PHQ9
Participant ID A string identifier written into the output file P001
Language Two-letter language code for the translation to load en
Collect URL (Optional) peblhub endpoint to upload results automatically https://peblhub.online/collect

After completion, data is written as a CSV file to PEBL's configured output directory (typically ~/pebl-exp/data/ or the directory you specified at launch). One row per item response is written, plus summary score columns for each dimension.

Pros and Cons

Pros Cons
  • Fully local — no internet connection required
  • Full CSV output with item-level and summary data
  • Works on Windows, Mac, and Linux
  • Easy to integrate into existing PEBL experiment batteries
  • Requires PEBL installation on each testing machine
  • Not suitable for unattended remote data collection

Run Scales via peblhub.online

peblhub.online is a web platform for running PEBL-compatible surveys directly in a participant's browser — no installation required. It is well suited to remote and online studies where participants access the task via a shared link.

Steps

  1. Create an account at peblhub.online or log in if you already have one.
  2. Select or upload a scale. OpenScales definitions are often available directly in the peblhub library. If your scale is not listed, upload the SCALECODE.json and SCALECODE.en.json files from the OpenScales repository.
  3. Configure the study — set the scale code, language, and any scale parameters you want to override for this run.
  4. Share the participation link with your participants. The URL follows this format:
https://peblhub.online/run?scale=PHQ9&participant=SUBID&collect=https://peblhub.online/collect/STUDYID

Replace SUBID with a participant identifier (or use a variable that your recruitment platform injects) and STUDYID with your peblhub study ID.

  1. Download data from the peblhub dashboard as a CSV file once participants have completed the study. The file format matches the PEBL local output.

Integration with OpenScales Runner

peblhub uses the same OpenScales runner under the hood. The collect URL parameter tells the runner where to POST the result data when the participant finishes. If you omit collect, results are not saved — useful for demos.

Run a Demo in the Browser (No Data Saved)

Any scale in OpenScales can be previewed instantly in your browser using the built-in runner, without creating an account or saving any data. This is useful for piloting a scale, demonstrating it in a class, or checking translations.

From the Scale Detail Page

Navigate to any scale in the catalogue, then click the ▶ Run Demo button in the sidebar. The runner opens with demo=1 set automatically, so no data is uploaded.

Direct URL

You can also open the runner directly with a URL:

../runner/scale-runner.html?scale=PHQ9&lang=en&demo=1

URL Parameters

Parameter Required Default Description
scale Yes — Scale code, e.g. PHQ9
lang No en Two-letter language code
participant No — Participant identifier written into output
collect No — URL to POST result data to on completion
demo No — Set to 1 to disable all data saving (demo mode)
redirect No — URL to navigate to after the scale is completed
param_* No — Override a named scale parameter, e.g. param_cutoff=10

Self-Hosting Survey Collection with collect.php

If you want to collect real participant data without using peblhub.online, the repository includes a minimal PHP endpoint — runner/server/collect.php — that you can drop onto any PHP-capable web host. It receives the POST that scale-runner sends on completion and writes structured CSV files to the server.

Requirements

  • A web server running PHP 7.4 or later (Apache, nginx + PHP-FPM, or any shared host)
  • The web server process must have write permission to the server/data/ directory
  • HTTPS strongly recommended for any study collecting real participant responses

Deployment Steps

  1. Copy the server folder to your web host. You only need two files: 
    runner/server/collect.php
runner/server/.htaccess   ← create this (see Security section below)
  2. Create the data directory and make it writable: 
    mkdir -p server/data
chmod 755 server/data
    The script creates per-scale subdirectories automatically on first use.
  3. Verify the endpoint is reachable. A GET request should return HTTP 405 (Method Not Allowed) — that confirms PHP is running: 
    curl -I https://your-server.example.com/server/collect.php
# Expected: HTTP/2 405
  4. Link the runner to your endpoint using the collect URL parameter and a participant identifier. In a study you would inject the participant ID from your recruitment platform (Prolific, SONA, etc.): 
    https://your-server.example.com/runner/scale-runner.html
  ?scale=PHQ9
  &lang=en
  &participant=PROLIFIC_PID
  &collect=https://your-server.example.com/server/collect.php
    Replace PROLIFIC_PID with the variable your platform provides (e.g., {{%PROLIFIC_PID%}} for Prolific, %7BSONA_ID%7D for SONA).

Output File Structure

After a participant completes a scale, collect.php writes two files under server/data/{SCALE_CODE}/:

File Contents
{SCALE}-{PARTICIPANT}.csv One row per item response: participant ID, timestamp, elapsed time, item ID, response value, and coded value. One file per participant.
pooled.csv Summary scores for all participants appended into a single file — one row per completed session, with a header written automatically on the first record. Ready to open in R, Python, or Excel.

Download these files via SFTP, or add an authenticated download script to your server. Do not expose the data/ directory over HTTP without access controls (see below).

Security Hardening

By default, collect.php accepts POST from any origin. For a real study you should restrict access. Create a server/.htaccess file: 

# Block all direct browser access to the data directory
<IfModule mod_authz_core.c>
    <Directory "data">
        Require all denied
    </Directory>
</IfModule>

# Optional: restrict collect.php to known origins only
# (remove or adjust the Allow lines to match your runner's domain)
<Files "collect.php">
    Header set Access-Control-Allow-Origin "https://your-runner-domain.example.com"
</Files>

If you want to require a shared secret token (to prevent anyone on the internet posting fake data), set the token URL parameter in your runner links and validate $_POST['token'] at the top of collect.php: 

// Add near the top of collect.php, after reading $scale / $participant:
$secret = 'CHANGE_THIS_TO_A_LONG_RANDOM_STRING';
if (($_POST['token'] ?? '') !== $secret) {
    json_response(403, ['error' => 'Forbidden']);
}

Then add &token=CHANGE_THIS_TO_A_LONG_RANDOM_STRING to all your runner URLs. The token travels over HTTPS so it stays private.

Redirect Participants on Completion

Use the redirect URL parameter to send participants to a debriefing page or back to your recruitment platform after the scale completes: 

?scale=PHQ9&participant=P001&collect=https://…/collect.php
  &redirect=https://app.prolific.com/submissions/complete?cc=YOURCODE

Export to Other Platforms

If your research workflow uses a platform other than PEBL, you can convert OpenScales definitions into formats accepted by REDCap, LimeSurvey, Qualtrics, PsyToolkit, and QTI-compatible systems.

Web Interface

Use the Convert page to select a scale and target format. The converted file is generated in your browser and ready to download.

Command-Line Tools

Conversion scripts are available in the tools/ directory of the repository:

# Convert PHQ9 to a REDCap data dictionary CSV
python3 tools/convert_to_redcap.py scales/PHQ9/ --output PHQ9_redcap.csv

# Convert to LimeSurvey .lss format
python3 tools/convert_to_limesurvey.py scales/PHQ9/ --output PHQ9.lss

# Convert to Qualtrics .qsf format
python3 tools/convert_to_qualtrics.py scales/PHQ9/ --output PHQ9.qsf

Citing Scales

Always cite the original scale authors when you use a scale in a publication or report. The citation for each scale is shown on its detail page and stored in the citation field of the scale definition file.

If you use the OSD (Open Scale Definition) format itself in your work — for example, if you distribute a scale you have defined using this format — please also cite the OpenScales repository: 

Mueller, S. T. (2024). OpenScales: An open repository of psychological measurement instruments
in machine-readable format. Retrieved from https://github.com/stmueller/OpenScales

License terms for individual scales vary. Always check the License field on the scale detail page before using a scale in commercial or redistributed contexts.