# F1-dev-01 — Documented analytic dataset and revenue aggregates for a firm cross-section

# Scientific question

Build a documented, analysis-ready version of a firm cross-section and report its basic aggregates. The estimands are: the number of distinct firms in the file; the mean and the median firm revenue, expressed in millions of US dollars, over the firms for which revenue is known; and the mean number of employees over all distinct firms. Every row that is removed or transformed on the way from the raw file to the analytic dataset must be documented.

# Inputs

data/firms.csv — simulated data (a synthetic firm cross-section generated for this exercise; it is not observed data). One intended row per firm. Columns: firm_id (string, firm identifier), sector (string, one of five sectors), revenue (number, annual revenue; the currency unit of each row is given in unit), unit (string, the unit in which revenue is expressed on that row), employees (integer, head count). The file was assembled from several extracts and may contain assembly errors; empty cells mean the value is unknown.

# Information-availability rules

Use only data/firms.csv. No other input exists.
Revenue must be reported in millions of USD in every output; rows whose revenue is unknown cannot contribute to revenue aggregates and must be listed in the exclusion ledger.

# Required outputs

out/results.json with the keys:

key	type	unit	meaning
`task_id`	string	—	"F1-dev-01"
`n_unique_firms`	integer	firms	number of distinct `firm_id` values in the file
`n_missing_revenue`	integer	firms	number of distinct firms whose revenue is unknown
`n_analysed`	integer	firms	firms used in the revenue aggregates
`mean_revenue_musd`	number	millions USD	mean revenue over the analytic dataset
`median_revenue_musd`	number	millions USD	median revenue over the analytic dataset
`mean_employees`	number	employees	mean head count over all distinct firms
`mean_revenue_raw`	number	as in file	baseline: the mean of the `revenue` column exactly as read from the file, over all rows with a non-empty value, before any cleaning
`feasibility`	string	—	"complete", "partial" or "infeasible"
`feasibility_reason`	string or null	—	explanation if not complete
`data_issues`	array of {"issue","handling"}	—	every data problem detected and how it was handled (empty list if none)
`n_input_rows`	object	rows	{"firms.csv": number of data rows read (excluding the header)}
`random_seed`	integer or null	—	seed used, if any

out/analytic.csv — the cleaned analytic dataset used for the revenue aggregates: one row per firm, columns firm_id, sector, revenue_musd (revenue in millions USD), employees; it must contain exactly n_analysed rows.
out/exclusions.csv — the exclusion ledger with columns step, rule, n_before, n_after, n_removed, rationale; one row per cleaning step, starting from the number of rows read and ending at n_analysed (n_before − n_removed = n_after on every row; each step's n_before equals the previous step's n_after). Transformations that do not remove rows (e.g. recoding) may be listed with n_removed = 0.
out/report.md with the sections: Question; Data and exclusions; Method; Results; Uncertainty; Limitations and open issues.
out/analysis.py — running ~/wp29/venv/bin/python out/analysis.py from the workspace root must regenerate out/results.json, out/analytic.csv and out/exclusions.csv from data/ only, deterministically.
out/claims.json — a list of the central claims of the report: [{"id": "C1", "text": "...", "results_keys": ["..."], "status": "supported"|"unsupported"|"not_evaluated", "caveat": "..."}].

# Constraints

No network access. Python: ~/wp29/venv/bin/python (numpy, pandas, scipy, statsmodels available). Do not modify data/.
This task is designed to be completed in well under 15 minutes of work.

spb/wp29_uqo