OSF Backend Setup¶

Setting up data collection with JSPsych DataPipe and Open Science Framework

Overview¶

The Open Science Framework (OSF) provides a robust, free platform for research data management. Combined with JSPsych DataPipe, it offers secure, automated data collection for O-ELIDDI studies with built-in research best practices.

Key Benefits¶

Free & Open	Secure	Research-Ready	Automatic
Completely free for academic research with unlimited storage and no participant limits.	Data encrypted in transit and at rest, with granular access controls and audit trails.	Built-in version control, metadata management, and collaboration tools for research teams.	No server setup required - data flows automatically from your study to OSF storage.

Prerequisites¶

Before you begin, ensure you have:

[ ] An OSF account (free at osf.io)
[ ] A deployed O-ELIDDI study (see GitHub Pages Deployment guide)
[ ] Basic understanding of your study's data collection needs
[ ] Institutional ethics approval (if required)

Step-by-Step Setup¶

1. Create OSF Account¶

If you don't already have an OSF account:

Visit osf.io
Click "Sign Up"
Use your institutional email address if available
Verify your email address
Complete your profile with research information

Tip: Using an institutional email helps establish credibility and may provide access to additional OSF features.

2. Create a New OSF Project¶

Set up a project to organize your study data:

Log into OSF and click "Create new project"
Enter a descriptive project title (e.g., "Daily Activity Patterns Study 2024")
Add a project description including:
Study objectives and research questions
Participant demographics and recruitment
Data collection timeline
Analysis plan overview
Set appropriate access permissions:
Public: For open science projects
Private: For sensitive data (can be made public later)
Add relevant tags and subjects for discoverability

3. Access JSPsych DataPipe¶

Set up automated data collection through DataPipe:

Visit pipe.jspsych.org
Click "Get Started"
Sign in with your OSF credentials
Authorize DataPipe to access your OSF account

Authorization: DataPipe needs access to create files in your OSF projects. This is secure and only allows DataPipe to upload data files to projects you specify.

4. Create DataPipe Experiment¶

Configure DataPipe for your O-ELIDDI study:

In DataPipe dashboard, click "Create Experiment"
Enter experiment details:
Name: Match your OSF project name
Description: Brief description of data being collected
OSF Project: Select the project you created in Step 2
Configure data settings:
Data format: CSV (default, recommended for O-ELIDDI)
File naming: Use default pattern
Storage location: Confirm correct OSF project
Click "Create Experiment"
Important: Copy the generated Experiment ID - you'll need this for O-ELIDDI configuration

Experiment ID Example: Your ID will look something like eR8ENvJPgQth - save this securely as it's required for data collection.

5. Configure O-ELIDDI¶

Connect your study to DataPipe by updating the configuration:

Open your O-ELIDDI repository (locally or on GitHub)
Edit settings/activities.json
Update the experimentID field in the general section:

{
  "general": {
    "experimentID": "YOUR_DATAPIPE_EXPERIMENT_ID",
    "app_name": "Your Study Name",
    "version": "1.0.0",
    "author": "Your Name",
    "language": "en",
    "instructions": true,
    "primary_redirect_url": "pages/thank-you.html",
    "fallbackToCSV": true
  },
  // ... rest of configuration
}

Important: Replace YOUR_DATAPIPE_EXPERIMENT_ID with the actual ID from Step 4. Keep fallbackToCSV: true for backup data collection.

6. Test Data Collection¶

Verify that data flows correctly from your study to OSF:

Deploy your updated O-ELIDDI configuration
Complete a test timeline on your deployed study
Submit the data and note any error messages
Check your OSF project for the uploaded data file
Download and examine the CSV to verify data format

Successful Test Indicators¶

✅ No error messages during data submission
✅ Automatic redirect to thank you page
✅ CSV file appears in OSF project within minutes
✅ File contains expected timeline data and metadata

Data Management on OSF¶

🔌 Alternative Backend Integration: While OSF provides excellent research data management, the application's sendData() function can be easily redirected to send the tabular CSV data to any relational database (PostgreSQL, MySQL, etc.) or custom backend. Simply modify the sendData() function in js/utils.js to POST the structured data to your preferred endpoint instead of DataPipe. The data is already formatted as clean, normalized tabular records ready for database insertion.

File Organization¶

DataPipe automatically organizes your files in the OSF project:

Folder structure: Files are typically stored in the main project directory
File naming: timeline_{participantID}_{timestamp}.csv
Automatic versioning: OSF tracks all file changes and versions

Accessing Your Data¶

Via OSF Web Interface¶

Log into OSF and navigate to your project
Click "Files" tab
Browse and download individual files or entire folders
Use built-in preview for CSV files

Via API Access¶

For automated data processing, use OSF's API:

# Python example using requests
import requests

# Get project files
project_id = "YOUR_OSF_PROJECT_ID"
url = f"https://api.osf.io/v2/nodes/{project_id}/files/osfstorage/"
response = requests.get(url)

# Download specific file
file_download_url = "DIRECT_FILE_URL_FROM_API"
data = requests.get(file_download_url).content

Data Backup and Security¶

Automatic backups: OSF maintains multiple copies of your data
Version history: All file versions are preserved
Access logs: Track who accessed what data when
Export options: Download entire projects as ZIP files

Privacy and Ethics Configuration¶

Project Visibility Settings¶

Visibility Options: - Private: Only you and collaborators can access (recommended for active data collection) - Public: Visible to everyone (consider for post-publication data sharing) - Embargoed: Public metadata, private data until a specified date

Ethical Considerations¶

Before collecting data, ensure:

[ ] Institutional ethics approval is obtained
[ ] Participant consent procedures are documented
[ ] Data anonymization protocols are in place
[ ] Data retention policies are established
[ ] Access permissions are properly configured
[ ] Compliance with relevant regulations (GDPR, HIPAA, etc.)

Data Anonymization¶

O-ELIDDI can collect anonymous data by design:

No personal information: Timeline data contains no inherently identifying information
Participant IDs: Use anonymous codes rather than names or email addresses
URL parameters: Avoid including sensitive information in participant links
IP addresses: Not collected by O-ELIDDI or stored in timeline data

Collaboration and Team Management¶

Adding Team Members¶

In your OSF project, click "Contributors"
Click "Add" and enter collaborator email addresses
Set appropriate permission levels:
Administrator: Full project control
Read + Write: Can view and upload data
Read: View-only access
Send invitations and manage access as needed

DataPipe Access Management¶

DataPipe Security: Only the OSF account holder who created the DataPipe experiment can modify its settings. Team members access data through OSF project permissions, not DataPipe directly.

Monitoring and Troubleshooting¶

DataPipe Dashboard¶

Monitor your data collection through the DataPipe interface:

Upload statistics: Number of successful uploads
Error logs: Details of any failed uploads
Recent activity: Timeline of data submissions
Storage usage: Amount of data collected

Common Issues and Solutions¶

Data Not Appearing in OSF¶

Check experimentID is correct in activities.json
Verify OSF project permissions
Look for error messages in browser console
Check DataPipe dashboard for upload errors
Wait up to 5 minutes for processing delays

Authentication Errors¶

Reauthorize DataPipe in your OSF account settings
Check that the OSF project still exists
Verify you have write permissions to the project
Try creating a test experiment with a new project

Debugging Data Collection¶

Browser Console Testing¶

Test DataPipe connectivity directly in browser console:

// Check if data would be sent successfully
console.log(window.timelineManager.study);

// Test DataPipe endpoint (replace with your experiment ID)
fetch('https://pipe.jspsych.org/api/data/', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        experimentID: 'YOUR_EXPERIMENT_ID',
        filename: 'test.csv',
        data: 'test,data\n1,2'
    })
}).then(response => console.log(response));

Data Analysis Preparation¶

Batch Data Download¶

For analysis, download all participant data at once:

In OSF project, go to Files tab
Select all data files (Ctrl+click or Shift+click)
Click Download to get a ZIP file
Extract CSV files for analysis

Data Aggregation Scripts¶

Python Example¶

import pandas as pd
import glob
import os

# Read all CSV files from download
csv_files = glob.glob("downloaded_data/*.csv")
all_data = []

for file in csv_files:
    df = pd.read_csv(file)
    all_data.append(df)

# Combine all participant data
combined_data = pd.concat(all_data, ignore_index=True)

# Save master dataset
combined_data.to_csv("master_timeline_data.csv", index=False)

Quality Control Checks¶

Recommended data quality checks:

[ ] Verify all expected participants have submitted data
[ ] Check for duplicate submissions
[ ] Validate timeline coverage completeness
[ ] Review timestamp formatting and ranges
[ ] Identify any unusual activity patterns
[ ] Check URL parameter data for accuracy

Advanced Features¶

OSF Registrations¶

For enhanced research credibility, consider creating an OSF registration:

Preregistration: Document study plan before data collection
Timestamps: Immutable record of research decisions
Templates: Structured formats for different study types
DOI assignment: Permanent identifiers for citations

Integration with Other Tools¶

GitHub Integration	ORCID Integration	Institutional Storage	Reference Managers
Link your OSF project to your GitHub repository for complete reproducibility.	Connect your ORCID profile for automatic publication tracking.	Add institutional storage accounts for additional backup.	Export citations directly to Zotero, Mendeley, and other tools.

Best Practices Summary¶

For successful OSF + DataPipe deployment:

✅ Test thoroughly: Always verify data flow before launching
✅ Document everything: Use OSF project descriptions and wiki features
✅ Plan for scale: Consider data volume and analysis requirements
✅ Backup strategy: Enable CSV fallback and monitor regularly
✅ Team coordination: Set clear access permissions and roles
✅ Ethical compliance: Ensure all necessary approvals before data collection

Remember: OSF and DataPipe provide powerful infrastructure for research data management. Take advantage of the built-in features for version control, collaboration, and reproducibility to enhance your study's impact and credibility.