# Writing data entries
# Layout and structure
Each data entry should contain the four sections outlined below. We have a page template that captures this structure.
We begin with a short introductory text explaining what will be covered in the entry and why it is relevant. We try to emphasise why the topic is interesting to researchers and the wider public. We include here only very brief definitions of the key variables (if necessary) and provide a quick overview of the main findings. We do not include a heading for the introduction – it comes straight below the entry title (see our entry on Corruption, for example).
I. Empirical View
- Purpose. This part of the entry discusses both historical trends and recent developments. We always aim to provide a discussion that covers as many countries as possible, and that spans across time, from today, to as far back as possible. The long time frame must be the focus of our work and if we need to spend a lot of time producing estimates, and piecing estimates together then we should still do it.
- Within this broad section we split content into two or more subsections, usually labeled as ‘Historical Perspective’ and ‘Recent developments’
- Content within subsections is organised in “headline – text – chart” blocks.
- In the specific case of headlines within the ‘Historical perspective’ subsection, the idea is to focus on long-run trends. We try to provide long-run global and regional perspectives, and then move on to explore particular cases that merit attention. Often there is only long-run data for a few specific countries or regions; and sometimes there is no long-run data at all.
- The headlines corresponding to ‘Recent developments’ mostly focus on cross-sectional comparisons: what is happening around the world today?
- The headline in the “headline – text – chart” blocks should be catchy
- Often, a catchy headline is a question (e.g. “Where is perceived corruption highest?”)
- Sometimes questions are forced and it is better to make a statement (e.g. “Many firms from high-income countries engage in bribery across the world”)
- The text in the “headline – text – chart” blocks should provide a discussion of
- the data and its necessary context: what are we looking at?
- the chart: how should I read this visualization? (Remember that we aim to make our work understandable to non-experts as well and we should guide the reader through the visualisation by pointing out some aspects that can be learned from the visualisation.)
- the findings: what can we learn from this visualization?
- the bigger picture: references to papers, books and web resources that tell us more about it, including research findings to be found elsewhere
- The titles for the ‘Historical perspective’ and ‘Recent developments’ subsections are flexible. For long and dense topics, having more subsections is helpful for readers, because subsections show up in the navigation menu. For an example of multiple subsections see our entry on Taxation.
- The idea of splitting the analysis into “headline – text – chart” blocks is to allow people to read the entry in any order – they can find the chart or headline that they are interested in and read the relevant piece of text.
- This means that each block should be self-contained, and at the same time, provide a basic sense of continuity (i.e. a basic narrative that runs through the entry).
- The priority is to make sure that each block is interesting and clear on its own. Narrative should not be discarded, but is secondary – few people tend to read the entry ‘from top to bottom’. This also helps to take out these blocks and use them in dedicated blog posts.
# Writing style
Text online needs to be to-the-point. Have one idea per paragraph.
Nobody reads web pages, people scan them and concise paragraphs that are making their point clearly is much more useful than long rambling texts. But the shortness should never come at the cost of necessary depth.
If it is necessary to be long then structure the text by helpful headings.
II. Correlates, Determinants & Consequences
- Purpose. This part of the entry discusses correlations and causal evidence. In most topics this section makes perfect sense. But in some cases we may decide to link to another entry looking at the relationship between topics – for example, we may have an education data entry on ‘Female Education and Child Mortality’.
- Within this broad section we only split content into subsections if it is necessary because there are too many aspects to consider. For example, our entry on Corruption does not have subsections here; whereas our entry on Trust does.
- If we do split into subsections, we usually use subject-specific titles (again, see the example from Trust).
- This section should give an overview of the best academic research on determinants and consequences of the changes we observe in Empirical View.
III. Data Quality, Definitions & What We Do Not Know:
- Purpose. In this part of the entry we try to address any weaknesses in the data identified by OWID or discussed in the literature.
- Examples of weaknesses include selection problems, coverage, missing data, censoring, and unusual definitions.
- It is important to state the definitions used to produce the data that we discuss in the other sections.
- Not yet introduced, but planned for the future is a section here on ‘What We Do Not Know’. This section will list what we would like to be able to present in sections II. and III., and that is currently not available. I think it would also be good to mention our suggestions for how to get there so that we and others can fill in these gaps over time.
- As in any other section, the discussion here follows the “headline – text – chart” structure.
- Sometimes there are points that need to be made without charts. But we still try to split the content into bite-sized comments separated by headlines.
- Similarly to Correlates, Determinants and Consequences, we group headlines into subsections if it is necessary. We did this, for example, in Financing Healthcare.
- As in any other section, the discussion here follows the “headline – text – chart” structure.
IV. Data Sources:
- Purpose. This section should include links to the websites of the relevant datasets or data providers, whether or not they are presented in the data entry, as well as providing summary information on the data. The formatting for this section can be found in [sec:Data-Sources].
- Structure. See HTML headings below
General style conventions
- Use American spelling – British spelling should be ‘americanized’
- Try to use passive whenever it makes sense (“it can be seen that poverty has declined”), or the plural of the first person (“we have reasons to believe this data is flawed”)
- This should also be applied to the ‘About’ page (currently with many references in the first person singular)
- Place any explanatory footnotes at the end of sentences, but leave citation footnotes (i.e. expanded reference citations) directly in the year of publication. For example, Ortiz-Ospina and Roser (2016)1 should be cited in the text as in this sentence. Below we discuss citations in more detail.
- Use ‘sentence casing’ for all visualization titles. Below we discuss labelling in detail. However, here are a few key points
- Label external images stating first the title and then the source (both in sentence case): e.g. “Penalties in U.S. Government FCPA cases since 1977 – Mintz Group2“.
- In some cases you will find that existing image titles include table numbers from the original source – this information should not be in the title, but in a footnote and needs to be changed.
- Some of the old OWID interactive charts also need labelling, because the charts do not have an embedded title (see for example this chart in the Literacy entry). These should be labelled similarly to external charts, but without ‘Our World in Data’ as the source in the title, since that would make it too long and the source is obvious from the OWID logo in the figure itself: e.g. Literacy rates around the world from the 15th century to present3
- Cite using APA conventions – other citation styles should be converted to APA.
# HTML headings and formatting
It is recommended that all data entries should be edited directly in HTML to prevent unexpected formatting issues not apparent in the WYSIWYG editor. When creating new data entries, it is possible to copy and paste the HTML code from another page – for example, from the page template.
Headers are used in the following way:
- h1: Do not use!
- <h1> not </h1>
- h2: Headings for the four main sections listed above only (these use Title Casing)
- <h2> Empirical View </h2>
- h3: Headings for subsections (these use Sentence casing)
- <h3> Subsection 1 </h3>
- h4: Headings for headlines in the “headline-text-chart” structure (these use Sentence casing)
- <h4> Headline 1</h4>
- h5: Headings for data sources (these use Title Casing)
- <h5> World Bank Education Data </h5>
- h6: Headings for image titles (these use Sentence casing)
- <h6> Mean years of schooling, 1970-2014 – World Bank </h6>
From an old workaround there are some headings formatted like this:
They should instead all be of the form
Special HTML formatting for section on Data Sources
The major data providers and datasets for the topic in question should be listed in the Data Sources section. These should all be
formatted in the following way:
<h5> TITLE </h5>
<li><strong>Data</strong>: … </li>
<li><strong>Geographical coverage:</strong> … </li>
<li><strong>Time span:</strong> … </li>
<li><strong>Available at:</strong> <a href=”…”target=”_blank”>…</a></li>
<hr class=”datasources-hr” />
An example from the terrorism data entry is:
<h5> International Terrorism: Attributes of Terrorist Events (ITERATE) </h5>
<li><strong>Data</strong>: International terrorist incidents</li>
<li><strong>Geographical coverage:</strong> Global by country</li>
<li><strong>Time span:</strong> 1978-2011</li>
<li><strong>Available at:</strong> <a href=”http://library.duke.edu/data/collections/iterate”target=”_blank”>http://library.duke.edu/data/collections/iterate</a>, restricted to Duke University members</li>
<hr class=”datasources-hr” />
# LaTeX in WordPress
It is possible to use LaTeX in Our World In Data. Here is an example page in Our World In Data that shows the capabilities. A detailed explanation can be found here: http://www.holoborodko.com/pavel/quicklatex/
For this we are using Quick LaTeX plugin (click for more information).
There are two ways of including LaTeX in a page.
1) LaTeX in one paragraph: For most cases it is enough to just have one formula here and there. Then you may always place a LaTeX expression within latex .. /latex in squared brackets “” shortcodes.
This is an example:
2) LaTeX on an entire page:
If we really need to include a lot of LaTeX on a page then you can write latexpage in squared brackets “” on the top of the page.You then do not need the latex .. /latex shortcodes in any paragraph.
# Handling Links
# General conventions
Links to other websites or data entries can be added using the WordPress tool or by directly writing the HTML code. Links are standardized in the following way.
External site: Links to external websites should always (i) open in a new tab, and (ii) use the link as the text unless the link is too long or messy. To force links to open in a new tab use the target=“_blank” attribute. Below are two examples:
– If the link is short and clean, it should appear as www.google.com:
<a href="http://www.google.com" target="_blank"> www.google.com</a>
– If the link is long or messy, it is preferable to use some identifying label rather than the address. However, try to use a meaningful label so that people know where they are going even if the link is broken. For example, instead of saying “online here”, say “online from ABC’s website“:
<a href="https://www.google.co.uk/?gws_rd=ssl#q=ABC" target="_blank"> ABC </a>
Link within OWID: Links within OWID should not open in a new tab. The text displayed for the link should be the name of the section or entry being linked to. For example:
– Link to the Data Sources section should appear as Data Sources:
<a href=”http://ourworldindata.org/data/education-knowledge/quality-of-education-drop-out-rates/#data-sources”>Data Sources </a>
# Fixing broken Links
Links and references to external sources can eventually become invalid for a variety of reasons. Perhaps their author moves between institutions, or the source does a big redesign of their site layout. Broken links on Our World in Data are periodically tested and logged by the Broken Link Checker. Hovering a link and selecting “Edit URL” within the link checker interface will let you replace it. In most cases, the automatically suggested archive.org replacement will be appropriate. However if the original page contained complex embedded content or was e.g. a link to buy a book then it may not be amenable to archival and you’ll want to fully replace it.
# Use meaningful text on links
The text on the link should be meaningful so that even if the link breaks it stays useful for the reader. This means that we should not write ‘More information can be found here‘ but instead we should always write something like ‘More information on the measurement of maternal mortality rate can be found in the UNICEF report ‘Trends in Maternal Mortality: 1990 to 2015‘ published on November 12, 2015’.
# Handling images
All images should be uploaded using the WordPress tool on the page editor (see Figure below). The standard formatting used by WordPress for images inserted using the tool should be fine in most cases.
The filename of the image will become its title in the WordPress image database and is also displayed when the image is clicked by users. For this reason, remember to give the image an appropriate filename before it is uploaded or to change the title once it has been uploaded. This will also make it easier to find the image in future using the WordPress search feature.
All images should have a title above written using the HTML header 6 – <h6>title</6> – discussed in the above section HTML-headings.
Images must be clickable by the reader so that they open in full resolution. The way to do this is to add a link in the image that refers to the “Media File” (which is the image itself). You add links in the menu in the ‘Add Media’ section or in the edit mode of the image (you get there by clicking on the image in the editor and then choosing the pencil icon).
As mentioned above, the title of all images and visualisations that are not created by Our World In Data must have the source in the title – and the detailed information associated with it in a footnote. An example for the title format is “Causes of child mortality in Asia in 1990 – UNICEF (2007)(ref)UNICEF (2007) – Committing to Child Survival: A Promise Renewed – Progress Report 2007.(/ref)” Of course the ref must be in  instead of (), but it would actually create a footnote if I wouldn’t put it in () in this example.
# Handling references
References are a key element of all data entries and should be used to indicate the source of any quotes, facts or images. All references will appear at the end of the data entry in a standardised way. HTML does not have a built in reference feature however OWID makes use of the WordPress plugin Side Matter to create references.
To provide a reference, two ref tags should be placed around the source, with the first tag placed at the intended location of the superscript number indicating a reference. One easy way to correctly format references is to search for the source on Google Scholar and click cite (see Figure below). As already mentioned, we should stick to APA citation guidelines (second option in Google Scholar in the Figure below).
Notice that these tags are not the same as the usual HTML </> type tags.
If the source is a journal article, it is important to link the citation to the journal page where it is hosted (e.g. JSTOR), or when possible, an open access source (Google Scholar usually provides an alternative).
# Producing tables in HTML
Generally we try to avoid tables and think of a way to display the information visually. However there are cases in which (a small) table is useful. In these cases we use the WordPress Plugin TablePress.
In the editor you click on TablePress (in the left column) and then on ‘add new table’.
In the ‘Input’ tab you can chose the option ‘Manual Input’ and there you can copy-paste the table directly from Excel. On the following page you can add the title of the table and specify the settings (please do not use fancy Features – they are useful for large tables, but we want to avoid large tables).
Finally you copy the shortcode for the table you created. The shortcode specifies the table id in brackets, and you copy it into the data entry to the position where it should appear.
In the editor you have to give the table a h6-headline and add the sources in the same way as for the images – attached to headline.
If everything works it looks like this:
Country or Region Mean age at first marriage Births per married women Percentage never married Total fertility rate Belgium 24.9 6.8 — 6.2 France 25.3 6.5 10 5.8 Germany 26.6 5.6 — 5.1 England 25.2 5.4 12 4.9 Netherlands 26.5 5.4 — 4.9 Scandinavia 26.1 5.1 14 4.5
# Writing blog posts
Blog posts should always start with the following statement:
Our World in Data presents the empirical evidence on global development in entries dedicated to specific topics.
This blog post draws on data and research thoroughly discussed in our entry on Global Extreme Poverty
This statement is therefore always included by default when starting a new Post.
# Writing the Glossary
To explain technical terms we write a glossary – it is here.
The structure is the following:
1 – The heading is always a question:
What is [term that is explained in bold]?
2 – Then follow synonymous terms. The tool that Jaiden develops will in the future also be able to show the same glossary explanation for these terms.
3 – Then follows one paragraph that will be displayed when hovering over the term somewhere in the website.
This is the most important part because only this first paragraph will be visible to the reader when she is hovering over the technical term in an entry or blog post.
We should therefore make sure that all the first paragraphs contain sufficient information to give a useful description of the concept by themselves.
4 – Then comes a text that can be as long as necessary that will be visible only when viewed in the glossary.
How to refer to the ‘international dollar’?
We use currently very different ways of referring to international dollars. From now we use the following:
spelled out only when it is first used: 198.7 international-$
then always: 198.7 int-$
(Please correct it wherever it is spelled differently.)
# OWID Grapher
This second part explains how to use, and the available capabilities of, the Our World in Data Grapher—the tool we developed for data visualization. General information and a video of how to use the Grapher can be found in a dedicated page.
# B1 Uploading Datasets
To create visualizations using data not already in our database, the new data must be documented and uploaded into the Grapher here. In this section, we explain the process of doing so. In summary: 1). Country names need to be homogenized, 2). The .csv file must be properly formatted, 3). The original dataset and documentation of its manipulation need to be saved, 4). New datasets need to be added to the Grapher database with consistently filled out metadata
Note that the Grapher currently only recognizes .csv files.
# 1). Homogenizing country names – the Grapher country name tool
All datasets uploaded into the Grapher must contain country (or territory) names that meet either the OWID or ISO3 standard. For the purpose of converting names into these standards, we have created a custom ‘Country name tool’ in the Grapher, which is simple to use and can be found here.
The country tool data can be updated here. Please be sure to follow these instructions:
- Download the existing country tool data from the link in order to update it,
- To add new country spellings: 1). Insert a new row below the country name you wish to add a new spelling for, 2). Enter the new spelling in the appropriate column, 3). Ensure that the remaining columns are filled in to match.
- To add new territories*: 1). Scroll to the last row, 2). Fill in the column fields.
* Since data is sometimes available for territories that do not have ISO3 codes, authors are strongly encouraged to use OWID names as the preferred standard. Not doing this may result in inconsistencies, such as repeated observations for a country. If a territory does not exist in the tool, but you consider that it should for the purpose of a specific dataset, then it can be added.
# 2). Formatting the .csv file
Single variable datasets
With panel data (time and space), the first cell of the first row A1 should contain the time interval used (e.g. ‘year’). The remaining cells of the first row should contain the years of observations. The first column should contain the names of the countries. The country names must be either the OWID name or the ISO3 code. To convert lists of countries in one format to another use the OWID Country name tool (see above for more detail). The Figure below is an example using the United Nation’s Human Development Index; the country names are the ISO3 codes.
Multi-variable datasets are those that contain panel data for several different variables. The first column should contain the country names with the first cell (A1) containing the word ‘country’. The second column should contain the year of the observation with the first cell (B1) containing the word ‘year’.
The remaining columns should contain the variables in the dataset, where the first cell of each column is the name of the variable. This format can also be used for single variable datasets. See the Figure below for an example using the Correlates of War dataset.
# 3). Storing the original dataset and documentation
Take John Cochrane’s advice seriously: “Document your work. A fellow graduate student must be able to sit down with your paper and all alone reproduce every number in it from instructions given in the paper, and any print or web appendices.”
We need to make sure that at any later point in time we understand clearly where the data presented on OWID comes from and what we did with it before we uploaded it into the Grapher.
- We need to know the original source.
- We need to know all the necessary manipulation–standardization of country names, rounding, merging of data etc.
For this reason we have the internal OWID database in Dropbox. That database is structured in the 16 categories and subcategories and for each dataset (or variable) we have a folder with the 3 subfolders ‘original’, ‘manipulation’, and ‘uploaded’.
The folder ‘original’ only has the original dataset(s) as downloaded. nothing else. Once the original file is there, you take that file and copy it to the folder ‘Manipulation’ and either document your manipulation or save Stata .do-files or R files there that make it clear how you manipulated the file. Once this is done, you finally copy that file to the ‘uploaded’ folder and save it there as an .csv file. And then you upload that file into the Grapher and document all of it in words in the source information.
Here is an example of what the structure of the Dropbox database looks like:
# 4). Adding a new dataset to the Grapher database
In order to keep the metadata of new datasets consistent, this section explains how to label various parts of the dataset when uploading it to the Grapher. Datasets consist of variables, and variables have sources attached to them. One source can be used in variables across multiple datasets. And one dataset can have several variables with different sources. Below is an explanation of the information that all A). Datasets, B). Variables and, C). Sources should have.
- Dataset name
Datasets should be named in a way that clearly (and succinctly) makes reference to the content and the main underlying source. The format should be something like “Overarching Variable Description – Author (year)” or “Overarching Variable Description – Institution, Project (year or vintage)”. The ‘Overarching variable description’ allows anyone to guess what kind of variables are included in that dataset without having to explicitly list all the variables in the title.
For example, the taxation data from the ICTD should be in a dataset called “Government Revenue Data – ICTD (2016)”. This makes it clear to anyone that the information inside will be related to taxation and possibly other sources of govt revenue. We should avoid having datasets that are lists of variables; for example, we should not have “Income, consumption and trade taxation data – ICTD (2016)” in this case. Examples of ‘Overarching variable description’ include “Life expectancy – Miller (1990)” or “Vaccination perception measures – XXX (2016)”.
- Dataset category
All datasets should have one category attached to them. The possible categories are listed in a dropdown menu. One category must be chosen, even if more than one category applies. These are only for internal organization (it allows us to browse the datasets by topics).
- Variable name
Variables should be named using some minimal description of the underlying content and the source. This should be in the format of “Minimal variable description (Source)”; for example “Top marginal income tax rate (Piketty 2014)”. Or “Tax revenue as share of GDP (ICTD 2016)”.
In some cases many variables share parts of the variable description within a given dataset. In those cases it could make sense to use hyphenation, for example “Vaccination perceptions – importance (Larson et al. 2016)” and then “Vaccination perceptions – safety (Larson et al. 2016)”, and so on.
- Variable description
The variable description will be displayed in charts (‘Sources’ tab). It will be the first row in the table explaining the variable sources. Variable descriptions should be concise but clear and self-contained. They will correspond, roughly, to the information that will go in the subtitle of charts.
For example: “Percentage of the population covered by health insurance (includes affiliated members of health insurance or estimation of the population having free access to health care services provided by the State)”.
- Variable unit
All variables should have a long and a short description of the data unit. The long unit should include all the information that is necessary to interpret observations (e.g. “metric tons per capita”). While the short unit is what will be displayed in axis-labels as suffix and in the legend of the map (e.g. %, or US $).
NB. Currently, there is only one field for ‘unit’. But we will move to a system with fields for long and short units.
C). Data sources
- Data source name
For academic papers, the name of the source should coincide with the protocol for referencing—so it should be “Authors (year)”, where “Authors” include surnames. For example, Arroyo-Abad and Lindert (2016).
For institutional projects or reports, the name should be “Institution, Project (year or vintage)”. For example, U.S. Bureau of Labor Statistics, Consumer Expenditure Survey (2015 release). Or Fraser Institute, Economic Freedom of the World (2015 Annual report). For data that we have modified extensively in order to change the meaning of the data, we should name the data as “Our World In Data based on Author (year)” or “Our World In Data based on Institution, Project (year or vintage)”. For example: Our World In Data based on Bourguignon and Morrisson (2002) and World Bank (2015).
In general, for data that combines sources we should include all authors in the name—even if we do not modify anything and simply stitch them together. For example, Flora (1983) and ICTD, Government Revenue Dataset (2016).
It doesn’t matter that much if names are very long, since we can always abbreviate the name that is displayed in the chart when we create it in the grapher.
Judgement will always have to play a role. But the idea is to stick to a format of author/year or institution/report/year, including all as relevant.
- Data source format
For academic papers, the first item in the description should be “Data published by: complete reference”. This should be followed by the authors underlying sources, a link to the paper, and the date on which the paper was accessed. For example:
Data published by: Lee, Jong-Wha; Lee, Hanol. Human capital in the long run. Journal of Development Economics, 2016.
Data publisher’s source: Compiled census observations and information on the year of establishment of the oldest school in individual countries
For institutional projects, the format should be similar, but detailing the corresponding project or report. For example:
Data published by: OECD Affordable Housing Database
Data publisher’s source: 2016 OECD Questionnaire on Affordable and Social Housing (QuASH 2016)
In some cases it will be hard to be specific about the underlying publisher’s source—but we should try to give at least basic pointers (interviews? surveys? administrative data? historical records?). We should not include anything longer than a couple of lines; if explanation is complicated, it’s better to simply say e.g. ‘various surveys – see Table x in reference for details’.
For data that we have modified extensively in order to change the meaning of the data, we should list OWID as publisher, and provide the name of the person in charge of the calculation. We should also change the field “Retrieved” to “Dataset produced:”.
The underlying sources should be included as part of the “Data publisher’s source”, with further details on the actual calculation to go as “Additional information”. For example:
Data published by: Our World In Data (Max Roser)
Data publisher’s source: Estimates up to 1981 use data from Bourguignon and Morrisson (2002), Inequality Among World Citizens: 1820–1992. In American Economic Review, 92, 4, 727–744. Estimates from 1981 to 2013 use data from World Bank PovcalNet (2015).
Link: XXX and YYY
- Data source additional information
The main purpose of the ‘additional information’ field is to provide essential information regarding where the data comes from. This includes key definitions, coverage, etc. This is the space where we should be very clear about any modification we have made to the data. We should provide clear pointers, but we should try to make this field concise, since otherwise nobody reads it (and it is crucial people do). For brevity, we should provide links to external resources. For example:
Data from the ICTD corresponds to estimates from OECD. More details in Prichard, W. (2016). Reassessing Tax and Development Research: A New Dataset, New Findings, and Lessons for Research. World Development, 80, 48-60.
In some cases quoting directly is the best solution. For example in the Lee and Lee (2016) data the additional information says:
The authors note: “We construct a complete data set of historical enrollment ratios, subdivided by education level and gender, for 111 countries from 1820 to 1945 (at five-year intervals) by using newly compiled census observations and information on the year of establishment of the oldest school in individual countries. Then, by utilizing these enrollment ratios, as well as available census data from 1945 onward on different age groups’ educational attainment, we construct a data set of estimated educational attainment, disag- gregated by gender and age group, and aggregate human capital stock that spans from 1870 to 2010.”
# B2 How to make charts
For explanation I’m describing the process of making a line chart with a map – other chart types have specifics that will be mentioned with the example of these different chart types below.
- Click on “Charts” in the main menu on the left
- You will have a preview of the chart on the left (this is pretty empty for now) and the menu for authoring the chart on the right. The author options are distributed over 5 tabs – from Basic to Export and can be extended to the Map tab as the 6th tab.
- On the first panel
- Choose a title (always in Sentence case)
- Never specify a time frame or name countries in the title. Instead you can use *time* and *country* as placeholders in the titles of visualizations. The Grapher will then automatically show the right time range. The *country* option is only relevant for Change-Country-Charts (see below) – but we should generally not mention specific country names since it becomes weird if the title says China and Brazil and some reader adds Norway and removes China – a screenshot of the chart for example becomes then unusable for the reader.
- Choose a subtitle
- The subtitle should explain the chart so that the chart can stand on its own. So it necessary to give an explanation of the variable. How is it measured? What does the measure mean exactly?
- The subtitle can also include an explanation of how to read the chart in case this is necessary.
- It is therefore okay if the subtitle is 2 or 3 lines long.
- Choose the type of chart that you want to have. All options are here except maps which are a special case – they are shown on a different layer and can be added on the Export Tab. (If you only want to make a map you have to chose a chart on the Basic Tab even though it won’t be seen in the end.)
- Check the link name under which the chart will be published (this appears under the chart title). The grapher will provide a default address based on the title, but you can edit it (only before publication).
- Choose a title (always in Sentence case)
- At any point throughout the process of making a chart you can click on the green Save Draft button – only after you save a draft, you will be given the option to publish the chart.
- On the second panel – Data – you can
- Add a variable. All variables are categorized and can be found in the category. They can also be searched.
- Once you found the right variable – let’s say “Penn World Table 8.1 (Real GDP at chained PPPs in 2005US$)” – you can select this and then you have to drag and drop this variable name on the field where this variable should be shown. In case of a simple line chart this is the Y Axis field.
- Now all the countries should be displayed and the chart will look very messy. In option F you can now specify which countries should be shown by default. If you want to change the color of a country you can click on it and you will see a menu.
- Option G – the time frame you can leave as it is, or play around with it,
- On the 3rd panel – Axis – you can
- Add a Y-axis label (we don’t need to put year on the X-axis as this is obvious)
- You can also add “$” as the Y-axis suffix
- Max and Min are rarely necessary to specify as the Grapher adjusts these automatically
- The Styling Tab
- has the important option to choose the type of line – please use “line with dots” if the data is patchy so that is clear to the user that the timeseries is “graphically linearly interpolated” when there is no dot.
- In Option M you can specify the popup units that is shown on hovering over the chart. Here is a small bug: This option only works by clicking the tick away and then adding the tick again. Here it is important to restrict the number of decimal places to something useful.
- On the Export Tab
- You can add a Map Tab
- Choose the default tab on which the chart is loaded
- Note that you can change the URL on which a chart is loaded also with adding the ?tab= option to the chart’s URL
- Note that you can change the URL on which a chart is loaded also with adding the ?tab= option to the chart’s URL
- On the Export Tab you can also copy the line of html code to embed the iFrame.
- The map tab
- Gap between years is 1 by default. This means that a map for every year can be selected by the viewer. You can increase this gap – for example if data is only available for every 5 or 10 years.
- You can also select a Tolerance (T) for observations shown in maps. This means that if for a variable there is no data for a specific year X the Grapher will automatically look in the following and preceding years to find the closest observation. The Grapher will then look for observations that are between X-T and X+T.
- Select a color scheme. These color schemes are the ColorBrewer2 schemes and you can helpfully see all of these by clicking on the small blue (i) next to color scheme.
- You can also increase the number of categories. Note that the color schemes differ in the number of categories.
- By default the data is automatically categorized but you can also do this yourself – just click away the tick next to “Automatically classify data”
- You can then add the bracket limits. The bracket limits have the limit smaller or equal <= to the bracket limit.
- You can also label the categories – this is useful for maps that show categorical data (see below in the example section).
- With the legend
- you can change the orientation – use portrait for long numbers or words so that they don’t overlap
- give the legend a title
- The square size should be increased if otherwise the labels of the legend overlap.
- That’s it. Go to to the export tab and copy the line of html code and embed your chart in your article.
# B3 List of possible visualizations
The Our World In Data Grapher is using the library NVD3.js and all examples of charts (and their names) are listed there http://nvd3.org/examples/index.html.
# 3.1 Line Chart
3.1.1 Simple line chart
Click on add country to show a different country. Click on a shown country to remove it from the chart.
How to create this chart: This is described above in a step-by-step guide.
3.1.2 Line chart with more than one variable associated with one country
In the example below adding or removing a country always adds and removes observations for men and women.
How to create this chart:
To do this chart pick “line chart” as the type of chart. In the data tab select female suicide rates and drag-and-drop it to the y-axis; then select male suicide rates and also drag-and-drop it to the y-axis. Done. (By the way, this also works for two unrelated variables like GDP and suicide rates, but they will be shown on the same y-axis which does not make sense.)
3.1.3 Ordering and coloring line charts
The visual stacking order of lines in charts (i.e. which line overlays another if they overlap) is based on the data selection order in the grapher.
Lines can also be coloured manually using the RGBA colour field code. RGBA codes can be found here. The format of RGBA codes is rgba(R,G,B,a), where R, G, and B are the decimal values for the red, green, and blue values of the color on the range 0 to 255 and a is the opacity of the color (a = 0 = transparent; a = 1 = opaque). For example, the color with decimal values 23 for red, 67 for green, and 88 for blue and which has an opacity of 0.5 (semi-transparent) is rgba(23,67,88,0.5).
# 3.2 Stacked area chart
3.2.1 Stacked Area Chart
This chart is useful if observations in a specific year sum up to a meaningful total.
How to create this chart:
On the first tab select Stacked Area Chart.
For this type of chart there are two distinct options: 1) stacking up the same measures for several countries or 2) stacking up several measures for the same country.
- You select this option on the second tab – Data: Default is option 1; if you want to stack up several measures for the same country instead, chose the option ‘Group by variables’ in option D and select ‘User can change country’ in option F.
Now add the variables to the Y-axis. Done.
3.2.2 Stacked Area with Change Country function – Population breakdown by education
You can click on Change Country to see the data for a different country.
How to create this chart:
# 3.4 Bar chart
(horizontal and vertical; single- and multi-bar charts)
3.4.1 Stacked/Grouped Multi-Bar Chart
This is a bar chart for time series information
Example shows war deaths – you can “group” or “stack” the data by year by choosing one or the other option on the top left.
How to create this chart:
3.4.3 Discrete Bar Chart
How to create this chart:
# 3.4 Scatter plot
How to create this chart:
Most of the options are described in the above section that explains how to create a line chart. Here only the differences between making a scatter plot and a line chart are explained – these are the settings in the Data Tab:
In the data panel you can select a variable (in the ‘Add variable’ box) and then drag-and-drop it to the x-axis, select a new variable and drag-and-drop it to the y-axis, and select a variable to drag-and-drop to the size (commonly this is the population of the country).
The year for which the scatter plot should show the data can be defined on the same panel in a menu that is accessible through the cogwheel. The menu accessible through the cogwheel is key for this chart – but admittedly it is not obvious to find.
The menu looks like this:
You can either “Display values for single year” or “Display values for entire period”. For the first option you of course can specify the single year for which the scatter plot should be done. In the second option observations for each year will be matched.
In both options you can select a Tolerance (T) – this means that if for a variable there is no data for a specific year X the Grapher will automatically look in the following and preceding years to find the closest observation. The Grapher will then look for observations that are between X-T and X+T.
# 3.5 Choropleth World Maps
(world maps and maps of all countries and continents)
How to create this chart:
Similar to maps you can select a Tolerance (T) for observations shown in maps. This means that if for a variable there is no data for a specific year X the Grapher will automatically look in the following and preceding years to find the closest observation. The Grapher will then look for observations that are between X-T and X+T.
3.5.1 World maps with numerical (ratio) data
3.5.2 Political Regime Map – World map with categorical data that is coded as numerical data and then displayed with category names
# World region
Our world regions are defined as shown in this map.
# Other world region definitions used on Our World in Data
# Color scheme
South America: #69c487
North America: #4d824b
# OWID Presentations
<!–To include an image and caption –>
<a target=”_blank” href=”https://ourworldindata.org/literacy”>
<!– To include an iframe and caption –>
<p>Fewer illiterate people: in 1930 the literate world population was only 33%; by 2014 it is at 85%</p>
<!– Headline plus image –>
<!– Just Image –>
<!– Just iFrame –>
<!– TITLE SLIDE – webaddresses & other links –>
<section class=”dark” id=”title-slide” data-transition=”slide”>
<h1>Conference<br>Our World In Data</h1>
<p><a href=”https://ourworldindata.org”><font color=”lightblue”>www.OurWorldInData.org</font></a></p>
<p><a href=”http://Conference.co.uk/”><font color=”white”>Conference – 1974</font></a></p>
<!– To make an element appear only after a next step include class=”fragment” like this:
# OWID Social Media & Communications
See here for general guidelines and best practice for managing OWID’s social media and other communications.