Document raw source file reference

2026-06-15 11:33:18 +02:00
commit b5ca9370f1
61 changed files with 293618 additions and 0 deletions
@@ -0,0 +1,64 @@
+# party2d
+
+Code and processed model inputs for generating two-dimensional party-position estimates from text and expert data. The model combines manifesto and media text indicators with expert survey placements in a Bayesian dynamic item-response framework.
+
+## Repository contents
+
+- `src/r/` — scripts that prepare processed model inputs from source datasets.
+- `src/julia/` — Stan data preparation, model fitting, post-estimation, enrichment, and validation.
+- `models/` — Stan model specification.
+- `data/` — processed party-level inputs used by the model.
+- `metadata/` — data dictionary and source-support documentation.
+- `docs/` — raw data source documentation, coding decisions, and operational notes.
+
+Processed inputs needed by the model are included in `data/` so the estimation step can be reproduced from the model-ready data.
+
+## Running the pipeline
+
+Run the full workflow with:
+
+```bash
+bash run_estimation.sh full
+```
+
+This executes the numbered workflow scripts:
+
+```bash
+bash scripts/01_prepare_data.sh
+bash scripts/02_fit_model.sh
+bash scripts/03_extract_estimates.sh
+bash scripts/04_enrich_estimates.sh
+```
+
+The numbered scripts can also be run manually in that order. `scripts/05_validate_estimates.sh` runs validation checks after estimates have been generated.
+
+The Bayesian model is computationally expensive. The production run used 4 cores on an AMD Ryzen 9 7945HX and took 60,372 seconds, approximately 16 hours 46 minutes.
+
+If model output is already available, rebuild estimates without refitting Stan:
+
+```bash
+bash run_estimation.sh reuse
+```
+
+`reuse` reruns source-data processing, post-estimation, and enrichment while skipping the Stan fitting step.
+
+To check the local setup without fitting the model, run:
+
+```bash
+bash run_estimation.sh dry-run
+```
+
+## Data inputs
+
+The model-ready inputs are included under `data/`.
+
+Original raw source files are not redistributed. See `docs/RAW_DATA_SOURCES.md` for the list of original data sources, access information, and expected local filenames for regenerating the processed inputs.
+
+## Output variables
+
+The two position variables are scaled from 0 to 1:
+
+- `economic_lr`: economic left to economic right.
+- `galtan`: cosmopolitan/socially liberal to traditionalist/nationalist.
+
+Column definitions are in `metadata/data_dictionary.csv`.