From ba8b65419a3e7c874e7db617c313f1680c2a29c8 Mon Sep 17 00:00:00 2001 From: GitHub Action Date: Tue, 28 May 2024 08:07:50 +0000 Subject: [PATCH] Build .adoc Files for GitHub Pages from f5e669dade9cbf2186a57a2c295922157c7a6a99 --- .github/CODEOWNERS | 4 - .github/ISSUE_TEMPLATE/bug.md | 33 - .github/ISSUE_TEMPLATE/feature.md | 24 - .github/ISSUE_TEMPLATE/question.md | 12 - .github/ISSUE_TEMPLATE/style.md | 47 - .github/ISSUE_TEMPLATE/typo.md | 46 - .github/PULL_REQUEST_TEMPLATE.md | 41 - .github/workflows/adoc_build.yml | 15 - OG_Format.adoc | 815 ------- OG_Format.html | 2098 +++++++++++++++++ history.adoc | 29 - history.html | 501 ++++ src/OG_Vocabulary.adoc | 146 -- src/OG_Vocabulary.html | 757 ++++++ .../tableOfControlledVocab.adoc | 189 -- .../tableOfControlledVocab.html | 901 +++++++ 16 files changed, 4257 insertions(+), 1401 deletions(-) delete mode 100644 .github/CODEOWNERS delete mode 100644 .github/ISSUE_TEMPLATE/bug.md delete mode 100644 .github/ISSUE_TEMPLATE/feature.md delete mode 100644 .github/ISSUE_TEMPLATE/question.md delete mode 100644 .github/ISSUE_TEMPLATE/style.md delete mode 100644 .github/ISSUE_TEMPLATE/typo.md delete mode 100644 .github/PULL_REQUEST_TEMPLATE.md delete mode 100644 .github/workflows/adoc_build.yml delete mode 100644 OG_Format.adoc create mode 100644 OG_Format.html delete mode 100644 history.adoc create mode 100644 history.html delete mode 100644 src/OG_Vocabulary.adoc create mode 100644 src/OG_Vocabulary.html delete mode 100644 vocabularyCollection/tableOfControlledVocab.adoc create mode 100644 vocabularyCollection/tableOfControlledVocab.html diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS deleted file mode 100644 index d8b58218..00000000 --- a/.github/CODEOWNERS +++ /dev/null @@ -1,4 +0,0 @@ -# Code Owners -# This list was created based on the original authors of OG format - -* @glidermann @vturpin @castelao @justinbuck @kerfoot @tcarval @emmerbodc @callumrollo @JuangaSocib diff --git a/.github/ISSUE_TEMPLATE/bug.md b/.github/ISSUE_TEMPLATE/bug.md deleted file mode 100644 index c1ced973..00000000 --- a/.github/ISSUE_TEMPLATE/bug.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -name: Error report -about: Report a logical error, inconsistency, or any break in the format -title: '' -labels: '' -assignees: '' - ---- - -Proponent(s): - -Moderator: @OceanGlidersCommunity/format-maintainers - -**Describe the error** - - -**Example** - - -**Potential solution** - - -**Platforms affected** - - -**Additional context** - diff --git a/.github/ISSUE_TEMPLATE/feature.md b/.github/ISSUE_TEMPLATE/feature.md deleted file mode 100644 index e0e0c5b1..00000000 --- a/.github/ISSUE_TEMPLATE/feature.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: Feature request -about: An enhancement that adds without changing the current format -title: '' -labels: '' -assignees: '' - ---- -moderator: @OceanGlidersCommunity/format-maintainers - -**Is your feature request related to a problem? Please describe.** -A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] - -**Is this related to a specific platform models** -A generic glider or describe the platform models that would be relevant for this. - -**Describe the solution you'd like** -A clear and concise description of what you want to happen. - -**Describe alternatives you've considered** -A clear and concise description of any alternative solutions or features you've considered. - -**Additional context** -Add any other context or screenshots about the feature request here. diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md deleted file mode 100644 index f52d9cd0..00000000 --- a/.github/ISSUE_TEMPLATE/question.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: Question Issue -about: Use for questions you want help with -title: '' -labels: question -assignees: '' - ---- - -Moderator: @OceanGlidersCommunity/format-maintainers - - diff --git a/.github/ISSUE_TEMPLATE/style.md b/.github/ISSUE_TEMPLATE/style.md deleted file mode 100644 index e891bc89..00000000 --- a/.github/ISSUE_TEMPLATE/style.md +++ /dev/null @@ -1,47 +0,0 @@ ---- -name: Style Issue -about: Use for formatting or document syntax that don't change the meaning -title: '' -labels: style -assignees: '' - ---- - - -Proponent(s): - -Moderator: @OceanGlidersCommunity/format-maintainers - -- [ ] I read the [code of conduct](https://github.com/OceanGlidersCommunity/OceanGliders/blob/main/CODE_OF_CONDUCT.md) - and agree to follow it. -- [ ] This correction should not change the meaning of the related text nor - result in some ambiguity. -- [ ] I don't need help to create a pull request to address it. -- [ ] Language **which spelling are we following**?? FIXME!!!! - - - -## Affected text - - -## Correction - - -## Explanation (if needed) - - -Thank you for your contribution. - -## For moderator - -- [ ] Keep track of the contributor's records. If this turns into a PR and - actually result in a modification, the moderator should keep track to - be sure that the proper credits are given. diff --git a/.github/ISSUE_TEMPLATE/typo.md b/.github/ISSUE_TEMPLATE/typo.md deleted file mode 100644 index 6583569d..00000000 --- a/.github/ISSUE_TEMPLATE/typo.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -name: Typo report -about: Use for small errors in spelling or grammar -title: '' -labels: typo -assignees: '' - ---- - -Proponent(s): - -Moderator: @OceanGlidersCommunity/format-maintainers - -- [ ] I read the [code of conduct](https://github.com/OceanGlidersCommunity/OceanGliders/blob/main/CODE_OF_CONDUCT.md) - and agree to follow it. -- [ ] This correction should not change the meaning of the related text nor - result in some ambiguity. -- [ ] I don't need help to create a pull request to address it. -- [ ] Language **which spelling are we following**?? FIXME!!!! - - - -## Affected text - - -## Correction - - -## Explanation (if needed) - - -Thank you for your contribution. - -## For moderator - -- [ ] Keep track of the contributor's records. If this turns into a PR and - actually result in a modification, the moderator should keep track to - be sure that the proper credits are given. diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index da61bede..00000000 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,41 +0,0 @@ - -Proponents: -Moderator: @OceanGlidersCommunity/format-mantainers - -# Type of PR - -- [ ] Typo without possible change of interpretation of the related text. -- [ ] Fix of some error, inconsistency, unforeseen limitation. -- [ ] Style that only affects visually the compiled document -- [ ] Addition that does not require change in the current structure. -- [ ] Enhancement that require changes to improve the format. - -# Related Issues - - -# Dates when it got review approvals - - -# Release checklist - -- [ ] Approved by at least two members of the committee? -- [ ] There were modifications after the review approvals? If so, please - ask reviewers to update their review. -- [ ] Proponents and moderador should explicitly agree that it is ready to - to merge. -- [ ] The moderador is the one in charge to actually merge or close this PR - according to the final decision. - -# For maintainers - -- [ ] Update the moderator with a volunteer from the committee. It would be - best to have one single moderator to guide and help this PR to move - forward. It is OK to update the moderador pass it to another one. -- [ ] Confirm that the associated branch was deleted after the merging. -- [ ] Wrap-up and close the related issues. - -# Comments - diff --git a/.github/workflows/adoc_build.yml b/.github/workflows/adoc_build.yml deleted file mode 100644 index b2b7bf0d..00000000 --- a/.github/workflows/adoc_build.yml +++ /dev/null @@ -1,15 +0,0 @@ -name: Make pages - -on: - workflow_dispatch: - push: - branches: [ main ] -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - with: - fetch-depth: 0 - - name: asciidoctor-ghpages - uses: manoelcampos/asciidoctor-ghpages-action@v2.3.0 diff --git a/OG_Format.adoc b/OG_Format.adoc deleted file mode 100644 index 58859fe9..00000000 --- a/OG_Format.adoc +++ /dev/null @@ -1,815 +0,0 @@ -[cols=",",options="header",] -|=========================================================================================== -|https://www.oceangliders.org/[image:figures/image1.png[image,width=164,height=144]] a| -OceanGliders 1.0 format - Terms of References + - -Navigation: + - -https://github.com/OceanGlidersCommunity/OG-format-user-manual[GitHub repository] + -https://oceangliderscommunity.github.io/OG-format-user-manual/OG_Format.html[Terms of reference] + -https://oceangliderscommunity.github.io/OG-format-user-manual/vocabularyCollection/tableOfControlledVocab.html[Vocabulary collections] + - -|=========================================================================================== - -//// -* [[Methodology]] -//// -== Methodology - -A working group on harmonization of the glider data format was set up in September 2020 at the request of the OceanGliders steering team. All members of the OceanGliders data management team were invited to join. -The three existing formats (at the time) were analysed and compared by the group. Regular technical meetings occurred and the format harmonization process was managed via a Google doc. In late 2021 the group decided to move the document to https://github.com/OceanGlidersCommunity/OG-format-user-manual[GitHub] to better manage the issues, work asynchronously and contribute to the open source community. -The GitHub repository is open to any comments from the community and validation rules were created by the working group (see the https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/governance.md[governance document]). -From there the working group organized regular meetings to validate the evolution of the format, discuss issues and reach a consensus on the OG1.0 format. It is envisaged that the format will continually evolve with contributions from the community. - - -//// -* [[Authors]] -//// -== Authorship - - -=== Authors -* https://github.com/justinbuck[Justin Buck], _National Oceanography Centre, British Oceanographic Data Centre, UK_ https://orcid.org/0000-0002-3587-4889[0000-0002-3587-4889] -* https://github.com/castelao[Guilherme Castelão], _Scripps Institution of Oceanography - UC San Diego, USA_ https://orcid.org/0000-0002-6765-0708[0000-0002-6765-0708] -* https://github.com/emmerbodc[Emma Gardner], _National Oceanography Centre, British Oceanographic Data Centre, UK_ https://orcid.org/0009-0007-9640-7268[0009-0007-9640-7268] -* https://github.com/glidermann[Daniel Hayes], [OGDMTT co-chair], _Cyprus Subsea Consulting and Services C.S.C.S. Ltd, Cyprus_ https://orcid.org/0000-0003-0141-9973[0000-0003-0141-9973] -* https://github.com/kerfoot[John Kerfoot], _Institute of Marine & Coastal Sciences, Rutgers University, New Jersey, USA_ https://orcid.org/0000-0003-1405-4248[0000-0003-1405-4248] -* https://github.com/vturpin[Victor Turpin], [OGDMTT co-chair], _OceanGliders Technical Coordinator at OceanOPS, Brest, France_ https://orcid.org/0000-0002-1662-4358[0000-0002-1662-4358] -* https://github.com/callumrollo[Callum Rollo], _Voice of the Ocean Foundation, Sweden_ https://orcid.org/0000-0002-5134-7886[0000-0002-5134-7886] -* https://github.com/jenseva[Jennifer Sevadjian], _Scripps Institution of Oceanography - UC San Diego, USA_ https://orcid.org/0000-0001-9286-2043[0000-0001-9286-2043] - - -=== Contributors -* https://github.com/soerenthomsen[Sören Thomsen], _LOCEAN, ISPL, Sorbonne University, Paris, France,_ https://orcid.org/0000-0002-0598-8340[0000-0002-0598-8340] -* https://github.com/ptestor[Pierre Testor], _National Centre for Scientific Research, France_ https://orcid.org/0000-0002-8038-9479[0000-0002-8038-9479] -* https://github.com/JuangaSocib[Juan Gabriel Fernández Pineda], _SOCIB, Mallorca, Spain_ https://orcid.org/0000-0002-8732-7887[0000-0002-8732-7887] -* https://github.com/tcarval[Thierry Carval], _IFREMER, Brest, France_ https://orcid.org/0000-0003-2700-4020[0000-0003-2700-4020] - -=== Acknowledgements - -Several organisations were instrumental in the development of this format. OceanGliders, UG2, and EGO provided encouragement and forums for initial discussion. Some authors received support from, amongst others, EuroSEA, AtlantOS, GOMO, EMODnet Physics, NERC, VOTO and GROOM II. - - -//// -* [[background]] -//// -== Background - -The https://www.oceangliders.org/[OceanGliders] program brings together marine scientists and glider operators from all over the world who observe the long-term physical, biogeochemical, biological ocean processes, and phenomena relevant for societal applications. It allows active coordination and strengthening the roles of gliders in the ocean observation programs worldwide and contributes to the present international efforts for ocean observation for climate, ocean health and real-time services. - -The program oversees the monitoring of global glider activity, a prerequisite for active coordination. By sharing requirements, efforts and scientific knowledge needed for glider data collection OceanGliders aims to continuously develop the network by supporting the dissemination of glider data in global databases, in real-time and delayed mode, for a wider community. - -The OceanGliders program was created about 10 years after the popularization of the use of gliders by ocean scientists. With no common rules on format, data managers from Australia (https://imos.org.au/[IMOS]), the USA (https://gliders.ioos.us/[IOOS]), and Europe (https://www.coriolis.eu.org/[Coriolis]) processed 3 regional formats that are not interoperable. - -Harmonization toward interoperability within the existing formats and many national/regional glider networks is a recommendation from the OceanGliders steering team to strengthen the program and reach the https://www.go-fair.org/fair-principles/[FAIR principles] (Findable, Accessible, Interoperable, Reusable) adopted by https://goosocean.org/[GOOS] (Global Ocean Observing System), and better monitor the program activity. - -//// -* [[objectives]] -= Objectives -//// -== Objectives - -This document defines the common OceanGliders data format, hereafter OG1.0. - -//// -* [[og1.0-general-conventions]] -= OG1.0 General conventions -//// -== OG1.0 General conventions - -* The required granularity of the data set is the glider mission, starting from deployment at sea to recovery. -* Data are recorded as a trajectory Discrete Geometry, using NetCDFfootnote:[NetCDF-3 does not satisfy the requirements of OG1.0 format] system and following CF 1.10footnote:[http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html] (Climate and Forecast) specifications. Each data file contains a series of dive cycles representing the mission of the glider. It can be produced in near real time after every glider transmission and revised later into a recovery-mode (when glider on shore and any data gaps filled in) or a delayed-mode (after rigorous QC) version. -* Format follows the ACDD 1.3footnote:[https://wiki.esipfed.org/Attribute_Convention_for_Data_Discovery_1-3] convention where possible. -* Vocabulary collections will be hosted in different places (NERC Vocabulary Server - NVS, OceanOPS, ICES, etc). The OceanGliders data management team will manage (additions, updates, etc.) the collections. Treatment of vocabularies is detailed in the https://oceangliderscommunity.github.io/OG-format-user-manual/vocabularyCollection/tableOfControlledVocab.html[vocabularies document]. -* OG1.0 defines some variables and definitions, as described in this document. Other types of measurements (e.g. intermediate parameters, technical measurements, other variables) not framed by OG1.0 can be included in OG1.0 data files. No control will be applied to those measurements. -* Geospatial variables and along-track positioning variables are mandatory. -* Methodologies used to interpolate data, compute along-track positioning variables, apply QC etc. Should be linked and, where possible, follow community best practices. It is encouraged to use unique resource identifiers (uris) to link to these resources. -* 3 recommendations level have been defined for OG1.0: - - - Mandatory: Minimum metadata set to be compliant with OG1.0 requirement. - - Highly desirable: Worth having for complete use of the data set. - - Suggested: If the information is available. - -== DOI management - -* A DOI can be minted at any level (PI, Reference Data Center, Data Assembly Center, Global Data Assembly Center) following the internal policy of data curation. -* A DOI can be minted for a single glider mission or multiple glider missions (i.e. project, reference lines). -* A DOI if included in OG1.0 files needs to be preserved. The DOI must remain unchanged if there is no valuable modification. If valuable information is aggregated/added or a new product produced, a new DOI should be created and the new DOI should link to the original DOI to acknowledge as the source -* The most effective way of preserving the integrity of the source citation is to preserve the initial DOI added in the OG1.0 file. - - -//// -* [[og1.0-file-naming-convention]] -= OG1.0 file naming convention -//// -== OG1.0 file naming convention - -* Data files should be named as follows: - - - ".nc" (ex : "sp065_20210616T143025_R.nc") - -Where = "__" (ex : "sp065_20210616T143025_R") - -In this case: - - - = "sp065" a Spray glider number 065 - - = "20210616T143025" The datetime in seconds precision 2021-06-16 14:30:25 formatted following ISO 8601 - - = "R" for near real time data - - -//// -* [[global-attributes]] -= Global attributes -//// -== Global attributes - -The global attribute section is used for data discovery. The following global attributes should appear in the global section. The NetCDF Climate and Forecast (CF) Metadata Conventions are available from: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#trajectory-data[_http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#trajectory-data_]. It is recommended that extra global attributes follow ACDD convention". - -[cols="5,6,3,6a",options="header",] -|===================================================================================================================================================================================================================================================================================== -|*Global attribute* |*Definition* |*Requirement status* |*Format, fixed value or example* -|title |A short phrase or sentence describing the dataset. |mandatory |**ex.:** “OceanGliders trajectory file” -|platform a| -Name of the platform(s) that supported the sensors data used to create this data set or product. - - - - |mandatory |**ex.:** "sub-surface gliders" -|platform_vocabulary |Controlled vocabulary for the names used in the "platform" attribute. -|mandatory |**ex.:** https://vocab.nerc.ac.uk/collection/L06/current/27/[_https://vocab.nerc.ac.uk/collection/L06/current/27/_] -|id a| -Formatted mission name: __ - -|mandatory | -**ex.:** - -* unit_1032_20230512T001245_delayed -* sea008_20180715T012451_delayed -* sp032_20150923T150451_R -* sg041_20381221T000032_R - - -|naming_authority a| -A unique name that identifies the institution who provided the id. -ACDD-1.3 recommends using reverse-DNS naming. -|highly desirable | -**ex.:** - -* IOOS -* IMOS -* Coriolis -* edu.ucsd.spray - -|institution a| -The name of the institution where the original data was produced. - -|highly desirable | -**ex.:** - -* Texas A-M University -* IMOS -* PLOCAN - -|internal_mission_identifier a| -The mission identifier used by the institution principally responsible for originating this data - - |highly desirable | - -**ex.:** - -* sverdrup_20200512_delayed -* Forster20201109 -* Estoc_2015_01 - -|geospatial_lat_min |Describes a simple lower latitude limit |suggested |**format:** decimal degree -|geospatial_lat_max |Describes a simple upper latitude limit |suggested |**format:** decimal degree -|geospatial_lon_min |Describes a simple longitude limit |suggested |**format:** decimal degree -|geospatial_lon_max |Describes a simple longitude limit |suggested |**format:** decimal degree -|geospatial_vertical_min |Describes the numerically smaller vertical limit. |suggested |**format:** meter depth -|geospatial_ vertical_max |Describes the numerically larger vertical limit |suggested |**format:** meter depth -|time_coverage_start | | |**format:** iso 8601 -|time_coverage_end | | |**format:** iso 8601 -|site |The name of the regular sample line or area. |highly desirable | **ex.:** MOOSE_T00, MOOSE_02 -|site_vocabulary |Controlled vocabulary of the names used in the “site” attribute |highly desirable |To be defined -|program |The overarching program(s) of which the dataset is a part. A program consists of a set (or portfolio) of related and possibly interdependent projects that meet an overarching objective. |Highly desirable |**ex.:** MOOSE glider program -|program_vocabulary | Controlled vocabulary of the program attribute| highly desirable | To be defined -|project |The name of the project(s) principally responsible for originating this data. Multiple projects can be separated by commas |suggested | **ex.:** SAMBA -|network |A network is a group of platforms crossing the boundaries of a single program. It can represent a mutual scientific objective, a geographical focus, an array and/or a project. Multiple networks shall be separated by commas. |suggested | **ex.:** Integrated Ocean Observing System (IOOS), Southern California Coastal Ocean Observing System (SCCOOS), Boundary Ocean Observing Network (BOON) -|contributor_name |Name of the contributors to the glider mission. Multiple contributors are separated by commas. |PI name is mandatory | **ex.:** "Victor Turpin, Callum Rollo" -|contributor_email |Email of the contributors to the glider mission. Multiple contributors' emails are separated by commas. |PI email is mandatory | **ex.:** "victor@eample.com, callum@example.com" -|contributor_id |Unique id of the contributors to the glider mission. Multiple contributors’ ids are separated by commas. |highly desirable | -|contributor_role |Role of the contributors to the glider mission. Multiple contributors’ roles are separated by commas. |PI vocabulary is mandatory | -|contributor_role_vocabulary |Controlled vocabulary for the roles used in the "contributors_role". Multiple contributors’ roles and vocabularies are separated by commas. |PI vocabulary is mandatory |**ex.:** http://vocab.nerc.ac.uk/search_nvs/W08/[_http://vocab.nerc.ac.uk/search_nvs/W08/_] -|contributing_institutions |Names of institutions involved in the glider mission. Multiple institutions are separated by commas. |Operator is mandatory | -|contributing_institutions_vocabulary |url to the repository of the id |highly desirable | **ex.:** https://edmo.seadatanet.org/report/544, https://ror.org/012tb2g32 -|contributing_institutions_role |Role of the institutions involved in the glider mission. Multiple institutions' roles are separated by a comma. |Operator role is mandatory | -|contributing_institutions_role_vocabulary |The controlled vocabulary of the role used in the institution's role. Multiple vocabularies are separated by commas. |Operator vocabulary is mandatory |**ex.:** https://vocab.nerc.ac.uk/collection/W08/current/[_https://vocab.nerc.ac.uk/collection/W08/current/_] -|uri |Other universal resource identifiers relevant to be linked to this dataset. Multiple uris are separated by a comma. |suggested | **ex.:** EDIOS, CSR, EDMERP, EDMED, CDI, ICES, etc. -|data_url |url link to where the OG1.0 data file is hosted |highly desirable| **ex.:** https://linkedsystems.uk/erddap/files/Public_OG1_Data_001/Kelvin_20231205/Kelvin_620_R.nc -|doi |The digital object identifier of the OG1.0 data file |highly desirable | **ex.:** https://doi.org/10.17882/56366 -|rtqc_method |The method used by DAC to apply real-time quality control to the data set |mandatory | **ex.:** "Quality control performed with IOOS QARTOD toolbox v2.1", "No QC applied" -|rtqc_method_doi |The digital object identifier of the methodology used to apply real-time quality control to the data set. |highly desirable | **ex.**: "n/a" -|web_link |url that provides useful information about anything related to the glider mission. Multiple urls are separated by commas. |suggested | **ex.:** https://observations.voiceoftheocean.org/SEA078/M25 -|comment |Miscellaneous information about the glider mission, data or methods used to produce it. |suggested | **ex.:** "glider recovered after 5 days due to leak" -|start_date | Datetime of glider deployment |mandatory |**format:** Formatted string: YYYYmmddTHHMMss **ex.:** 20240425T145805 -|date_created |date of creation of this data set |mandatory |**format:** Formatted string: YYYYmmddTHHMMss **ex.:** 20240425T145805 -|featureType |Description of a single feature with this discrete sampling geometry |mandatory |**fixed value:** "trajectory" -|Conventions |A comma-separated list of the conventions that are followed by the dataset. |mandatory |**ex.:** "CF-1.10, ACDD-1.3, OG-1.0" -|===================================================================================================================================================================================================================================================================================== - - -//// -* [[dimension-and-definition]] -= Dimension and definition -//// -== Dimension and definition - -[cols=",,",options="header",] -|================================================================================================================================================================================================================================================================= -|*Name* |*Definition* |*Comment* -|N_MEASUREMENTS |N_MEASUREMENTS = unlimited; |Number of recorded locations. -|================================================================================================================================================================================================================================================================= - -//// -* [[location-variables]] -= Location variables -//// -== Location variables -//// -** [[gps-variables]] -== GPS variables -//// -=== GPS variables - -OG1.0 requirements cover the GPS variables delivered by the glider when at the sea surface, described in the table below. - - -[cols="1a,2a,1",options="header",] -|============================================================ -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|LATITUDE_GPS - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “latitude of each GPS location”; -* standard_name = “latitude”; -* units = “degrees_north”; -* _FillValue = -9999.9; -* valid_min = -90.0; -* valid_max = 90.0; -* ancillary_variables = "LATITUDE_GPS_QC" - - |mandatory -|LONGITUDE_GPS - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “longitude of each GPS location”; -* standard_name = “longitude”; -* units = “degrees_east”; -* _FillValue = -9999.9; -* valid_min = -180.0; -* valid_max = 180.0; -* ancillary_variables = "LONGITUDE_GPS_QC" - - |mandatory -|TIME_GPS - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “time of each GPS location”; -* calendar = "gregorian" ; -* units = “seconds since 1970-01-01T00:00:00Z”; -* _FillValue = -1.0 ; -* valid_min = 1e9 ; -* valid_max = 4e9 ; -* ancillary_variables = “TIME_GPS_QC” - - |mandatory -|============================================================ - - -//// -* [[along-track-positioning-variables]] -== Along track positioning variables -//// -== Along track positioning variables - -OG1.0 requirements cover positioning variables and geolocation of any scientific measurements made by the glider during its mission, described in the table below. - -[cols="1a,2a,1",options="header",] -|============================================================ -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|LATITUDE - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “latitude of each measurement and GPS location”; -* standard_name = “latitude”; -* units = “degrees_north”; -* _FillValue = -9999.9; -* valid_min = -90.0; -* valid_max = 90.0; -* ancillary_variables = "LATITUDE_GPS_QC" -* interpolation_methodology = “”; - - - |mandatory -|LONGITUDE - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “longitude of each measurement and GPS location”; -* standard_name = “longitude”; -* units = “degrees_east”; -* _FillValue = -9999.9; -* valid_min = -180.0; -* valid_max = 180.0; -* ancillary_variables = "LONGITUDE_GPS_QC"; -* interpolation_methodology = “”; - - |mandatory -|TIME - -* data type: double -* dimension: N_MEASUREMENTS | - -* long_name = “time of measurement”; -* calendar = "gregorian" ; -* units = “seconds since 1970-01-01T00:00:00Z”; -* _FillValue = -1.0 ; -* valid_min = 1e9 ; -* valid_max = 4e9 ; -* ancillary_variables = “TIME_GPS_QC”; -* interpolation_methodology = “”; - - |mandatory -|============================================================ - - -See parameters section for guidance on attributes and conventions on _QC channels. - -//// -* [[trajectory-name]] -== Trajectory name -//// -== Trajectory Name - -[cols=",,,",options="header",] -|======================================================================================== -|*VARIABLE NAME* |*variable attributes* |*requirement status* | *Format, fixed value or example* -|TRAJECTORY a| -string TRAJECTORY - -TRAJECTORY:cf_role = "trajectory_id" - -TRAJECTORY:long_name = “trajectory name”; - -TRAJECTORY:format = "_" - -Where is defined below + -Where refers to the deployment start UTC date under iso 8601. + - - a| -mandatory | -*ex.:* sp041_20210909T160556 - -|======================================================================================== - - -//// -* [[platform-information]] -== Platform information -//// -=== Platform information - -[cols=",,,",options="header",] -|======================================================================================== -|*VARIABLE NAME* |*variable attributes* |*requirement status* | *Format, fixed value or example* -|WMO_IDENTIFIER a| -string WMO_IDENTIFIER - -WMO_IDENTIFIER:long_name = “wmo id”; - - |mandatory -| *ex.:* '6801706' - -|PLATFORM_MODEL a| -string PLATFORM_MODEL - -PLATFORM_MODEL:long_name: “model of the glider”; - -PLATFORM_MODEL:platform_model_vocabulary = “”; - - |mandatory -| **ex.:** "Kongsberg Maritime Seaglider M1 glider" - -PLATFORM_MODEL: platform_model_vocabulary = “https://vocab.nerc.ac.uk/ -collection/B76/current/B7600002/”; - -|PLATFORM_SERIAL_NUMBER a| -string PLATFORM_SERIAL_NUMBER - -PLATFORM_SERIAL_NUMBER:long_name = “glider serial number”; - - |mandatory -| The platform serial should be constructed from the manufacturer prefix and the platform serial number *ex.:* "sg001" (seaglider), "unit_001" (slocum), "sea001" (seaexplorer), "sp001" (spray). Where the serial number of the platform is not known, a local nickname can be used e.g. "orca", "sverdrup", "ammonite". -|PLATFORM_NAME a| - -string PLATFORM_NAME - -PLATFORM_NAME:long_name = “Local or nickname of the glider”; - |highly desirable -| a local nickname for the glider *ex.:* "orca", "sverdrup", "ammonite". - -|PLATFORM_DEPTH_RATING a| -integer PLATFORM_DEPTH_RATING - -PLATFORM_DEPTH_RATING:long_name = “depth limit in meters of the glider for this mission”; - -PLATFORM_DEPTH_RATING:convention = “positive value expected - e.g. 100m depth = 100”; - - |highly desirable -| *ex.:* 1000 -|ICES_CODE a| -string ICES_CODE - -ICES_CODE:long_name = “ICES platform code of the glider”; - -ICES_CODE:ices_code_vocabulary = “”; - - |highly desirable -| *ex.:* "7460" - -ICES_CODE:ices_code_vocabulary = -“https://vocab.ices.dk/? -codeguid=690d82e2 --b4e2-4e30-9772-7499c66144c6”; -|PLATFORM_MAKER a| -string PLATFORM_MAKER - -PLATFORM_MAKER:long_name = “glider manufacturer”; - -PLATFORM_MAKER:platform_maker_vocabulary = “”; - - |suggested -| *ex.:* "Teledyne Webb Research" - -PLATFORM_MAKER: platform_maker_vocabulary = “https://vocab.nerc.ac.uk/ -collection/B75/current/ORG01077/”; -|======================================================================================== - -//// -* [[deployment-information]] -== Deployment information -//// -=== Deployment information - -[cols=",,",options="header",] -|============================================================ -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|DEPLOYMENT_TIME a| -double DEPLOYMENT_TIME - -DEPLOYMENT_TIME:long_name = “date of deployment”; - -DEPLOYMENT_TIME:standard_name = "time"; - -DEPLOYMENT_TIME:calendar = "gregorian"; - -DEPLOYMENT_TIME:units = "seconds since 1970-01-01T00:00:00Z"; - - |mandatory -|DEPLOYMENT_LATITUDE a| -double DEPLOYMENT_LATITUDE - -DEPLOYMENT_LATITUDE:long_name = “latitude of deployment”; - - |mandatory -|DEPLOYMENT_LONGITUDE a| -double DEPLOYMENT_LONGITUDE - -long_name = “longitude of deployment”; - - |mandatory -|============================================================ - - -//// -* [[field-comparison-information]] -== Field comparison information -//// -=== Field comparison information - -[cols=",,",options="header",] -|========================================================================================================================================= -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|FIELD_COMPARISON_REFERENCE a| -String FIELD_COMPARISON_REFERENCE: - -FIELD_COMPARISON_REFERENCE:long_name = “links (uri or url) to supplementary data that can provide field comparison for platform sensors.”; - -FIELD_COMPARISON_REFERENCE:comment = “multiple links are separated by a comma” - - |highly desirable -|========================================================================================================================================= - -Note: FIELD_COMPARISON_REFERENCE is applicable to deployment, recovery, and delayed versions. - -//// -* [[hardware-information]] -== Hardware information -//// -=== Hardware information - -[cols=",,",options="header",] -|============================================================================= -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|GLIDER_FIRMWARE_VERSION a| -string GLIDER_FIRMWARE_VERSION - -GLIDER_FIRMWARE_VERSION:long_name = “version of the internal glider firmware”; - - |highly desirable -|LANDSTATION_VERSION a| -string LANDSTATION_VERSION - -LANDSTATION_VERSION:long_name = “version of the server onshore”; - - |highly desirable -|BATTERY_TYPE a| -string BATTERY_TYPE - -BATTERY_TYPE:long_name = “type of the battery”; - -BATTERY_TYPE:battery_type_vocabulary = “”; - - |suggested -|BATTERY_PACK a| -string BATTERY_PACK - -BATTERY_PACK:long_name = “battery packaging”; - - |suggested -|============================================================================= - -//// -* [[telecom-information]] -== Telecom information -//// -=== Telecom information - -[cols=",,",options="header",] -|=============================================================================== -|*VARIABLE NAME* |*variable attributes* |*requirement status* -|TELECOM_TYPE a| -string TELECOM_TYPE - -TELECOM_TYPE:long_name = “type of telecommunication systems used by the glider”; - -TELECOM_TYPE:telecom_type_vocabulary = “”; - - |highly desirable -|TRACKING_SYSTEM a| -string TRACKING_SYSTEM - -TRACKING_SYSTEM:long_name = “type of tracking systems used by the glider”; - -TRACKING_SYSTEM:tracking_system_vocabulary = “”; - - |highly desirable -|=============================================================================== - -//// -* [[phase-variable]] -= Phase variable -//// -== Phase variable - -PHASE describes the glider behaviors when at sea. The different behaviors are described in the phase vocabulary (ascent, descent, surfacing, parking, inflection, etc.) - -Note that the vocabulary will be fully described and implemented in the control vocabulary tool during the implementation phase. - -Phase calculation methodologies need publishing as a best practice document separately to the OG1.0 terms of reference. - -The tables below describe the mandatory information to PHASE stored in two ways. - -[cols=",,",options="header",] -|============================================================= -|*VARIABLES NAME* |*variable attributes* |*requirement status* -|PHASE a| -Byte PHASE(N_MEASUREMENTS) - -PHASE:long_name = “behavior of the glider at sea”; - -PHASE:phase_vocabulary: “https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/phase.md”; - -PHASE:_FillValue = 0b ; - -PHASE:phase_calculation_method = “”; - -PHASE:phase_calculation_method_vocabulary = “”; - -PHASE: ancillary_variables = "PHASE_QC" - - |Highly desirable -|PHASE_QC a| -Byte PHASE_QC(N_MEASUREMENTS) - -PHASE_QC:long_name = "quality flag"; - -PHASE_QC:_FillValue = " "; - -PHASE_QC:valid_range = 0b, 1b, 2b, 3b, 4b; - -PHASE_QC:flag_values = 0b, 1b, 2b, 3b, 4b; - -PHASE_QC:flag_meanings = "No QC has been applied, - Good data, - Probably good data, - Probably bad data, - Bad data" ; - - |Highly desirable -|============================================================= - - -PHASE is used to derive data product (profile, trajectory profiles, gridded product) from OG1.0 data sets. It is recommended to include PHASE when possible. - -//// -* [[sensor-information]] -= Sensor information -//// -== Sensor information - -Each geophysical variable to be recorded must be described with its sensor. Sensor information are stored in an empty and dimensionless variable filled with variable attributes. - -=== Naming convention of the sensor variables - -Sensor variables are named as follows: *SENSOR__* - -Where is a controlled vocabulary: see vocabulary guidelines - - -[cols=",,",options="header",] -|============================================================= -|*VARIABLE NAME* |*variable attributes* and *requirement status* | *example* - -|SENSOR__ - a| - -string SENSOR__ - -attributes: - -sensor_type_vocabulary: “” - mandatory - -long_name: “” - mandatory - -sensor_model: “” - mandatory - -sensor_model_vocabulary: “” - mandatory - -sensor_maker: “” - highly desirable - -sensor_maker_vocabulary: “” - highly desirable - -sensor_serial_number: “” - highly desirable - -sensor_calibration_date: “” - highly desirable - Format iso8601 ("YYYY-MM-DD") -| - -SENSOR_CTD_206523 - -attributes: - -sensor_type_vocabulary: "https://vocab.nerc.ac.uk/collection/L05/current/130” - -long_name: “RBR Legato3 CTD” - -sensor_model: “RBR Legato3 CTD” - -sensor_model_vocabulary: “https://vocab.nerc.ac.uk/collection/L22/current/TOOL1745” - -sensor_maker: “RBR” - -sensor_maker_vocabulary: “https://vocab.nerc.ac.uk/collection/L35/current/MAN0049” - -sensor_serial_number: “206523” - -sensor_calibration_date: “2021-03-01” - - -|============================================================= - - -//// -* [[geophysical-variables]] -= Geophysical variables -//// -== Geophysical variables - -Geophysical variables are measurements of a physical phenomenon (or an intermediate variable needed to measure a physical phenomenon); It is provided directly by a sensor (in sensor counts or in physical units) or computed (derived) from other parameters (i.e. intermediate parameters). - -The fill value should have the same data type as the variable and be outside the range of possible data values. - -[cols=",,,",options="header",] -|========================================================================================================================== -|*VARIABLE NAME* |*variable attributes* |*requirement status* | *example* -| a| -float (N_MEASUREMENT); - -:long_name = ""; :standard_name = ""; - -:vocabulary = ""; - -:_FillValue = ; Note: The fill value should have the same data type as the variable and be outside the range of possible data values. - -:units = ""; - -:ancillary_variables = "_QC"; - -:coordinates = "LATITUDE, LONGITUDE, DEPTH, TIME" - -:sensor = "SENSOR__" - - a| -mandatory - - contains the values of a parameter listed in the control vocabulary related to OceanGliders parameters. - -: these fields are specified in the control vocabularies. - -| CNDC(N_MEASUREMENT); - -attributes: - -long_name = "Electrical conductivity of the water body by CTD" - -standard_name = ""; - -vocabulary = "https://vocab.nerc.ac.uk/collection/OG1/current/CNDC/"; - -_FillValue = NaNf - -units = "mS cm-1" - -ancillary_variables = "CNDC_QC"; - -coordinates = "LATITUDE, LONGITUDE, DEPTH, TIME" - -sensor = "SENSOR_CTD_206523" - -|_QC a| -Byte _QC(N_MEASUREMENT); _QC:long_name = "quality flag"; - -_QC:_FillValue = " "; - -_QC:valid_range = 0b, 1b, 2b, 3b, 4b; - -_QC:flag_values = 0b, 1b, 2b, 3b, 4b; - -_QC:flag_meanings = "No QC has been applied, - Good data, - Probably good data, - Probably bad data, - Bad data" ; - -_QC:RTQC_methodology = “”; - -_QC:RTQC_methodology_vocabulary = “”; - -_QC:RTQC_methodology_doi = “”; - - |higly desirable | -|========================================================================================================================== - - -//// -* [[best-practices]] -= Best practices -//// -== Best practices - -Methodologies used to produce files meeting the OG format should be published in the IODE Ocean Best Practice (OBP) repository (https://repository.oceanbestpractices.org/[_https://repository.oceanbestpractices.org/_]) under the community “OceanGliders” and the collection “data management”. The following methodologies are covered, among others: - -* Interpolation -* PHASE computation -* RTQC - -Methodologies should describe the computation methods used (typically by Data Assembly Centers) to produce the data set. Ocean Best Practices are assigned a DOI and should be tagged as "OceanGliders" practices by the submitter. Additionally, OBP endorsed by the OceanGliders data management task team will be marked as such. - -//// -* [[evolution-process-inclusion-of-new-variables.]] -= Evolution process, inclusion of new variables. -//// -== Evolution process, the inclusion of new variables. - -Management of the evolution of the format will be organized by the OceanGliders data management team. - - diff --git a/OG_Format.html b/OG_Format.html new file mode 100644 index 00000000..b5d9af63 --- /dev/null +++ b/OG_Format.html @@ -0,0 +1,2098 @@ + + + + + + + +Methodology + + + + + +
+ ++++ + + + + + + +
imageOceanGliders 1.0 format - Terms of References
+ +Navigation:
+ +GitHub repository
+Terms of reference
+Vocabulary collections
+
+

Methodology

+
+
+

A working group on harmonization of the glider data format was set up in September 2020 at the request of the OceanGliders steering team. All members of the OceanGliders data management team were invited to join. +The three existing formats (at the time) were analysed and compared by the group. Regular technical meetings occurred and the format harmonization process was managed via a Google doc. In late 2021 the group decided to move the document to GitHub to better manage the issues, work asynchronously and contribute to the open source community. +The GitHub repository is open to any comments from the community and validation rules were created by the working group (see the governance document). +From there the working group organized regular meetings to validate the evolution of the format, discuss issues and reach a consensus on the OG1.0 format. It is envisaged that the format will continually evolve with contributions from the community.

+
+
+
+
+

Authorship

+
+
+

Authors

+
+ +
+
+
+

Contributors

+
+ +
+
+
+

Acknowledgements

+
+

Several organisations were instrumental in the development of this format. OceanGliders, UG2, and EGO provided encouragement and forums for initial discussion. Some authors received support from, amongst others, EuroSEA, AtlantOS, GOMO, EMODnet Physics, NERC, VOTO and GROOM II.

+
+
+
+
+
+

Background

+
+
+

The OceanGliders program brings together marine scientists and glider operators from all over the world who observe the long-term physical, biogeochemical, biological ocean processes, and phenomena relevant for societal applications. It allows active coordination and strengthening the roles of gliders in the ocean observation programs worldwide and contributes to the present international efforts for ocean observation for climate, ocean health and real-time services.

+
+
+

The program oversees the monitoring of global glider activity, a prerequisite for active coordination. By sharing requirements, efforts and scientific knowledge needed for glider data collection OceanGliders aims to continuously develop the network by supporting the dissemination of glider data in global databases, in real-time and delayed mode, for a wider community.

+
+
+

The OceanGliders program was created about 10 years after the popularization of the use of gliders by ocean scientists. With no common rules on format, data managers from Australia (IMOS), the USA (IOOS), and Europe (Coriolis) processed 3 regional formats that are not interoperable.

+
+
+

Harmonization toward interoperability within the existing formats and many national/regional glider networks is a recommendation from the OceanGliders steering team to strengthen the program and reach the FAIR principles (Findable, Accessible, Interoperable, Reusable) adopted by GOOS (Global Ocean Observing System), and better monitor the program activity.

+
+
+
+
+

Objectives

+
+
+

This document defines the common OceanGliders data format, hereafter OG1.0.

+
+
+
+
+

OG1.0 General conventions

+
+
+
    +
  • +

    The required granularity of the data set is the glider mission, starting from deployment at sea to recovery.

    +
    • +
  • +

    Data are recorded as a trajectory Discrete Geometry, using NetCDF[1] system and following CF 1.10[2] (Climate and Forecast) specifications. Each data file contains a series of dive cycles representing the mission of the glider. It can be produced in near real time after every glider transmission and revised later into a recovery-mode (when glider on shore and any data gaps filled in) or a delayed-mode (after rigorous QC) version.

    +
    • +
  • +

    Format follows the ACDD 1.3[3] convention where possible.

    +
    • +
  • +

    Vocabulary collections will be hosted in different places (NERC Vocabulary Server - NVS, OceanOPS, ICES, etc). The OceanGliders data management team will manage (additions, updates, etc.) the collections. Treatment of vocabularies is detailed in the vocabularies document.

    +
    • +
  • +

    OG1.0 defines some variables and definitions, as described in this document. Other types of measurements (e.g. intermediate parameters, technical measurements, other variables) not framed by OG1.0 can be included in OG1.0 data files. No control will be applied to those measurements.

    +
    • +
  • +

    Geospatial variables and along-track positioning variables are mandatory.

    +
    • +
  • +

    Methodologies used to interpolate data, compute along-track positioning variables, apply QC etc. Should be linked and, where possible, follow community best practices. It is encouraged to use unique resource identifiers (uris) to link to these resources.

    +
    • +
  • +

    3 recommendations level have been defined for OG1.0:

    +
    +
      +
    • +

      Mandatory: Minimum metadata set to be compliant with OG1.0 requirement.

      +
      • +
    • +

      Highly desirable: Worth having for complete use of the data set.

      +
      • +
    • +

      Suggested: If the information is available.

      +
      • +
    +
    +
    • +
+
+
+
+
+

DOI management

+
+
+
    +
  • +

    A DOI can be minted at any level (PI, Reference Data Center, Data Assembly Center, Global Data Assembly Center) following the internal policy of data curation.

    +
    • +
  • +

    A DOI can be minted for a single glider mission or multiple glider missions (i.e. project, reference lines).

    +
    • +
  • +

    A DOI if included in OG1.0 files needs to be preserved. The DOI must remain unchanged if there is no valuable modification. If valuable information is aggregated/added or a new product produced, a new DOI should be created and the new DOI should link to the original DOI to acknowledge as the source

    +
    • +
  • +

    The most effective way of preserving the integrity of the source citation is to preserve the initial DOI added in the OG1.0 file.

    +
    • +
+
+
+
+
+

OG1.0 file naming convention

+
+
+
    +
  • +

    Data files should be named as follows:

    +
    +
      +
    • +

      "<id>.nc" (ex : "sp065_20210616T143025_R.nc")

      +
      • +
    +
    +
    • +
+
+
+

Where <id> = "<platform_serial>_<start_date>_<data_mode>" (ex : "sp065_20210616T143025_R")

+
+
+

In this case:

+
+
+
    +
  • +

    <platform_serial> = "sp065" a Spray glider number 065

    +
    • +
  • +

    <start_date> = "20210616T143025" The datetime in seconds precision 2021-06-16 14:30:25 formatted following ISO 8601

    +
    • +
  • +

    <data_mode> = "R" for near real time data

    +
    • +
+
+
+
+
+

Global attributes

+
+
+

The global attribute section is used for data discovery. The following global attributes should appear in the global section. The NetCDF Climate and Forecast (CF) Metadata Conventions are available from: http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#trajectory-data. It is recommended that extra global attributes follow ACDD convention".

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Global attributeDefinitionRequirement statusFormat, fixed value or example

title

A short phrase or sentence describing the dataset.

mandatory

+

ex.: “OceanGliders trajectory file”

+

platform

+

Name of the platform(s) that supported the sensors data used to create this data set or product.

+

mandatory

+

ex.: "sub-surface gliders"

+

platform_vocabulary

Controlled vocabulary for the names used in the "platform" attribute.

mandatory

+

ex.: https://vocab.nerc.ac.uk/collection/L06/current/27/

+

id

+

Formatted mission name: <platform_serial>_<start_date>_<data_mode>

+

mandatory

+

ex.:

+
+
+
    +
  • +

    unit_1032_20230512T001245_delayed

    +
    • +
  • +

    sea008_20180715T012451_delayed

    +
    • +
  • +

    sp032_20150923T150451_R

    +
    • +
  • +

    sg041_20381221T000032_R

    +
    • +
+

naming_authority

+

A unique name that identifies the institution who provided the id. +ACDD-1.3 recommends using reverse-DNS naming.

+

highly desirable

+

ex.:

+
+
+
    +
  • +

    IOOS

    +
    • +
  • +

    IMOS

    +
    • +
  • +

    Coriolis

    +
    • +
  • +

    edu.ucsd.spray

    +
    • +
+

institution

+

The name of the institution where the original data was produced.

+

highly desirable

+

ex.:

+
+
+
    +
  • +

    Texas A-M University

    +
    • +
  • +

    IMOS

    +
    • +
  • +

    PLOCAN

    +
    • +
+

internal_mission_identifier

+

The mission identifier used by the institution principally responsible for originating this data

+

highly desirable

+

ex.:

+
+
+
    +
  • +

    sverdrup_20200512_delayed

    +
    • +
  • +

    Forster20201109

    +
    • +
  • +

    Estoc_2015_01

    +
    • +
+

geospatial_lat_min

Describes a simple lower latitude limit

suggested

+

format: decimal degree

+

geospatial_lat_max

Describes a simple upper latitude limit

suggested

+

format: decimal degree

+

geospatial_lon_min

Describes a simple longitude limit

suggested

+

format: decimal degree

+

geospatial_lon_max

Describes a simple longitude limit

suggested

+

format: decimal degree

+

geospatial_vertical_min

Describes the numerically smaller vertical limit.

suggested

+

format: meter depth

+

geospatial_ vertical_max

Describes the numerically larger vertical limit

suggested

+

format: meter depth

+

time_coverage_start

+

format: iso 8601

+

time_coverage_end

+

format: iso 8601

+

site

The name of the regular sample line or area.

highly desirable

+

ex.: MOOSE_T00, MOOSE_02

+

site_vocabulary

Controlled vocabulary of the names used in the “site” attribute

highly desirable

+

To be defined

+

program

The overarching program(s) of which the dataset is a part. A program consists of a set (or portfolio) of related and possibly interdependent projects that meet an overarching objective.

Highly desirable

+

ex.: MOOSE glider program

+

program_vocabulary

Controlled vocabulary of the program attribute

highly desirable

+

To be defined

+

project

The name of the project(s) principally responsible for originating this data. Multiple projects can be separated by commas

suggested

+

ex.: SAMBA

+

network

A network is a group of platforms crossing the boundaries of a single program. It can represent a mutual scientific objective, a geographical focus, an array and/or a project. Multiple networks shall be separated by commas.

suggested

+

ex.: Integrated Ocean Observing System (IOOS), Southern California Coastal Ocean Observing System (SCCOOS), Boundary Ocean Observing Network (BOON)

+

contributor_name

Name of the contributors to the glider mission. Multiple contributors are separated by commas.

PI name is mandatory

+

ex.: "Victor Turpin, Callum Rollo"

+

contributor_email

Email of the contributors to the glider mission. Multiple contributors' emails are separated by commas.

PI email is mandatory

+

ex.: "victor@eample.com, callum@example.com"

+

contributor_id

Unique id of the contributors to the glider mission. Multiple contributors’ ids are separated by commas.

highly desirable

contributor_role

Role of the contributors to the glider mission. Multiple contributors’ roles are separated by commas.

PI vocabulary is mandatory

contributor_role_vocabulary

Controlled vocabulary for the roles used in the "contributors_role". Multiple contributors’ roles and vocabularies are separated by commas.

PI vocabulary is mandatory

+

ex.: http://vocab.nerc.ac.uk/search_nvs/W08/

+

contributing_institutions

Names of institutions involved in the glider mission. Multiple institutions are separated by commas.

Operator is mandatory

contributing_institutions_vocabulary

url to the repository of the id

highly desirable

+

ex.: https://edmo.seadatanet.org/report/544, https://ror.org/012tb2g32

+

contributing_institutions_role

Role of the institutions involved in the glider mission. Multiple institutions' roles are separated by a comma.

Operator role is mandatory

contributing_institutions_role_vocabulary

The controlled vocabulary of the role used in the institution’s role. Multiple vocabularies are separated by commas.

Operator vocabulary is mandatory

+

ex.: https://vocab.nerc.ac.uk/collection/W08/current/

+

uri

Other universal resource identifiers relevant to be linked to this dataset. Multiple uris are separated by a comma.

suggested

+

ex.: EDIOS, CSR, EDMERP, EDMED, CDI, ICES, etc.

+

data_url

url link to where the OG1.0 data file is hosted

highly desirable

+

ex.: https://linkedsystems.uk/erddap/files/Public_OG1_Data_001/Kelvin_20231205/Kelvin_620_R.nc

+

doi

The digital object identifier of the OG1.0 data file

highly desirable

+

ex.: https://doi.org/10.17882/56366

+

rtqc_method

The method used by DAC to apply real-time quality control to the data set

mandatory

+

ex.: "Quality control performed with IOOS QARTOD toolbox v2.1", "No QC applied"

+

rtqc_method_doi

The digital object identifier of the methodology used to apply real-time quality control to the data set.

highly desirable

+

ex.: "n/a"

+

web_link

url that provides useful information about anything related to the glider mission. Multiple urls are separated by commas.

suggested

+

ex.: https://observations.voiceoftheocean.org/SEA078/M25

+

comment

Miscellaneous information about the glider mission, data or methods used to produce it.

suggested

+

ex.: "glider recovered after 5 days due to leak"

+

start_date

Datetime of glider deployment

mandatory

+

format: Formatted string: YYYYmmddTHHMMss ex.: 20240425T145805

+

date_created

date of creation of this data set

mandatory

+

format: Formatted string: YYYYmmddTHHMMss ex.: 20240425T145805

+

featureType

Description of a single feature with this discrete sampling geometry

mandatory

+

fixed value: "trajectory"

+

Conventions

A comma-separated list of the conventions that are followed by the dataset.

mandatory

+

ex.: "CF-1.10, ACDD-1.3, OG-1.0"

+
+
+
+
+

Dimension and definition

+
+ +++++ + + + + + + + + + + + + + + +
NameDefinitionComment

N_MEASUREMENTS

N_MEASUREMENTS = unlimited;

Number of recorded locations.

+
+
+
+

Location variables

+
+
+

GPS variables

+
+

OG1.0 requirements cover the GPS variables delivered by the glider when at the sea surface, described in the table below.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status
+

LATITUDE_GPS

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “latitude of each GPS location”;

    +
    • +
  • +

    standard_name = “latitude”;

    +
    • +
  • +

    units = “degrees_north”;

    +
    • +
  • +

    _FillValue = -9999.9;

    +
    • +
  • +

    valid_min = -90.0;

    +
    • +
  • +

    valid_max = 90.0;

    +
    • +
  • +

    ancillary_variables = "LATITUDE_GPS_QC"

    +
    • +
+

mandatory

+

LONGITUDE_GPS

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “longitude of each GPS location”;

    +
    • +
  • +

    standard_name = “longitude”;

    +
    • +
  • +

    units = “degrees_east”;

    +
    • +
  • +

    _FillValue = -9999.9;

    +
    • +
  • +

    valid_min = -180.0;

    +
    • +
  • +

    valid_max = 180.0;

    +
    • +
  • +

    ancillary_variables = "LONGITUDE_GPS_QC"

    +
    • +
+

mandatory

+

TIME_GPS

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “time of each GPS location”;

    +
    • +
  • +

    calendar = "gregorian" ;

    +
    • +
  • +

    units = “seconds since 1970-01-01T00:00:00Z”;

    +
    • +
  • +

    _FillValue = -1.0 ;

    +
    • +
  • +

    valid_min = 1e9 ;

    +
    • +
  • +

    valid_max = 4e9 ;

    +
    • +
  • +

    ancillary_variables = “TIME_GPS_QC”

    +
    • +
+

mandatory

+
+
+
+
+

Along track positioning variables

+
+
+

OG1.0 requirements cover positioning variables and geolocation of any scientific measurements made by the glider during its mission, described in the table below.

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status
+

LATITUDE

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “latitude of each measurement and GPS location”;

    +
    • +
  • +

    standard_name = “latitude”;

    +
    • +
  • +

    units = “degrees_north”;

    +
    • +
  • +

    _FillValue = -9999.9;

    +
    • +
  • +

    valid_min = -90.0;

    +
    • +
  • +

    valid_max = 90.0;

    +
    • +
  • +

    ancillary_variables = "LATITUDE_GPS_QC"

    +
    • +
  • +

    interpolation_methodology = “”;

    +
    • +
+

mandatory

+

LONGITUDE

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “longitude of each measurement and GPS location”;

    +
    • +
  • +

    standard_name = “longitude”;

    +
    • +
  • +

    units = “degrees_east”;

    +
    • +
  • +

    _FillValue = -9999.9;

    +
    • +
  • +

    valid_min = -180.0;

    +
    • +
  • +

    valid_max = 180.0;

    +
    • +
  • +

    ancillary_variables = "LONGITUDE_GPS_QC";

    +
    • +
  • +

    interpolation_methodology = “”;

    +
    • +
+

mandatory

+

TIME

+
+
+
    +
  • +

    data type: double

    +
    • +
  • +

    dimension: N_MEASUREMENTS

    +
    • +
+
+
    +
  • +

    long_name = “time of measurement”;

    +
    • +
  • +

    calendar = "gregorian" ;

    +
    • +
  • +

    units = “seconds since 1970-01-01T00:00:00Z”;

    +
    • +
  • +

    _FillValue = -1.0 ;

    +
    • +
  • +

    valid_min = 1e9 ;

    +
    • +
  • +

    valid_max = 4e9 ;

    +
    • +
  • +

    ancillary_variables = “TIME_GPS_QC”;

    +
    • +
  • +

    interpolation_methodology = “”;

    +
    • +
+

mandatory

+
+

See parameters section for guidance on attributes and conventions on _QC channels.

+
+
+
+
+

Trajectory Name

+
+ ++++++ + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement statusFormat, fixed value or example

TRAJECTORY

+

string TRAJECTORY

+
+
+

TRAJECTORY:cf_role = "trajectory_id"

+
+
+

TRAJECTORY:long_name = “trajectory name”;

+
+
+

TRAJECTORY:format = "<platform_serial>_<start_date>"

+
+
+

Where <platform_serial> is defined below
+Where <start_date> refers to the deployment start UTC date under iso 8601.

+
+

mandatory

+

ex.: sp041_20210909T160556

+
+

Platform information

+ ++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement statusFormat, fixed value or example

WMO_IDENTIFIER

+

string WMO_IDENTIFIER

+
+
+

WMO_IDENTIFIER:long_name = “wmo id”;

+

mandatory

ex.: '6801706'

PLATFORM_MODEL

+

string PLATFORM_MODEL

+
+
+

PLATFORM_MODEL:long_name: “model of the glider”;

+
+
+

PLATFORM_MODEL:platform_model_vocabulary = “”;

+

mandatory

ex.: "Kongsberg Maritime Seaglider M1 glider"

+

PLATFORM_MODEL: platform_model_vocabulary = “https://vocab.nerc.ac.uk/ +collection/B76/current/B7600002/”;

PLATFORM_SERIAL_NUMBER

+

string PLATFORM_SERIAL_NUMBER

+
+
+

PLATFORM_SERIAL_NUMBER:long_name = “glider serial number”;

+

mandatory

The platform serial should be constructed from the manufacturer prefix and the platform serial number ex.: "sg001" (seaglider), "unit_001" (slocum), "sea001" (seaexplorer), "sp001" (spray). Where the serial number of the platform is not known, a local nickname can be used e.g. "orca", "sverdrup", "ammonite".

PLATFORM_NAME

+

string PLATFORM_NAME

+
+
+

PLATFORM_NAME:long_name = “Local or nickname of the glider”;

+

highly desirable

a local nickname for the glider ex.: "orca", "sverdrup", "ammonite".

PLATFORM_DEPTH_RATING

+

integer PLATFORM_DEPTH_RATING

+
+
+

PLATFORM_DEPTH_RATING:long_name = “depth limit in meters of the glider for this mission”;

+
+
+

PLATFORM_DEPTH_RATING:convention = “positive value expected - e.g. 100m depth = 100”;

+

highly desirable

ex.: 1000

ICES_CODE

+

string ICES_CODE

+
+
+

ICES_CODE:long_name = “ICES platform code of the glider”;

+
+
+

ICES_CODE:ices_code_vocabulary = “”;

+

highly desirable

ex.: "7460"

+

ICES_CODE:ices_code_vocabulary = +“https://vocab.ices.dk/? +codeguid=690d82e2 +-b4e2-4e30-9772-7499c66144c6”;

PLATFORM_MAKER

+

string PLATFORM_MAKER

+
+
+

PLATFORM_MAKER:long_name = “glider manufacturer”;

+
+
+

PLATFORM_MAKER:platform_maker_vocabulary = “”;

+

suggested

ex.: "Teledyne Webb Research"

+

PLATFORM_MAKER: platform_maker_vocabulary = “https://vocab.nerc.ac.uk/ +collection/B75/current/ORG01077/”;

+
+
+

Deployment information

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status

DEPLOYMENT_TIME

+

double DEPLOYMENT_TIME

+
+
+

DEPLOYMENT_TIME:long_name = “date of deployment”;

+
+
+

DEPLOYMENT_TIME:standard_name = "time";

+
+
+

DEPLOYMENT_TIME:calendar = "gregorian";

+
+
+

DEPLOYMENT_TIME:units = "seconds since 1970-01-01T00:00:00Z";

+

mandatory

DEPLOYMENT_LATITUDE

+

double DEPLOYMENT_LATITUDE

+
+
+

DEPLOYMENT_LATITUDE:long_name = “latitude of deployment”;

+

mandatory

DEPLOYMENT_LONGITUDE

+

double DEPLOYMENT_LONGITUDE

+
+
+

long_name = “longitude of deployment”;

+

mandatory

+
+
+

Field comparison information

+ +++++ + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status

FIELD_COMPARISON_REFERENCE

+

String FIELD_COMPARISON_REFERENCE:

+
+
+

FIELD_COMPARISON_REFERENCE:long_name = “links (uri or url) to supplementary data that can provide field comparison for platform sensors.”;

+
+
+

FIELD_COMPARISON_REFERENCE:comment = “multiple links are separated by a comma”

+

highly desirable

+
+

Note: FIELD_COMPARISON_REFERENCE is applicable to deployment, recovery, and delayed versions.

+
+
+
+

Hardware information

+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status

GLIDER_FIRMWARE_VERSION

+

string GLIDER_FIRMWARE_VERSION

+
+
+

GLIDER_FIRMWARE_VERSION:long_name = “version of the internal glider firmware”;

+

highly desirable

LANDSTATION_VERSION

+

string LANDSTATION_VERSION

+
+
+

LANDSTATION_VERSION:long_name = “version of the server onshore”;

+

highly desirable

BATTERY_TYPE

+

string BATTERY_TYPE

+
+
+

BATTERY_TYPE:long_name = “type of the battery”;

+
+
+

BATTERY_TYPE:battery_type_vocabulary = “”;

+

suggested

BATTERY_PACK

+

string BATTERY_PACK

+
+
+

BATTERY_PACK:long_name = “battery packaging”;

+

suggested

+
+
+

Telecom information

+ +++++ + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement status

TELECOM_TYPE

+

string TELECOM_TYPE

+
+
+

TELECOM_TYPE:long_name = “type of telecommunication systems used by the glider”;

+
+
+

TELECOM_TYPE:telecom_type_vocabulary = “”;

+

highly desirable

TRACKING_SYSTEM

+

string TRACKING_SYSTEM

+
+
+

TRACKING_SYSTEM:long_name = “type of tracking systems used by the glider”;

+
+
+

TRACKING_SYSTEM:tracking_system_vocabulary = “”;

+

highly desirable

+
+
+
+
+

Phase variable

+
+
+

PHASE describes the glider behaviors when at sea. The different behaviors are described in the phase vocabulary (ascent, descent, surfacing, parking, inflection, etc.)

+
+
+

Note that the vocabulary will be fully described and implemented in the control vocabulary tool during the implementation phase.

+
+
+

Phase calculation methodologies need publishing as a best practice document separately to the OG1.0 terms of reference.

+
+
+

The tables below describe the mandatory information to PHASE stored in two ways.

+
+ +++++ + + + + + + + + + + + + + + + + + + + +
VARIABLES NAMEvariable attributesrequirement status

PHASE

+

Byte PHASE(N_MEASUREMENTS)

+
+
+

PHASE:long_name = “behavior of the glider at sea”;

+
+
+

PHASE:phase_vocabulary: “https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/phase.md”;

+
+
+

PHASE:_FillValue = 0b ;

+
+
+

PHASE:phase_calculation_method = “”;

+
+
+

PHASE:phase_calculation_method_vocabulary = “”;

+
+
+

PHASE: ancillary_variables = "PHASE_QC"

+

Highly desirable

PHASE_QC

+

Byte PHASE_QC(N_MEASUREMENTS)

+
+
+

PHASE_QC:long_name = "quality flag";

+
+
+

PHASE_QC:_FillValue = " ";

+
+
+

PHASE_QC:valid_range = 0b, 1b, 2b, 3b, 4b;

+
+
+

PHASE_QC:flag_values = 0b, 1b, 2b, 3b, 4b;

+
+
+

PHASE_QC:flag_meanings = "No QC has been applied, + Good data, + Probably good data, + Probably bad data, + Bad data" ;

+

Highly desirable

+
+

PHASE is used to derive data product (profile, trajectory profiles, gridded product) from OG1.0 data sets. It is recommended to include PHASE when possible.

+
+
+
+
+

Sensor information

+
+
+

Each geophysical variable to be recorded must be described with its sensor. Sensor information are stored in an empty and dimensionless variable filled with variable attributes.

+
+
+

Naming convention of the sensor variables

+
+

Sensor variables are named as follows: SENSOR_<sensor_type>_<sensor_serial_number>

+
+
+

Where <sensor_type> is a controlled vocabulary: see vocabulary guidelines

+
+ +++++ + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributes and requirement statusexample

SENSOR_<sensor_type>_ +<sensor_serial_number>

+

string SENSOR_<sensor_type>_<sensor_serial_number>

+
+
+

attributes:

+
+
+

sensor_type_vocabulary: “” - mandatory

+
+
+

long_name: “” - mandatory

+
+
+

sensor_model: “” - mandatory

+
+
+

sensor_model_vocabulary: “” - mandatory

+
+
+

sensor_maker: “” - highly desirable

+
+
+

sensor_maker_vocabulary: “” - highly desirable

+
+
+

sensor_serial_number: “” - highly desirable

+
+
+

sensor_calibration_date: “” - highly desirable - Format iso8601 ("YYYY-MM-DD")

+

SENSOR_CTD_206523

+

attributes:

+

sensor_type_vocabulary: "https://vocab.nerc.ac.uk/collection/L05/current/130”

+

long_name: “RBR Legato3 CTD”

+

sensor_model: “RBR Legato3 CTD”

+

sensor_model_vocabulary: “https://vocab.nerc.ac.uk/collection/L22/current/TOOL1745”

+

sensor_maker: “RBR”

+

sensor_maker_vocabulary: “https://vocab.nerc.ac.uk/collection/L35/current/MAN0049”

+

sensor_serial_number: “206523”

+

sensor_calibration_date: “2021-03-01”

+
+
+
+
+

Geophysical variables

+
+
+

Geophysical variables are measurements of a physical phenomenon (or an intermediate variable needed to measure a physical phenomenon); It is provided directly by a sensor (in sensor counts or in physical units) or computed (derived) from other parameters (i.e. intermediate parameters).

+
+
+

The fill value should have the same data type as the variable and be outside the range of possible data values.

+
+ ++++++ + + + + + + + + + + + + + + + + + + + + + + +
VARIABLE NAMEvariable attributesrequirement statusexample

<PARAM>

+

float <PARAM>(N_MEASUREMENT);

+
+
+

<PARAM>:long_name = "<X>"; <PARAM>:standard_name = "<X>";

+
+
+

<PARAM>:vocabulary = "";

+
+
+

<PARAM>:_FillValue = <X>; Note: The fill value should have the same data type as the variable and be outside the range of possible data values.

+
+
+

<PARAM>:units = "<X>";

+
+
+

<PARAM>:ancillary_variables = "<PARAM>_QC";

+
+
+

<PARAM>:coordinates = "LATITUDE, LONGITUDE, DEPTH, TIME"

+
+
+

<PARAM>:sensor = "SENSOR_<sensor_type>_<sensor_serial_number>"

+
+

mandatory

+
+
+

<PARAM> contains the values of a parameter listed in the control vocabulary related to OceanGliders parameters.

+
+
+

<X>: these fields are specified in the control vocabularies.

+

CNDC(N_MEASUREMENT);

+

attributes:

+

long_name = "Electrical conductivity of the water body by CTD"

+

standard_name = "<X>";

+

vocabulary = "https://vocab.nerc.ac.uk/collection/OG1/current/CNDC/";

+

_FillValue = NaNf

+

units = "mS cm-1"

+

ancillary_variables = "CNDC_QC";

+

coordinates = "LATITUDE, LONGITUDE, DEPTH, TIME"

+

sensor = "SENSOR_CTD_206523"

<PARAM>_QC

+

Byte <PARAM>_QC(N_MEASUREMENT); <PARAM>_QC:long_name = "quality flag";

+
+
+

<PARAM>_QC:_FillValue = " ";

+
+
+

<PARAM>_QC:valid_range = 0b, 1b, 2b, 3b, 4b;

+
+
+

<PARAM>_QC:flag_values = 0b, 1b, 2b, 3b, 4b;

+
+
+

<PARAM>_QC:flag_meanings = "No QC has been applied, + Good data, + Probably good data, + Probably bad data, + Bad data" ;

+
+
+

<PARAM>_QC:RTQC_methodology = “”;

+
+
+

<PARAM>_QC:RTQC_methodology_vocabulary = “”;

+
+
+

<PARAM>_QC:RTQC_methodology_doi = “”;

+

higly desirable

+
+
+
+

Best practices

+
+
+

Methodologies used to produce files meeting the OG format should be published in the IODE Ocean Best Practice (OBP) repository (https://repository.oceanbestpractices.org/) under the community “OceanGliders” and the collection “data management”. The following methodologies are covered, among others:

+
+
+
    +
  • +

    Interpolation

    +
    • +
  • +

    PHASE computation

    +
    • +
  • +

    RTQC

    +
    • +
+
+
+

Methodologies should describe the computation methods used (typically by Data Assembly Centers) to produce the data set. Ocean Best Practices are assigned a DOI and should be tagged as "OceanGliders" practices by the submitter. Additionally, OBP endorsed by the OceanGliders data management task team will be marked as such.

+
+
+
+
+

Evolution process, the inclusion of new variables.

+
+
+

Management of the evolution of the format will be organized by the OceanGliders data management team.

+
+
+
+
+ + + + \ No newline at end of file diff --git a/history.adoc b/history.adoc deleted file mode 100644 index 3031fc56..00000000 --- a/history.adoc +++ /dev/null @@ -1,29 +0,0 @@ -History of format evolution process - - -PR #103: Sensors as groups - -Proposed by: @castelao - -Approved on 2022-09-12 by: @callumrollo, @vturpin, @JuangaSocib, @emmerbodc, @glidermann, and @justinbuck. - -notes: -- @JuangaSocib had proposed before alternative solutions (#45 & #69), and later agreed with #103 . -- @emmerbodc and @vturpin did intensive and careful review providing a lot of improvements. - - -//// -* [[History]] -//// -== History - -* _Drafted: Victor Turpin – 13/12/2019__ -* _Edited: Daniel Hayes -18/12/2019_ -* _Reviewed: data format harmonization working group – 07/05/2020_ -* _Reviewed: Victor Turpin – 17/11/2020_ -* _Edited: Justin Buck/Emma Slater – 26/11/2020_ -* _Edited: Thierry Carval – 17/03/2021_ -* _Edited: Emma Slater – 24/08/2022_ -* _Reviewed: data format harmonization working group – 24/04/2023_ -* _Finalized and proposed: data format harmonization group – _ - diff --git a/history.html b/history.html new file mode 100644 index 00000000..bac5b96d --- /dev/null +++ b/history.html @@ -0,0 +1,501 @@ + + + + + + + +History + + + + + +
+
+

History of format evolution process

+
+
+

PR #103: Sensors as groups

+
+
+

Proposed by: @castelao

+
+
+

Approved on 2022-09-12 by: @callumrollo, @vturpin, @JuangaSocib, @emmerbodc, @glidermann, and @justinbuck.

+
+
+

notes: +- @JuangaSocib had proposed before alternative solutions (#45 & #69), and later agreed with #103 . +- @emmerbodc and @vturpin did intensive and careful review providing a lot of improvements.

+
+
+

History

+
+
+
    +
  • +

    Drafted: Victor Turpin – 13/12/2019_

    +
    • +
  • +

    Edited: Daniel Hayes -18/12/2019

    +
    • +
  • +

    Reviewed: data format harmonization working group – 07/05/2020

    +
    • +
  • +

    Reviewed: Victor Turpin – 17/11/2020

    +
    • +
  • +

    Edited: Justin Buck/Emma Slater – 26/11/2020

    +
    • +
  • +

    Edited: Thierry Carval – 17/03/2021

    +
    • +
  • +

    Edited: Emma Slater – 24/08/2022

    +
    • +
  • +

    Reviewed: data format harmonization working group – 24/04/2023

    +
    • +
  • +

    _Finalized and proposed: data format harmonization group – _

    +
    • +
+
+
+
+
+ + + \ No newline at end of file diff --git a/src/OG_Vocabulary.adoc b/src/OG_Vocabulary.adoc deleted file mode 100644 index c7fa49e1..00000000 --- a/src/OG_Vocabulary.adoc +++ /dev/null @@ -1,146 +0,0 @@ -[#anchor]####OG1.0 – Control vocabularies - -*This document describes the OceanGliders requirements on global -attributes and variable attributes. This is a first draft that needs -edition from the data management team.* - -_Drafted: Victor Turpin – 27/04/2020_ - -_Complemented: Victor Turpin - 26/08/2021_ - -_Reviewed:_ - -_Draft:_ - -[#anchor-1]####Overview - -Control vocabularies contribute to standardizing the information -provided by the glider community in the OG1.0 format. It is part of the -data management strategy to implement the FAIR principles. - -The following element of OG1.0 falls under the control vocabulary procedure. -The aim is to manage the content of key elements of the format (variable -and attribute), to build interoperability within the data providers and -across networks. It is also required to implement part of the FAIR -principles. - -Each element of each collection listed below is agreed by the -OceanGliders data management team. It is associated with a “short_name”, -a “long_name”, a definition, and an uri (unique resource identifier). -The host and manager of each collection are identified in the table below. - -[cols=",,,,",] -|=== -|*Metadata field* |*Vocabulary exists* |*Link to vocabulary* |*host* -|*Possible governance* - -|link:#_gzm334qf15ax[_platform_] |yes -|http://vocab.nerc.ac.uk/collection/L06/current/25/[_http://vocab.nerc.ac.uk/collection/L06/current/25/_] -|NVS |SeaVox - -|link:#_wcgz3tnlm891[_site_] |No | |NVS |OceanOPS - -|link:#_k5037fhkro59[_contributors_role_] |No | |NVS |OceanGliders - -|link:#_6mt06dbkes2l[_agencies_role_] |No | |NVS |OceanGliders - -|link:#_2fcny0wzutbl[_agencies_id_] |Yes -|https://edmo.seadatanet.org/[_https://edmo.seadatanet.org/_] |Maris -|SeaDataNet - -|link:#_yq785e1xz75v[_rtqc_method_] |No | |? |OceanGliders - -|link:#_yyy0h0t0nabp[_phase_calculation_method_] |No | |? |OceanGliders - -|link:#_a9i45kmkxsz[_platform_type_] |Yes -|http://vocab.nerc.ac.uk/collection/L06/current/27/[_http://vocab.nerc.ac.uk/collection/L06/current/27/_] -|NVS |OceanGliders - -|link:#_6apefww83azg[_platform_model_] |Yes -|http://vocab.nerc.ac.uk/collection/B76/current/[_http://vocab.nerc.ac.uk/collection/B76/current/_] -|NVS |OceanGliders - -|link:#_dnf968hwgv87[_ICES_code_] |Yes -|https://ocean.ices.dk/codes/ShipCodes.aspx[_https://ocean.ices.dk/codes/ShipCodes.aspx_] -|ICES, mirrored in NVS C17) |ICES - -|link:#_rswzmp9psmxc[_platform_maker_] |Yes -|http://vocab.nerc.ac.uk/collection/B75/current/[_http://vocab.nerc.ac.uk/collection/B75/current/_] -|NVS |OceanGliders - -|link:#_no2swd2b130[_battery_type_] |No | |NVS |OceanGliders - -|link:#_2u578u1wu5ow[_telecom_type_] |No | |NVS |OceanGliders - -|link:#_xvte5wz9feo1[_tracking_system_] |No | |NVS |OceanGliders - -|link:#_ma03i4ov3nmu[_sensor_model_] |Yes -|http://vocab.nerc.ac.uk/collection/L22/current/[_http://vocab.nerc.ac.uk/collection/L22/current/_] -|NVS |OceanGliders - -|link:#_qobrmr3dp3h[_data_mode_] |No | |NVS |OceanGliders - -|link:#_sx0ncoagdcvt[_phase_] |No | |NVS |OceanGliders - -|link:#_jvucaj3xuuyd[_variable names_] |Yes -|http://vocab.nerc.ac.uk/collection/OG1/current/[_http://vocab.nerc.ac.uk/collection/OG1/current/_] -|NVS |OceanGliders -|=== - -[#anchor-2]####Management of the evolution of OG1.0 controlled -vocabularies. - -The data management board of OceanGliders will maintain its reference -table autonomously. BODC will complement OG1.0 vocabulary and map it to -master lists that cover more than the network's needs. - -[#anchor-3]####Collections - -[#anchor-4]####platform - -[cols=",,,,",] -|=== -|Url |Short_name |Long_name |Definition |Status - -|http://vocab.nerc.ac.uk/collection/L06/current/25/[_http://vocab.nerc.ac.uk/collection/L06/current/25/_] -|Autonomous underwater vehicle |Autonomous underwater vehicle |A -free-roving platform operating in the water column with propulsion but -no human operator on board. |approved -|=== - -_Master list:_ __ -__http://vocab.nerc.ac.uk/collection/L06/current/[_http://vocab.nerc.ac.uk/collection/L06/current/_] - -_Host_: NERC Vocabulary Server - -_Management_: OceanGliders - -_Note_: “platform” does not refer to a collection but a single value for -all ocean gliders. - -[#anchor-5]####Sites - -Sites listed here are under discussion within the data management group. -This vocabulary collection is not approved yet. The definition of sites -needs review and agreement. - -[cols=",,,,",] -|=== -|Url |Short_name |Long_name |Definition |Status - -| |53° North |53° North |LINESTRING (-52.00 53.00,-49.90 53.00) | - -| |A05 |Atlantic Ocean 5 |LINESTRING (-14.21 27.62, -13.4 27.92, -15.30 -28.00) | - -| |Agulhas, GINA |Gliders in the _Agulhas_ Experiment |POLYGON ((26.50 --34.50, 27.50 -34.50, 33.00 -29.500, 32.700 -27.80, 32.41 -28.54, 31.15 --29.80, 30.42 -30.96, 28.46 -32.811, 27.242 -33.574, 26.500 -34.500)) | - -| |Alter Eco |Alternative framework to assess marine Ecosystem -functioning in the shelf seas |LINESTRING (2.1 55.2, 2.12 56.5) | - -| |AntarcticPeninsula |Antarctic Peninsula |LINESTRING (-65 -64.35, -67 --63.75) | - -| |BaffinDavis |Baffin Davis |LINESTRING (-60.43 66.72, -56.8 67) diff --git a/src/OG_Vocabulary.html b/src/OG_Vocabulary.html new file mode 100644 index 00000000..6a009f78 --- /dev/null +++ b/src/OG_Vocabulary.html @@ -0,0 +1,757 @@ + + + + + + + +Untitled + + + + + +
+
+

##OG1.0 – Control vocabularies

+
+
+

This document describes the OceanGliders requirements on global +attributes and variable attributes. This is a first draft that needs +edition from the data management team.

+
+
+

Drafted: Victor Turpin – 27/04/2020

+
+
+

Complemented: Victor Turpin - 26/08/2021

+
+
+

Reviewed:

+
+
+

Draft:

+
+
+

##Overview

+
+
+

Control vocabularies contribute to standardizing the information +provided by the glider community in the OG1.0 format. It is part of the +data management strategy to implement the FAIR principles.

+
+
+

The following element of OG1.0 falls under the control vocabulary procedure. +The aim is to manage the content of key elements of the format (variable +and attribute), to build interoperability within the data providers and +across networks. It is also required to implement part of the FAIR +principles.

+
+
+

Each element of each collection listed below is agreed by the +OceanGliders data management team. It is associated with a “short_name”, +a “long_name”, a definition, and an uri (unique resource identifier). +The host and manager of each collection are identified in the table below.

+
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

Metadata field

Vocabulary exists

Link to vocabulary

host

Possible governance

_platform

yes

http://vocab.nerc.ac.uk/collection/L06/current/25/

NVS

SeaVox

_site

No

NVS

OceanOPS

_contributors_role

No

NVS

OceanGliders

_agencies_role

No

NVS

OceanGliders

_agencies_id

Yes

https://edmo.seadatanet.org/

Maris

SeaDataNet

_rtqc_method

No

?

OceanGliders

_phase_calculation_method

No

?

OceanGliders

_platform_type

Yes

http://vocab.nerc.ac.uk/collection/L06/current/27/

NVS

OceanGliders

_platform_model

Yes

http://vocab.nerc.ac.uk/collection/B76/current/

NVS

OceanGliders

_ICES_code

Yes

https://ocean.ices.dk/codes/ShipCodes.aspx

ICES, mirrored in NVS C17)

ICES

_platform_maker

Yes

http://vocab.nerc.ac.uk/collection/B75/current/

NVS

OceanGliders

_battery_type

No

NVS

OceanGliders

_telecom_type

No

NVS

OceanGliders

_tracking_system

No

NVS

OceanGliders

_sensor_model

Yes

http://vocab.nerc.ac.uk/collection/L22/current/

NVS

OceanGliders

_data_mode

No

NVS

OceanGliders

_phase

No

NVS

OceanGliders

_variable names

Yes

http://vocab.nerc.ac.uk/collection/OG1/current/

NVS

OceanGliders

+
+

##Management of the evolution of OG1.0 controlled +vocabularies.

+
+
+

The data management board of OceanGliders will maintain its reference +table autonomously. BODC will complement OG1.0 vocabulary and map it to +master lists that cover more than the network’s needs.

+
+
+

##Collections

+
+
+

##platform

+
+ +++++++ + + + + + + + + + + + + + + + + + + +
UrlShort_nameLong_nameDefinitionStatus

http://vocab.nerc.ac.uk/collection/L06/current/25/

Autonomous underwater vehicle

Autonomous underwater vehicle

A +free-roving platform operating in the water column with propulsion but +no human operator on board.

approved

+
+

Master list: +http://vocab.nerc.ac.uk/collection/L06/current/

+
+
+

Host: NERC Vocabulary Server

+
+
+

Management: OceanGliders

+
+
+

Note: “platform” does not refer to a collection but a single value for +all ocean gliders.

+
+
+

##Sites

+
+
+

Sites listed here are under discussion within the data management group. +This vocabulary collection is not approved yet. The definition of sites +needs review and agreement.

+
+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
UrlShort_nameLong_nameDefinitionStatus

53° North

53° North

LINESTRING (-52.00 53.00,-49.90 53.00)

A05

Atlantic Ocean 5

LINESTRING (-14.21 27.62, -13.4 27.92, -15.30 +28.00)

Agulhas, GINA

Gliders in the Agulhas Experiment

POLYGON 26.50 -34.50, 27.50 -34.50, 33.00 -29.500, 32.700 -27.80, 32.41 -28.54, 31.15 -29.80, 30.42 -30.96, 28.46 -32.811, 27.242 -33.574, 26.500 -34.500

Alter Eco

Alternative framework to assess marine Ecosystem +functioning in the shelf seas

LINESTRING (2.1 55.2, 2.12 56.5)

AntarcticPeninsula

Antarctic Peninsula

LINESTRING (-65 -64.35, -67 +-63.75)

+
+ + + \ No newline at end of file diff --git a/vocabularyCollection/tableOfControlledVocab.adoc b/vocabularyCollection/tableOfControlledVocab.adoc deleted file mode 100644 index d3c4c241..00000000 --- a/vocabularyCollection/tableOfControlledVocab.adoc +++ /dev/null @@ -1,189 +0,0 @@ -[cols=",",options="header",] -|=========================================================================================== -|image:../figures/image1.png[image,width=164,height=144] a| -OceanGliders 1.0 format - Vocabulary Collections + - -Navigation: + - -https://github.com/OceanGlidersCommunity/OG-format-user-manual[Github repository] + -https://oceangliderscommunity.github.io/OG-format-user-manual/OG_Format.html[Terms of reference] + -https://oceangliderscommunity.github.io/OG-format-user-manual/vocabularyCollection/tableOfControlledVocab.html[Vocabulary collections] + - -|=========================================================================================== -//// -* [[Guidelines for controlled vocabularies]] -//// -== Controlled vocabulary -A controlled vocabulary is a curated list of terms that have been pre-defined and approved for use within a specific context, such as data management. This type of vocabulary serves as a standardized set of terms used to monitor content consistently, ensuring uniformity, precision and analysis. - -== Use controlled vocabulary -Each OG1.0 controlled vocabulary (list of terms) is referenced in this document. -To find the appropriate term, click on the link to the list and find the term that suits your needs. - -Each attribute or variable controlled by a vocabulary is associated with a attribute called **_vocabulary* in the format. This attribute refers to the uri of the term. - -For instance global attribute *platform* is a controlled vocabulary. In the format description it is followed by the global attribute *platform_vocabulary*. - -In this case: - -* platform = "sub-surface gliders" ; -* platform_vocabulary = "https://vocab.nerc.ac.uk/collection/L06/current/27/" ; - -== Vocabulary Collections -The series of concepts of the https://github.com/OceanGlidersCommunity/OG1.0-user-manual[OG1.0 format] are controlled by a set of vocabulary collections managed by the OceanGliders data management team and other governance bodies. + -These concepts are listed in the table below. Each concept is linked to its collection of vocabularies. Each collection has a status attribute. + -[square] -* The *pending* entries are being discussed by the community and are not yet supported by the OG1.0 format. + -* The *validated* entries have been validated by the vocabulary working group and can be used in the OG1.0 format. + -* The *published* entries have been published by the host when it exists. + - -Vocabulary collections that are not governed by OceanGliders do not follow the *status* convention described above. - -=== "host" and "governance" of the vocabulary collection - -**host** : The host is the entity that is serving the *published* vocabulary collections and enable machine to machine communication. + -**governance** : Governance refers to the entity in charge of the maintenance, evolution and publication of the vocabulary collection. - -=== Requesting a new term -To request a new term for an existing vocabularly collection please create an new issue in the OceanGliders repository including the label 'vocab'. - -New terms may also be requested via the 'Request new term' URLs in the table below. Please clearly indicate in the ticket 'for approval by OceanGliders vocabularly working group' and include as much detail as possible. - -=== Requesting a new collection -If you are unsure where a new term fits and believe a new collection is needed, please create an issue in the OceanGliders repository clearly including the title 'vocab'. - - -=== Validation process - -A working group for controlled vocabulary collections will review the requests regularly to approve new terms. Simple terms adding to existing collections will have a quick turnaround. -Requests for new vocabularly collections will take longer to review and approve. - - -=== Table of controlled vocabularies for "mandatory" metadata in the OG 1.0 format - -|=== -|OceanGliders reference name | Collection URL or Scheme URL | Examples | Request new terms | Governance - - | platform | https://vocab.nerc.ac.uk/collection/L06/current/[L06 - SeaVoX Platform Categories] | | https://github.com/nvs-vocabs/L06/issues | SeaDataNet and MarineXML Vocabulary Content Governance Group - | contributors_role | https://vocab.nerc.ac.uk/search_nvs/C86/[C86 - SeaDataNet contact and security access roles] | https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/contributors_role.md[contributors_role] | | SeaDataNet - | institution_role* | *pending* | https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/agencies_role.md[institution_role] | | SeaDataNet - | institution_id | https://edmo.seadatanet.org/[EDMO] | | | SeaDataNet - | rtqc_method** | *pending*| https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/rtqc_method.md[Real Time Quality Control methods] | |OceanGliders - | platform_model | https://vocab.nerc.ac.uk/search_nvs/B76/[B76 - BODC Platform Models] | | https://github.com/nvs-vocabs/B76/issues | British Oceanographic Data Centre - | sensor type| http://vocab.nerc.ac.uk/collection/L05/current/[L05 - SeaDataNet device categories] | | https://github.com/nvs-vocabs/L05/issues | SeaDataNet - | sensor_model | https://vocab.nerc.ac.uk/search_nvs/L22/[L22 - SeaVoX Device Catalogue] and subset https://vocabdev.nerc.ac.uk/scheme/GLIDER_SENSORS/current/[GLIDER_SENSORS] | | https://github.com/nvs-vocabs/L22/issues | OceanGliders - | data_mode** | *pending* | https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/main/vocabularyCollection/data_mode.md[data_mode] | | OceanGliders - | parameter | https://vocab.nerc.ac.uk/search_nvs/OG1/[OG1 - OceanGliders Parameter Usage Vocabulary] | | https://github.com/nvs-vocabs/OG1/issues | OceanGliders - - -|=== -*only operating institution is mandatory -**still in development - - - -=== Table of controlled vocabularies for "highly desirable" or "suggested" metadata in the OG 1.0 format - -|=== -|OceanGliders reference name | Collection name | OceanGliders subset | Request new terms | Governance - - | platform_serial_number_prefix_*** | *tbd* | https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/serial_number_prefix.md[pending list] | *tbd* | OceanGliders - | program** | *tbd* | *tbd* | *tbd* | OceanOPS - | oceangliders_site | *tbd* | *tbd* | *tbd* | OceanOPS - | naming_authority | https://edmo.seadatanet.org/[EDMO code] | No subset available for this collection | *tbd* | SeaDataNet - | ICES_code | https://vocab.ices.dk/?codetypeguid=7f9a91e1-fb57-464a-8eb0-697e4b0235b5[ICES reference table] | No subset available for this collection | *tbd* | ICES - | platform_maker | http://vocab.nerc.ac.uk/collection/L35/current/[L35 - SenseOcean device developers and manufacturers] | *OceanGliders vocabulary subset tbd* https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/platform_maker.md[pending list] | *tbd* | OceanGliders - | battery_type** | *tbd* | *tbd* https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/battery_type.md[pending list] | *tbd* | OceanGliders - | telecom_type** | https://vocab.nerc.ac.uk/search_nvs/R10/[*_e.g. R10 - Argo transmission systems_*] | *tbd* https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/telecom_type.md[pending list] | *tbd* | OceanGliders - | tracking_system** | *tbd* | *tbd* https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/tracking_system.md[pending list] | *tbd* | OceanGliders - | phase | *tbd* | *tbd* https://github.com/OceanGlidersCommunity/OG-format-user-manual/blob/vturpin-patch-3-VocabularyCollectionSection/vocabularyCollection/phase.md[pending list] | *tbd* | OceanGliders - | QC_flag | IODE Primary Level quality flags | https://vocab.nerc.ac.uk/search_nvs/L34/ | n/a | IODE - - - -|=== - -**still in development - - - -===Examples -Examles of how vocabularies are implemented in the OG file are in the og_format_examples. - - - -## Global attributes - - -|=== -| Global attribute | Exemples - -| platform | :platform = "sub-surface gliders"; -| platform_vocabulary | :platform_vocabulary = https://vocab.nerc.ac.uk/collection/L06/current/27/; -| institution | :institution = "OGS"; -| institution_vocabulary | :institution_vocabulary = "https://edmo.seadatanet.org/report/120"; -*_HERE WE NEED TO ADD institution_vocabulary IN THE FORMAT_* -| program | :program = "OGS glider program" ; -| program_vocabulary | :program_vocabulary = ; -*_HERE WE NEED TO ADD program_vocabulary IN THE FORMAT_* -| oceangliders_site | :oceangliders_site = "CONVEX"; -| oceangliders_site_vocabulary | :oceangliders_site_vocabulary = ; -*_HERE WE NEED TO ADD oceangliders_site_vocabulary IN THE FORMAT_* -| contributor | :contributor = "Elena Mauri,Silvina Logarzo" -| contributor_role | :contributor_role = "principal investigator,Data scientist"; -| contributor_role_vocabulary | :contributor_role_vocabulary = "http://vocab.nerc.ac.uk/collection/W08/current/CONT0004/,http://vocab.nerc.ac.uk/collection/W08/current/CONT0006/"; -| agency | :agency = "OGS,CNR,Coriolis"; -| agency_vocabulary | :agency_vocabulary = "https://edmo.seadatanet.org/report/120,https://edmo.seadatanet.org/report/227,https://edmo.seadatanet.org/report/227"; -*_HERE WE NEED TO ADD agency_vocabulary IN THE FORMAT_* -| agency_role | :agency = "operating agency,funding agency,data assembly center"; -| agency_role_vocabulary | :agency_role_vocabulary = ",,"; - -|=== - -## Variable Attributes -### Platform Information -*_Which option do we follow here?_* -|=== -| Variable | Variable attribute | exemplar - -| PLATFORM_MODEL | - -:long_name = "model of the glider"; - -:platform_model_vocabulary = "https://vocab.nerc.ac.uk/collection/B76/current/B7600002"; - - - -:long_name = "model of the glider"; - -:platform_model_vocabulary = "https://vocab.nerc.ac.uk/collection/B76/current/B7600001/"; | -Kongsberg Maritime Seaglider M1 glider - -Teledyne Webb Research Slocum G2 glider - -| *OR* | | - -| ICES_CODE | -:long_name = "Trieste_1"; - -:ices_code_vocabulary = "https://vocab.ices.dk/?CodeID=230740"; | - - - -| PLATFORM_MAKER | -:long_name = "Kongsberg Maritime AS"; - -:platform_maker_vocabulary = "https://vocab.nerc.ac.uk/collection/B75/current/ORG00360/"; - - - -:long_name = "Teledyne Webb Research"; - -:platform_maker_vocabulary = "https://vocab.nerc.ac.uk/collection/B75/current/ORG01077/"; | -|=== - - -https://github.com/OceanGlidersCommunity/OG-format-user-manual/edit/emma/Vocabs/src/vocabularyCollection/vocabulary_guidance.md[Check Emma's branch here] - - - diff --git a/vocabularyCollection/tableOfControlledVocab.html b/vocabularyCollection/tableOfControlledVocab.html new file mode 100644 index 00000000..c430baed --- /dev/null +++ b/vocabularyCollection/tableOfControlledVocab.html @@ -0,0 +1,901 @@ + + + + + + + +Controlled vocabulary + + + + + +
+ ++++ + + + + + + +
imageOceanGliders 1.0 format - Vocabulary Collections
+ +Navigation:
+ +Github repository
+Terms of reference
+Vocabulary collections
+
+

Controlled vocabulary

+
+
+

A controlled vocabulary is a curated list of terms that have been pre-defined and approved for use within a specific context, such as data management. This type of vocabulary serves as a standardized set of terms used to monitor content consistently, ensuring uniformity, precision and analysis.

+
+
+
+
+

Use controlled vocabulary

+
+
+

Each OG1.0 controlled vocabulary (list of terms) is referenced in this document. +To find the appropriate term, click on the link to the list and find the term that suits your needs.

+
+
+

Each attribute or variable controlled by a vocabulary is associated with a attribute called *_vocabulary in the format. This attribute refers to the uri of the term.

+
+
+

For instance global attribute platform is a controlled vocabulary. In the format description it is followed by the global attribute platform_vocabulary.

+
+
+

In this case:

+
+
+
    +
  • +

    platform = "sub-surface gliders" ;

    +
    • +
  • +

    platform_vocabulary = "https://vocab.nerc.ac.uk/collection/L06/current/27/" ;

    +
    • +
+
+
+
+
+

Vocabulary Collections

+
+
+

The series of concepts of the OG1.0 format are controlled by a set of vocabulary collections managed by the OceanGliders data management team and other governance bodies.
+These concepts are listed in the table below. Each concept is linked to its collection of vocabularies. Each collection has a status attribute.

+
+
+
    +
  • +

    The pending entries are being discussed by the community and are not yet supported by the OG1.0 format.

    +
    • +
  • +

    The validated entries have been validated by the vocabulary working group and can be used in the OG1.0 format.

    +
    • +
  • +

    The published entries have been published by the host when it exists.

    +
    • +
+
+
+

Vocabulary collections that are not governed by OceanGliders do not follow the status convention described above.

+
+
+

"host" and "governance" of the vocabulary collection

+
+

host : The host is the entity that is serving the published vocabulary collections and enable machine to machine communication.
+governance : Governance refers to the entity in charge of the maintenance, evolution and publication of the vocabulary collection.

+
+
+
+

Requesting a new term

+
+

To request a new term for an existing vocabularly collection please create an new issue in the OceanGliders repository including the label 'vocab'.

+
+
+

New terms may also be requested via the 'Request new term' URLs in the table below. Please clearly indicate in the ticket 'for approval by OceanGliders vocabularly working group' and include as much detail as possible.

+
+
+
+

Requesting a new collection

+
+

If you are unsure where a new term fits and believe a new collection is needed, please create an issue in the OceanGliders repository clearly including the title 'vocab'.

+
+
+
+

Validation process

+
+

A working group for controlled vocabulary collections will review the requests regularly to approve new terms. Simple terms adding to existing collections will have a quick turnaround. +Requests for new vocabularly collections will take longer to review and approve.

+
+
+
+

Table of controlled vocabularies for "mandatory" metadata in the OG 1.0 format

+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OceanGliders reference nameCollection URL or Scheme URLExamplesRequest new termsGovernance

platform

L06 - SeaVoX Platform Categories

https://github.com/nvs-vocabs/L06/issues

SeaDataNet and MarineXML Vocabulary Content Governance Group

contributors_role

C86 - SeaDataNet contact and security access roles

contributors_role

SeaDataNet

institution_role*

pending

institution_role

SeaDataNet

institution_id

EDMO

SeaDataNet

rtqc_method**

pending

Real Time Quality Control methods

OceanGliders

platform_model

B76 - BODC Platform Models

https://github.com/nvs-vocabs/B76/issues

British Oceanographic Data Centre

sensor type

L05 - SeaDataNet device categories

https://github.com/nvs-vocabs/L05/issues

SeaDataNet

sensor_model

L22 - SeaVoX Device Catalogue and subset GLIDER_SENSORS

https://github.com/nvs-vocabs/L22/issues

OceanGliders

data_mode**

pending

data_mode

OceanGliders

parameter

OG1 - OceanGliders Parameter Usage Vocabulary

https://github.com/nvs-vocabs/OG1/issues

OceanGliders

+
+

*only operating institution is mandatory +**still in development

+
+
+
+

Table of controlled vocabularies for "highly desirable" or "suggested" metadata in the OG 1.0 format

+ +++++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OceanGliders reference nameCollection nameOceanGliders subsetRequest new termsGovernance

platform_serial_number_prefix_***

tbd

pending list

tbd

OceanGliders

program**

tbd

tbd

tbd

OceanOPS

oceangliders_site

tbd

tbd

tbd

OceanOPS

naming_authority

EDMO code

No subset available for this collection

tbd

SeaDataNet

ICES_code

ICES reference table

No subset available for this collection

tbd

ICES

platform_maker

L35 - SenseOcean device developers and manufacturers

OceanGliders vocabulary subset tbd pending list

tbd

OceanGliders

battery_type**

tbd

tbd pending list

tbd

OceanGliders

telecom_type**

e.g. R10 - Argo transmission systems

tbd pending list

tbd

OceanGliders

tracking_system**

tbd

tbd pending list

tbd

OceanGliders

phase

tbd

tbd pending list

tbd

OceanGliders

QC_flag

IODE Primary Level quality flags

https://vocab.nerc.ac.uk/search_nvs/L34/

n/a

IODE

+
+

**still in development

+
+
+

===Examples +Examles of how vocabularies are implemented in the OG file are in the og_format_examples.

+
+
+
+
+
+

Global attributes

+
+ ++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Global attributeExemples

platform

:platform = "sub-surface gliders";

platform_vocabulary

:platform_vocabulary = https://vocab.nerc.ac.uk/collection/L06/current/27/;

institution

:institution = "OGS";

institution_vocabulary

:institution_vocabulary = "https://edmo.seadatanet.org/report/120"; +HERE WE NEED TO ADD institution_vocabulary IN THE FORMAT

program

:program = "OGS glider program" ;

program_vocabulary

:program_vocabulary = ; +HERE WE NEED TO ADD program_vocabulary IN THE FORMAT

oceangliders_site

:oceangliders_site = "CONVEX";

oceangliders_site_vocabulary

:oceangliders_site_vocabulary = ; +HERE WE NEED TO ADD oceangliders_site_vocabulary IN THE FORMAT

contributor

:contributor = "Elena Mauri,Silvina Logarzo"

contributor_role

:contributor_role = "principal investigator,Data scientist";

contributor_role_vocabulary

:contributor_role_vocabulary = "http://vocab.nerc.ac.uk/collection/W08/current/CONT0004/,http://vocab.nerc.ac.uk/collection/W08/current/CONT0006/";

agency

:agency = "OGS,CNR,Coriolis";

agency_vocabulary

:agency_vocabulary = "https://edmo.seadatanet.org/report/120,https://edmo.seadatanet.org/report/227,https://edmo.seadatanet.org/report/227"; +HERE WE NEED TO ADD agency_vocabulary IN THE FORMAT

agency_role

:agency = "operating agency,funding agency,data assembly center";

agency_role_vocabulary

:agency_role_vocabulary = ",,";

+
+
+
+

Variable Attributes

+
+
+

Platform Information

+
+

Which option do we follow here?

+
+ +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
VariableVariable attributeexemplar

PLATFORM_MODEL

:long_name = "model of the glider";

+

:platform_model_vocabulary = "https://vocab.nerc.ac.uk/collection/B76/current/B7600002";

+

:long_name = "model of the glider";

+

:platform_model_vocabulary = "https://vocab.nerc.ac.uk/collection/B76/current/B7600001/";

Kongsberg Maritime Seaglider M1 glider

+

Teledyne Webb Research Slocum G2 glider

OR

ICES_CODE

:long_name = "Trieste_1";

+

:ices_code_vocabulary = "https://vocab.ices.dk/?CodeID=230740";

PLATFORM_MAKER

:long_name = "Kongsberg Maritime AS";

+

:platform_maker_vocabulary = "https://vocab.nerc.ac.uk/collection/B75/current/ORG00360/";

+

:long_name = "Teledyne Webb Research";

+

:platform_maker_vocabulary = "https://vocab.nerc.ac.uk/collection/B75/current/ORG01077/";

+
+

Check Emma’s branch here

+
+
+
+
+
+ + + \ No newline at end of file