Metadata-Version: 2.4
Name: belonginglab
Version: 0.1.0
Summary: Measure school belonging and identify social stressor patterns in adolescent survey data.
Project-URL: Homepage, https://github.com/sharab/belonginglab
Project-URL: Issues, https://github.com/sharab/belonginglab/issues
Author: Akshara Balakrishnan
License: MIT
License-File: LICENSE
Keywords: adolescent-health,education-research,public-health,school-belonging,youth-survey,yrbss
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Sociology
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == 'dev'
Requires-Dist: matplotlib>=3.7; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: twine>=4.0; extra == 'dev'
Provides-Extra: plots
Requires-Dist: matplotlib>=3.7; extra == 'plots'
Description-Content-Type: text/markdown

# 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

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

## Quickstart

```python
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:

```python
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
