Naming policy for published files: what a composite is called, and when a file may be renamed

[mmcky]

The published tree is flat, so a dataset's filename is its whole identity — the served URL's last segment and, once qeld ships, the qeld.url('<filename>') key. Forty-one files carry names they inherited from wherever they came from, and the phase-2 rename review (#87) already holds four that plainly need changing. What we do not have is the rule that would have prevented those, and the P4 work is about to add the first new files in a while — a World Bank set and a FRED composite for business_cycle, then more for the other live-API lectures. This issue is to settle the policy before they are named, so they are named once.

business_cycle_data.csv stays as it is until this is decided; it has no consumers yet, so renaming stays free for the moment, and it is the worked example below.

The kinds of file we have to name

Looking at the corpus and the P4 queue, four shapes recur:

Shape	Examples today	The naming problem
One series, one source	lingcod_msy_recovery.csv, japan_earthquakes.csv	easy — name the thing measured
One source, several series, one lecture's selection	business_cycle_data.csv (GDP growth, 5 economies), fred_data.csv (six yields + recession dummy), bbh_macro_quarterly.csv (fourteen series)	the lecture is the only thing the selection has in common — so the inherited names say the lecture (business_cycle_…) or the source (fred_…), and #87 objects to both
Verbatim third-party release	mpd2020.xlsx, SCF_plus_mini.csv, test_pwt.csv	keep the upstream's name where it is recognisable (mpd2020), which is also what makes the vintage visible
Author-assembled	assignat.xlsx, dette.xlsx, caron.npy	name what it is; the inherited names are fine where they are the paper's own terms

The second row is the hard one, and it is the shape every P4 composite will take.

Questions to settle

1. What does a composite get named? Candidates for the World Bank file that is business_cycle_data.csv today, once it holds GDP growth for eight economies:

• gdp_growth_annual.csv — names the variable; ignores that it is a hand-picked eight economies rather than the world
• gdp_growth_selected_economies.csv — honest about the selection, vaguer
• wdi_gdp_growth.csv — source-prefixed; the objection to fred_data.csv was that it named only the source, so a source prefix plus the variable may be acceptable
• business_cycle_data.csv — the status quo, lecture-named; forbids reuse by any other lecture in spirit

And for the FRED composite (UNRATE, USREC, UMCSENT, CPILFESL, INDPRO, historical unemployment, monthly, 1919→): us_monthly_indicators.csv? fred_business_cycle_monthly.csv? Something else? The FRED ids are themselves the names economists use, which is an argument for id-based names on single-series files — but a composite has no id.

2. Source prefix: yes or no? A consistent wdi_ / fred_ / owid_ prefix groups files by provenance in a flat listing and disambiguates same-named variables from different sources (two "unemployment rate" files, annual World Bank vs monthly FRED, are exactly what P4 produces). Against: it is the thing #87 criticised, and qeld.url('wdi_gdp_growth.csv') reads worse in a lecture than qeld.url('gdp_growth.csv').

3. Frequency and coverage in the name? _annual / _monthly / _quarterly distinguishes the two unemployment files above without a source prefix. Coverage (_1960_2025) must not be in the name of a dynamic snapshot — it changes on every refresh, and #112 already showed that vintage facts in a manifest's prose go stale; in a filename they would break URLs.

4. Selection in the name? When the file is "these eight economies", does the name say so (_selected, _g8-style), or does the manifest carry it and the name stay generic? A generic name invites a later lecture to assume the file has more than it does.

5. Lecture-named files: never, or as a last resort? business_cycle_data.csv is readable and honest about its origin. The cost is that the name discourages reuse and ties the file to one lecture's fate. Is there a shape of file where lecture-naming is right — e.g. a bundle whose only coherence is "what one lecture plots"?

6. When may an existing file be renamed? Proposed rule, consistent with AGENTS.md: freely while consumers: []; otherwise only as a new-filename vintage with the old name kept serving (a rename is a breaking change for every consumer and every downloaded notebook). This is why the P4 files should be named right before lecture-wasm adopts them.

A strawman, to argue with

• Name the variable(s), not the source and not the lecture: gdp_growth, unemployment_rate, private_credit_to_gdp.
• Add frequency when the same variable could plausibly exist at another frequency: unemployment_rate_annual.csv (World Bank) vs unemployment_rate_monthly.csv (FRED).
• A composite is named for what unites its members, and if the only thing that unites them is one lecture, say the topic rather than the lecture file: us_business_cycle_monthly.csv rather than business_cycle_data.csv — the topic is reusable, the filename is not.
• No source prefix in the name; the source is the manifest's job, and CATALOG.md already shows it beside every file.
• Never coverage or vintage in a dynamic snapshot's name; verbatim releases keep the upstream's own vintage-bearing name (mpd2020).
• Existing files are renamed only per question 6, and the four on Batch rename for the §5.1 generic filenames, paired with their prose edits #87 go through it.

Decisions here feed #87 (the phase-2 rename review), manifest-schema.yml (a short "naming" note beside filename), and the draft convention in QuantEcon/QuantEcon.manual#108.