ess-dive-community / essdive-leaf-gas-exchange

READY TO USE. Documentation associated with the leaf-level gas exchange data and metadata reporting format for the ESS-DIVE repository

ESS-DIVE Leaf-level gas exchange data and metadata reporting format v1.0.3

This documentation contains guidance for the content and format of leaf-level gas exchange data and metadata. The reporting format comprises defined variable names and units for data tables, a methods metadata template, and instrument details template and guidance on inclusion of other related data and metadata.

About the leaf-level gas exchange data and metadata reporting format

The ESS-DIVE leaf-level gas exchange data and metadata reporting format has been developed to meet the needs of the community for a unified reporting format. This initial effort covers the most common variables and provides templates for metadata reporting. Additional reporting requirements have been developed for seven common data types:

• Survey
• Response of photosynthesis to intercellular CO₂ concentration (ACi curves)
• Photosynthetic parameters derived from ACi curves
• Vcmax from one point
• Response of photosynthesis to irradiance (AQ curves)
• Photosynthetic parameters derived from AQ curves
• Dark adapted respiration

For a full description of the reporting format, refer to Ely et al (2021). A reporting format for leaf-level gas exchange data and metadata. Ecological Informatics. https://doi.org/10.1016/j.ecoinf.2021.101232

Getting started: links to instructions and templates

Instructions for how to use this reporting format:

• Leaf-level gas exchange reporting format instructions

Other documents to get started:

• Methods metadata template: Download spreadsheet template for recording experiment and methods metadata.
• Instrument details template: Download spreadsheet template to record instrument details.

---

Updates in v1.0.3

Added a section to the Instructions on how to use this format in combination with other reporting formats to provide guidance on missing value, temporal and spatial data types.

See Releases for complete versioning details.

How to contribute

This leaf-level gas exchange data reporting format is evolving and growing to meet the needs of the community. Feedback and new contributions are welcome, and can be made by submitting an issue or feedback.

The issue templates we use are modeled from that provided by Darwin Core: Darwin Core maintenance group, Biodiversity Information Standards (TDWG) (2014). Darwin Core. Zenodo. https://doi.org/10.5281/zenodo.592792

Copyright information

The leaf-level gas exchange data and metadata reporting format is licensed under the Creative Commons Attribution 4.0 International (CCby4).

Funding and acknowledgements

Funding for the development of ESS-DIVE's leaf-level gas exchange data and metadata reporting format was provided by the US Department of Energy (DOE), Biological and Environmental Research Program, Earth and Environmental Systems Sciences Division, Data Management.

The format was developed with input and feedback of over 80 subject experts, including data collectors, data scientists, data users (empiricists and modelers), and instrument manufacturers. Thank you all.

For further description of the reporting format, and the development process, refer to:

Ely et al (2021). A reporting format for leaf-level gas exchange data and metadata. Ecological Informatics. https://doi.org/10.1016/j.ecoinf.2021.101232

Recommended citation

Ely K.S., Rogers A, Crystal-Ornelas R (2020): ESS-DIVE reporting format for leaf-level gas exchange data and metadata. Environmental Systems Science Data Infrastructure for a Virtual Ecosystem. doi:10.15485/1659484

essdive-leaf-gas-exchange's Issues

Leaf-level or Leaf-Level

@emilyarobles
In my interpretation, Chicago Manual of Style offers no clear, hard guidance on this. Section 8.169 offers the simple "Capitalize only the first element unless the second is a proper noun or adjective". Section 8.170 (preferred by Chicago) offers a more thorough set of rules, including 2) Capitalize any subsequent element unless they are articles, prepositions, (and a few other tings), however Rule 5 is "Break a rule when it doesn't work".

So my conclusion is that both are acceptable but we need to pick Leaf-Level or Leaf-level and apply it consistently. File-level in FLMD should also use the same format.

Edit: APA style is "In title case, capitalize the following words in a title or heading:major words, including the second part of hyphenated major words (e.g., “Self-Report,” not “Self-report”)". That has me leaning towards Leaf-Level and File-Level (although either would still be fine, just need to be consistent).

There are currently a mixture of uses in the RF Keywords and Standards spreadsheet.

Addition of Missing Value Codes to comply with CSV Reporting Format

• Documentation reference (URL): N/A
• Submitter: Dylan O'Ryan
• Justification (why is this change necessary?): To comply with the CSV Structure Reporting format missing value codes

I suggest the following changes: While looking through the reporting format instructions and documents, I was unable to locate guidance for missing value codes (e.g., N/A and -9999) for the files. If not included in the reporting format information, I suggest adding this information to ensure that datasets using this reporting format will comply with the CSV reporting format guidance.

Data Dictionary template file

A data dictionary provides definitions of variables (row/column names) used within data files. For v1.1 of the Leaf Gas Exchange RF, we should add a data dictionary file in CSV format to the Templates folder with complete list of variables for each data and metadata type.

Review GitHub folder and file name structure

This change was originally suggested by @regnans

Changing the GitHub structure to flatten folders where possible will make the content more approachable and easier to navigate. Additionally, Kim recommends renaming the instructions/template files to include a numbering order similar to the one used in the UAS reporting format documentation.

GitBook doesn't link to most recent version of methodsMetadataTemplate

• Submitter: Rob C-O

Hi @regnans just keeping track of this gitbook issue we are having here.

To summarize:

When downloading the templates directly from GitHub we get:

• instrumentDetailsTemplate v1.0
• methodsMetadataTemplate v1.0.2

When I click the two template links from this page on GitBook: https://ess-dive.gitbook.io/leaf-level-gas-exchange/#getting-started

I can download both of what appear to be the same Excel files.

• methodsMetadataTemplate v1.0.2 (updated 16 days ago)
• instrumentDetailsTemplate v1.0 (updated december 2020)

However, on the instructions page, we get linked to an older version of the methodsMetadataTemplate:

• methodsMetadataTemplate v1.0 (updated December 2020)
• instrumentDetailsTemplate  v1.0 (updated december 2020)

I have a support ticket into GitBook, so I'll update with the solution when I hear back

File Naming Conventions

Standard naming conventions for each file within a reporting format are being proposed for those that do not already have them defined. For the leaf gas exchange RF, we have proposed: *_leaf_data.csv, *_methods.csv, *_instrument_md.csv

However, the *_leaf_data.csv file name could become very lengthy, so we will revisit whether this or a different suffix for the file name is best. @regnans please let me know your thoughts.

proposed section heading change

• Documentation reference (URL): https://github.com/ess-dive-community/essdive-leaf-gas-exchange
• Submitter: Kim
• Justification (why is this change necessary?): help guide users to the essential components

I suggest the following changes: Change "Getting started" heading in README to "Getting started: links to instructions and templates". It's a bit clunky, but I think this change could help users in the GitBook, as the links to templates are only there as inline text, there is no separate folder for them.

I realize that there is an effort to keep a consistent format across the different formats, but @robcrystalornelas would you be OK with adding this clarification?

expected range for gws incorrect

*Term to change: gsw
Submitter: Kim
Justification: value wrong order of magnitude

I suggest the following changes (leave blank whatever would not change):

• Term name:
• Definition of the term:
• Format of the term:
• Additional Instructions (recommendations regarding content, etc.): change max range from 100 to 1000
• Examples:
• Refines (name of the broader term this term refines, if applicable):
• Replaces (name of the existing term that would be replaced by this term, if applicable):

Modifying contribute.MD templates

Change documentation

• Documentation reference (URL): https://github.com/ess-dive-community/essdive-leaf-gas-exchange/blob/master/contribute.md
• Submitter: Rob Crystal-Ornelas
• Justification (why is this change necessary?): Make submitting issues more efficient since we can avoid copy and pasting templates

I suggest the following changes: I propose changing the way we display the issue templates from how we have them in the contribute.md document which requires copy and pasting to a new format that avoids copy and pasting templates. See an example here. When you click new issue you can then select from 3 different types of issues, and the templates from your contributing file will autogenerate. Let me know if you like this format and I can make the change.

fix the typo!

We work on leaves, not leads.

Updating first short table for measurementProtocol

Change documentation

• Documentation reference (URL): https://github.com/ess-dive-community/essdive-leaf-gas-exchange/blob/master/dataTypesProtocols.md
• Submitter: Rob Crystal-Ornelas
• Justification (why is this change necessary?): When I parsed the CSV into markdown, I wasn't sure how to fill in the measurementProtocols table

I suggest the following changes: Updating where I left NA in the first short table so that it accurately reflects that the protocol is required for all datatypes. Also, mostly just testing out GitHub issues for this repo