Tutorial: Adding indicators

This tutorial will describe how to add a new indicator to your Open SDG implementation. This is intended to be a continuation of the quick start tutorial.

Topics covered

  • Data updates
  • Metadata updates
  • Data and site builds

Level of difficulty

This tutorial involves working with text files, but requires no previous technical expertise.

Gather the data and metadata for your new indicator

Normally you would gather data and metadata from actual sources, but for the purposes of this tutorial you will make up data and metadata for a new indicator: 15.3.1.a - "Proportion of wetland that is degraded over total wetland area".

Whether or not goal 15 is the appropriate place for such an indicator is beside the point - this is just an example.

Your imaginary data for this new indicator could be the following, disaggregated by urbanisation:

Year Urbanisation Value
2015 55
2016 60
2017 65
2015 Urban 75
2016 Urban 80
2017 Urban 80
2015 Rural 35
2016 Rural 40
2017 Rural 45

And your imaginary metadata for this new indicator could be the following:

Indicator name: Proportion of wetland that is degraded over total wetland area
Computation units: Percentage
Source: Wetland Statistics Agency (wetlandstaticsagency.org)
Description: Lorem ipsum dolor sit amet, consectetur adipiscing elit...

Convert the data into a CSV file and upload it

This is most easily done with spreadsheet software like Excel or Google Sheets. Simply enter the data into the sofware and then export to CSV (such as with "Save as" in Excel, or "Download as" in Google Sheets). A few important guidelines:

  1. Make the left-most column the "Year" column (with a capital Y).
  2. Make the right-most column the "Value" column (with a capital V).
  3. Any disaggregation columns (eg, "Urbanisation") can be named whatever you would like.
  4. Name the file indicator_15-3-1-a.csv (the "indicator_" is simply an Open SDG convention).

Steps to upload the CSV file:

  1. Go to github.com and login, then go to your data repository.
  2. In the list of files, navigate to the data folder.
  3. Press the "Add file" drop-down and select "Upload files".
  4. Drag in your new indicator_15-3-1-a.csv file or click to browse for it.
  5. At the bottom select Create a new branch for this commit and start a pull request.
  6. Change the name of the branch to indicator-tutorial. You will use this same branch name for all changes in this tutorial.
  7. Beneath this, click "Propose new file".
  8. Change the name of the pull request to "Indicator tutorial".
  9. Click on the green "Create pull request" button.

In contrast to past tutorials, do not "merge" this pull request. You will be adding another change to the pull-request before merging it.

Convert the metadata into a YAML/Markdown file and upload it

This step is most easily done directly in Github.com.

  1. Go to github.com and login, then go to your data repository.
  2. In the list of files, navigate to the meta folder.
  3. Press the "Add file" drop-down and select "Create a new file".
  4. For "Name your file" enter 15-3-1-a.md (this is an Open SDG convention as well).
  5. Under "edit new file", enter the following lines: --- indicator_name: Proportion of wetland that is degraded over total wetland area indicator_number: 15.3.1.a computation_units: Percentage source_active_1: true source_organisation_1: Wetland Statistics Agency source_url_1: "https://wetlandstaticsagency.org" reporting_status: complete --- Lorem ipsum dolor sit amet, consectetur adipiscing elit...
  6. At the bottom you should see "Commit directly to the indicator-tutorial branch".
  7. Click the "Commit changes" button.

Explanation of metadata format

Before continuing, let's explain the parts of that metadata file.

  • indicator_name: This is the indicator's name.
  • indicator_number: This is the ID of the indicator - in this case we chose a 4-part indicator ID.
  • computation_units: A description of the unit of measurement.
  • source_active_1: This tells Open SDG that there is a source.
  • source_organisation_1: This is the name of the source.
  • source_url_1: This is the website of the source.
  • reporting_status: The 'complete' here tells Open SDG that it should display this indicator's data.

This syntax, some_key: Some value is known as YAML.

The --- above and below the YAML section is Open SDG convention.

The description at the bottom ("Lorem ipsum") can contain Markdown or even HTML.

Merge the pull request

Now your pull request is ready to merge.

  1. In your data repository, click on "Pull requests".
  2. Click on the "Indicator tutorial" pull request.
  3. At the bottom click on the green "Merge pull request" button.

Getting the new indicator to your site

Although you have now updated your data repository, you will find if you visit your site that the new indicator is not there. This is because the site repository now needs to be rebuilt.

The site repository is automatically rebuilt every 24 hours, so you could simply wait. But in the interests of time, you can also trigger a site build by simply changing any file in your site repository. Here is an example:

  1. Go to github.com and log in, then go to your site repository.
  2. In the list of files, click on the README.md file.
  3. Click the pencil icon to begin editing the file.
  4. Add an extra line at the bottom.
  5. At the bottom select Create a new branch for this commit and start a pull request.
  6. Click Commit changes.
  7. Click Create pull request.
  8. Wait for the tests to complete, and then click Merge pull request.

For a way to automate this process, see the triggered site builds documentation.

View your results

Your site will now begin rebuilding. After about 5 minutes, if you visit your site and go to Goal 15, you should see the new indicator.

Troubleshooting

If this did not appear to work, please consult the troubleshooting page.