faostat-scientific-paper

name

faostat-scientific-paper

description

Use when the user wants an academic / peer-reviewable research paper built from FAOSTAT data — "scientific paper", "academic paper", "research paper", "journal article", "IMRaD write-up", "peer-reviewed paper", "manuscript". The deliverable is a .docx following IMRaD structure (Abstract, Introduction, Methods, Results, Discussion, Conclusion, References), a multi-sheet .xlsx data appendix, and a .bib BibTeX reference file. Tone is cautious, hedged, and statistically framed. Do NOT use when the user asks for an "analytical brief" or "policy brief" → route to `faostat-analytical-brief`. Do NOT use for "story" / "article" / "explainer" → `faostat-story`. Do NOT use for "infographic" / "one-pager" → `faostat-infographic`. Do NOT use for a policy brief styled as a "white paper" — that's still `faostat-analytical-brief`.

FAOSTAT Scientific Paper

Build a peer-reviewable research paper from FAOSTAT data. Audience is researchers, reviewers and methodologists — not policymakers, not general readers. Length target 3,000–8,000 words, 6–12 numbered figures/tables, 15–40 references. Deliverable bundle: .docx manuscript + .xlsx data appendix + .bib BibTeX file.

Prerequisites

Before starting, confirm FAOSTAT MCP tools are available: faostat_get_data, faostat_search_codes, faostat_list_groups, faostat_list_domains, faostat_get_rankings, faostat_get_metadata. If not, stop and tell the user the skill requires the FAOSTAT MCP server.

Python packages needed for output: python-docx, openpyxl, pandas, scipy (for scipy.stats.kendalltau and Mann–Kendall test — install pymannkendall if available, otherwise implement from scipy.stats). Install with --break-system-packages in the sandbox.

Invariants

Cross-skill invariants (all six — violations are skill bugs):

1. FILTER vs DISPLAY codes. faostat_get_data takes FILTER codes (e.g., 2510 Production). faostat_get_rankings takes DISPLAY codes (e.g., 5510). Never invert.

2. Year syntax. Comma-separated lists only ('2010,2011,...,2023'). Colon ranges return empty in practice.

3. Element filter required on every faostat_get_data call.

4. TCL for national trade aggregates, TM only for partner breakdowns. Never sum TM rows to reconstruct national totals.

5. China composite default (Apr 2026 user preference). Country-level numbers and rankings default to composite China (area 351). China, mainland (41) is available as an opt-in — do not substitute 41 unless the user explicitly asks. Flag the choice in the Methods section with the FAOSTAT-default-41 caveat. Map carve-out: if the paper embeds a choropleth, the map uses disaggregation (41 on CHN polygon + HKG 96 + MAC 128 + TWN 214) while narrative rankings and tables use 351.

6. faostat_get_rankings HTTP-500 fallback. On failure, reconstruct by pulling faostat_get_data across all reporting countries and sorting client-side. Note the fallback in Methods.

7. Element and item code resolution. Never use a hardcoded numeric element or item code as the primary value in a faostat_get_data call. Always resolve at runtime: faostat_search_codes(domain_code='<dom>', dimension_id='element', query='<metric name>') for elements; faostat_search_codes(domain_code='<dom>', dimension_id='item', query='<item name>') for items. Numeric codes shown in reference tables and code examples are verified hints — use them to validate the search result, not as the authoritative source. Domain letter-codes (QCL, TCL, GT, EM, FBS, FS…) are stable and may be used directly.

Paper-specific invariants:

8. Every number traces to the xlsx. Results-section numbers and every numeric claim in the Abstract, Discussion, and Conclusion live in a row of the data appendix (with source_sheet + source_row columns in a Claims sheet). Unverifiable numbers are a bug.
9. Hedged claims. No unqualified causal language unless the method is causal (DiD, IV, RCT). Use "associated with", "correlated with", "consistent with", "suggests". Reserve "causes" / "drives" / "due to" for causal designs only.
10. Complete Limitations subsection. Every paper names at least three limitations: (a) FAOSTAT data-quality caveats (estimated or imputed values, revisions), (b) coverage or temporal gaps, (c) methodological boundaries (descriptive vs causal, unit conversions, aggregation choices). This is non-optional.
11. Structured abstract. Fixed order: Background / Methods / Results / Conclusions. 200–300 words total, four labelled paragraphs or inline labelled sentences.
12. No FAO impersonation. Do not reproduce the FAO logo, "Food and Agriculture Organization of the United Nations" masthead, ISSN, "FAO Statistics Division" stamp, or "Required citation: FAO. …" line. Use a neutral "Suggested citation: [Author] ([YYYY])" block. CC-BY-4.0 data attribution to FAOSTAT stays — it's a property of the source data.

Workflow

Step 1 — Gather parameters

Ask the user (via AskUserQuestion if Cowork, inline otherwise) for anything not specified:

• Topic / research question — the paper needs a single testable framing ("Did global agrifood emissions grow significantly between 2001 and 2023, and what components drove the trend?").
• Time window — start year, end year. At least 10 years for a meaningful trend test.
• Geographic scope — global, regional (Africa / Americas / Asia / Europe / Oceania), or country-level.
• Citation style — APA 7 (default) or Nature / Science numbered. Use AskUserQuestion if not specified. No third option — keep the skill lean.
• Author block — name, affiliation, email. Neutral defaults if unspecified ("Prepared by [Analyst]").
• Target journal / venue — informs word-count target and figure density. Not required.

One clarifying round maximum. Pick sensible defaults for anything still unspecified (global scope, APA 7, anonymous author block).

Step 2 — Draft the research question and title

A good FAOSTAT paper question is:

• Measurable — can be answered with the data that exists
• Bounded — specific commodity / emission category / country list / time window
• Testable — admits a clear statistical test (trend / difference / rank correlation / regression)

Write a working title and the one-sentence research question before pulling data. If the data contradicts the framing on pull, rewrite.

Step 3 — Design the Methods before pulling data

Specify in advance (so Methods is fully determined before any figures are drawn):

• Data source — FAOSTAT domain(s) by code (GT, QCL, TCL, etc.), accessed date, licence (CC-BY-4.0).
• Elements — FILTER element codes on all get_data calls. Always resolve at runtime via faostat_search_codes (invariant 7) — e.g. faostat_search_codes(domain_code='QCL', dimension_id='element', query='production quantity') → e.g. 2510. Record both the resolved code and the search query in the Methodology sheet.
• Items — FAOSTAT item codes with canonical names.
• Geographic coverage — FAOSTAT area codes. Rankings use composite China (area 351) unless the user opts into mainland (41); map figures disaggregate (see invariant 5).
• Temporal coverage — comma-separated year list.
• Aggregations — regional groupings by FAOSTAT group codes (5100 Africa, etc.) or user-defined; unit conversions (kt → Mt, etc.).
• Statistical tests — default battery (see Step 6). Pre-declare which test applies to which question.
• Software — Python 3.x, pandas, scipy, openpyxl, python-docx; cite versions in Methods.

Step 4 — Pull the data

Apply invariants 1–7. Use response_format='compact', show_unit=True, comma year lists, FILTER element codes on get_data. Resolve all element and item codes via faostat_search_codes before each call (invariant 7).

Log every pull into the xlsx Methodology sheet with columns: call_id, domain, element, items, areas, years, timestamp, row_count, notes.

Step 5 — Build the data appendix (xlsx) first

Before writing prose, lay out the xlsx with at minimum:

sheet	purpose
README	paper title, author, citation-style, build date, one-paragraph scope
Claims	every numeric claim in the paper — columns: claim_id, text, section, value, units, source_sheet, source_row
Fig<N>_<slug>	one per figure — data + chart spec
Tab<N>_<slug>	one per table — tidy rows
Methodology	one row per faostat_get_data call (see Step 4)
Stats	one row per statistical test — columns: test_id, question, method, statistic, p_value, ci_lower, ci_upper, n, notes
Sources	all cited works, mirror of the .bib

Per invariant 7, every number that appears in the .docx must have a Claims row with a pointer back.

Step 6 — Run the statistical tests

Default battery (descriptive + trend-tests):

• Descriptive — means, medians, IQR, growth rates: compound annual growth rate (CAGR = (end/start)^(1/n) - 1), absolute deltas, shares of total.
• Trend test — Mann–Kendall non-parametric trend test on the full time series (reports tau, p-value). Preferred over linear regression for FAOSTAT annual series because it is robust to non-normality, monotonic trends, and outliers from methodological revisions. Use pymannkendall.original_test(series) if available; otherwise implement from scipy.stats.kendalltau(years, values).
• Rank correlation — Spearman's rho when comparing two rank orders (e.g., countries ranked by production vs by exports). Reports rho, p-value, n.
• Group comparison — Kruskal–Wallis H-test when comparing three or more groups (regions, commodity classes). Reports H-statistic, degrees of freedom, p-value. Pairwise follow-up with Dunn's test only if the user asks for it — otherwise report effect sizes (median differences) without claiming causality.

Not in the default battery (ask before using): OLS regression, panel/fixed-effects, difference-in-differences, causal-inference methods. These require a user-named identification strategy and go in a custom Methods subsection.

Every test result lands in the Stats sheet with the columns in Step 5.

Step 7 — Draft the manuscript in IMRaD order

Write in this order. Do not skip ahead — Abstract last, Conclusion second-to-last.

Title page

• Title (≤ 15 words, includes the outcome, the domain, and the time window)
• Author block (name, affiliation, email)
• Running head
• Keywords — 4–6, include "FAOSTAT"
• Data availability statement (points to the xlsx appendix and to FAOSTAT)

Introduction (≤ 800 words)

• Paragraph 1 — subject framing and policy/scientific relevance
• Paragraph 2 — short related-work review citing named FAO sources and one or two peer-reviewed anchor works. Suggested anchors by topic:
  • Emissions (GT/EM): Tubiello et al. (2022) Pre- and post-production processes...; FAO (2024) The State of Food and Agriculture; FAO / IPCC AR6 Ch.7.
  • Production (QCL): FAO (annual) World Food and Agriculture – Statistical Yearbook; Alexandratos & Bruinsma (2012) World agriculture towards 2030/2050.
  • Trade (TCL): FAO (2024) The State of Agricultural Commodity Markets; Fuglie et al. (2020) Harvesting Prosperity.
  • Temperature change (ET): Hansen et al. (2010) Global surface temperature change; FAO (2024) Temperature change on land in FAOSTAT.
  • Prices (PP): FAO Food Price Index methodology note; Headey & Martin (2016) The Rising Price of Food. For any topic without a canonical anchor, insert [add peer-reviewed refs] placeholders and tell the user. Never fabricate citations. Invented references are a skill bug; when in doubt, leave a placeholder.
• Paragraph 3 — research question, explicit and testable.
• Last paragraph — paper roadmap ("Section 2 describes…; Section 3 presents…; Section 4 discusses…").

Materials and Methods (≤ 1,200 words)

Fixed subsections:

1. Data source — FAOSTAT domain codes, licence, accessed date, composite-China choice, map carve-out if applicable.
2. Variables — element codes (FILTER), item codes, unit conversions.
3. Geographic and temporal coverage — area codes, comma year list.
4. Statistical analysis — every test by name (Mann–Kendall, Spearman, Kruskal–Wallis), software versions, significance threshold (α = 0.05 unless the user says otherwise).
5. Reproducibility — refer to the xlsx Methodology and Stats sheets. Include a sentence: "All faostat_get_data API calls, parameters, and results are logged in the accompanying xlsx appendix."

Results (text + figures + tables; 800–2,000 words)

Write one paragraph per figure / table. Open each paragraph with the finding, then the test statistic. Example:

Fig. 1 shows a monotonic increase in global agrifood-systems emissions between 2001 and 2023. A Mann–Kendall trend test returned τ = 0.89 (p < 0.001, n = 23), consistent with a significant upward trend. CAGR over the window was 0.87 %.

Every figure gets a "Figure N: caption" line with a Source line below:

Source: FAO. 2026. FAOSTAT: Climate Change - Agrifood Systems Emissions. Licence: CC-BY-4.0.

Tables follow the same convention ("Table N").

Results reports findings without interpreting them. Interpretation lives in Discussion.

Discussion (≤ 1,500 words)

Fixed subsections:

1. Interpretation — what the findings mean, hedged language only (invariant 8).
2. Comparison with prior work — where findings agree/disagree with cited anchor works.
3. Limitations — non-optional (invariant 9). Name at least: FAOSTAT data quality, coverage gaps, methodological boundaries (descriptive vs causal, aggregation choices).
4. Future work — 2–4 sentences on what a follow-up could do (causal identification, finer disaggregation, updated vintages).

Conclusion (≤ 250 words)

One paragraph. Restate the research question, the headline finding with its test statistic, and one practical implication. Hedged.

Abstract (200–300 words, structured)

Fixed four-label order:

• Background (2–3 sentences) — why the question matters.
• Methods (2–3 sentences) — data source, time window, tests used.
• Results (3–5 sentences) — headline numbers with test statistics.
• Conclusions (1–2 sentences) — hedged takeaway.

Write the Abstract last so the numbers already match the Results section.

References

Render in the chosen style.

• APA 7 — alphabetical by first author surname, author-date in-text (e.g., "(Tubiello et al., 2022)").
• Nature / Science numbered — superscripts ¹²³, references numbered in order of appearance.

All references also land in references.bib as BibTeX for import into Zotero / Mendeley.

Data availability

One paragraph: "The FAOSTAT data used in this study (domains [codes]) are freely available under CC-BY-4.0 at https://www.fao.org/faostat/. All API calls, parameters, derived tables, and statistical test outputs are logged in the xlsx appendix accompanying this manuscript."

Funding, Acknowledgements, COI, Author contributions

All optional; generate blank templates if the user hasn't filled them in.

Step 8 — Build the docx

Use python-docx. Structure:

• Times New Roman or Cambria, 11pt body, 10pt tables, 10pt footnotes, 1.5 line-spacing double-column layout is NOT default — keep single-column for editability.
• Numbered headings (1. Introduction, 2. Materials and Methods, …) — matches IMRaD convention.
• Figures embedded as PNG (render with matplotlib or the faostat-map skill for choropleths). Caption style "Figure N." in bold, rest in regular weight.
• In-text citations follow the chosen style; rebuild the reference list in the chosen style at the end.
• Page numbers in the footer.
• Suggested citation block in the front matter:

  Suggested citation: [Author] ([YYYY]). [Title]. Manuscript.
  

  — no "Required citation: FAO. …". Any such line is a skill bug.

Step 9 — Write the BibTeX file

Create references.bib alongside the docx. One entry per cited work. Use @article, @book, @techreport, or @misc as appropriate. Include doi = where known, leave blank otherwise. Key format: author-year-firstword (e.g., tubiello-2022-pre).

Step 10 — Save and describe

Share computer:// links for:

• the .docx
• the .xlsx appendix
• the .bib file

Give a 4–5 sentence description: the research question, the time window, the key Mann–Kendall / Spearman / Kruskal–Wallis finding, any invariant that materially shaped the output (China composite choice, rankings fallback, unit conversion).

Step 11 — Offer refinements

• Swap citation style (APA ↔ Nature).
• Add a regression (requires the user to name covariates).
• Deepen the lit review (requires the user to upload or name specific papers).
• Alternate time window / geographic scope — triggers a full rebuild.
• Causal framing — requires the user to name an identification strategy; skill adds a "Causal identification" subsection to Methods.

Composition with other skills

• faostat-map — called when a Results figure is a choropleth. Pass palette (any neutral — "Ink" is closest to academic), disaggregate_china=true, output_format='png' (for embedding) or 'svg' (for sharper output).
• faostat-analytical-brief — different audience (policymakers vs researchers). A paper is not a brief with more words — the statistical framing, hedged tone, and structured abstract are fundamentally different. Do not cross-use templates.
• faostat-infographic — cross-link only via the Data availability statement ("A public-facing infographic summary is available at […]"). Papers and infographics do not share figures.
• faostat-export-dataset — the xlsx appendix is already an export; the export skill is for standalone data releases without a manuscript.

Error handling

• Empty faostat_get_data payload — retry with comma year list (invariant 2); if still empty, widen by ±2 years and log the adjustment in Methods.
• requires_confirmation on faostat_search_codes — stop and ask the user via AskUserQuestion. Never guess codes — a wrong item code is a silent fabrication.
• faostat_get_rankings HTTP 500 — fall back to client-side sort (invariant 6) and note in Methods.
• Mann–Kendall on fewer than 8 data points — refuse the trend test; report descriptive stats only and note the minimum-n limitation in Limitations.
• User asks for a causal claim without a causal design — push back. Offer to either rewrite the claim as an association or to add a custom causal-identification subsection. Do not silently soften — explain the invariant.
• User asks to add FAO branding (logo, masthead, "Required citation: FAO.") — push back. Explain invariant 11. The CC-BY-4.0 data attribution in Methods and Data availability is sufficient.
• User requests auto-drafted literature review beyond the named anchors — push back. Explain fabrication risk. Offer the skeleton + [add peer-reviewed refs] path, or ask the user to upload / name papers.

Suggested citation block (goes in the docx front matter)

Suggested citation: [Author]. [YYYY]. [Title]. Manuscript. Accessed FAOSTAT [Month YYYY].

Never "Required citation: FAO. …". Any such line is a skill bug.