# Research Platform Extension

Generated: 12 May 2026

The Atlas app was extended to support multi-study research workflows that randomise participants to packeted case collections while reusing existing collection-taking, timing, marking, and attempt models.

Randomisation on site Pseudo-ID workflow Per-packet marking config CSV/JSON export

## Implemented Data Model

- `ResearchStudy`: study container with slug, active flag, demographic collection toggle, and randomisation mode.
- `ResearchStudyArm`: packet definition linked to existing `CaseCollection`, including weighting and marking scheme metadata.
- `ResearchParticipant`: pseudo-ID keyed participant with demographic fields, consent flag, assigned arm, and generated CID credential link.

Migration generated: `atlas/migrations/0103_researchstudy_researchstudyarm_researchparticipant.py`.

## Participant Flow

- Participant visits: `/atlas/research/run/<study_slug>/<pseudo_id>/`.
- Site captures consent and simple demographics (configurable per study).
- Participant is randomised to a packet (study arm) by configured strategy.
- A dedicated `CidUser` credential is created and attached to the participant if needed.
- Assigned packet `CaseCollection` is launched via existing candidate collection routes.

This reuses current Atlas taking/timing/marking behavior and avoids changes to candidate-facing scoring internals.

## Randomisation Logic

Mode | Behavior
--- | ---
Completely random | Weighted random choice over active arms using `allocation_weight`.
Balanced (equal-fill) | Assigns to least-filled active arm; tie broken randomly.
Balanced within group | If enabled, balancing is applied within `candidate_group` strata.

## Marking and Scoring

- Existing answer models remain in use: `CidReportAnswer` / `UserReportAnswer`.
- Existing collection mark views remain functional for non-technical markers.
- Per-packet configuration fields added on study arm:
  - `marking_scheme_name`
  - `marking_guidance`
  - `scoring_mode` and `max_case_score` for normalised exports

Current marker UI itself is unchanged; packet-specific configuration is reflected in study management and exports.

## Management and Export

### Management Views

- `/atlas/research/` list studies
- `/atlas/research/create/` create study
- `/atlas/research/<pk>/` study detail + packets + participants
- `/atlas/research/<pk>/update/` update study
- `/atlas/research/<pk>/arm/<arm_id>/update/` update packet

### Exports

- `/atlas/research/<pk>/export.csv`
- `/atlas/research/<pk>/export.json`

Export rows include demographics, assignment metadata, credential ID, attempt status, and raw/normalised scores.

## Files Added/Updated

- Updated: `atlas/models.py`, `atlas/forms.py`, `atlas/views.py`, `atlas/urls.py`, `atlas/admin.py`
- Added templates:
  - `atlas/templates/atlas/research_study_list.html`
  - `atlas/templates/atlas/research_study_form.html`
  - `atlas/templates/atlas/research_study_detail.html`
  - `atlas/templates/atlas/research_study_arm_form.html`
  - `atlas/templates/atlas/research_participant_entry.html`
- Added migration: `atlas/migrations/0103_researchstudy_researchstudyarm_researchparticipant.py`

## Compatibility Notes

- No existing collection, case, or answer model behavior was removed.
- Randomisation and participant routing are additive and isolated to new research URLs.
- Author/editor permission pattern is respected for study management views.