hristudio/docs/structure.md

HRIStudio Structure and Requirements

Structure

A study is a general term for a research project.

An experiment is a specific set of steps and actions that will be conducted with a participant and robot. Experiments are designed and configured via a dedicated drag and drop experiment designer. This interactive designer features a dotted background—similar to Unreal Engine's IDE drag and drop area—that clearly indicates drop zones. Users can add, reorder, and connect individual steps and actions visually.

An trial is a specific instance of an experiment. It is a single run of the experiment with a specific participant and robot.

A step is a general term for something that is being done in the experiment. It is represented as a collection of actions that are being done in a specific order.

An action is a specific operation that is being done (like "move to position", "press button", "say something", etc.) These are the smallest atomic units of the platform.

A participant is a person that has been added to a study. This person does not have an account.

A user is a person that has an account, which is a person that has been added to a study. Anyone can sign up for an account, but they must be added to a study or create their own. A user can have different roles in different studies.

Experiment Design and Implementation

Experiments are central to HRIStudio and are managed with full CRUD operations. The Experiment Design feature includes:

• Drag and Drop Designer: An interactive design area with a dotted background, reminiscent of Unreal Engine's IDE, which allows users to visually add, reposition, and connect steps and actions. The designer includes:
  • A dotted grid background that provides visual cues for alignment and spacing
  • Highlighted drop zones that activate when dragging components
  • Visual feedback for valid/invalid drop targets
  • Smooth animations for reordering and nesting
  • Connection lines showing relationships between steps
  • A side panel of available actions that can be dragged into steps
• Experiment Templates: The ability to save and reuse experiment configurations.
• CRUD Operations: Procedures to create, retrieve, update, and delete experiments associated with a study.
• Dynamic Interaction: Support for adding and reordering steps, and nesting actions within steps.

Roles and Permissions

Core Roles

1. Owner

   • Single owner per study
   • Full control over all aspects of the study
   • Can delete study or transfer ownership
   • Can manage all other roles
   • Usually the study creator or designated successor
   • Cannot be removed except through ownership transfer

2. Admin

   • Multiple admins allowed
   • Can manage participants, experiments, and study settings
   • Can invite and manage other users (except Owner)
   • Cannot delete study or transfer ownership
   • Appointed by Owner

3. Principal Investigator (PI)

   • Scientific oversight role
   • Full access to participant data and experiment design
   • Can manage experiment protocols
   • Can analyze and export all data
   • Cannot modify core study settings or manage user roles
   • Typically one PI per study

4. Wizard

   • Operates the robot during experiment trials
   • Can control live experiment sessions
   • Can view anonymized participant data
   • Can annotate experiments in real-time
   • Cannot modify study design or access sensitive participant data
   • Multiple wizards allowed

5. Researcher

   • Can view and analyze experiment data
   • Can access anonymized participant information
   • Can export and analyze results
   • Cannot modify study design or participant data
   • Cannot run experiment trials
   • Multiple researchers allowed

6. Observer

   • Can view live experiments
   • Can view anonymized participant data
   • Can add annotations
   • Cannot modify any study aspects
   • Cannot access sensitive data
   • Multiple observers allowed

Permission Categories

1. Study Management

   • Create/Delete Study (Owner only)
   • Edit Study Settings
   • Transfer Ownership (Owner only)
   • Manage Study Metadata

2. Participant Management

   • Add/Remove Participants
   • View Participant Details (identifiable vs. anonymized)
   • Edit Participant Information
   • Manage Participant Consent Forms

3. Experiment Design

   • Create/Edit Experiment Templates
   • Define Steps and Actions
   • Set Robot Behaviors
   • Configure Data Collection

4. Experiment Execution

   • Run Experiment Trials
   • Control Robot Actions
   • Monitor Live Sessions
   • Add Real-time Annotations

5. Data Access

   • View Raw Data
   • View Anonymized Data
   • Export Data
   • Access Participant Identifiable Information

6. User Management

   • Invite Users
   • Assign Roles
   • Remove Users
   • Manage Permissions

Role-Permission Matrix

Permission Category	Owner	Admin	PI	Wizard	Researcher	Observer
Study Management	Full	Most	No	No	No	No
Participant Management	Full	Full	Full	Limited	Limited	View Only
Experiment Design	Full	Full	Full	No	No	No
Experiment Execution	Full	Full	Full	Full	View Only	View Only
Data Access	Full	Full	Full	Limited	Limited	Limited
User Management	Full	Most	No	No	No	No

Special Considerations

1. Data Privacy

   • Identifiable participant information is only accessible to Owner, Admin, and PI roles
   • All other roles see anonymized data
   • Audit logs track all data access

2. Role Hierarchy

   • Owner > Admin > PI > Wizard/Researcher > Observer
   • Higher roles inherit permissions from lower roles
   • Certain permissions (like study deletion) are restricted to specific roles

3. Role Assignment

   • Users can have different roles in different studies
   • One user cannot hold multiple roles in the same study
   • Role changes are logged and require appropriate permissions

Participant Management: can create, update, delete participants, as well as view their personal information

• Admin: can do everything
• Principal Investigator: can do everything
• Wizard: can view participants, but cannot view their personal information
• Researcher: can view participants, but cannot view their personal information

Experiment Management: can create, update, delete experiments, as well as view their data and results.

• Admin: Can do everything
• Principal Investigator: Can do everything
• Wizard: Runs experiment trials, can view results
• Researcher: Can view results

Experiment Design: can create, update, delete steps and actions, as well as specify general parameters for the experiment.

• Admin: Can do everything
• Principal Investigator: Can do everything
• Wizard: Can create, update, delete steps and actions, as well as specify general parameters for the experiment
• Researcher: Can view steps and actions.