MindScale

A Psychometric Foundation Model for
Population-Scale Adolescent Mental Health Assessment

Overview · Training · Loading · Use · Limitations · License

📋 Overview

• Model

  MindScale is a language-model-based psychometric foundation model adapted from Meta-Llama-3-8B for questionnaire-based adolescent mental health screening and psychiatric symptom assessment.

• Released files

  The release contains LoRA adapter weights and requires the base model for use.

⬆️ Back to top

📊 Training Details

• Dataset: Large-scale adolescent questionnaire dataset

• Scale: 402,301 students from 377 schools

• Instruments: 22 questionnaires comprising 250 items

• Information domains: Environmental factors, psychological characteristics, and questionnaire-derived psychiatric symptoms

• Training method: LoRA-based parameter-efficient fine-tuning

• Training stages: Pretraining, at-risk identification, and psychiatric symptom assessment

• Data access: The full participant-level training cohort is not included because it contains sensitive information from adolescents.

⬆️ Back to top

🤗 Loading the Adapters

• Adapter directories: Pretrain/, Screen/, and Assessment/.

• Stage dependencies: Screening requires the pretraining and screening adapters; assessment requires all three.

• Before running: Use the MindScale code directory with its runtime dependencies installed. The example uses the code release's helpers to prepare special tokens and stage adapters consistently.

from pathlib import Path
from huggingface_hub import snapshot_download
from transformers import AutoTokenizer
from configs import (
    SerializerConfig, TokenizerConfig, TrainConfig_Screen, LoraConfig_Screen,
)
from models.llama_model import load_llama_3_lora

base_model_id = "meta-llama/Meta-Llama-3-8B"
adapter_id = "Rango001/Adolescent-mental-health"

weights_dir = Path(snapshot_download(
    repo_id=adapter_id,
    allow_patterns=["*/adapter_config.json", "*/adapter_model.safetensors"],
))
tokenizer = AutoTokenizer.from_pretrained(base_model_id, use_fast=False)
model, tokenizer = load_llama_3_lora(
    tokenizer, SerializerConfig(), TokenizerConfig(), base_model_id,
    task_type="Screen",
    train_config=TrainConfig_Screen(), lora_config=LoraConfig_Screen(),
    pretrain_state_dict_path=str(weights_dir / "Pretrain"),
    screen_state_dict_path=str(weights_dir / "Screen"),
    test_task=True,
)
model.eval()

• Base model access: Accept the Meta Llama 3 license on Hugging Face.

• Runtime: A CUDA-enabled environment is required. The example uses the code release's existing 8-bit loading.

• Questionnaire inference: Follow the accompanying code README for input preparation and prediction export.

⬆️ Back to top

📝 Intended Use

MindScale is intended for:

• Population screening: Research on adolescent mental health assessment.
• Method development: Studies of structured questionnaire modelling.
• Model evaluation: Evaluation on questionnaire-derived tabular data.

⬆️ Back to top

⚠️ Limitations

• Input scope: The model was trained on questionnaire-based data and may not generalize to other input formats or populations.

• Class imbalance and bias: Predictions may be affected by class imbalance and cohort-specific biases.

• Clinical validation: The model has not been validated for routine clinical use.

• Distribution shifts: Performance may decline under demographic, linguistic, institutional, or other distribution shifts.

⬆️ Back to top

🛡️ Ethical Considerations

• Research use only: MindScale must not be used for clinical diagnosis, treatment decisions, crisis triage, or autonomous decisions affecting students.

• Prediction uncertainty: Outputs may be incorrect or biased, particularly for underrepresented groups.

• Participant protection: Any use involving participant data requires appropriate ethical approval, privacy protection, fairness assessment, and qualified human oversight.

⬆️ Back to top

📄 License

Use of this adapter and the Meta-Llama-3-8B backbone is subject to the Meta Llama 3 Community License and its Acceptable Use Policy.

⬆️ Back to top