Preregistration Workflow

Background & Key Concepts

Why Preregister?

Preregistration timestamps a study's hypotheses, design, and analysis plan before data collection. It prevents two major threats to research validity:

• HARKing (Hypothesizing After Results are Known): presenting exploratory findings as confirmatory
• p-hacking: selectively reporting analyses that yield p < .05

Preregistered findings carry stronger evidential weight because the researcher could not have adjusted the hypothesis to fit the data.

Platform Comparison

Deviation Tracking

Every deviation from the preregistered protocol must be documented with:

1. What was planned
2. What was done instead
3. Justification
4. Whether it was pre-specified as a contingency

Environment Setup

Install Dependencies

pip install requests>=2.28 pandas>=1.5 jinja2>=3.0 python-dotenv>=1.0 reportlab>=4.0

OSF API Token

# 1. Go to https://osf.io/settings/tokens/
# 2. Create a personal access token with osf.full_write scope
# 3. Set environment variable:
export OSF_TOKEN="<paste-your-osf-token>"

import os
from dotenv import load_dotenv

load_dotenv()
OSF_TOKEN = os.getenv("OSF_TOKEN", "")
if not OSF_TOKEN:
    print("Warning: OSF_TOKEN not set. Set export OSF_TOKEN='<paste-your-token>'")

HEADERS = {
    "Authorization": f"Bearer {OSF_TOKEN}",
    "Content-Type": "application/json"
}

Core Workflow

Step 1: Create an OSF Project and Draft Registration

import requests
import json
import os

OSF_API = "https://api.osf.io/v2"
OSF_TOKEN = os.getenv("OSF_TOKEN", "")
HEADERS = {"Authorization": f"Bearer {OSF_TOKEN}", "Content-Type": "application/json"}

def create_osf_project(title: str, description: str, public: bool = False) -> dict:
    """Create a new OSF project (node) via API."""
    payload = {
        "data": {
            "type": "nodes",
            "attributes": {
                "title": title,
                "description": description,
                "category": "project",
                "public": public,
            }
        }
    }
    resp = requests.post(f"{OSF_API}/nodes/", headers=HEADERS, json=payload)
    resp.raise_for_status()
    project = resp.json()["data"]
    print(f"Created project: {project['id']} — {project['attributes']['title']}")
    print(f"URL: https://osf.io/{project['id']}/")
    return project

def upload_protocol_file(node_id: str, file_path: str, filename: str) -> dict:
    """Upload a file (e.g., protocol PDF) to an OSF project."""
    upload_url = f"https://files.osf.io/v1/resources/{node_id}/providers/osfstorage/"
    with open(file_path, "rb") as fh:
        resp = requests.put(
            f"{upload_url}?name={filename}",
            headers={"Authorization": f"Bearer {OSF_TOKEN}"},
            data=fh
        )
    resp.raise_for_status()
    print(f"Uploaded {filename} → node {node_id}")
    return resp.json()

# Demo (requires valid OSF_TOKEN):
if OSF_TOKEN:
    project = create_osf_project(
        title="Study: Effect of X on Y — Preregistration",
        description="Preregistration for RCT testing the effect of intervention X on outcome Y.",
        public=False
    )
    PROJECT_ID = project["id"]