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:
- Make the left-most column the "Year" column (with a capital Y).
- Make the right-most column the "Value" column (with a capital V).
- Any disaggregation columns (eg, "Urbanisation") can be named whatever you would like.
- Name the file
indicator_15-3-1-a.csv
(the "indicator_" is simply an Open SDG convention).
Steps to upload the CSV file:
- Go to github.com and login, then go to your data repository.
- In the list of files, navigate to the
data
folder. - Press the "Add file" drop-down and select "Upload files".
- Drag in your new
indicator_15-3-1-a.csv
file or click to browse for it. - At the bottom select
Create a new branch for this commit and start a pull request.
- Change the name of the branch to
indicator-tutorial
. You will use this same branch name for all changes in this tutorial. - Beneath this, click "Propose new file".
- Change the name of the pull request to "Indicator tutorial".
- 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.
Upload metadata in YAML format¶
This step is most easily done directly in Github.com.
- Go to github.com and login, then go to your data repository.
- From the drop-down on the
code
tab, type in and open the feature branch created earlier –indicator-tutorial
- In the list of files, navigate to the
meta
folder. - Ensure you are on your
indicator-tutorial
branch, if not use the dropdown menu to select this branch. - Press the "Add file" drop-down and select "Create a new file".
- For "Name your file" enter
15-3-1-a.yml
(this is an Open SDG convention as well). - 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
- At the bottom you should see "Commit directly to the
indicator-tutorial
branch". - 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.
Merge the pull request¶
Now your pull request is ready to merge.
- In your data repository, click on "Pull requests".
- Click on the "Indicator tutorial" pull request.
- 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:
- Go to github.com and log in, then go to your site repository.
- In the list of files, click on the
README.md
file. - Click the pencil icon to begin editing the file.
- Add an extra line at the bottom.
- At the bottom select
Create a new branch for this commit and start a pull request.
- Click
Commit changes
. - Click
Create pull request
. - 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 populated with data and metadata.
Troubleshooting¶
If this did not appear to work, please consult the troubleshooting page.