Category: Study Management Level: Intermediate Reading time: 8 minutes Updated: 2026-01-03

Study Snapshots & Version Control

Quick Summary: Snapshots capture your study configuration at specific points in time, enabling reproducibility, version tracking, and rollback capabilities.

What You'll Learn

What study snapshots are and why they're important for research
How snapshots are automatically created during study lifecycle transitions
What information is included in (and excluded from) snapshots
How to view snapshot history and download snapshot packages
How to use snapshots for reproducible research

Overview

Study snapshots are immutable captures of your study's complete configuration at a specific point in time. They serve as version control for your research studies, similar to git commits for code.

Why Snapshots Matter

Reproducibility: Scientific research requires that experiments can be replicated. Snapshots ensure you can recreate the exact test configuration used for any participant, even if you later modify parameters or update tests.

Version tracking: As your study evolves (e.g., pilot → active → public), snapshots document each change, creating an audit trail of your methodology.

Collaboration safety: When multiple researchers work on a study, snapshots prevent confusion about which configuration is "official" for data collection.

Publication requirements: Many journals now require detailed methodology documentation. Snapshot packages provide complete, machine-readable study specifications.

When Snapshots Are Created

Snapshots are automatically created when:

Study activated: Moving from draft → pilot or pilot → active
Study made public: Moving to public state
Study reactivated: Changing from disabled back to active
Manual request (if implemented)

Snapshots are not created for:

Routine parameter edits while study is in draft
Adding/removing tests while in draft
Editing study name, description, or notes
Collaborator changes

Important: Once a snapshot is created, it's immutable. You cannot edit or delete snapshots. This ensures research integrity.

What's Included in a Snapshot

Each snapshot captures:

✅ Test list: Which tests are included in the study ✅ Test parameters: Complete parameter JSON for each test ✅ Test file metadata: Filenames and modification dates (not file contents) ✅ Chain configurations: Complete test sequences with consent forms, HTML pages ✅ Custom translations: All custom translation JSON files ✅ Battery version: Which version of PEBL battery was used ✅ PEBL version: Which version of PEBL runtime compiled the tests ✅ Platform version: Which version of PEBLOnlinePlatform hosted the study ✅ Creator info: Who created the snapshot and when

What's Excluded from Configuration Snapshots

Configuration snapshots (the snapshot.json package) do not include:

❌ Test file contents: .pbl source code (stored in frozen bundles instead) ❌ Media files: Images, audio files (stored in frozen bundles instead) ❌ Participant data: CSV files, responses, session records ❌ Study metadata: Study name, description, notes (can change without affecting validity) ❌ Collaborators: Who has access (administrative, not scientific)

Rationale: Configuration snapshots focus on study configuration (what parameters you set, which tests you chose, what chains you created) while minimizing storage overhead. Test source code and media files are preserved separately in frozen bundles (see Frozen Snapshots).

Important distinction:

Configuration snapshots (this document): Document your study setup (parameters, chains, settings)
Frozen bundles (Frozen Snapshots): Preserve the actual test files (.pbl scripts, images, sounds)

Together, these two systems provide complete reproducibility: configuration snapshots show what you configured, and frozen bundles preserve what participants actually ran.

Step-by-Step Guide

Step 1: Viewing Snapshot History

Log in to PEBL Hub
Go to My Studies
Click on your study name
In the study management page, click "📦 View Snapshot History"

You'll see a list of all snapshots for this study, ordered from newest to oldest.

What you'll see for each snapshot:

Version name: Auto-generated (e.g., "Version 1", "Version 2") or custom notes
Current badge: Green badge indicating which snapshot is currently active
Snapshot ID: Unique identifier like SNAP_a8f3e7b2c4d1... (first 32 characters of checksum)
Created date/time: When the snapshot was captured
Created by: Username who triggered snapshot creation
Battery version: Which PEBL battery release (e.g., 2.2, 2.3)
PEBL version: Which PEBL compiler version
Tests included: List of all tests in the snapshot

Current snapshot: The snapshot marked with a green "✓ Current" badge is the configuration currently being used for new participants. This is the snapshot that was active when the study entered its current state.

Step 2: Downloading a Snapshot Package

Snapshot packages are ZIP files containing all configuration files needed to reproduce the study.

To download:

Go to Snapshot History for your study
Find the snapshot you want to download
Click "📥 Download Package"
Your browser will download a ZIP file named:

{StudyName}_{Version}_{SnapshotID}.zip

Package contents:

StudyName_v1_SNAP_a8f3e7b2.zip
├── snapshot.json           # Complete configuration metadata
├── tests/
│   ├── corsi/
│   │   └── params/
│   │       └── corsi.json  # Parameter configuration
│   ├── stroop/
│   │   └── params/
│   │       └── stroop.json
│   └── ...
├── chains/
│   ├── chain_001.json      # Test sequence configuration
│   └── ...
├── translations/
│   ├── corsi.pbl-es.json   # Custom Spanish translation
│   └── ...
└── README.txt              # Human-readable summary

snapshot.json structure:

{
  "token_id": "STUDY_ABC123",
  "study_name": "Memory Study 2026",
  "researcher_username": "shanem",
  "created_at": "2026-01-03 10:30:00",
  "battery_version": "2.2",
  "pebl_version": "2.2.0",
  "platform_version": "1.0.0",
  "snapshot_created_at": "2026-01-03 15:45:00",
  "tests": [
    {
      "test_id": "corsi",
      "test_name": "Corsi Block Tapping Task",
      "main_file": "corsi.pbl",
      "category": "Memory",
      "duration_minutes": 10,
      "files": [
        {"path": "corsi.pbl", "modified": "2025-12-15 08:30:00", "size": 15234}
      ],
      "parameters": {
        "forward_trials": 3,
        "backward_trials": 3,
        "starting_length": 3
      }
    }
  ],
  "chains": [
    {
      "chain_id": "CHAIN_001",
      "chain_name": "Main Test Battery",
      "items": [
        {"item_type": "consent", "consent_required": true},
        {"item_type": "test", "test_name": "corsi"},
        {"item_type": "test", "test_name": "stroop"}
      ]
    }
  ],
  "translations": []
}

Step 3: Viewing Snapshot Details

For detailed inspection without downloading:

Go to Snapshot History
Find the snapshot you want to inspect
Click "👁 View Details"

This expands an inline view showing:

Complete JSON configuration
All parameter values
All tests and their settings
Chain configurations

Use case: Quickly check parameter values used in a specific version without downloading the full package.

Step 4: Understanding Snapshot Checksums

Each snapshot has a unique Snapshot ID derived from a SHA-256 checksum of its configuration.

How checksums work:

System collects all configuration data:

Battery version

Test file metadata (names, dates)
Complete parameter JSON
Complete chain JSON
Complete translation JSON

Concatenates into a deterministic string
Computes SHA-256 hash
Uses first 32 characters as Snapshot ID

Benefits:

Deduplication: If you activate the same configuration twice, the system reuses the existing snapshot instead of creating a duplicate
Integrity verification: Checksum changes if any scientifically-relevant setting changes
Version comparison: Different Snapshot IDs guarantee different configurations

Example scenario:

You activate your study (creates Snapshot A), then deactivate it to make parameter edits. If you change parameters and reactivate, a new Snapshot B is created with a different ID. If you undo your changes back to the original parameters and reactivate, the system reuses Snapshot A instead of creating a duplicate.

Step 5: Using Snapshots for Reproducible Research

Publishing your methods section:

Download the snapshot package for your study
Upload the snapshot.json file to a public repository (GitHub, OSF, Zenodo)
Include the Snapshot ID and download link in your paper's methods section
Readers can download and inspect your exact test configuration

Example citation:

"We used the PEBL Corsi Block Tapping Task (battery v2.2) with the following configuration: forward trials=3, backward trials=3, starting length=3. Complete study configuration is available at https://osf.io/abc123/ (Snapshot ID: SNAP_a8f3e7b2c4d1...)."

Replicating your study:

Download the snapshot package
Create a new study in PEBL Hub
Add the same tests listed in snapshot.json
Upload the parameter JSON files from the package
Configure chains to match chains/ directory
Upload custom translations from translations/ directory

The new study will use the same configuration as your original research.

Comparing studies across time:

If you run the same protocol multiple times (e.g., 2024 cohort, 2025 cohort, 2026 cohort):

Each cohort gets its own study
Each study creates its own snapshot when activated
Download all snapshots and compare snapshot.json files
Document any differences in your paper

This proves consistency (or documents intentional changes) across cohorts.

Common Issues

Problem: No snapshots showing in history

Solution:

Ensure your study has been activated at least once
Snapshots are only created when moving to pilot, active, or public states
Draft studies don't have snapshots yet
Click "Activate Study" to create the first snapshot

Why this happens: Snapshots are created on lifecycle transitions to capture "official" configurations. Draft mode is for experimentation and doesn't need versioning.

Problem: Downloaded ZIP is empty or corrupt

Solution:

Try downloading again - network interruption may have occurred
Check that you have permission to download from this study (owner or collaborator with view rights)
Verify your browser isn't blocking the download
Try a different browser

Why this happens: Large snapshots (many tests with complex parameters) can occasionally timeout during ZIP generation. Package building is done on-demand, not pre-generated.

Problem: Snapshot shows old parameters, not current ones

Solution:

Check which snapshot is marked "Current" - that's what participants see
If you've edited parameters since activation, those changes aren't in the current snapshot
Deactivate and reactivate the study to create a new snapshot with updated parameters
The old snapshot is preserved for reproducibility

Why this happens: Snapshots are immutable and only created on state transitions. Parameter edits in active studies don't automatically update the snapshot. This is intentional to prevent configuration drift during data collection.

Best practice: Make all parameter changes in draft mode, then activate to lock them in.

Problem: Two snapshots look identical but have different IDs

Solution:

Click "View Details" on both snapshots
Compare the JSON carefully - there is guaranteed to be a difference
Common subtle differences:

Test file modification dates changed (battery update)

Parameter value changed (even by a single character)
Chain item reordered
Translation added/removed

Why this happens: Checksums are highly sensitive. Even trivial changes (whitespace in JSON, file timestamp updates) produce different hashes.

Problem: Can't create a snapshot manually

Solution: This feature is not currently available through the UI. Snapshots are automatically created on state transitions.

Workaround:

Deactivate your study
Reactivate it immediately
A new snapshot will be created

Why this happens: Manual snapshot creation could lead to confusion about which version is "official". The automatic creation on state changes provides clear, audit-trailed versioning.

Problem: Want to delete a snapshot

Solution: Snapshots cannot be deleted by design. This ensures research integrity and reproducibility.

Rationale: If you could delete snapshots, you could:

Remove evidence of configuration changes
Break reproducibility for published papers
Violate audit trail requirements

If a snapshot contains sensitive information (e.g., participant IDs accidentally included), contact your system administrator.

Best Practices

Before Activating Your Study

Finalize all parameters in draft mode: Make all test configurations, chain setups, and translations before activation
Test with pilot data: Run a few pilot sessions to verify the configuration works as intended
Document your intent: Use study notes to explain what this version is for
Review the snapshot after activation: Immediately download and inspect the snapshot to confirm it captured your settings correctly

During Active Data Collection

Don't edit parameters: Once activated, avoid parameter changes unless absolutely necessary
If you must edit: Deactivate → Edit → Reactivate to create a new snapshot
Note the transition date: Record when you switched from Snapshot A to Snapshot B so you can segment participants by version
Download snapshots immediately: After creating a new snapshot, download it and store it with your research files

For Publication

Upload to permanent repository: Use OSF, Zenodo, or GitHub to host snapshot.json
Assign DOI: These repositories can mint DOIs for your configuration
Include in methods section: Reference snapshot ID and download link
Include checksum in supplementary materials: The full SHA-256 hash provides extra verification

For Multi-Site Studies

Share snapshot package: Send ZIP to collaborating sites
Verify matching configuration: All sites should use identical parameters
Compare Snapshot IDs: After each site activates, compare IDs to confirm they match
Centralize parameter changes: One coordinator should manage parameter updates and redistribute snapshots

For Longitudinal Studies

One study per wave: Create separate studies for Year 1, Year 2, etc.
Reuse snapshot configurations: Download Year 1 snapshot, use it to configure Year 2
Document intentional changes: If parameters must change between waves, document why in study notes
Maintain snapshot archive: Keep all snapshots from all waves for comparison

Advanced: Snapshot Comparison

While the UI doesn't currently show a visual diff, you can manually compare snapshots:

Using command-line tools:

# Download two snapshots
unzip Study_v1_SNAP_abc123.zip -d snapshot1/
unzip Study_v2_SNAP_def456.zip -d snapshot2/

# Compare JSON files
diff snapshot1/snapshot.json snapshot2/snapshot.json

# Or use a JSON diff tool
jq -S '.' snapshot1/snapshot.json > sorted1.json
jq -S '.' snapshot2/snapshot.json > sorted2.json
diff sorted1.json sorted2.json

Using online tools:

Download both snapshots
Extract snapshot.json from each
Use an online JSON diff tool like jsondiff.com
Paste both JSON files and compare

What to look for:

battery_version changed → Battery update
tests[].parameters changed → Parameter modification
tests[] array different length → Test added/removed
chains[].items different → Test sequence changed

Study Snapshots & Version Control

What You'll Learn

Overview

Why Snapshots Matter

When Snapshots Are Created

What's Included in a Snapshot

What's Excluded from Configuration Snapshots

Step-by-Step Guide

Step 1: Viewing Snapshot History

Step 2: Downloading a Snapshot Package

Step 3: Viewing Snapshot Details

Step 4: Understanding Snapshot Checksums

Step 5: Using Snapshots for Reproducible Research

Common Issues

Problem: No snapshots showing in history

Problem: Downloaded ZIP is empty or corrupt

Problem: Snapshot shows old parameters, not current ones

Problem: Two snapshots look identical but have different IDs

Problem: Can't create a snapshot manually

Problem: Want to delete a snapshot

Best Practices

Before Activating Your Study

During Active Data Collection

For Publication

For Multi-Site Studies

For Longitudinal Studies

Advanced: Snapshot Comparison

Related Topics

Related Topics