belonginglab 0.1.1

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 — real CDC YRBSS 2023 data

from belonginglab import (
    load_yrbss_fixed_width, map_variables,
    flag_stressors, count_stressor_stack, compare_groups,
)

df = load_yrbss_fixed_width(
    "XXH2023_YRBS_Data.dat",
    "2023XXH-SAS-Input-Program.sas",
)
df = map_variables(df, schema="yrbss_2023")
df = flag_stressors(df, yrbss=True)       # handles YRBSS 1=yes/2=no coding

print(count_stressor_stack(df, complete_cases=True).summary())
print(compare_groups(df, by="race_ethnicity"))

Download the three CDC files (data, SAS program, users' guide PDF) from https://www.cdc.gov/yrbs/data/index.html.

Quickstart — try without any download (synthetic data)

from belonginglab import (
    make_synthetic_yrbss, compute_belonging_score, flag_stressors
)

df = compute_belonging_score(make_synthetic_yrbss(n=500))
df = flag_stressors(df)                   # synthetic data uses generic Likert/binary

Core API

Function	Purpose
load_yrbss(path)	Read CSV, .sas7bdat, or .xpt
load_yrbss_fixed_width(dat, sas_program)	Parse the CDC fixed-width ASCII release using its SAS program
map_variables(df, schema)	Rename raw Q-codes to canonical names
prepare_yrbss(df)	Recode YRBSS 1=yes/2=no items to 1/0 (preserves missing)
clean_yrbss(df, subgroup=...)	Coerce missing values and optionally filter
compute_belonging_score(df)	Add a 0–100 belonging-score column
flag_stressors(df, yrbss=False)	Add nullable Int8 stressor flags; pass yrbss=True for raw YRBSS 1/2 coding
count_stressor_stack(df, complete_cases=True)	Stressor-count distribution across respondents
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