Metadata-Version: 2.4
Name: belonginglab
Version: 0.1.1
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 — real CDC YRBSS 2023 data

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

```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)                   # 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
