Data & Reproducibility

Reproduction (the actual code, end-to-end)

git clone https://git.catalystgroup.tech/herman/msf-forecast-pipeline
cd msf-forecast-pipeline
pip install -r requirements.txt   # numpy, pandas, matplotlib, scipy, statsmodels, pytest
make all                          # ≈ 2 minutes on a single CPU

End-to-end runtime: ~2 minutes on a single CPU. Six pytest cases cover the loaders, feature builder, and metric helpers. Output:

• results/features.csv — 522-week × 40-feature panel
• results/predictions_test.csv — 104-week × 20-col TEST-set forecasts + actuals
• results/metrics_{count,any,high}.csv — TEST-set metrics per task
• results/cv_metrics.csv — rolling-origin development-CV scores
• results/model_coefficients.csv — full NB GLM coefficients
• results/model_metadata.json — study-weeks, RF-skip reason, training window
• results/calibration_any.png — reliability diagram for the any-incident target
• results/figures/{observed_vs_predicted,feature_importance,residuals,roc_any}.png

Inputs (all public, all committed under src/data/raw/ in the pipeline repo)

To regenerate from the original public sources:

curl -sL "https://raw.githubusercontent.com/Codeholics/US-Mass-Shootings/master/Export/Codeholics%20-%20Mass%20Shootings%20Database%201982-2025.csv" \
  -o /tmp/codeh_msf.csv
curl -sL "https://raw.githubusercontent.com/BuzzFeedNews/nics-firearm-background-checks/master/data/nics-firearm-background-checks.csv" \
  -o /tmp/nics_full.csv
curl -sL "https://api.worldbank.org/v2/country/USA/indicator/SP.POP.TOTL?date=2014:2024&format=json&per_page=20" \
  -o /tmp/us_pop_raw.json
python3 scripts/_prep_data.py   # rebuilds the 4 CSVs from these

Schemas

gva_mass_shootings.csv — per-incident (Mother Jones ≥3-fatality definition)

case,date,city,state,latitude,longitude,fatalities,injured,total_victims,year
"Las Vegas Strip shooting","2017-10-01","Las Vegas","Nevada",36.094,-115.146,60,867,604,2017

gtrends_mass_shooting.csv — monthly incident count (proxy for the public-coverage signal)

month,incidents_count
2014-01,0
2014-02,1

This is the substitute for Google Trends data (which requires API auth). It captures the same "public attention / news-coverage" signal — each incident triggers coverage and social-media reaction. Documented in the paper §4 as a material limitation.

nics_monthly.csv — FBI NICS national monthly sums

month,handgun,long_gun,multiple,other,total
2014-01,762568,476335,27131,991932,2257966

us_population.csv — annual US population

year,population
2014,318428000

Definitions

This project uses the Mother Jones standard definition of mass shooting: ≥3 fatalities in a single public, indiscriminate incident. Matches the canonical academic reference (Follman, Aronsen & Pan, Mother Jones) and applied consistently across all targets.

The Gun Violence Archive applies a broader definition (≥4 shot, including injured); the paper §3 discusses the difference and the resulting data shape. The dataset name gva_mass_shootings.csv is preserved from the original Codeholics schema; calling it "GVA mass shootings" would be incorrect.

Counts (committed)

• 82 incidents across 522 weeks (2014-W01 → 2023-W52), avg 0.157/week.
• 77 weeks with ≥1 incident in the full panel.
• 5 weeks with ≥2 incidents in the full panel.
• 23 TEST weeks (104 total) had ≥1 incident (prevalence 22%).
• 1 TEST week had ≥2 incidents (prevalence 1%).

Train / val / test split (declared BEFORE modeling)

• TRAIN: 2014-W01 → 2021-W52 (8 years, 418 weeks)
• VAL (last chronological 10% of train): 2021-W01 → 2021-W52
• TEST: 2022-W01 → 2023-W52 (2 years, 104 weeks, never fit)