Ecosystem Status Report Best Practices Document

Author

Gulf IEA

Published

October 17, 2025

1 Outline

NoteMap Interaction Guide

This map is fully interactive. Use the following steps to explore the system:

  1. Zoom and Pan: Use your mouse scroll wheel/trackpad to zoom in and out. Click and drag the map background to pan.
  2. View Profiles: Click any element (node) to open its profile on the side panel, which contains detailed information.
  3. Focus on a Node: Use the magnifying glass icon on the map’s toolbar to search for a specific element, or click the Focus button, which pops up on the lower right of the side panel when you click on an element, to highlight that element and its immediate connections.

1.1 Naming conventions

Add a table here with all of our outputs/products, how they are named, and an example

1.2 Starting a new ESR / updating a previous one

If you are making an ESR from scratch, step one is to go to the ESR-Report-Template repository in the Gulf-IEA Github organization and click “use this template”. Re-name the new repository xxx-ESR (e.g., Gulf-ESR, SA-ESR, Caribbean-ESR, Wind-ESR, etc.). You will also need to go to the projects tab for the Gulf-IEA organization and create a new project from the template “Indicator scoping” project. Name the project “Indicator scoping [report]” (e.g., “Indicator scoping Gulf”, “Indicator scoping Caribbean”, etc.) and link that project to your new repository.

If you are updating an existing ESR, go to the repository for that ESR (e.g., Caribbean-ESR), make sure the previous version was tagged by checking the tags in the main branch. From there, go to the Indicator scoping project linked to the repository. Change everything in the “selected” column to maybe for all listed metrics. Change everything in the “Code reviewer name”, “Code reviewed”, and “Production form submitted” columns back to blank.

Note

Note: Here we should add some screenshots showing where things are and what to select.

1.3 Indicator scoping

1.3.1 Compiling ideas

If you think of ideas for a new metric or someone you talk to suggests a metric, go to the issues tab and create a new issue. Use the “Metric Idea Form” issue template. Fill out as much information as you can, leaving entries blank as needed. Anyone can fill this form out with an idea. If you already know the data do not exist or are extremely limited, you can note that. You should ideally know where the data exist so you can note that on the form before we decide to include the metric. If you identify data online, you should test that it can be downloaded and everything looks kosher. If you need to run any code just to check/download the data and take a preliminary look at what it is, you can make a script and put it in the sandbox/prelim_code folder. Make sure to link the script/code in the comments of the metric idea issue corresponding to that metric.

Important

When you’ve finished filling out the Metric Idea Form, make sure you assign that issue to the “Indicator scoping xxx” project, so it automatically adds an entry to the project board.

1.3.2 Metric selection

Once the project board is filled with ideas and the appropriate people / teams have been consulted about metric ideas, the IEA team will meet to go over the list of metric ideas and decide which ones to include in the ESR and which ones not to. By the end of this meeting, all the metrics that will be included will have the selected category changed to “yes”, everything else will be changed to “no” if the metric is not going to be used in the current report. Also, each metric will be assigned to an IEA POC by the end of the meeting. Make sure a root name has been created for each metric and documented in the project.

1.4 Data processing

Note

Note we will want to add some info here about packages and renv.lock.

If an IEA POC has been assigned a metric, it is their job to either create the code, or find and adapt existing code, or re-run existing code to update for a new year. If it is important to consult with SMEs or data stewards, that is the responsibility of the IEA POC.

STEP 1: Identify the data type (automated, non-automated, or confidential)

STEP 2: Create a new branch and name it the root name for the metric (the root name is designated in the metric idea form).

STEP 3: Within the new branch, use the create_metric_code_file function in IEAnalyzeR to create an R script (or quarto doc if you prefer) within the appropriate scripts/metrics folder based on your data type. If you do not have IEAnalyzeR installed you will need to install it:

install.packages("devtools")
library(devtools)
devtools::install_github("Gulf-IEA/IEAnalyzeR")

Use the appropriate template (metric_code_template.R or metric_code_template.qmd). These templates can be found in scripts/other/templates and will be called using the create_metric_code_file function. To use the function, specify the metric name, format of the file (R or qmd), and data type. Best practice is to run the code for the function in your console. The new script file will be created in the appropriate folder.

STEP 4: In your R script or qmd file, follow the template prompts to load your necessary packages and bring in the data/call the data from an online source, do whatever data manipulations/analysis are needed, and convert to the standard IEA data format (see example below). The template will prompt you to save the data in the appropriate format and location.

Note

Once your code is done be sure to check off the “coded” column in the indicator scoping project.

Important

Be cognizant of others. Annotate your code. You will be expected to add a plain language version of your code to the production form to be included in the methods document. Be kind to your future self and do it now.

Note

include an example here of the appropriate data format.

STEP 4: One you are satisfied with your code, do a pull request and tag another IEA POC as a reviewer. The reviewer will pull the branch, go through the script, test that the code works, check for errors, and accept the pull request once everything looks good. If there are issues, contact the IEA POC.

Note

Once the code is checked and the branch is merged into the main branch, check off the “code checked” column in the indicator scoping project.

STEP 5: The IEA POC now fills out the metric production form for each of their assigned metrics. Some of the information can be copied from the metric idea form.

Note

Make sure you go back to the indicator scoping project and check off the column called “Production form submitted”.

1.5 Report writing

STEP 1: The IEA indicator development team (IEA lab group) meets to go over all the metrics and decide how to turn the metrics into indicators and how to structure the report (sections, order, etc.)

STEP 2: Send the Report Text Google Form to SMEs / data stewards / whoever is best suited to writing about the metric/indicator and interpreting the plot.

STEP 3: The Quarto Book Master creates the quarto book files, updates the YAML, etc. Run the template R code to pull the text data from the google form and combine it with the code chunks to create the indicator plots in the qmd files.