# Research Methodology

## Purpose and scope

MindScreen AI is a **screening aid**, not a diagnostic instrument. It is
intended to help young adults (18–30) reflect on patterns in mood, anxiety,
and stress, using the same validated self-report instruments used in
primary-care and research screening, delivered conversationally rather than
as a static form. It is designed for research/educational deployment under
informed consent and (for any real study) IRB/ethics-board approval.

## Instruments used

| Instrument | Construct | Items | Range | Source |
|---|---|---|---|---|
| PHQ-9 | Depression | 9 | 0–27 | Kroenke, Spitzer & Williams (2001), public domain, widely validated in primary care and research |
| GAD-7 | Anxiety | 7 | 0–21 | Spitzer, Kroenke, Williams & Löwe (2006), public domain |
| PSS-10 | Perceived stress | 10 | 0–40 | Cohen, Kamarck & Mermelstein (1983) |

Severity bands follow the instruments' standard published cut-offs (e.g.
PHQ-9: 0–4 minimal, 5–9 mild, 10–14 moderate, 15–19 moderately severe,
20–27 severe). See `mindscreen/questionnaires.py` for exact thresholds.

**Important limitation:** these instruments are validated when administered
in their standard form. Weaving them into free-flowing conversation and
mapping free-text answers back onto the 0–3/0–4 Likert scale (see
`conversation_manager.py`) is a deliberate UX choice for engagement, but it
introduces potential measurement error relative to the validated
administration format. The system asks for clarification on ambiguous
answers rather than guessing, but a rigorous study should validate this
conversational administration against the standard paper/form
administration (e.g. test-retest or concurrent validity study) before
relying on it for research conclusions.

## AI/NLP component

A secondary, **exploratory** signal is derived from the conversation text
itself:
- Lexicon-based sentiment and domain-marker detection (depression/anxiety/
  stress-related phrases), entirely offline/local — see `nlp_analysis.py`
  and `lexicons.py`.
- Linguistic features associated with depressive/anxious language in prior
  literature: increased first-person singular pronoun use, absolutist
  language ("always", "never", "completely"), and negative sentiment.
- A scikit-learn RandomForest classifier (`ml_classifier.py`) trained, in
  this build, on **synthetic data only** — it exists to demonstrate the
  explainable-ML pipeline (feature importances surfaced per prediction) but
  carries no evidentiary weight until retrained on real, labeled,
  IRB-approved data.

The **combination rule** (`risk_engine.py`) weights the validated
questionnaire 75% and the NLP signal 25% per domain, explicitly to keep the
validated instrument as the dominant, well-understood signal while still
demonstrating a text-analysis contribution. This weighting is a design
choice, not an empirically fitted one, and should be revisited once
real outcome data is available (e.g. by comparing screening output against
clinician-rated outcomes in a validation study).

## Explainability

Every score returned to a participant or researcher is accompanied by a
plain-language explanation listing exactly which inputs (questionnaire raw
score, specific marker counts, sentiment) produced it — see
`ScreeningResult.explanation_summary` and each `DomainScore.explanation`.
This is a deliberate design choice: a black-box score is a poor fit for
mental-health screening, where the person receiving a "moderate risk" label
should be able to see why.

## Safety design

- Every user message is screened for crisis language *before* any other
  processing (`safety.py`), independent of questionnaire progress.
- PHQ-9 item 9 (thoughts of self-harm / being better off dead) is checked
  directly and independently of free-text crisis detection — endorsing it
  above zero always flags the session, even if phrased in a way the
  lexicon doesn't catch.
- On a safety trigger, the system stops screening and returns crisis
  resources; it explicitly does not attempt crisis counseling, de-escalation
  scripting, or diagnosis.

## Ethical principles followed

- **Informed consent:** explicit consent step before any screening begins;
  a separate `consent_given_at` timestamp is recorded on the user's account
  for research audit.
- **Transparency:** the tool repeatedly states it is a screening aid, not a
  diagnosis, in the consent message, every generated report, and the
  reflection close-out message.
- **Privacy:** dashboard/export data uses a randomly generated
  `participant_code`, never email, name, or raw message text.
- **Non-maleficence / safety-first:** see Safety design above.
- **Data minimization:** date of birth is collected only to confirm
  eligibility and is not included in research exports.

## Known limitations / future validation work

1. Free-text-to-Likert mapping accuracy has not been empirically validated
   against standard form administration.
2. The NLP lexicons are small, hand-curated, and English-only — they will
   miss slang, sarcasm, code-switching, and non-English input.
3. The ML classifier is trained on synthetic data and must be retrained
   before any evidentiary use.
4. No test-retest reliability or concurrent validity study has been run on
   this specific conversational delivery format.
5. This document does not constitute an IRB protocol; any real study must
   go through the appropriate institutional ethics review before
   participant recruitment.