Adding first draft of template and instruction file (#128)

* dding first draft of template and instruction file

* fix figures

* fix typos

* fix references

* remove name

* Template updates

* change toc

* qa

* finalise template

---------

Co-authored-by: Christopher Goddard <[email protected]>
Co-authored-by: Mattia Almansi <[email protected]>
Co-authored-by: Christopher Goddard <[email protected]>

Seasonal_Forecasts/seasonal_seasonal-monthly-single-levels_forecast-skill_q02.ipynb

@@ -273,7 +273,7 @@
     "    \"WNA\",\n",
     "]\n",
     "\n",
-    "# Ploting settings\n",
+    "# Plotting settings\n",
     "plot_kwargs = {\n",
     "    \"total_precipitation\": {\"cmap\": \"BrBG\"},\n",
     "}\n",

Seasonal_Forecasts/seasonal_seasonal-monthly-single-levels_forecast-skill_q04.ipynb

@@ -813,7 +813,7 @@
     "\n",
     "The figure below shows that, among the sample regions considered in this analysis, those with the higher and more persistent hit-rate are South East Asia (SEA) and North West South America (NWS). These areas are under the direct influence of ENSO and are expected to benefit from a significantly higher degree of predictability compared to other regions. Other areas with significant, and potentially usable, in practical applications are Northern-East Africa (NEAF) and (North East South America) NES. Other areas like Southern Asia (SAS) and Souther Europe/Mediterranean (MED) have a moderate hit-rate, limited mostly to short lead times, whereas NWS shows only scattered cases of hit-rate above 50% [[2]](https://doi.org/10.1038/s41612-023-00519-8) [[8]](https://doi.org/10.1175/BAMS-D-19-0019.1.) [[9]](https://doi.org/10.1175/WAF-D-19-0106.1.) [[10]](https://doi.org/10.1007/s00704-018-2421-9).\n",
     "\n",
-    "Compared to the similar assessment conducted [systematic bias of seasonal forecasts](https://ecmwf-projects.github.io/c3s_eqc_book_main/seasonal/D520.3.2.3b.SEASONAL_multimodel_bias.html), a significant aspect of the hit-rates for terciles is their weak dependance on the originating centre. Although minor differences exist in the performance of the different forecasting systems, the overall patterns of significant hit-rates and even their seasonality is very similar, e.g. higher hit-rates in North West South America during the period October-December associated to El Niño."
+    "Compared to the similar assessment conducted [systematic bias of seasonal forecasts](https://ecmwf-projects.github.io/c3s_eqc_book_main/seasonal/D520.3.2.3b.SEASONAL_multimodel_bias.html), a significant aspect of the hit-rates for terciles is their weak dependence on the originating centre. Although minor differences exist in the performance of the different forecasting systems, the overall patterns of significant hit-rates and even their seasonality is very similar, e.g. higher hit-rates in North West South America during the period October-December associated to El Niño."
    ]
   },
   {
@@ -888,7 +888,7 @@
     "\n",
     "* For **2m dew point temperature** the pattern of significant hit-rates is clearly linked to the hit-rates of **2m temperature** coherently with an approximately constant pattern of relative humidity whereby the dewpoint temperature is directly related to local temperature by the Clausius-Clapeyron relation [[11]](https://doi.org/10.1175/JHM-D-19-0095.1.).\n",
     "\n",
-    "Similarly to **2m temperature** hit-rates for terciles of seasonal forecasts for other variables have a weak dependance from the originating centres.\n",
+    "Similarly to **2m temperature** hit-rates for terciles of seasonal forecasts for other variables have a weak dependence on the originating centres.\n",
     "\n",
     "The analysis highlights how seasonal forecasts provide a significant hit-rate for terciles of anomalies observed at a monthly time scale mainly for some specific areas and variables.\n",
     "\n",

_toc.yml

@@ -40,7 +40,10 @@ parts:
     sections:
     - glob: Climate_Projections/*
 
-- caption: Assessment template
+- caption: Quality assessment template
   chapters:
-  - glob: templates/*
+  - file: templates/template_instructions.md
+  - file: templates/template.ipynb
+    title: Template
+
 

intro.md

@@ -54,7 +54,7 @@ These assessments are organised by the type of data they address. Note that whil
 
 ## Running the Notebooks
 
-Most of these quality assessments include Python code to produce data and figures which help answer the user question. This code is included primarily for transparency and traceability, as the software was designed to support evaluators running the assessments on EQC infrastructure, rather than to be easily reproducable. However, sections of it may also be directly applicable to your application and can be adapted or adjusted to your needs.
+Most of these quality assessments include Python code to produce data and figures which help answer the user question. This code is included primarily for transparency and traceability, as the software was designed to support evaluators running the assessments on EQC infrastructure, rather than to be easily reproducible. However, sections of it may also be directly applicable to your application and can be adapted or adjusted to your needs.
 
 Most code in the Notebooks is self contained (but does make use of the [custom software](https://github.com/bopen/c3s-eqc-automatic-quality-control/tree/main/c3s_eqc_automatic_quality_control) prepared by [BOpen](https://www.bopen.eu/) for EQC evaluators). Some quality assessments may rely on the outcomes and code of previous assessments, or offline computations.
 

templates/template_instructions.md

@@ -0,0 +1,86 @@
+![logo](../LogoLine_horizon_C3S.png)
+
+# Template instructions
+
+Instructions for the [Jupyter Notebook template for quality assessments](./template.ipynb). This template aims to ensure consistency in content and the look and feel of the assessment once it is included in the [Jupyter Book](https://ecmwf-projects.github.io/c3s2-eqc-quality-assessment/intro.html). The syntax includes MyST formatting needed for the Jupyter Book which will not render in all Jupyter Notebook viewers, or GitHub, but works in Jupyter Lab on the Virtual Machine.
+
+```{note}
+Some additional formatting required for the Jupyter Book will be automatically applied when the page for a given assessment is built, and so are not included in this template. This includes the extraction of embedded images, 'collapsing' the code cells, and adding a logo line.
+```
+
+```{note}
+Please follow the headings and subheadings approach used in the template. The level of the heading is determined by the number of hashes before it (#Title, ##Use case, etc.). The following link should be helpful: https://jupyterbook.org/en/stable/reference/cheatsheet.html
+```
+
+```{note}
+There is a new approach to linking the methodology list to the subsections in analysis and results.
+```
+
+## Assessment title
+
+We do not aim to be completely prescriptive about the title, it should be readable and descriptive, but also include some key tags to increase searchability, e.g. *Seasonal forecasts bias assessment for impact models*.
+
+- **Data stream**: Satellite (observations), Insitu (observations), Reanalysis, Seasonal (Forecasts), Climate (projections)
+- **Quality area**: bias, forecast skill, completeness, intercomparison of X and Y, comparison to X, trend assessment, extremes, spatial/temporal resolution, reliability, accuracy, etc.
+- **Application area**: impact models, risk assessment, climate monitoring, scientific study of X, X sector, 'region', 'specific C3S application', flood forecasting, etc.
+
+```{note}
+The title will be used in the table of contents for the data stream and the side bar of the Jupyter Book, so it needs to be unique, not too long, and help guide users to the assessment by mentioning the key analysis or outcomes.
+```
+
+```{note}
+The title should be the only 'level one' heading (single # before the heading), otherwise the other headings will also appear as separate links in the table of contents for the data stream and sidebar.
+```
+
+## Production date and author
+
+Include a production date (approximating when the data was downloaded and code first run, or document first accessed). Optionally, the author(s) can be acknowledge, by name and/or institute, or instead 'EQC evaluator'.
+
+## Use case
+
+The use case is listed directly in the heading of the section: `## Use case: ...`
+
+## User question
+
+User question, or User questions, if more than one question is answered in the assessment, or if a second question helps clarify the aim of the assessment. The question or questions are bold and highlighted with bullet points.
+
+## Context text (no heading)
+
+A section of text with no heading which appears after the user question and before the quality assessment statement. References can be used to link to examples of relevant literature or example applications relevant to the use case and user question. It should be as short as possible, but contain enough information for users to understand the context of the assessment and the main approach to be used. Together with the assessment title, use case and user question, and assessment statement all key information should be contained at the top of the assessment.
+
+## Quality assessment statement
+
+Key results and guidance including an answer to the user question - to be visually highlighted and with the section title ‘Quality assessment statement’.
+
+```{note}
+The blue notification box that contains the quality assessment statement bullet points will not appear in GitHub, but will be rendered when the Jupyter Book page is created.
+```
+
+## Figure
+
+A key figure should be included if possible, acting as a 'graphical abstract' for the assessment. This could be a figure generated later in the code, or from an external source (if licensing allows reproduction) - in this case the source should be cited in the caption. Images should be dragged and dropped into the markdown cell, which created an 'attachment code', and the external file is no longer needed. If the image file already includes a figure number and the caption then simple syntax can be used (`![](attachment:... ID from drag and drop)`). Otherwise, figure formatting can be used, where the attachment code from the drag and drop needs to be wrapped in the figure syntax. This approach should also be followed if images not generated by code are included later in the assessment.
+
+```{note}
+The figure formatting will not render in Github, but will work when the Jupyter Book page is built.
+```
+
+## Methodology
+
+Some text to introduce the methodology, including relevant sources, followed by a numbered list of the analysis steps under the 'analysis and results' section. The headings of each list item should link to the sections within 'Analysis and results' - this needs to be done manually. Extra steps or explanations can be added in the bullets between each numbered item.
+
+The syntax for the link in the methodology list is: `[](section-1)`, where no text in the square brackets is needed (the heading of the corresponding section in 'Analysis and Results' will be shown automatically), and the label in the circle brackets is the manually set label used later to identify the section in question like
+
+```md
+(section-1)=
+### 1. Section 1 title
+```
+
+## Analysis and results
+
+A series of subsections with the same titles as in the listen in the methodology. In turn, these can have their own subsections. Code cells will be collapsed when the Jupyter Book is built. The final results should be clearly presented and discussed, supporting (but not repeating), the quality assessment statement.
+
+## If you want to know more
+
+Including a key resources subsection, which can link to suggested further reading, code packages used, and the relevant CDS catalogue entries.
+
+Including a references subsection, which is a numbered list of the references used throughout the text. However, the references in the text will link to the external source, rather than the references list at the bottom of the assessment.