Scientific Chat Export

Scientific Chat Export & Data Archiving

1. Overview

For behavioral, social, and psychological experiments conducted either in the laboratory or online, hroot provides an integrated live-chat and announcement system (ChatMessage). To scientifically analyze communication data, archive dialogues for replication packages (Open Science), and link transcripts to external experimental datasets, hroot provides standardized export interfaces (CSV and JSON) both at the single-session level and aggregated across all sessions of an experiment.

---

2. Export Locations & Access

A. Experiment-Wide (Aggregated across all sessions):

• Participant Pool Overview (Participants > Index): Available under the table actions dropdown (...): Export chat....
• Clicking the button opens a modal dialog allowing experimenters to choose from three standardized scientific export formats. The output aggregates all communication events across all sessions chronologically.

B. Session-Level (Individual session):

• Session Participants (Sessions > Participants): Available under the actions dropdown (...): Export chat....
• Displays the export format selection dialog scoped specifically to the active session.

---

3. The Three Scientific Export Formats

1. Complete Chat Log (CSV): Full raw dataset with absolute UTC timestamps, relative seconds elapsed since session start, IDs, participant names, and text metrics (optimized for Microsoft Excel, R, Stata, and SPSS).
2. Anonymized Chat Log (CSV - Open Science): De-identified according to GDPR and institutional ethics standards: full names and email addresses are masked (Participant Seat X, Experimenter), while the immutable sessiontoken is preserved to enable cross-linking with de-identified experimental datasets (e.g. on OSF or Zenodo).
3. Structured Chat Log (JSON): Hierarchical nested JSON object including full metadata and message metrics, tailored for Natural Language Processing (NLP), text mining, and computational linguistics.

---

4. Export Variables & Schema

Every row in the exported file corresponds to a discrete communication event:

Column	Type	Description
message_id	Integer	Unique identifier of the message (preserves sequence integrity)
session_id	Integer	ID of the experimental session
experiment_id	Integer	ID of the parent experiment
session_start_utc	ISO 8601	Scheduled start time of the session in UTC
message_created_at_utc	ISO 8601	Exact transmission timestamp in UTC
relative_seconds_from_session_start	Integer	Relative seconds elapsed from session start. Enables millisecond/second-level synchronization with software logfiles (e.g. oTree, z-Tree, Qualtrics)
sender_type	String	Originator: admin (experimenter), participant, or system
sender_id	Integer / null	User account ID of the sender (masked when anonymize=1)
sender_name	String	Display name of the sender (pseudonymized as Participant Seat X or Experimenter when anonymized)
recipient_type	String	Destination type: participant, admin, or all (broadcast)
recipient_id	Integer / null	User account ID of the recipient (masked when anonymize=1)
recipient_name	String	Display name of the recipient (or All Participants (Broadcast))
session_participation_id	Integer	Primary key of the participation record in hroot
sessiontoken	String	Key Linkage Variable: 10-character session token matching external software tokens (e.g. oTree participant code, z-Tree subject ID)
seat_nr	Integer	Assigned cubicle / seat number in the laboratory
read_at_utc	ISO 8601	Timestamp when the message was acknowledged or opened by the recipient
read_latency_seconds	Integer	Latency in seconds from transmission to reading (response latency metric)
char_count	Integer	Character length of the message body
word_count	Integer	Word count of the message body (metric for text volume)
message	String	Text content of the message

---

5. Privacy Architecture & Permissions (view_personal_data)

hroot's privacy architecture enforces a strict boundary between operational study administration and access to identifying participant data:

• Experimenters without the view_personal_data permission:
  • Are strictly and permanently restricted to pseudonymized exports.
  • Names and account IDs are stripped server-side.
  • The export dialog hides the non-anonymized option and displays a notice that data is automatically sanitized in compliance with GDPR.
  • Server-side controllers enforce anonymization even if the endpoint is called directly without anonymize=1.
• Users with view_personal_data (or Admins):
  • Can freely choose between full operational raw logs (e.g. for audit or dispute resolution) and sanitized Open Science packages.

---

6. Formatting & Character Encoding

• Delimiter: Semicolon (;) to prevent formatting errors caused by natural commas in dialogue text.
• Encoding: UTF-8 with Byte Order Mark (\uFEFF), ensuring special characters and language-specific umlauts render cleanly in Microsoft Excel across Windows and macOS.