How to use the CCR Platform

A guide to running a Contextualized Construct Representation (CCR) analysis: upload your texts, choose a psychological construct, and get per-text scores you can inspect, export, and reproduce. No coding required.

What the platform does

CCR measures how strongly a piece of text reflects a psychological construct (for example individualism, moral concern, depression, or gratitude) without relying on word counts or keyword lists. You provide a set of questionnaire-style items that define the construct - either from a validated scale in the built-in library, or your own. The platform embeds each item and each of your texts with a sentence-embedding language model, then scores every text by its semantic similarity (cosine) to the items. Higher similarity means the text more strongly reflects the construct.

The pipeline is based on Atari et al. (2023) and follows the reference ccr_wrapper implementation, so scores are comparable to the published method. Everything runs on this server: your text is never sent to a third-party AI service for embedding.

Accounts (optional, but recommended)

You can try a small analysis without signing in. A free account lifts the anonymous limits and, importantly, keeps your datasets and runs instead of deleting the upload after each analysis. Sign in from the top right (email and password, or Google where enabled).

Sample datasets: try it without your own data

New to CCR and don't have a corpus handy? Download one of these ready-to-run example files, upload it in Step 1, and pick the suggested construct. They are small synthetic demo texts made by the lab for trying the platform, not research data.

Each file has one text per row (a text column) and the platform detects the text column for you. When you choose a construct, prefer a validated scale from the library whenever one exists.

Running an analysis, step by step

1. Create a project

   A project holds your datasets and runs. Name it after your study. Use the sidebar to switch between projects or create a new one.

2. Upload your corpus (Step 1)

   Upload a CSV or Excel file with one text per row - tweets, essays, open-ended survey answers, transcripts. Extra columns (IDs, conditions, demographics) are fine; they pass through untouched into the results file. The platform suggests which column holds the text; confirm or change it. No corpus of your own yet? Start with a sample dataset.

3. Choose your construct(s) (Step 2)

   Pick from the library of validated scales, or add your own. You can select several constructs (up to 10) to score them together in one run and see how they correlate in your texts. See Constructs below for all four ways to add one, including drafting items with AI.

4. Pick a model and language (Step 3)

   Choose the embedding model and the corpus language. Start with MiniLM (the CCR reference model) for English. Scores are only comparable within the same model, never across model families. See Models.

5. Run, and read the warnings first

   Press Run. When it finishes, read the amber warnings panel before anything else: it flags things like empty or duplicate rows, texts that were too short, texts longer than the model's window (truncated), or a mismatch between your corpus language and the model. Warnings never change your scores - they tell you how to read them.

6. Inspect the results

   Each run shows a score distribution (histogram plus mean, SD, min, max), the per-item loadings (how each questionnaire item contributed), and the top- and bottom-scoring texts. If the top texts do not look like your construct, trust that instinct. Multi-construct runs add a correlation card showing the Pearson correlation between constructs across your texts.

7. Export and reproduce

   Download the results CSV (your columns plus per-item similarities and the CCR score), the run metadata, and a script that reproduces the numbers on your own machine. See Exports and reproducibility.

Constructs: four ways to add one

A construct is a set of short questionnaire-style items. There are four ways to provide them:

• From the library. Search the built-in collection of validated psychological scales by name or category (for example "GAD-7" or "empathy"). This is the preferred option whenever a validated scale exists.
• Type or paste. Enter a scale's items yourself, one per line. Append (R) to a line to mark it reverse-scored.
• Upload a file. A CSV/XLSX with an item column (and optionally a reverse column). You review the parsed items before saving. Uploaded item files are never retained on the server.
• Draft with AI. When no validated scale exists, the platform can draft candidate items from the construct's name and a short description. Signed-in users only. See below.

Drafting construct items with AI

For a construct with no validated questionnaire, describe it (name plus a few sentences) and the platform drafts candidate items for you to review. This is a starting point, not a validated scale: you review, edit, and delete items before saving, and everything the construct touches is labeled "AI-generated - not validated" in the picker, in the results, and in the exported metadata.

The exact model name, provider, and prompt version shown above are read live from this instance, so they always match what actually drafts your items. The same details are stamped onto every saved AI construct and carried into run metadata and the reproduction script.

Exports and reproducibility

Every run is designed to be auditable and reproducible outside the platform. From the results page you can download:

• Results CSV. One row per text: all of your original columns, plus a similarity column per construct item (sim_item_1, sim_item_2, ...) and the overall ccr_score. Multi-construct runs prefix these columns per construct (for example mfq_care_sim_item_1, mfq_care_ccr_score), so every number - including the between-construct correlations - is recomputable from the file.
• Metadata (JSON). The exact model revision, the construct snapshot with an item hash, the language block, environment/package versions, and any warnings. For AI constructs it also records the drafting model, prompt version, and date, plus a machine-readable cautionary note.
• Reproduction script + requirements. A standalone Python script and a requirements file, both stamped with your run's id.

Running the reproduction script

The script re-embeds your items and texts and recomputes the scores with the same model and settings, on any machine, with no access to this platform. It embeds the construct items verbatim from the run, so the numbers reproduce offline. From the script's header (which lists the exact commands with your run id and file name):

pip install -r requirements-repro_<run-id>.txt
python reproduce_analysis_<run-id>.py your_corpus.csv

The reproduced values match the exported CSV to within about 1e-5 with the real models. Because the script carries the model revision and the construct snapshot, it is also a durable record of exactly how a result was produced - useful for a methods section or a reviewer. If the run used AI-drafted items, the script and metadata carry that provenance too, so the caveat travels with the numbers.

Models available

Chosen on the Step 3 card. Larger models are slower and, the first time anyone selects one on this instance, take a couple of extra minutes to download before the run starts; after that they stay warm. Scores are comparable only within the same model.

Your data and privacy

The embedding models run on this server - your uploaded text is never sent to a third-party AI service. The one exception is the optional AI item-drafting feature, where only the construct name and description you type (never your corpus) are sent to the drafting model. Signed-out uploads are deleted after each analysis; signed-in datasets and runs are kept until you delete them. Please avoid uploading sensitive or identifiable data.

Questions or feedback

This platform is built and maintained by the Culture & Morality Lab (PI: Mohammad Atari) at the University of Massachusetts Amherst. For suggestions, questions, bugs, and ideas, reach the maintainer at devaanand@umass.edu.