# Nationality Allocation Experiment (oTree)

This project is an oTree app for a short behavioural survey experiment about social decision-making in an international student environment. Participants are asked to imagine an international welcome event, allocate limited interaction time across student profiles from different nationalities, answer a short follow-up survey, and optionally join a friend-matching exercise.

## Overview

The app studies how participants distribute a fixed amount of interaction time across six potential student contacts in a hypothetical international setting.

The experiment includes:
- informed consent
- background questions
- a randomized scenario treatment
- a 61-minute allocation task
- short follow-up measures
- an optional friend-matching module

The app is configured as a one-round, individual-decision experiment.

## App structure

- **App name:** `allocation_app`
- **URL name:** `allocation_app`
- **Players per group:** `None`
- **Number of rounds:** `1`

## Core logic

### Randomization
Participants are randomly assigned to one of two conditions:
- `control`
- `treatment`

The treatment changes the scenario shown before the allocation task:

- **Control:** the participant is still looking around and has not yet started a conversation.
- **Treatment:** the participant has already started talking with another student from their own country.

### Profile generation
Each participant sees 6 student profiles:
- 5 profiles are randomly drawn from a predefined country pool
- 1 profile is the participant’s own nationality
- the order is shuffled randomly

The participant’s own nationality is stored internally using `own_index`, which allows later identification of how many minutes they allocated to someone from their own country.

The app uses a fixed country pool:
- Canada
- Germany
- Japan
- Brazil
- Morocco
- Italy
- Poland
- Korea, Republic of

### Allocation task
Participants must allocate exactly **61 minutes** across 6 profiles:
- `alloc_1` to `alloc_6`
- each allocation must be an integer from 0 to 61
- the total must equal exactly 61

The allocation page includes JavaScript that:
- displays the running total live
- disables the continue button until the total equals 61
- replaces blank allocation fields with `0` on submission

Server-side validation also checks that:
- all allocation fields are completed
- no allocation is negative
- the total equals exactly 61

### Follow-up measures
Participants then answer the following follow-up questions:
- who they have socialized with most so far this semester
- how often they feel homesick or miss their home country
- how important it was before university to meet people from their own country
- how comfortable they feel approaching students from very different backgrounds
- how many languages they speak at a conversational level

### Optional friend-matching exercise
After the main study, participants may optionally join a separate friend-matching exercise.

If they choose yes, they are asked for:
- email address (required)
- short introduction (required)
- name (optional)
- phone number (optional)
- age (optional)

If they choose no, they skip this step.

## Page flow

The page sequence is:

1. `Consent`
2. `NoConsentExit`
3. `Background`
4. `Allocation`
5. `FollowUp`
6. `MatchingInvite`
7. `MatchingForm`
8. `Results`

### Notes on flow
- If `consent = 'no'`, the participant is shown `NoConsentExit`
- If `consent = 'yes'`, they proceed through the main study
- `MatchingForm` is shown only if `consent = 'yes'` and `join_matching = 'yes'`

## Data collected

### Consent
- `consent`

### Background
- `nationality`
- `level_of_study`
- `student_status`
- `time_in_country`
- `prior_abroad_experience`
- `background_time_sec`

### Experimental variables
- `treatment`
- `own_index`
- `alloc_1` to `alloc_6`
- `allocation_time_sec`

### Follow-up measures
- `socialized_with_most`
- `homesick_frequency`
- `own_country_importance_before_uni`
- `comfort_unfamiliar`
- `languages_spoken`
- `followup_time_sec`

### Optional matching
- `join_matching`
- `match_email`
- `short_intro`
- `match_name`
- `match_phone`
- `match_age`

## Files

### Python
- `allocation_app/__init__.py`  
  Contains constants, model fields, page definitions, randomization logic, validation, and page sequence.

- `settings.py`  
  Contains session configuration and oTree project settings.

### Templates
The app uses the following templates:
- `Consent.html`
- `NoConsentExit.html`
- `Background.html`
- `Allocation.html`
- `Followup.html`
- `MatchingInvite.html`
- `MatchingForm.html`
- `Results.html`

### Deployment files
- `Procfile`
- `requirements.txt`

## Country handling

The app uses `pycountry` to generate a full list of valid country names for the autocomplete field in the background page:

```python
NATIONALITIES = sorted([country.name for country in pycountry.countries])