The descriptive report¶

Exercise descriptive-report-annex.pdf · PDF

Before you download a game, what do you read? The store page. What it is, who made it, how big the download is, what the reviews say, whether it runs on your machine. One minute, and you decide.

Now think about games_clean. You have spent five weeks cleaning it and one lesson measuring it. You know that the price has a tail, that nine games in ten have no Metascore, that "owners" is the bottom of a range. Nobody else knows any of that. If a classmate opens your table tomorrow, they see 26,685 rows and no warnings.

Today you write the page that tells them. It is the last piece of the "prepare" stage: the label on the crate before it goes to the people who will build with it.

The store page of a dataset¶

A descriptive report is a short text that tells someone who has never opened a dataset what is in it, where it comes from, how good it is and what it cannot be used for.

It is the store page of your data. You read it before you "install" the data in a chart. And like a store page, it has the same sections every time, so a reader knows where to look. We keep the store page for the whole lesson.

flowchart LR
    subgraph CTX ["Can I trust it?"]
        direction TB
        P1["<b>1 · Source</b><br>who, where, when"] --> P2["<b>2 · Size</b><br>rows, columns, period"] --> P3["<b>3 · Variables</b><br>columns, types, units"]
    end
    subgraph FIG ["What does it say?"]
        direction TB
        P4["<b>4 · Quality</b><br>missing, estimated, doubtful"] --> P5["<b>5 · Key figures</b><br>centre, spread, distribution"]
    end
    subgraph LIM ["Where does it stop?"]
        P6["<b>6 · Limits</b><br>what it cannot tell you"]
    end
    CTX --> FIG --> LIM

The whole thing fits in 250 words. That limit is not a punishment. It is the exercise.

Two reports, same data¶

Two students describe the same table. Which one would you trust?

Now point at the exact words that make the difference:

That last row matters. The table shows 53 games released in 2004 and 8,845 in 2018. That is more games released. It is not more players: the table does not count players at all. Report A went beyond the data. Report B knew when to stop.

Parts 1 to 3: what is this?¶

These three need almost no queries. They answer "what am I looking at?".

Part 1 · Source¶

Say who collected the data, where it was published and when, and who cleaned it. For our table: the data was collected by Liza Wood from the site Steam Spy, and published by the TidyTuesday project on 30 July 2019 as video_games.csv (the file on the Resources page). We cleaned it in class into games_clean.

A report is reproducible when another person, with only what you wrote, can get the same data and reach the same numbers.

A file stays the same. An API does not: it can answer differently tomorrow. So when your data comes from an API, as some of your own project datasets do, "source" must name three more things, or nobody can ever get the same rows again:

APIs come from Data sources: you ask a web address and it answers with data. Writing "source: PokéAPI" is like citing a book as "source: the library".

Part 2 · Size¶

One query gives you most of it:

SELECT COUNT(*) AS n_games, MIN(release_date) AS first_release,
       MAX(release_date) AS last_release
FROM games_clean;

Add the number of columns (the table has 15) and, above all, say what one row is. It sounds too obvious to write. It is the single most useful sentence of the report.

Part 3 · Variables¶

Do not list all 15 columns. Group the important ones and give each its type and its unit.

Without the unit, "playtime 110" could be minutes, hours or sessions. In this dataset it is minutes.

Parts 4 and 5: what does it say?¶

Here you reuse the stat card from Exploratory statistics. Every sentence is built the same way.

Number + unit + meaning. "4.99" is a query result. "The typical game costs 4.99 USD (median)" is a sentence.

Part 4 · Quality¶

Name what is missing, estimated or doubtful, and how much. A count or a percentage, always.

SELECT COUNT(*) AS games, COUNT(metascore) AS with_score,
       ROUND(100.0 * COUNT(metascore) / COUNT(*), 1) AS pct_with_score
FROM games_clean;

Notice the second sentence of the strong version. In Imputation you decided not to fill the Metascore. The report is where you tell the reader about your decisions: what you filled, with what, and what you refused to fill.

Part 5 · Key figures¶

Centre, spread and one distribution. For the distribution, the share-of-the-total pattern from Synthetic variables does the work:

SELECT price_band, COUNT(*) AS n,
       ROUND(100.0 * COUNT(*) / SUM(COUNT(*)) OVER (), 1) AS pct
FROM games_clean GROUP BY price_band ORDER BY n DESC;

Part 6: what the data cannot tell you¶

This is the part beginners skip, and the part that makes a report trustworthy.

The limits of a dataset are the questions it cannot answer and the conclusions it does not support.

Ask yourself: what would a journalist in a hurry wrongly conclude from this table? Then write the warning. A good limit often starts with "This data cannot tell..." or "Careful: ...".

Three more columns hide a limit each: metascore, price and release_date. Think about which games get a review score, on which day the price was read, and what the last date in the table is. Finding those limits is your job in the practice below.

Try it: write the report¶

Write the descriptive report of games_clean: six headed parts, 250 words maximum, so that a classmate from another group could use the table without asking you anything.

Step 1 — Parts 1 to 3. Source and variables come from your notes of this unit. Size needs the one query above.

Step 2 — Parts 4 and 5. Reuse your stat card. Minimum: two quality problems, each with a count or a percentage; the centre and spread of price; and one distribution (price_band or owners_tier).

Step 3 — Part 6. No queries at all. At least two limits.

Step 4 — Attach the SQL. Paste the queries behind every figure below the report. They do not count towards the 250 words. They are what makes it reproducible.

Step 5 — Swap. Give your report to a classmate and take theirs. Tick this checklist. The rule: every "No" must point at the line it refers to. No marks and no adjectives, only yes, no and where.

Then fix one "No" in your own report. Reading a report you did not write is the fastest way to see what is missing in yours.

Key takeaways¶

• A descriptive report is the store page of a dataset: read it before you use the data.
• It has six parts: source, size, variables, quality, key figures, limits. Always in that order, each with its heading.
• Every figure is number + unit + meaning, and the query that produced it is attached.
• The source must make the report reproducible. For an API that means endpoint, parameters and extraction date.
• For a skewed column such as price, write the median (or both centres) and say why.
• Limits say what the data cannot tell. They make the report trustworthy, not weak.
• A report selects. All your query results pasted together are a log, not a report.

Quick check¶

That closes the "prepare" stage. Your table is clean, measured and described. It has also never been drawn. Time to build the HUD: Unit 3 · Data visualisation.