belonginglab 0.1.0

Measure school belonging and identify social stressor patterns in adolescent survey data.

belonginglab

belonginglab is a Python library for measuring school belonging and identifying social stressor patterns in adolescent survey data. It is designed around the CDC YRBSS 2023 release, which includes recent topics such as social media use, racism in schools, unfair discipline, and school connectedness.

Why belonging?

Adolescent well-being is shaped not only by internal emotional states but by the school environment around a student. belonginglab treats belonging as a measurable, systems-level construct — a composite of connectedness, supportive adult relationships, and the absence of bullying, discrimination, and discipline inequity.

Supported datasets

• CDC YRBSS 2023 (national and state files, CSV or SAS export)
• Custom surveys, via a user-supplied variable-name mapping

Install

pip install belonginglab
# with plotting:
pip install "belonginglab[plots]"

Quickstart

from belonginglab import (
    load_yrbss, map_variables, clean_yrbss,
    compute_belonging_score, flag_stressors,
    count_stressor_stack, compare_groups,
    generate_summary_report,
)

df = load_yrbss("yrbs_2023.csv")
df = map_variables(df, schema="yrbss_2023")
df = clean_yrbss(df)

df = compute_belonging_score(df)
df = flag_stressors(df)

stack = count_stressor_stack(df)
print(stack.summary())

print(compare_groups(df, by="race_ethnicity"))
print(generate_summary_report(df, group_by="sex"))

Try it without downloading anything:

from belonginglab import make_synthetic_yrbss, compute_belonging_score, flag_stressors
df = compute_belonging_score(make_synthetic_yrbss(n=500))
df = flag_stressors(df)

Core API

Function	Purpose
load_yrbss(path)	Read CSV, .sas7bdat, or .xpt
map_variables(df, schema)	Rename raw Q-codes to canonical names
clean_yrbss(df, subgroup=...)	Coerce missing values and optionally filter
compute_belonging_score(df)	Add a 0–100 belonging-score column
flag_stressors(df)	Add binary stressor flags
count_stressor_stack(df)	Distribution of stressor counts per respondent
compare_groups(df, by=...)	Subgroup table (n, score stats, stressor prevalence)
generate_summary_report(df)	Markdown/text summary, optionally written to file

Methodology note

The default belonging score is a weighted z-score composite:

• Positive contributors: school connectedness, supportive-adult indicator
• Negative contributors: bullying (school + electronic), racism in school, unfair discipline, heavy social media use, sadness/hopelessness

Each component is z-scored, multiplied by its weight (see belonginglab.DEFAULT_WEIGHTS), summed, and — by default — percentile-ranked to a 0–100 scale for interpretability. Weights and scaling are user-overridable. Variables absent from the dataset are skipped rather than imputed.

Ethical note

belonginglab is for research and educational analysis. It does not diagnose mental health conditions or determine individual student risk. Scores should be interpreted at the population or subgroup level, not at the level of a single student.

Roadmap

• v0.1 (MVP): loader, belonging score, four stressor flags, group comparison, summary report
• v0.2: weighted survey estimates (weight, strata, psu), trend comparison across years
• v0.3: additional schemas (state YRBSS releases, Healthy Minds, other adolescent surveys)
• v0.4: clustering/latent-class stressor patterns

License

MIT © Akshara Balakrishnan