diff --git a/_quarto.yml b/_quarto.yml index c09c116..9b29f43 100644 --- a/_quarto.yml +++ b/_quarto.yml @@ -49,6 +49,14 @@ website: collapse-level: 2 contents: - ci_handbook/index.qmd + - ci_handbook/model-output-standards.qmd + - ci_handbook/design_justice.qmd + - ci_handbook/workflow_design.qmd + - ci_handbook/modularity.qmd + - ci_handbook/data_standards.qmd + - ci_handbook/cloud_computing.qmd + - ci_handbook/continuous_integration.qmd + - ci_handbook/example.qmd - id: reference title: "Reference" diff --git a/ci_handbook/cloud_computing.qmd b/ci_handbook/cloud_computing.qmd new file mode 100644 index 0000000..cbac99f --- /dev/null +++ b/ci_handbook/cloud_computing.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Cloud Computing" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/cloud_computing.jpg" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/continuous_integration.qmd b/ci_handbook/continuous_integration.qmd new file mode 100644 index 0000000..3a3c10c --- /dev/null +++ b/ci_handbook/continuous_integration.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Continuous Integration & Delivery" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/gitlab_cicd.png" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/data_standards.qmd b/ci_handbook/data_standards.qmd new file mode 100644 index 0000000..cc66534 --- /dev/null +++ b/ci_handbook/data_standards.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Data Standards" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/parquet.png" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/design_justice.qmd b/ci_handbook/design_justice.qmd new file mode 100644 index 0000000..3fcbe04 --- /dev/null +++ b/ci_handbook/design_justice.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Design Justice" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/DJN.png" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/example.qmd b/ci_handbook/example.qmd new file mode 100644 index 0000000..27f1cee --- /dev/null +++ b/ci_handbook/example.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Example Forecast CI" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/example.jpg" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/index.qmd b/ci_handbook/index.qmd index 7235ab9..2c6ff85 100644 --- a/ci_handbook/index.qmd +++ b/ci_handbook/index.qmd @@ -8,8 +8,20 @@ format: comments: utterances: repo: eco4cast/efi-ci-workshop-2024 +listing: + contents: + - "model-output-standards.qmd" + - "design_justice.qmd" + - "workflow_design.qmd" + - "modularity.qmd" + - "data_standards.qmd" + - "cloud_computing.qmd" + - "continuous_integration.qmd" + - "example.qmd" + fields: [image, title, reading-time] + sort: "title desc" + type: grid --- -## CI Handbook Documents :construction: Under Construction :construction: diff --git a/ci_handbook/model-output-standards.qmd b/ci_handbook/model-output-standards.qmd new file mode 100644 index 0000000..7c2af35 --- /dev/null +++ b/ci_handbook/model-output-standards.qmd @@ -0,0 +1,45 @@ +--- +title: "{{< fa arrow-right >}} Model Output Standards" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/Lego_dimensions.svg.png" +--- + +## Importance of Standardizing Model Output + +Agreed-upon model standards and conventions, such as variable names and data structures, are essential for achieving model interoperability and developing shared, reusable tools. Establishing these conventions enhance data consistency, facilitate dissemination, and support efficient data analysis. + +By leveraging existing community standards and conventions within the broader modeling community, researchers can enhance engagement and make their products more valuable to a wider audience. **We recommend adopting the model output standard described by [@dietze2023community] for all ecological forecasts**. As a community-driven convention, contributions to further develop and improve this standard are highly encouraged. + +## Model Output Standards + +The model output standards outlined by [@dietze2023community] build upon the Climate and Forecast ([CF](http://cfconventions.org/)) conventions [@eaton2003netcdf] and Cooperative Ocean/Atmosphere Research Data Service ([COARDS](https://ferret.pmel.noaa.gov/noaa_coop/coop_cdf_profile.html)) conventions. + +For all model output, the recommended order of dimensions should be T, Z, Y, X, U, where: + +- **T**: Time +- **Z**: Vertical dimension +- **Y**: Latitude +- **X**: Longitude +- **U**: Uncertainty (e.g., ensemble member or summary statistic) + +The following dimension names should be used as listed in order to describe T, Z, Y, X, U: + +| Dimension | Description | +|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| *reference_datetime* | **REQUIRED**. ISO 8601 ([ISO, 2019](https://www.iso.org/standard/70907.html)) datetime the forecast starts from (aka issue time). Datetimes are allowed to be earlier than the *reference_datetime* if a reanalysis/reforecast is run before the start of the forecast period. | +| *datetime* | **REQUIRED**. ISO 8601 ([ISO, 2019](https://www.iso.org/standard/70907.html)) datetime being predicted and follows [CF convention](http://cfconventions.org/cf-conventions/cf-conventions.html#time-coordinate). | +| *duration* | **REQUIRED**. Specifies the time step of the prediction. Use `P1D` for a daily prediction, `P1W` for a weekly prediction, and `PT30M` for a 30-minute prediction. The format should adhere to [ISO 8601 duration](https://en.wikipedia.org/wiki/ISO_8601#Durations). | +| *depth* or *height* | **REQUIRED IF STORING MULTIPLE Z DIMENSIONS**. No single standard name for the Z dimension. Where possible, use [CF conventions](https://cfconventions.org/cf-conventions/cf-conventions.html#vertical-coordinate) for vertical dimension names and attributes. | +| *lat* or *Y* | **REQUIRED IF PREDICTING ON GRID**. Latitude (units = `degrees_north`). | +| *lon* or *X* | **REQUIRED IF PREDICTING ON GRID**. Longitude (units = `degrees_east`) is the default spatial coordinate. The alternative use of Y, X for spatial coordinates should conform to the CF convention and requires additional metadata about grids and projections. | +| *site_id* | **REQUIRED IF NOT PREDICTING ON A GRID**. For predictions that are not on a spatial grid, use a site dimension that maps to a more detailed geometry (points, polygons, etc.). *site_id* should be used when making predictions that map to a stream network geofabric, for example. | +| *family* | **REQUIRED**. Describes the distribution of the prediction (e.g., `normal` for a normal distribution). For ensemble predictions, use `ensemble`. If the predictions yield a single realization (i.e., there is no associated uncertainty), it is preferred to specify `ensemble` with the ensemble size set to 1. If this dimension remains constant, it is acceptable to define *family* as a variable attribute, provided that the file format supports this (e.g., netCDF). Refer to [appendix S1](https://esajournals.onlinelibrary.wiley.com/action/downloadSupplement?doi=10.1002%2Fecs2.4686&file=ecs24686-sup-0001-AppendixS1.pdf) of [@dietze2023community] for supported _family_ and _parameter_ names. | +| *parameter* | **REQUIRED**. For ensemble predictions, specify integers from `1` to `Ne` (where `Ne` represents the total size of the ensemble). For named distributions, indicate the parameter or statistic being specified (e.g., a normal distribution would have `mean` and `sigma` as the values in the *parameter* column). | +| *variable* | **REQUIRED**. Standardized variable name of what is being predicted. We recommend using [CSDMS Standard Names](https://csdms.colorado.edu/wiki/CSDMS_Standard_Names). For example, maximum stream temperature would be named `channel_water_surface_water__max_of_temperature`. However, existing widely-used variable names (e.g., `max_temp_c`) are also acceptable. | +| *prediction* | **REQUIRED**. Predicted value for the parameter in the *parameter* column. For an ensemble forecast, the value is the prediction for the ensemble member. For a distribution forecast, the value corresponds to the parameter associated with the distribution in the *parameter* column. | + diff --git a/ci_handbook/modularity.qmd b/ci_handbook/modularity.qmd new file mode 100644 index 0000000..00ac6be --- /dev/null +++ b/ci_handbook/modularity.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Modularity" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/hive.jpg" +--- + +:construction: Under Construction :construction: diff --git a/ci_handbook/workflow_design.qmd b/ci_handbook/workflow_design.qmd new file mode 100644 index 0000000..b8fa7f6 --- /dev/null +++ b/ci_handbook/workflow_design.qmd @@ -0,0 +1,12 @@ +--- +title: "{{< fa arrow-right >}} Workflow Design" +format: + html: + toc: true + toc-depth: 3 + toc-position: left +reading-time: true +image: "../images/workflow.png" +--- + +:construction: Under Construction :construction: diff --git a/images/DJN.png b/images/DJN.png new file mode 100644 index 0000000..14cf67e Binary files /dev/null and b/images/DJN.png differ diff --git a/images/Lego_dimensions.svg.png b/images/Lego_dimensions.svg.png new file mode 100644 index 0000000..d4f7556 Binary files /dev/null and b/images/Lego_dimensions.svg.png differ diff --git a/images/acronyms.png b/images/acronyms.png new file mode 100644 index 0000000..e9410d2 Binary files /dev/null and b/images/acronyms.png differ diff --git a/images/cloud_computing.jpg b/images/cloud_computing.jpg new file mode 100644 index 0000000..44a27b3 Binary files /dev/null and b/images/cloud_computing.jpg differ diff --git a/images/example.jpg b/images/example.jpg new file mode 100644 index 0000000..cacc09a Binary files /dev/null and b/images/example.jpg differ diff --git a/images/gitlab_cicd.png b/images/gitlab_cicd.png new file mode 100644 index 0000000..ea9f1d1 Binary files /dev/null and b/images/gitlab_cicd.png differ diff --git a/images/hive.jpg b/images/hive.jpg new file mode 100644 index 0000000..2e037fb Binary files /dev/null and b/images/hive.jpg differ diff --git a/images/parquet.png b/images/parquet.png new file mode 100644 index 0000000..be9a66f Binary files /dev/null and b/images/parquet.png differ diff --git a/images/workflow.png b/images/workflow.png new file mode 100644 index 0000000..c39cf94 Binary files /dev/null and b/images/workflow.png differ diff --git a/reference/EFI_CI_reference.qmd b/reference/EFI_CI_reference.qmd index b7f1d12..8aadaef 100644 --- a/reference/EFI_CI_reference.qmd +++ b/reference/EFI_CI_reference.qmd @@ -8,6 +8,7 @@ format: comments: utterances: repo: eco4cast/efi-ci-workshop-2024 +image: "../images/acronyms.png" --- ## Acronyms and Abbreviations diff --git a/reference/index.qmd b/reference/index.qmd index 72ab33a..1645b82 100644 --- a/reference/index.qmd +++ b/reference/index.qmd @@ -8,9 +8,13 @@ format: comments: utterances: repo: eco4cast/efi-ci-workshop-2024 +listing: + contents: + - "EFI_CI_reference.qmd" + - "participants.qmd" + fields: [image, title, reading-time] + sort: "title desc" + type: grid --- -## Reference Documents -* [Acronyms and Definitions](EFI_CI_reference.qmd) -* [Participants](participants.qmd) diff --git a/reference/participants.qmd b/reference/participants.qmd index e87c876..f260055 100644 --- a/reference/participants.qmd +++ b/reference/participants.qmd @@ -8,6 +8,7 @@ format: comments: utterances: repo: eco4cast/efi-ci-workshop-2024 +image: "../images/DSC_7900.JPG" --- ## Named Participants and Affiliations diff --git a/references.bibtex b/references.bibtex index 28b05df..911f5fa 100644 --- a/references.bibtex +++ b/references.bibtex @@ -45,4 +45,10 @@ pages={1--9}, year={2016}, publisher={Nature Publishing Group} +} +@article{eaton2003netcdf, + title={NetCDF Climate and Forecast (CF) metadata conventions}, + author={Eaton, Brian and Gregory, Jonathan and Drach, Bob and Taylor, Karl and Hankin, Steve and Caron, John and Signell, Rich and Bentley, Phil and Rappa, Greg and H{\"o}ck, Heinke and others}, + journal={URL: http://cfconventions. org/Data/cf-conventions/cf-conventions-1.8/cf-conventions. pdf}, + year={2003} } \ No newline at end of file