`tables`

A table is a collection of indicators that share the same index. The table metadata fields are the attributes of the TableMeta object in ETL.

`tables[].description`

type: string | recommended (often automatic)

Description of the table (mostly for internal purposes, or for users of our data catalog) which is a one- (or a few) paragraph description of the table.

Guidelines

Must start with a capital letter.
Must end with a period.
Should not mention other metadata fields (e.g. producer or date_published). Exceptions:
- The other metadata fields are crucial in the description of the data product.
Should ideally contain just one or a few paragraphs, that describe its content succinctly.
Should be used only to override the automatic description (which usually is the description of the origin). For example, use it when the table has multiple origins.

`tables[].title`

type: string | required (often automatic)

Title of the table (mostly for internal purposes, or for users of our data catalog) which is a few words description of the table.

Guidelines

Must start with a capital letter.
Must not end with a period.
Should identify the table.
Should be used only to override the automatic title (which usually is the title of the origin). For example, use it when the table has multiple origins.

`tables[].variables`

An indicator (also commonly called 'variable') is a collection of data points (usually a time series) with metadata. The indicator metadata fields are the attributes of the VariableMeta object in ETL.

`tables[].variables[].description_from_producer`

type: string | recommended (if existing)

Description of the indicator written by the producer, if any was given.

Guidelines

Must start with a capital letter.
Must end with a period.
Should be identical to the producer's text, except for some formatting changes, typo corrections, or other appropriate minor edits.
Should only be given if the producer clearly provides such definitions in a structured way. Avoid spending time searching for a definition given by the producer elsewhere.

`tables[].variables[].description_key`

type: array | recommended (for curated indicators)

List of key pieces of information about the indicator.

Guidelines

Must be a list of one or more short paragraphs.
- Each paragraph must start with a capital letter.
- Each paragraph must end with a period.
Should contain all the key information given in other description fields, like description_short, grapher_config.subtitle or grapher_config.note.
Should not contain information about processing (which should be in description_processing).
Should only contain information that is key to the public.
- Anything that is too detailed or technical should be left in the code.

`tables[].variables[].description_processing`

type: string | required (if applicable)

Relevant information about the processing of the indicator done by OWID.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be used if important editorial decisions have been taken during data processing.
Must not be used to describe common processing steps like country harmonization.
Should only contain key processing information to the public.
- Anything that is too detailed or technical should be left in the code.

`tables[].variables[].description_short`

type: string | required

One or a few lines that complement the title to have a short description of the indicator.

Guidelines

Must start with a capital letter.
Must end with a period.
Must be one short paragraph (for example suitable to fit in a chart subtitle).
Should not mention any other metadata fields (like information about the processing, or the origins, or the units). Exceptions:
- The unit can be mentioned if it is crucial for the description.

`tables[].variables[].display`

We keep display for the time being as the 'less powerful sibling' of grapher config.

`tables[].variables[].display.color`

type: string

Color to use for the indicator in e.g. line charts.

`tables[].variables[].display.conversionFactor`

type: number

Conversion factor to apply to indicator values. NOTE: We should avoid using this, and instead convert data and units (and possibly other metadata fields where the units are mentioned) consistently in the ETL grapher step.

`tables[].variables[].display.description`

type: string

Description to display for the indicator, to replace the indicator's description.

`tables[].variables[].display.entityAnnotationsMap`

type: string

Entity annotations

`tables[].variables[].display.includeInTable`

type: boolean

Whether to render this indicator in the table sheet.

`tables[].variables[].display.isProjection`

type: boolean

Indicates if this time series is a forward projection (if so then this is rendered differently in e.g. line charts).

`tables[].variables[].display.name`

type: string

Title to display for the indicator, to replace the indicator's title. NOTE: Currently, grapher_config.title will be used only in charts, whereas display.name will be used in other places, like the table tab.

`tables[].variables[].display.numDecimalPlaces`

type: integer

Number of decimal places to show in charts (and in the table tab).

`tables[].variables[].display.shortUnit`

type: string

Short unit to use in charts instead of the indicator's short_unit.

`tables[].variables[].display.tableDisplay`

Configuration for the table tab for this indicator, with options hideAbsoluteChange and hideRelativeChange.

`tables[].variables[].display.tableDisplay.hideAbsoluteChange`

type: boolean

Whether to hide the absolute change.

`tables[].variables[].display.tableDisplay.hideRelativeChange`

type: boolean

Whether to hide the relative change.

`tables[].variables[].display.tolerance`

type: integer

Tolerance (in years or days) to use in charts. If data points are missing, the closest data point will be shown, if it lies within the specified tolerance.

`tables[].variables[].display.unit`

type: string

Unit to use in charts instead of the indicator's unit.

`tables[].variables[].display.yearIsDay`

type: boolean

Switch to indicate if the number in the year column represents a day (since zeroDay) or a year.

`tables[].variables[].display.zeroDay`

type: string

ISO date day string for the starting date if yearIsDay is True.

`tables[].variables[].license`

type: string | required (in the future this could be automatic)

License of the indicator, which depends on the indicator's processing level and the origins' licenses.

Guidelines

If the indicator's processing_level is major, assign CC BY 4.0.
If the indicator's processing_level is minor, choose the most strict license among the origins' licenses.

`tables[].variables[].origins`

type: array

List of all origins of the indicator. Automatically filled.

`tables[].variables[].presentation`

An indicator's presentation defines how the indicator's metadata will be shown on our website (e.g. in data pages). The indicator presentation metadata fields are the attributes of the VariablePresentationMetaobject in ETL.

`tables[].variables[].presentation.attribution`

type: string | optional

Citation of the indicator's origins, to override the automatic format producer1 (year1); producer2 (year2).

Guidelines Examples

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must join multiple attributions by a ;.
Must not end in a period (and must not end in ;).
Must contain the year of date_published, for each origin, in parenthesis.
Should only be used when the automatic format producer1 (year1); producer2 (year2) needs to be overridden.

DO	DON'T
«`Energy Institute - Statistical Review of World Energy (2023); Ember (2022)`»	«`UN (2023), WHO (2023)`»

`tables[].variables[].presentation.attribution_short`

type: string | recommended (for curated indicators)

Very short citation of the indicator's main producer(s).

Guidelines

Must start with a capital letter. Exceptions:
- The name of the institution or the author must be spelled with small letter, e.g. van Haasteren.
Must not end in a period.
Should be very short.
Should be used if the automatic concatenation of origin's attribution_short are too long. In those cases, choose the most important attribution (e.g. the main producer of the data).

`tables[].variables[].presentation.faqs`

type: array | recommended (for curated indicators)

List of references to questions in an FAQ google document, relevant to the indicator.

Guidelines

Each reference must contain fragment_id (question identifier) and gdoc_id (document identifier).

`tables[].variables[].presentation.grapher_config`

Our World in Data grapher configuration. Most of the fields can be left empty and will be filled with reasonable default values.

Find more details on its attributes here.

`tables[].variables[].presentation.title_public`

type: string | optional

Indicator title to be shown in data pages, that overrides the indicator's title.

Guidelines

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
Should not mention other metadata fields like producer or version.
Should help OWID and expert users identify the indicator.
For big datasets where constructing human-readable titles is hard (e.g. FAOSTAT), consider using other metadata fields to improve the public appearance of the title (namely presentation.title_public and grapher_config.title).

`tables[].variables[].presentation.title_variant`

type: string | optional

Short disambiguation of the title that references a special feature of the methods or nature of the data.

Guidelines Examples

Must start with a capital letter.
Must not end in a period.
Should be very short.
Should only be used if the indicator's title is ambiguous (e.g. if there are multiple indicators with the same title).

DO	DON'T
«`Age-standardized`»	«`The data is age-standardized`»
«`Historical data`»	«`Historical data from 1800 to 2010`»

`tables[].variables[].presentation.topic_tags`

type: array | recommended (for curated indicators)

List of topics where the indicator is relevant.

Guidelines

Must be an existing topic tag, and be spelled correctly (see the list of topic tags in datasette (requires Tailscale).
The first tag must correspond to the most relevant topic page (since that topic page will be used in citations of this indicator).
Should contain 1, 2, or at most 3 tags.

`tables[].variables[].presentation_license`

License to display for the indicator, overriding license.

`tables[].variables[].presentation_license.name`

type: string

`tables[].variables[].presentation_license.url`

type: string

`tables[].variables[].processing_level`

type: string | required (in the future this could be automatic).

Level of processing that the indicator values have experienced.

Guidelines

Must be minor if the indicator has undergone only minor operations since its origin:
- Rename entities (e.g. countries or columns)
- Multiplication by a constant (e.g. unit change)
- Drop missing values.
Must be major if any other operation is used:
- Data aggregates (e.g. sum data for continents or income groups)
- Operations between indicators (e.g. per capita, percentages, annual changes)
- Concatenation of indicators, etc.

`tables[].variables[].short_unit`

type: string | required

Characters that represent the unit we use to measure the indicator value.

Guidelines Examples

Must follow the rules of capitalization of the International System of Units, when applicable.
Must not end with a period.
Must be empty if the indicator has no units.
Should not contain spaces.
If, for clarity, we prefer to simplify the units in a chart, e.g. to show kWh instead of kWh/person, use display.short_unit for the simplified units, and keep the correct one in indicator.short_unit (and ensure there is no ambiguity in the chart).

DO	DON'T
«`t/ha`»	«`t / ha`»
«`%`»	«`pct`»
«`kWh/person`»	«`pc`»

`tables[].variables[].sources`

type: array

List of all sources of the indicator. Automatically filled. NOTE: This is no longer in use, you should use origins.

`tables[].variables[].title`

type: string | required

Title of the indicator, which is a few words definition of the indicator.

Guidelines Examples

Must start with a capital letter.
Must not end with a period.
Must be one short sentence (a few words).
Should not mention other metadata fields like producer or version.
For big datasets where constructing human-readable titles is hard (e.g. FAOSTAT), consider using other metadata fields to improve the public appearance of the title (namely presentation.title_public and grapher_config.title).

DO	DON'T
«`Number of neutron star mergers in the Milky Way`»	«`Number of neutron stars (NASA)`»
«`Share of neutron star mergers that happen in the Milky Way`»	«`Share of neutron star mergers that happen in the Milky Way (2023)`»

`tables[].variables[].unit`

type: string | required

Very concise name of the unit we use to measure the indicator values.

Guidelines Examples

Must not start with a capital letter.
Must not end with a period.
Must be empty if the indicator has no units.
Must be in plural.
Must be a metric unit when applicable.
Should not use symbols like “/”.
- If it is a derived unit, use 'per' to denote a division, e.g. '... per hectare', or '... per person'.
Should be '%' for percentages.

DO	DON'T
«`tonnes per hectare`»	«`tonnes/hectare`»
«`kilowatts per person`»	«`kilowatts per capita`»