# Using this edition in research

The archive preserves 153 release-level observations from the Gürkaynak–Wolfers economic-derivatives package. The page illustrates the data; it does not replicate the original paper's empirical results. Vultax's contribution is the allowlisted edition, source tracing, validation and interface. Original-author and peer review of this edition have not been recorded.

## Citation and versions

The original 2005 research package, the [September 2005 FRBSF Working Paper 2005-26](https://www.frbsf.org/wp-content/uploads/wp05-26bk.pdf), and [NBER Working Paper 11929, January 2006](https://doi.org/10.3386/w11929) are distinct objects. Use the date and identifier for the version actually cited. The earlier preview combined a 2005 date with the NBER reference; that has been corrected.

Cite the original research when interpreting the data. If using Vultax's transformed edition or interface, also identify edition `0.3.2` and its file checksum. This research edition has no deposited DOI. Citation and BibTeX files distinguish the scholarly source from the curation work. The researchers' permission and credit do not imply that they reviewed or endorse the new edition.

## Definitions that affect analysis

- The four indicators have different units: thousands of payroll jobs, ISM index points, percentage change in retail sales excluding autos, and thousands of initial claims. Preserve the unit with the value.
- Each observation is an auction/release pair, not a trade. Unequal series sample sizes and coverage matter when pooling: 33 payrolls, 30 ISM, 26 retail-sales and 64 initial-claims records.
- Probabilities are implied by auction prices. The original paper studies their relation to beliefs and risk preferences; our interface does not independently establish that equivalence.
- Source percentages are retained without normalization. Thirty-two totals differ from 100% by more than 0.05 percentage points. Record both the raw and any explicitly transformed values if scoring later.
- The first and last bins are open tails, represented in the source by `-9999` and `9999`. Those markers are not numerical outcomes. Adjacent-bin edge inclusion remains undocumented in this inspection. Twenty-three outcomes lie exactly on boundaries and stay unassigned.
- Bin widths vary. A bin's probability mass is not a probability density. A histogram density comparison would need finite bin widths and an explicit treatment of tails. Comparing the largest bin probability across different partitions does not, by itself, compare forecast confidence.
- A result inside a bin gives an interval of possible cumulative positions, not its exact percentile. A median, mean, entropy or log score may depend on additional conventions, partition choices or tail assumptions.
- Announced outcomes are retained as recorded. Later revisions are not substituted. The data do not supply a full vintage history or a verified release-time timezone. Auction and release dates coincide for 125 records; this does not establish their exact intraday ordering.

The opening jobs example was chosen because it is surprising. Edition 0.3.0 pairs it with an ordinary example and a boundary example, each chosen by a stated rule (see `METHODS-AND-DATA-DESCRIPTOR.md`). None of them is a sample or a calibration test.

## What another researcher can check now

Run `python3 validate.py` from this directory to check the field allowlist, all bin values against the prepared input, unique IDs, dates, shared boundaries, open tails, source totals, source-record hashes, 2,235 exported bin rows and file checksums. It reports clearly when comparison with the original source has not run.

With the original source ZIP available, run:

```bash
python3 validate.py --source-zip /path/to/Gurkaynak_Wolfers_2005_data_code.zip
```

This additionally compares all allowlisted values to the original CSV member and verifies the ZIP/member hashes. It never runs downloaded Stata code or republishes excluded survey/market fields. Validation is distinct from reproducing the original statistical results.

## The worthwhile next research

1. Run the prespecified protocol in `EVALUATION-PROTOCOL.md` (version 1.1, written before any calibration or scoring statistic was computed) and publish every result it produces, by indicator and pooled.
2. Explain the original paper's distinction between uncertainty within a forecast and disagreement among forecasters. Do not redistribute the excluded survey columns to illustrate it; a clearly labelled schematic can teach the distinction.
3. Document the original and revised announcement vintages separately, if authoritative release histories can be joined without changing the original outcomes.
4. Done in 0.3.0: credited chart export, a reproducible exercise (`EXERCISE.md`) and record-level citation. Still needed: an immutable deposited edition to cite.

## Maintaining a durable edition

Keep original source bytes immutable, issue an append-only correction log, and publish a new version whenever values or interpretation change. Package the article, data, schema/dictionary, source code and checks together. A reviewed independent repository deposit should outlive the Vultax website; its real persistent identifier and exact rights statement must be recorded after deposit. Do not invent an open license for the underlying source.

Future identifiers should connect the curation edition to its source and paper, and connect later versions to earlier ones, using explicit relationships such as those documented by [DataCite](https://support.datacite.org/docs/connecting-to-works). This metadata is prepared locally; no repository deposit or preservation guarantee is claimed.