globalmind 0.0.1__tar.gz

globalmind-0.0.1/.gitignore

@@ -0,0 +1,59 @@
+# Byte-compiled / cache
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# Build
+dist/
+build/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Hatch
+.hatch/
+
+# Coverage
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+
+# IDE & editor
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+.directory
+
+# Jupyter
+.ipynb_checkpoints/
+*.ipynb
+
+# Environment
+.env
+.env.*
+
+# Data (large CSV / parquet — do not commit raw or processed data)
+*.csv
+*.parquet
+*.processed.parquet
+
+# Tests — not included in distribution
+tests/
+
+# Python type stubs
+*.pyi
+
+# Logs
+*.log

globalmind-0.0.1/LICENSE.txt

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026-present Nianyu Su <mirakelor@outlook.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

globalmind-0.0.1/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.4
+Name: globalmind
+Version: 0.0.1
+Summary: GMP (Global Mind Project) mental health data analysis toolkit
+Project-URL: Documentation, https://github.com/Mirakelor/globalmind#readme
+Project-URL: Issues, https://github.com/Mirakelor/globalmind/issues
+Project-URL: Source, https://github.com/Mirakelor/globalmind
+Author-email: Nianyu Su <mirakelor@outlook.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: DSM-5,GMP,Global-Mind-Project,MHQ,Mind-Health-Quotient,data-science,mental-health,polars,psychometrics,public-health,questionnaire,survey-analysis,wellbeing
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Requires-Python: >=3.10
+Requires-Dist: polars>=1.0.0
+Description-Content-Type: text/markdown
+
+# globalmind
+
+[![PyPI - Version](https://img.shields.io/pypi/v/globalmind.svg)](https://pypi.org/project/globalmind)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/globalmind.svg)](https://pypi.org/project/globalmind)
+
+-----
+
+Python pipeline for the [Global Mind Project (GMP)](https://sapienlabs.org/global-mind-project/) — ingest, filter, profile, and
+classify mental health data collected through the Mind Health Quotient (MHQ).
+
+## Background
+
+The Global Mind database contains mental health profiles from nearly 2 million
+internet-enabled respondents across 130+ countries in 17+ languages, with
+1,000–2,000 new responses added each day. Data are collected using the **Mind
+Health Quotient (MHQ)** — an online assessment developed from a review of over
+10,000 questions drawn from 126 commonly used mental health tools spanning 10
+disorders. The MHQ consists of 47 items that rate individual aspects of mind
+health on a 1–9 scale, together with aggregate scores, demographics, and
+lifestyle/life‑context factors.
+
+`globalmind` provides a pure‑Polars pipeline to go from raw CSV exports to
+DSM‑5 diagnostic classifications in a few lines of code. All operations are
+**lazy** (build a query plan, `.collect()` once at the end) for memory‑safe
+processing of the full dataset.
+
+## Features
+
+### Data loading & cleaning
+- **`read_table(path)`** — scan CSV with automatic N/A → null conversion,
+  pipe‑delimited multi‑select splitting (21 columns), and stray‑pipe cleanup on
+  single‑select categoricals.
+- **`clean_data(df)`** — apply four quality filters:
+  - completion time ≥ 7 minutes
+  - response variance across 47 rating items (std dev ≥ 0.2)
+  - comprehension check (`understanding` ≠ "No")
+  - countries with ≥ 1,000 responses
+
+### 205‑column schema
+- **`COLUMN_DESCRIPTIONS`** — dictionary mapping every column name to an
+  English description with a Chinese gloss.
+- **`describe_column(name)`** — lookup helper.
+
+### Symptom identification & DSM‑5 mapping
+- **`identify_symptoms(df)`** — flags each of the 47 MHQ items as a clinical
+  symptom per DSM‑5 thresholds:
+  - *Problem items* (20): threshold ≥ 8 on a 1–9 severity scale
+  - *Spectrum items* (27): threshold ≤ 1 (challenge end of the spectrum)
+  - Adds 47 `_symptom` boolean columns + a `symptom_count` column.
+- **`mapping_to_DSM5(df)`** — data‑driven rule engine classifying 10 disorder
+  categories: Depression, Anxiety, Bipolar, PTSD, OCD, Schizophrenia, Eating
+  Disorder, Addiction, ADHD, ASD.
+
+## Installation
+
+```console
+pip install globalmind
+```
+
+Requires Python ≥ 3.10 and `polars ≥ 1.0`.
+
+## Quick start
+
+```python
+from globalmind import (
+    read_table, clean_data,
+    identify_symptoms, mapping_to_DSM5,
+)
+
+df = read_table("gmp_data.csv")
+df = clean_data(df)
+df = identify_symptoms(df)
+df = mapping_to_DSM5(df)
+df.collect()  # all operations are lazy
+```
+
+## References
+
+- **Data cleaning criteria** — Bala, Jerzy, Oleksii Sukhoi, Jennifer Jane
+  Newson, Priscila Pereira Machado, Mark Lawrence, and Tara C. Thiagarajan.
+  "Estimation of the Nature and Magnitude of Mental Distress in the Population
+  Associated with Ultra-Processed Food Consumption." *Frontiers in Nutrition* 12
+  (November 2025): 1562286.
+  [https://doi.org/10.3389/fnut.2025.1562286](https://doi.org/10.3389/fnut.2025.1562286)
+- **Symptom thresholds & DSM‑5 mapping** — Newson, Jennifer Jane, Vladyslav
+  Pastukh, and Tara C. Thiagarajan. "Poor Separation of Clinical Symptom
+  Profiles by DSM-5 Disorder Criteria." *Frontiers in Psychiatry* 12 (November
+  2021): 775762.
+  [https://doi.org/10.3389/fpsyt.2021.775762](https://doi.org/10.3389/fpsyt.2021.775762)
+
+## License
+
+`globalmind` is distributed under the terms of the
+[MIT](https://spdx.org/licenses/MIT.html) license.

globalmind-0.0.1/README.md

@@ -0,0 +1,94 @@
+# globalmind
+
+[![PyPI - Version](https://img.shields.io/pypi/v/globalmind.svg)](https://pypi.org/project/globalmind)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/globalmind.svg)](https://pypi.org/project/globalmind)
+
+-----
+
+Python pipeline for the [Global Mind Project (GMP)](https://sapienlabs.org/global-mind-project/) — ingest, filter, profile, and
+classify mental health data collected through the Mind Health Quotient (MHQ).
+
+## Background
+
+The Global Mind database contains mental health profiles from nearly 2 million
+internet-enabled respondents across 130+ countries in 17+ languages, with
+1,000–2,000 new responses added each day. Data are collected using the **Mind
+Health Quotient (MHQ)** — an online assessment developed from a review of over
+10,000 questions drawn from 126 commonly used mental health tools spanning 10
+disorders. The MHQ consists of 47 items that rate individual aspects of mind
+health on a 1–9 scale, together with aggregate scores, demographics, and
+lifestyle/life‑context factors.
+
+`globalmind` provides a pure‑Polars pipeline to go from raw CSV exports to
+DSM‑5 diagnostic classifications in a few lines of code. All operations are
+**lazy** (build a query plan, `.collect()` once at the end) for memory‑safe
+processing of the full dataset.
+
+## Features
+
+### Data loading & cleaning
+- **`read_table(path)`** — scan CSV with automatic N/A → null conversion,
+  pipe‑delimited multi‑select splitting (21 columns), and stray‑pipe cleanup on
+  single‑select categoricals.
+- **`clean_data(df)`** — apply four quality filters:
+  - completion time ≥ 7 minutes
+  - response variance across 47 rating items (std dev ≥ 0.2)
+  - comprehension check (`understanding` ≠ "No")
+  - countries with ≥ 1,000 responses
+
+### 205‑column schema
+- **`COLUMN_DESCRIPTIONS`** — dictionary mapping every column name to an
+  English description with a Chinese gloss.
+- **`describe_column(name)`** — lookup helper.
+
+### Symptom identification & DSM‑5 mapping
+- **`identify_symptoms(df)`** — flags each of the 47 MHQ items as a clinical
+  symptom per DSM‑5 thresholds:
+  - *Problem items* (20): threshold ≥ 8 on a 1–9 severity scale
+  - *Spectrum items* (27): threshold ≤ 1 (challenge end of the spectrum)
+  - Adds 47 `_symptom` boolean columns + a `symptom_count` column.
+- **`mapping_to_DSM5(df)`** — data‑driven rule engine classifying 10 disorder
+  categories: Depression, Anxiety, Bipolar, PTSD, OCD, Schizophrenia, Eating
+  Disorder, Addiction, ADHD, ASD.
+
+## Installation
+
+```console
+pip install globalmind
+```
+
+Requires Python ≥ 3.10 and `polars ≥ 1.0`.
+
+## Quick start
+
+```python
+from globalmind import (
+    read_table, clean_data,
+    identify_symptoms, mapping_to_DSM5,
+)
+
+df = read_table("gmp_data.csv")
+df = clean_data(df)
+df = identify_symptoms(df)
+df = mapping_to_DSM5(df)
+df.collect()  # all operations are lazy
+```
+
+## References
+
+- **Data cleaning criteria** — Bala, Jerzy, Oleksii Sukhoi, Jennifer Jane
+  Newson, Priscila Pereira Machado, Mark Lawrence, and Tara C. Thiagarajan.
+  "Estimation of the Nature and Magnitude of Mental Distress in the Population
+  Associated with Ultra-Processed Food Consumption." *Frontiers in Nutrition* 12
+  (November 2025): 1562286.
+  [https://doi.org/10.3389/fnut.2025.1562286](https://doi.org/10.3389/fnut.2025.1562286)
+- **Symptom thresholds & DSM‑5 mapping** — Newson, Jennifer Jane, Vladyslav
+  Pastukh, and Tara C. Thiagarajan. "Poor Separation of Clinical Symptom
+  Profiles by DSM-5 Disorder Criteria." *Frontiers in Psychiatry* 12 (November
+  2021): 775762.
+  [https://doi.org/10.3389/fpsyt.2021.775762](https://doi.org/10.3389/fpsyt.2021.775762)
+
+## License
+
+`globalmind` is distributed under the terms of the
+[MIT](https://spdx.org/licenses/MIT.html) license.

globalmind-0.0.1/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "globalmind"
+dynamic = ["version"]
+description = 'GMP (Global Mind Project) mental health data analysis toolkit'
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = [
+  "GMP", "Global-Mind-Project", "MHQ", "Mind-Health-Quotient",
+  "mental-health", "wellbeing", "DSM-5", "psychometrics",
+  "questionnaire", "survey-analysis", "public-health",
+  "polars", "data-science",
+]
+authors = [
+  { name = "Nianyu Su", email = "mirakelor@outlook.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: Implementation :: CPython",
+]
+dependencies = [
+  "polars>=1.0.0"
+]
+
+[project.urls]
+Documentation = "https://github.com/Mirakelor/globalmind#readme"
+Issues = "https://github.com/Mirakelor/globalmind/issues"
+Source = "https://github.com/Mirakelor/globalmind"
+
+[tool.hatch.version]
+path = "src/globalmind/__about__.py"
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+]
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/globalmind tests}"
+[tool.hatch.envs.test]
+dependencies = [
+    "pytest>=8.0.0",
+    "pytest-cov>=5.0.0",       
+]
+[tool.hatch.envs.test.scripts]
+test = "pytest -v {args:tests}"
+cov  = "pytest --cov=src/globalmind --cov-report=term-missing {args:tests}"
+
+[tool.coverage.run]
+source_pkgs = ["globalmind", "tests"]
+branch = true
+parallel = true
+omit = [
+  "src/globalmind/__about__.py",
+]
+
+[tool.coverage.paths]
+globalmind = ["src/globalmind", "*/globalmind/src/globalmind"]
+tests = ["tests", "*/globalmind/tests"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]

globalmind-0.0.1/src/globalmind/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2026-present Nianyu Su <mirakelor@outlook.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.0.1"

globalmind-0.0.1/src/globalmind/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026-present Nianyu Su <mirakelor@outlook.com>
+#
+# SPDX-License-Identifier: MIT
+
+"""GlobalMind: GMP (Global Mind Project) data analysis toolkit."""
+
+from globalmind.data import read_table, clean_data
+from globalmind.schema import COLUMN_DESCRIPTIONS, describe_column
+from globalmind.symptom import identify_symptoms, mapping_to_DSM5
+from globalmind.__about__ import __version__
+
+__all__ = [
+    "read_table",
+    "clean_data",
+    "COLUMN_DESCRIPTIONS",
+    "describe_column",
+    "identify_symptoms",
+    "mapping_to_DSM5",
+    "__version__",
+]

globalmind-0.0.1/src/globalmind/data.py

@@ -0,0 +1,123 @@
+from pathlib import Path
+import polars as pl
+
+# Columns whose values are pipe-delimited multi-select strings.
+_PIPE_DELIMITED_COLS: list[str] = [
+    "live_close_nature",
+    "time_nature",
+    "sleep_problem_type",
+    "work_factors",
+    "substance_use",
+    "medical_condition_type",
+    "treatment_type_new",
+    "treatment_type",
+    "trauma_childhood",
+    "trauma_adulthood",
+    "friendship_type",
+    "parental_support",
+    "help_seeking",
+    "mental_health_disorder",
+    "internet_restrictions",
+    "sm_impact",
+    "ai_use_general",
+    "ai_use_social",
+    "ai_impact_personal",
+    "ai_impact_work",
+    "immersion_nature",
+]
+
+# Clean | artifacts from single-select categorical columns
+_SINGLE_SELECT_PIPE_COLS: list[str] = [
+    "ethnicity",
+    "income_household",
+    "city",
+    "country",
+    "employment_sector",
+    "job_sector",
+    "work_activity",
+    "family_situation",
+]
+
+# Rating questions (1-9 scale, all MHQ items except categorical _type cols)
+_RATING_COLS = [
+    "adapt_to_change", "self_worth_confidence", "creativity_problem_solving",
+    "drive_motivation", "stability_calmness", "sleep_quality",
+    "self_control_impulsivity", "ability_learn", "coordination", "relationships",
+    "emotional_resilience", "planning_organization", "physical_intimacy",
+    "speech_language", "memory", "social_cooperation", "decision_risk",
+    "curiosity_enthusiasm", "energy", "emotional_control", "focus_concentration",
+    "appetite_regulation", "empathy", "sensory_sensitivity", "self_image",
+    "outlook_optimism", "selective_attention", "restless_hyperactive",
+    "fear_anxiety", "infections", "aggression", "avoidance", "obsessive_thoughts",
+    "mood_swings", "detached_reality", "nightmares", "addictions", "anger",
+    "suicidal_thoughts", "pain", "guilt_blame", "hallucinations", "flashblacks",
+    "repetitive_actions", "sad_hopeless", "physical_health", "confusion",
+]
+
+def read_table(path: str) -> pl.LazyFrame:
+    """Reads a CSV file and returns a Polars LazyFrame.
+    Args:
+        path (str): The path to the CSV file.
+    Returns:
+        pl.LazyFrame: The resulting Polars LazyFrame.
+    Raises:
+        FileNotFoundError: If the specified file does not exist.
+        NotImplementedError: If the file format is not supported.
+    """
+    source = Path(path)
+    if not source.exists():
+        raise FileNotFoundError(f"File not found: {path}")
+    if source.suffix.lower() == ".csv":
+        _score_cols = [
+            "overall_mhq_score", "cognition_score", "adapt_resilience_score",
+            "drive_motivation_score", "mood_outlook_score", "social_self_score",
+            "mind_body_score",
+        ]
+        df = pl.scan_csv(
+            path,
+            infer_schema_length=0,
+            null_values=["N/A", "NA", "null", "", "Prefer not to say"],
+            schema_overrides={c: pl.Float64 for c in _RATING_COLS + _score_cols},
+            )
+        df = df.with_columns([
+            pl.col(col).str.split("|").list.eval(pl.element().filter(pl.element().str.strip_chars() != "")).alias(col) 
+            if col != "substance_use" 
+            else pl.col(col).str.split("|").list.eval(pl.element().str.replace_all("##PIPE##", "|").filter(pl.element().str.strip_chars() != "")).alias(col)
+            for col in _PIPE_DELIMITED_COLS
+        ])
+        df = df.with_columns([
+            pl.col(col).str.strip_chars("|").str.replace_all(r"\|+", ",").alias(col) 
+            for col in _SINGLE_SELECT_PIPE_COLS
+        ])
+        return df
+    else:
+        raise NotImplementedError(f"Unsupported file format: {source.suffix}")
+    
+def clean_data(df: pl.LazyFrame) -> pl.LazyFrame:
+    """Apply GMP data quality filters.
+
+    Removes records if:
+    - time_to_complete < 7 minutes
+    - same option selected for all rating questions (std dev < 0.2)
+    - responded 'No' to 'Did you find this assessment easy to understand?'
+    - country has fewer than 1,000 responses
+    """
+    # Filter out records with time_to_complete < 7 minutes
+    df = df.with_columns(
+        (pl.col("time_to_complete").str.split(":").list.get(0).cast(pl.Int64) * 60 + pl.col("time_to_complete").str.split(":").list.get(1).cast(pl.Int64))
+        .alias("time_to_complete_minutes")
+    ).filter(pl.col("time_to_complete_minutes") >= 7).drop("time_to_complete_minutes")
+
+    # Filter out records with low variance in rating questions
+    df = df.with_columns(
+        pl.concat_list([pl.col(col) for col in _RATING_COLS]).list.std().alias("_ratings_std")
+    ).filter(pl.col("_ratings_std") >= 0.2).drop("_ratings_std")
+
+    # Filter out records that responded 'No' to 'Did you find this assessment easy to understand?'
+    df = df.filter(pl.col("understanding") != "No")
+
+    # Filter out countries with fewer than 1,000 responses
+    country_counts = df.group_by("country").len().filter(pl.col("len") >= 1000).select("country")
+    df = df.join(country_counts, on="country", how="semi")
+
+    return df

globalmind-0.0.1/src/globalmind/schema.py

@@ -0,0 +1,348 @@
+"""Column name → human-readable description mapping for the GMP (Global Mind Project) dataset.
+
+Grouped by topic for easy browsing and documentation generation.
+"""
+
+# =============================================================================
+# Meta & timestamps
+# =============================================================================
+META = {
+    "language": "Survey language (问卷语言)",
+    "start_date_utc": "Assessment start time in UTC (评估开始时间 UTC)",
+    "day": "Day of assessment (评估日期 日)",
+    "month": "Month of assessment (评估日期 月)",
+    "year": "Year of assessment (评估日期 年)",
+    "submit_data_utc": "Submission time in UTC (提交时间 UTC)",
+    "time_to_complete": "Time taken to complete the assessment (完成耗时)",
+}
+
+# =============================================================================
+# MHQ aggregate scores (7)
+# =============================================================================
+MHQ_SCORES = {
+    "overall_mhq_score": "Overall MHQ score (MHQ 总得分)",
+    "cognition_score": "Cognition score (认知能力得分)",
+    "adapt_resilience_score": "Adaptation & resilience score (适应与韧性得分)",
+    "drive_motivation_score": "Drive & motivation score (驱动力与动机得分)",
+    "mood_outlook_score": "Mood & outlook score (情绪与展望得分)",
+    "social_self_score": "Social self score (社交自我得分)",
+    "mind_body_score": "Mind-body connection score (身心连接得分)",
+}
+
+# =============================================================================
+# MHQ 47 individual assessment items
+# =============================================================================
+MHQ_ITEMS = {
+    # --- Cognition ---
+    "understanding": "Understanding (理解能力)",
+    "ability_learn": "Ability to learn (学习能力)",
+    "memory": "Memory (记忆力)",
+    "creativity_problem_solving": "Creativity & problem solving (创造力与解决问题)",
+    "planning_organization": "Planning & organization (计划与组织)",
+    "selective_attention": "Selective attention (选择性注意力)",
+    "focus_concentration": "Focus & concentration (专注力)",
+    "speech_language": "Speech & language (言语与语言)",
+    "confusion": "Confusion (困惑感)",
+
+    # --- Mood & emotion ---
+    "stability_calmness": "Stability & calmness (情绪稳定与冷静)",
+    "emotional_resilience": "Emotional resilience (情绪韧性)",
+    "emotional_control": "Emotional control (情绪控制)",
+    "mood_swings": "Mood swings (情绪波动)",
+    "sad_hopeless": "Sadness & hopelessness (悲伤/绝望)",
+    "outlook_optimism": "Outlook & optimism (乐观展望)",
+    "fear_anxiety": "Fear & anxiety (恐惧/焦虑)",
+    "anger": "Anger (愤怒)",
+    "guilt_blame": "Guilt & self-blame (内疚/自责)",
+    "guilt_blame_type": "Guilt/blame trigger type (内疚/自责触发类型)",
+
+    # --- Self ---
+    "self_worth_confidence": "Self-worth & confidence (自我价值/自信)",
+    "self_image": "Self-image (自我形象)",
+    "drive_motivation": "Drive & motivation (驱动力与动机)",
+    "curiosity_enthusiasm": "Curiosity & enthusiasm (好奇心与热情)",
+    "energy": "Energy level (精力水平)",
+    "adapt_to_change": "Adaptability to change (适应变化能力)",
+    "decision_risk": "Decision-making & risk assessment (决策与风险评估)",
+
+    # --- Social ---
+    "relationships": "Relationship quality (人际关系质量)",
+    "social_cooperation": "Social cooperation (社交合作能力)",
+    "empathy": "Empathy (同理心)",
+    "coordination": "Coordination (协调能力)",
+    "physical_intimacy": "Physical intimacy (身体亲密)",
+    "aggression": "Aggression (攻击性)",
+    "avoidance": "Social avoidance (社交回避)",
+
+    # --- Mind-body ---
+    "sleep_quality": "Sleep quality (睡眠质量)",
+    "appetite_regulation": "Appetite regulation (食欲调节)",
+    "physical_health": "Physical health perception (身体健康感受)",
+    "self_control_impulsivity": "Self-control & impulsivity (自控力/冲动控制)",
+    "sensory_sensitivity": "Sensory sensitivity (感官敏感度)",
+    "pain": "Physical pain (身体疼痛)",
+
+    # --- Clinical ---
+    "restless_hyperactive": "Restlessness & hyperactivity (烦躁/多动)",
+    "obsessive_thoughts": "Obsessive thoughts (强迫思维)",
+    "obsessive_thoughts_type": "Obsessive thought type (强迫思维类型)",
+    "detached_reality": "Detached reality (现实感脱离)",
+    "nightmares": "Nightmares (噩梦)",
+    "hallucinations": "Hallucinations (幻觉)",
+    "flashblacks": "Flashbacks (闪回)",
+    "repetitive_actions": "Repetitive actions (重复行为)",
+    "addictions": "Addictive behaviors (成瘾行为)",
+    "infections": "Infections (感染)",
+    "suicidal_thoughts": "Suicidal thoughts (自杀念头)",
+}
+
+# =============================================================================
+# Core demographics
+# =============================================================================
+DEMOGRAPHICS_CORE = {
+    "age": "Age group (年龄段)",
+    "biological_sex": "Biological sex (生理性别)",
+    "gender_diff": "Gender identity vs. biological sex difference (性别认同与生理性别差异)",
+    "gender_identity": "Gender identity (性别认同)",
+    "gender": "Gender (性别)",
+    "ethnicity": "Ethnicity (种族/民族)",
+    "country": "Country (国家)",
+    "state": "State / province / region (州/省/地区)",
+    "rural_urban": "Rural vs. urban classification (城乡分类)",
+    "city": "City (城市)",
+    "education": "Education level (教育程度)",
+    "employment": "Employment status (就业状态)",
+}
+
+# =============================================================================
+# Work & employment
+# =============================================================================
+WORK = {
+    "employment_sector": "Employment sector (就业行业)",
+    "job_role": "Job role / position (职位/角色)",
+    "income_household": "Household income level (家庭收入水平)",
+    "veteran_status_US": "US veteran status (美国退伍军人身份)",
+    "productivity_absent": "Days absent from work — past 4 weeks (缺勤天数 过去4周)",
+    "productivity_unproductive": "Unproductive work days — past 4 weeks (低效工作天数 过去4周)",
+    "team_situation": "Team working arrangement (团队工作模式)",
+    "job_features": "Job features description (工作特征描述)",
+    "work_situation": "Work mode — remote / on-site / hybrid (工作模式 远程/现场/混合)",
+    "organization_size": "Organization size (组织规模)",
+    "job_duration": "Time in current role (在当前岗位时长)",
+    "work_control_time": "Control over work schedule (对工作时间安排的控制)",
+    "work_control_job": "Autonomy over how work is done (对工作方式的自主权)",
+    "work_amount": "Workload pressure (工作量压力)",
+    "work_purpose": "Sense of purpose & meaning at work (工作目标感/意义感)",
+    "work_learning": "Learning opportunities at work (工作中学习机会)",
+    "work_colleagues": "Relationship with colleagues (与同事关系)",
+    "work_manager": "Relationship with manager/supervisor (与上司关系)",
+    "work_informed": "Being kept informed at work (工作信息知情度)",
+    "work_recognition": "Recognition at work (工作认可度)",
+    "work_factors": "Work stress factors — multi-select (工作压力因素 多选)",
+    "job_sector": "Industry sector (所属行业)",
+    "work_activity": "Type of work activity (工作活动类型)",
+}
+
+# =============================================================================
+# Lifestyle — diet, exercise, sleep, socialising
+# =============================================================================
+LIFESTYLE = {
+    "cantril": "Cantril ladder — overall life evaluation 1-9 (Cantril 阶梯 总体生活评价 1-9)",
+    "sleep_freq": "Frequency of getting enough sleep (充足睡眠频率)",
+    "sleep_problem_type": "Sleep problem type — multi-select (睡眠问题类型 多选)",
+    "exercise_freq": "Exercise frequency — ≥30 min/session (运动频率 ≥30分钟/次)",
+    "UPF_freq": "Ultra-processed food consumption frequency (超加工食品摄入频率)",
+    "fruit_veg_freq": "Fresh fruit & vegetable intake frequency (新鲜蔬果摄入频率)",
+    "organic_fruit_veg_freq": "Organic fruit & vegetable consumption (有机蔬果食用频率)",
+    "sugary_food_freq": "Sweet/sugary food or dessert frequency (甜食/含糖食物频率)",
+    "meat_diet": "Meat consumption habits (肉类摄入习惯)",
+    "fish_diet": "Fish/shellfish consumption habits (鱼类/贝类摄入习惯)",
+    "plastic_food": "Food/drinks from plastic containers (塑料容器装食物/饮品频率)",
+    "plastic_hot_food": "Hot food from plastic containers (塑料容器装热食频率)",
+    "plastic_hot_drink": "Hot drinks in paper cups (纸杯热饮频率)",
+    "social_freq": "In-person socializing frequency (线下社交频率)",
+}
+
+# =============================================================================
+# Substance use, medical conditions & treatment
+# =============================================================================
+SUBSTANCE_AND_MEDICAL = {
+    "substance_use": "Substance use — multi-select (物质使用 多选)",
+    "medical_condition_presence": "Whether diagnosed with a medical condition (是否有确诊疾病)",
+    "medical_condition_type": "Medical condition type — multi-select (疾病类型 多选)",
+    "treatment_status": "Whether currently receiving treatment (是否正在接受治疗)",
+    "help_seeking": "Whether sought help (是否寻求过帮助)",
+    "treatment_type_new": "Treatment type — new version, multi-select (治疗类型 新版 多选)",
+    "treatment_type": "Treatment type — old version, multi-select (治疗类型 旧版 多选)",
+    "therapy_efficacy": "Perceived effectiveness of psychological therapy (心理治疗有效性评价)",
+    "medication_efficacy": "Perceived effectiveness of medication (药物治疗有效性评价)",
+    "brain_stim_efficacy": "Perceived effectiveness of brain stimulation (脑刺激治疗效果)",
+    "neurofeedback_efficacy": "Perceived effectiveness of neurofeedback (神经反馈治疗效果)",
+    "mental_health_disorder": "Mental health disorder diagnosis (心理健康障碍诊断)",
+}
+
+# =============================================================================
+# Trauma & adversity
+# =============================================================================
+TRAUMA = {
+    "trauma_childhood": "Childhood trauma experiences — before age 18, multi-select (童年创伤经历 18岁前 多选)",
+    "trauma_adulthood": "Adult trauma experiences — after age 18, multi-select (成年创伤经历 18岁后 多选)",
+    "trauma_life_old": "Life trauma — archived old version (人生创伤经历 旧版 已归档)",
+}
+
+# =============================================================================
+# Family, friendship & community
+# =============================================================================
+FAMILY_AND_FRIENDS = {
+    "family_situation": "Current family situation (当前家庭状况)",
+    "children_num": "Number of children (子女数量)",
+    "household_size": "Number of people sharing household (共同居住人数)",
+    "siblings_num": "Number of siblings growing up — archived (成长中兄弟姐妹数 已归档)",
+    "friends_num": "Number of close friends — archived (密友数量 已归档)",
+    "friends_childhood": "Friends known since childhood — archived (童年至今朋友数量 已归档)",
+    "friends_proximity": "Close friends live nearby — archived (密友是否住附近 已归档)",
+    "friendship_type": "Mode of interaction with friends — archived (与朋友的互动方式 已归档)",
+    "friends_help_out": "Whether friends would help out when in need (是否有朋友能帮忙)",
+    "friends_confide_in": "Whether has friends to confide in — archived (是否有朋友可倾诉 已归档)",
+    "household_nature": "Nature of household growing up — conflict/stable, archived (成长家庭冲突/稳定性 已归档)",
+    "household_description": "Household growing up — warm/distant, archived (成长家庭温暖/疏离程度 已归档)",
+    "parental_support": "Type of parental/caregiver support — archived (父母/照顾者支持类型 已归档)",
+    "family_proximity": "Adult family living nearby — archived (成年家人是否住附近 已归档)",
+    "family_relationships": "Quality of relationships with adult family (与成年家人关系质量)",
+}
+
+# =============================================================================
+# Faith & religion
+# =============================================================================
+FAITH = {
+    "spirituality_connection": "Spiritual/transcendent connection — archived (灵性/超越连接感 已归档)",
+    "love_feelings": "Extent of loving feelings towards others (对他人的关爱程度)",
+    "religious_identity": "Religious identity — archived (宗教身份认同 已归档)",
+    "religious_practice": "Whether actively practices religion — archived (是否践行宗教活动 已归档)",
+    "individual_collective": "Individualism vs. collectivism orientation — archived (个人主义 vs 集体主义倾向 已归档)",
+}
+
+# =============================================================================
+# Technology — smartphones, social media, AI, VR, gaming, nature
+# =============================================================================
+TECHNOLOGY = {
+    # Smartphone & tablet
+    "smartphone_own_old": "Owns a smartphone — old version, archived (是否拥有手机 旧版 已归档)",
+    "smartphone_age_access": "Age first obtained a smartphone (首次获得手机年龄)",
+    "smartphone_school_old": "Smartphone use at school — old version, archived (学校使用手机情况 旧版 已归档)",
+    "smartphone_class_old": "Smartphone use in class — old version, archived (课堂上使用手机 旧版 已归档)",
+    "smartphone_ownership _age": "Age of smartphone ownership (拥有手机年龄)",
+    "smartphone_friends": "Number of friends with smartphones (手机朋友数量)",
+    "smartphone_school_age": "Age school provided a smartphone (学校提供手机年龄)",
+    "smartphone_class": "Smartphone use in class — new version (课堂使用手机 新版)",
+    "smartphone_recess": "Smartphone use during recess (课间使用手机)",
+    "tablet_ownership_age": "Age obtained a tablet (获得平板电脑年龄)",
+    "smartphone_tablet_age": "Age obtained a smartphone/tablet (获得手机/平板年龄)",
+    "laptop_school_age": "Age school provided a laptop (学校提供笔记本年龄)",
+    "laptop_class": "Laptop use in class (课堂使用笔记本)",
+    "internet_restrictions": "Internet access restrictions (上网限制)",
+
+    # Social media
+    "social_media_age": "Age started using social media (开始使用社交媒体年龄)",
+    "social_media_freq": "Social media use frequency (社交媒体使用频率)",
+    "sm_freq_new": "Social media use frequency — new version (社交媒体使用频率 新版)",
+    "sm_impact": "Social media impact on life — multi-select (社交媒体对生活的影响 多选)",
+
+    # AI
+    "ai_freq": "AI tool usage frequency (AI 工具使用频率)",
+    "ai_use_general": "AI general use cases — multi-select (AI 通用用途 多选)",
+    "ai_use_social": "AI social/emotional use cases — multi-select (AI 社交/情感用途 多选)",
+    "ai_impact_personal": "AI impact on personal life — multi-select (AI 对个人的影响 多选)",
+    "ai_impact_work": "AI impact on work — multi-select (AI 对工作的影响 多选)",
+
+    # VR, gaming & nature
+    "vr_freq": "VR headset usage frequency (VR 头显使用频率)",
+    "gaming_freq": "Video gaming frequency (电子游戏频率)",
+    "time_nature": "Time spent in natural environments (在自然环境中时长)",
+    "live_close_nature": "Whether lives close to nature (是否居住在自然附近)",
+    "immersion_nature": "Most-frequented natural environment types — multi-select (最常接触的自然环境类型 多选)",
+}
+
+# =============================================================================
+# Benchmarking scales — PHQ-9, GAD-7, life satisfaction
+# =============================================================================
+BENCHMARKING = {
+    # PHQ-9 (depression screening)
+    "PHQ9_interest": "PHQ-9: Little interest or pleasure in doing things (做事缺乏兴趣或乐趣)",
+    "PHQ9_depressed": "PHQ-9: Feeling down, depressed, or hopeless (感到沮丧、抑郁或绝望)",
+    "PHQ9_sleep": "PHQ-9: Trouble falling/staying asleep or sleeping too much (入睡困难、易醒或嗜睡)",
+    "PHQ9_energy": "PHQ-9: Feeling tired or having little energy (感到疲倦或缺乏精力)",
+    "PHQ9_failure": "PHQ-9: Poor appetite or overeating (食欲不振或暴饮暴食)",
+    "PHQ9_appetite": "PHQ-9: Feeling bad about yourself — failure, letting family down (自我否定/觉得自己失败)",
+    "PHQ9_concentration": "PHQ-9: Trouble concentrating on things (注意力难以集中)",
+    "PHQ9_movement": "PHQ-9: Moving/speaking slowly or being fidgety/restless (动作迟缓或焦躁不安)",
+    "PHQ9_self_harm": "PHQ-9: Thoughts of self-harm or being better off dead (自伤或自杀念头)",
+    # GAD-7 (anxiety screening)
+    "GAD7_nervous": "GAD-7: Feeling nervous, anxious, or on edge (感到紧张、焦虑)",
+    "GAD7_worry": "GAD-7: Not being able to stop or control worrying (无法停止或控制担忧)",
+    "GAD7_self_control": "GAD-7: Worrying too much about different things (对很多事情过度担忧)",
+    "GAD7_relax": "GAD-7: Trouble relaxing (难以放松)",
+    "GAD7_restless": "GAD-7: Being so restless that it is hard to sit still (坐立不安)",
+    "GAD7_irritable": "GAD-7: Becoming easily annoyed or irritable (容易烦躁或易怒)",
+    "GAD7_afraid": "GAD-7: Feeling afraid as if something awful might happen (感到害怕)",
+    "GAD7_impact": "GAD-7: How difficult these problems made daily life (上述问题对生活的影响程度)",
+    # Life satisfaction
+    "life_satisfaction": "Overall life satisfaction 1-9 (总体生活满意度 1-9)",
+}
+
+# =============================================================================
+# Momentary assessments — archived
+# =============================================================================
+MOMENTARY = {
+    "time_day": "Time of day when assessment taken — archived (评估时间段 已归档)",
+    "mood_current": "Current mood at assessment time — archived (当前情绪 已归档)",
+    "alertness_current": "Current alertness level — archived (当前清醒程度 已归档)",
+    "sleep_prevous_night": "Hours slept the previous night — archived (前一晚睡眠时长 已归档)",
+    "time_last_meal": "Time since last meal — archived (距上次进食时间 已归档)",
+    "physical_complaints": "Physical complaints at assessment time — archived (当前身体不适症状 已归档)",
+    "pregnancy": "Whether currently pregnant — archived (是否怀孕 已归档)",
+}
+
+# =============================================================================
+# COVID-19 impact — archived
+# =============================================================================
+COVID = {
+    "covid_health": "COVID-19: health & social impact — archived (新冠疫情 健康与社交影响 已归档)",
+    "covid_finance": "COVID-19: financial impact — archived (新冠疫情 财务影响 已归档)",
+}
+
+# =============================================================================
+# Repeat respondent identifiers (anonymous, derived from email)
+# =============================================================================
+DEDUP = {
+    "Repeat identifier": "Repeat respondent identifier — anonymous, derived from email (重复受访者标识符, 由邮箱匿名化生成)",
+    "Repeat identifier 2": "Repeat respondent identifier — backup (重复受访者标识符 备用)",
+}
+
+# =============================================================================
+# Flat aggregated dict for direct column-name lookup
+# =============================================================================
+COLUMN_DESCRIPTIONS: dict[str, str] = {}
+for _group in [
+    META,
+    MHQ_SCORES,
+    MHQ_ITEMS,
+    DEMOGRAPHICS_CORE,
+    WORK,
+    LIFESTYLE,
+    SUBSTANCE_AND_MEDICAL,
+    TRAUMA,
+    FAMILY_AND_FRIENDS,
+    FAITH,
+    TECHNOLOGY,
+    BENCHMARKING,
+    MOMENTARY,
+    COVID,
+    DEDUP,
+]:
+    COLUMN_DESCRIPTIONS.update(_group)
+
+
+def describe_column(name: str) -> str:
+    """Return the human-readable description for a column, or the column name itself if not found."""
+    return COLUMN_DESCRIPTIONS.get(name, name)

globalmind-0.0.1/src/globalmind/symptom.py

@@ -0,0 +1,244 @@
+import polars as pl
+
+# 20 Problem items — clinical threshold ≥8
+_PROBLEM_COLS = [
+    "restless_hyperactive",          # Restlessness & Hyperactivity
+    "fear_anxiety",                  # Fear & Anxiety
+    "infections",                    # Susceptibility to Infections
+    "aggression",                    # Aggression Towards Others
+    "avoidance",                     # Avoidance & Withdrawal
+    "obsessive_thoughts",            # Unwanted, Strange or Obsessive Thoughts
+    "mood_swings",                   # Mood Swings
+    "detached_reality",              # Sense of being detached from reality
+    "nightmares",                    # Nightmares
+    "addictions",                    # Addictions
+    "anger",                         # Anger & Irritability
+    "suicidal_thoughts",             # Suicidal Thoughts or Intentions
+    "pain",                          # Experience of Pain
+    "guilt_blame",                   # Guilt & Blame
+    "hallucinations",                # Hallucinations
+    "flashblacks",                   # Traumatic Flashbacks
+    "repetitive_actions",            # Repetitive or Compulsive Actions
+    "sad_hopeless",                  # Feelings of Sadness, Distress or Hopelessness
+    "physical_health",               # Physical Health Issues
+    "confusion",                     # Confusion or Slowed Thinking
+]
+
+# 27 Spectrum items — clinical threshold ≤1
+_SPECTRUM_COLS = [
+    "adapt_to_change",               # Adaptability to Change
+    "self_worth_confidence",         # Self Worth & Confidence
+    "creativity_problem_solving",    # Creativity & Problem Solving
+    "drive_motivation",              # Drive & Motivation
+    "stability_calmness",            # Stability & Calmness
+    "sleep_quality",                 # Sleep Quality
+    "self_control_impulsivity",      # Self Control & Impulsivity
+    "ability_learn",                 # Ability to Learn
+    "coordination",                  # Coordination
+    "relationships",                 # Relationships with others
+    "emotional_resilience",          # Emotional Resilience
+    "planning_organization",         # Planning & Organisation
+    "physical_intimacy",             # Physical Intimacy
+    "speech_language",               # Speech & Language
+    "memory",                        # Memory
+    "social_cooperation",            # Social interactions & Cooperation
+    "decision_risk",                 # Decision-making & Risk-taking
+    "curiosity_enthusiasm",          # Curiosity, Interest & Enthusiasm
+    "energy",                        # Energy Level
+    "emotional_control",             # Emotional Control
+    "focus_concentration",           # Focus & Concentration
+    "appetite_regulation",           # Appetite Regulation
+    "empathy",                       # Empathy
+    "sensory_sensitivity",           # Sensory Sensitivity
+    "self_image",                    # Self-Image
+    "outlook_optimism",              # Outlook & Optimism
+    "selective_attention",           # Selective Attention
+]
+
+# DSM‑5 mapping rules
+_SYM = "_symptom"
+
+_DSM5_RULES: dict[str, dict] = {
+    "DSM5_depression": {
+        "core_groups": [0, 1], "min_groups": 5,
+        "groups": [
+            [f"drive_motivation{_SYM}", f"curiosity_enthusiasm{_SYM}"],
+            [f"sad_hopeless{_SYM}", f"outlook_optimism{_SYM}"],
+            [f"appetite_regulation{_SYM}"], [f"confusion{_SYM}"], [f"energy{_SYM}"],
+            [f"self_worth_confidence{_SYM}", f"self_image{_SYM}", f"guilt_blame{_SYM}"],
+            [f"focus_concentration{_SYM}", f"selective_attention{_SYM}", f"decision_risk{_SYM}"],
+            [f"suicidal_thoughts{_SYM}"],
+        ],
+    },
+    "DSM5_anxiety": {
+        "required": [f"fear_anxiety{_SYM}"], "required_groups": [0], "min_groups": 3,
+        "groups": [
+            [f"stability_calmness{_SYM}", f"emotional_control{_SYM}"],
+            [f"restless_hyperactive{_SYM}"], [f"energy{_SYM}"],
+            [f"focus_concentration{_SYM}", f"selective_attention{_SYM}"],
+            [f"anger{_SYM}"], [f"pain{_SYM}"], [f"sleep_quality{_SYM}"], [f"avoidance{_SYM}"],
+        ],
+    },
+    "DSM5_bipolar": {
+        "required": [f"mood_swings{_SYM}"], "core_groups": [0, 1], "min_groups": 5,
+        "groups": [
+            [f"drive_motivation{_SYM}", f"curiosity_enthusiasm{_SYM}"],
+            [f"sad_hopeless{_SYM}", f"outlook_optimism{_SYM}"],
+            [f"appetite_regulation{_SYM}"], [f"confusion{_SYM}"], [f"energy{_SYM}"],
+            [f"self_worth_confidence{_SYM}", f"self_image{_SYM}", f"guilt_blame{_SYM}"],
+            [f"focus_concentration{_SYM}", f"selective_attention{_SYM}", f"decision_risk{_SYM}"],
+            [f"suicidal_thoughts{_SYM}"],
+        ],
+    },
+    "DSM5_ptsd": {
+        "trauma_required": True, "core_groups": [0],
+        "required": [f"avoidance{_SYM}"], "min_groups": 2,
+        "groups": [
+            [f"flashblacks{_SYM}", f"nightmares{_SYM}", f"obsessive_thoughts{_SYM}"],
+            [f"memory{_SYM}"],
+            [f"self_worth_confidence{_SYM}", f"self_image{_SYM}", f"outlook_optimism{_SYM}"],
+            [f"guilt_blame{_SYM}"], [f"sad_hopeless{_SYM}"],
+            [f"curiosity_enthusiasm{_SYM}", f"drive_motivation{_SYM}"],
+            [f"relationships{_SYM}"],
+        ],
+    },
+    "DSM5_ocd": {
+        "required": [f"obsessive_thoughts{_SYM}", f"repetitive_actions{_SYM}", f"fear_anxiety{_SYM}"],
+        "min_groups": 1,
+        "groups": [
+            [f"stability_calmness{_SYM}"], [f"self_control_impulsivity{_SYM}"],
+            [f"emotional_control{_SYM}"],
+        ],
+    },
+    "DSM5_schizophrenia": {
+        "required": [f"obsessive_thoughts{_SYM}", f"hallucinations{_SYM}"], "min_groups": 1,
+        "groups": [
+            [f"speech_language{_SYM}"], [f"repetitive_actions{_SYM}"],
+            [f"drive_motivation{_SYM}", f"relationships{_SYM}",
+             f"social_cooperation{_SYM}", f"curiosity_enthusiasm{_SYM}"],
+        ],
+    },
+    "DSM5_eating": {
+        "required": [f"appetite_regulation{_SYM}", f"fear_anxiety{_SYM}", f"self_image{_SYM}"],
+        "groups": [],
+    },
+    "DSM5_addiction": {
+        "required": [f"addictions{_SYM}"], "min_groups": 2,
+        "groups": [
+            [f"decision_risk{_SYM}"], [f"emotional_control{_SYM}"], [f"avoidance{_SYM}"],
+            [f"relationships{_SYM}"], [f"self_control_impulsivity{_SYM}"],
+        ],
+    },
+    "DSM5_adhd": {
+        "min_groups": 4,
+        "groups": [
+            [f"focus_concentration{_SYM}"], [f"selective_attention{_SYM}"],
+            [f"drive_motivation{_SYM}"], [f"planning_organization{_SYM}"], [f"memory{_SYM}"],
+        ],
+    },
+    "DSM5_asd": {
+        "min_groups": 3,
+        "groups": [
+            [f"social_cooperation{_SYM}"], [f"relationships{_SYM}"],
+            [f"repetitive_actions{_SYM}"], [f"adapt_to_change{_SYM}"],
+            [f"sensory_sensitivity{_SYM}"],
+            [f"selective_attention{_SYM}", f"focus_concentration{_SYM}"],
+        ],
+    },
+}
+
+def _group_flags(df: pl.LazyFrame, groups: list[list[str]]) -> list[pl.Expr]:
+    """Return one boolean expression per group (True if any symptom in group is True)."""
+    return [
+        pl.any_horizontal(
+            [
+                pl.col(c).fill_null(False)
+                for c in grp
+            ]
+        )
+        for grp in groups
+    ]
+
+def identify_symptoms(df: pl.LazyFrame) -> pl.LazyFrame:
+    """Identify symptoms based on clinical thresholds for problem and spectrum items.
+    Args:
+        df (pl.LazyFrame): Input Polars LazyFrame containing the data.
+    Returns:
+        pl.LazyFrame: A new Polars LazyFrame with additional columns indicating the presence of symptoms.
+    """
+    # Identify problem symptoms (clinical threshold ≥8)
+    for col in _PROBLEM_COLS:
+        df = df.with_columns(
+            (pl.col(col) >= 8).alias(f"{col}_symptom")
+        )
+
+    # Identify spectrum symptoms (clinical threshold ≤1)
+    for col in _SPECTRUM_COLS:
+        df = df.with_columns(
+            (pl.col(col) <= 1).alias(f"{col}_symptom")
+        )
+    
+    df = df.with_columns(
+        pl.sum_horizontal(
+            [pl.col(f"{c}_symptom") for c in _PROBLEM_COLS + _SPECTRUM_COLS]
+        ).alias("symptom_count")
+    )
+
+    return df
+
+def mapping_to_DSM5(df: pl.LazyFrame) -> pl.LazyFrame:
+    """Map the identified symptoms to DSM-5 categories.
+    Args:
+        df (pl.LazyFrame): Input Polars LazyFrame containing the data with symptom indicators.
+    Returns:
+        pl.LazyFrame: A new Polars LazyFrame with additional columns indicating DSM-5 categories.
+    """
+
+    # Pre‑compute a "has trauma" flag for PTSD
+    df = df.with_columns(
+        pl.when(
+            pl.col("trauma_childhood").list.len() > 0
+            & ~pl.col("trauma_childhood").list.contains(
+                "I did not experience any of the above during my childhood"
+            )
+        )
+        .then(True)
+        .when(
+            pl.col("trauma_adulthood").list.len() > 0
+            & ~pl.col("trauma_adulthood").list.contains(
+                "I did not experience any of the above"
+            )
+        )
+        .then(True)
+        .otherwise(False)
+        .alias("_has_trauma")
+    )
+
+    for label, rule in _DSM5_RULES.items():
+        g = _group_flags(df, rule["groups"])
+        ok = pl.lit(True)
+
+        # Required single columns (ALL must be True)
+        for c in rule.get("required", []):
+            ok = ok & pl.col(c).fill_null(False)
+
+        # Required groups (each must be True)
+        for gi in rule.get("required_groups", []):
+            ok = ok & g[gi]
+
+        # Core group check (≥1 of this set must be True)
+        if "core_groups" in rule:
+            ok = ok & pl.any_horizontal([g[i] for i in rule["core_groups"]])
+
+        # Min total groups check
+        if rule.get("min_groups"):
+            total = pl.sum_horizontal([*g])
+            ok = ok & (total >= rule["min_groups"])
+
+        # Special: trauma flag
+        if rule.get("trauma_required"):
+            ok = ok & pl.col("_has_trauma")
+
+        df = df.with_columns(ok.alias(label))
+
+    return df.drop("_has_trauma")