Ecosystem Status Report Best Practices Document
1 Outline
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: 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.
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
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). Within the new branch, create an R script (or quarto doc if you prefer) within the appropriate scripts/metrics folder based on your data type. Call the file [root_name_formatting].R (or [root_name_formatting].qmd).
STEP 3: In your R script, first call the code snippet for your particular data type, and then 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). Save the file as a csv. Data should be saved in the data/formatted/formatted_csvs folder. Once you have the csv, run it through the IEAnalyzeR data_prep function and save the output (with the same root name) to the data/formatted/final_objects. Finally, run the output of the data_prep function through the IEAnalyzeR plotting function. Save the resulting plot in the figures/plots folder. Call it [root_name].png. Consider sharing this plot with the SME or data steward if necessary.
Once your code is done be sure to check off the “coded” column in the indicator scoping project.
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.
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.
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.
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.