diff --git a/README.md b/README.md index 9535db27..ed1194d6 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # cf-convention.github.io -This repo contains the source files for CF Conventions web site: -[http://cfconventions.org]. \ No newline at end of file +This repo contains the source files for [the CF Conventions web site](cf-website). + +[cf-website]: http://cfconventions.org/ diff --git a/about-trac.md b/about-trac.md index cf8bd333..1cd7b4d1 100755 --- a/about-trac.md +++ b/about-trac.md @@ -5,35 +5,45 @@ title: Governance ## CF Trac Website -This page is an archive copy, kept only for historical interest, of information about the former [CF Metadata Trac](Data/trac.html) site, which itself also is now kept only as an archive. The Trac site was used until July 2018 for discussion of enhancements to the CF convention. New proposals are now [discussed in GitHub](discussion.html). The following information should be read in the past tense. - +This page is an archive copy, kept only for historical interest, of information about the former [CF Metadata Trac](Data/trac.html) site, which itself also is now kept only as an archive. +The Trac site was used until July 2018 for discussion of enhancements to the CF convention. +New proposals are now [discussed in GitHub](discussion.html). +The following information should be read in the past tense. ## How the Ticket System Works -A Trac ticket is more or less equivalent to a discussion thread. The ticket system is aligned with a series of email lists corresponding to various thrusts of CF evolution (represented as "components" in Trac). The biggest change in the new system is that individuals no longer send email directly to the mailing list. Instead, the Trac system will automatically send email to the appropriate list(s) each time you create or modify a ticket. The mailing lists are arranged in such a way that you can choose to subscribe to only the discussions of interest to you - or you can subscribe to the parent list and receive an email for every single message post. +A Trac ticket is more or less equivalent to a discussion thread. +The ticket system is aligned with a series of email lists corresponding to various thrusts of CF evolution (represented as "components" in Trac). +The biggest change in the new system is that individuals no longer send email directly to the mailing list. +Instead, the Trac system will automatically send email to the appropriate list(s) each time you create or modify a ticket. +The mailing lists are arranged in such a way that you can choose to subscribe to only the discussions of interest to you - or you can subscribe to the parent list and receive an email for every single message post. In summary, you send messages using the Trac web interface and you receive messages via the mailing lists you subscribe to or by reading the messages in your web browser. - - ## Joining the Discussion -Spammers have managed to make our lives miserable, and they are getting more sophisticated. They now even have bots that create spam Trac tickets! For this reason, each person is required to have an account in Trac to create and modify tickets. Follow the steps below to get started: +Spammers have managed to make our lives miserable, and they are getting more sophisticated. +They now even have bots that create spam Trac tickets! +For this reason, each person is required to have an account in Trac to create and modify tickets. +Follow the steps below to get started: If you ARE already a member of the cf-metadata@cgd.ucar.edu mailing list: -Note: Step 1 is only required if you want to post messages. If you only want to listen in, you don't have to do anything. +Note: Step 1 is only required if you want to post messages. +If you only want to listen in, you don't have to do anything. 1. Request a Trac account by sending your first name, last name, and preferred username to: webmaster@pcmdi.llnl.gov -As a member of the cf-metadata@cgd.ucar.edu mailing list, you will automatically be subscribed to the new cf-metadata@lists.llnl.gov mailing list. At a later date, if you wish to limit email traffic to certain aspects of CF discussions, you can unsubscribe yourself from cf-metadata@lists.llnl.gov and subscribe instead to one or more of the sub-lists. +As a member of the cf-metadata@cgd.ucar.edu mailing list, you will automatically be subscribed to the new cf-metadata@lists.llnl.gov mailing list. +At a later date, if you wish to limit email traffic to certain aspects of CF discussions, you can unsubscribe yourself from cf-metadata@lists.llnl.gov and subscribe instead to one or more of the sub-lists. - If you ARE NOT already a member of the cf-metadata@cgd.ucar.edu mailing list: -Note: Step 1 is only required if you want to post messages. If you only want to listen in, skip to Step 2. +Note: Step 1 is only required if you want to post messages. +If you only want to listen in, skip to Step 2. 1. Request a Trac account by sending your first name, last name, and preferred username to: webmaster@pcmdi.llnl.gov. -2. Subscribe yourself to the mailing lists you're interested in. You will automatically be subscribed to the cf-conventions and cf-standard-names mailing lists. You must independently subscribe to the working group lists. - +2. Subscribe yourself to the mailing lists you're interested in. +You will automatically be subscribed to the cf-conventions and cf-standard-names mailing lists. +You must independently subscribe to the working group lists. ## Components and Mailing Lists @@ -52,7 +62,6 @@ cf-wg-in-situ-obs | cf-wg-in-situ-obs@lists.llnl.gov | How to handle in situ obs cf-wg-discovery | cf-wg-discovery@lists.llnl.gov | How to include discovery information in CF. cf-wg-compliance | cf-wg-compliance@lists.llnl.gov | Reference implementations, CF API, CMOR, sample datasets. - ## Subscribing to the Mailing Lists To subscribe to any of the above mailing lists, send a message to majordomo@lists.llnl.gov with the following contained in the email body: @@ -76,4 +85,6 @@ where is one of the Component names (not the full mailing list name) ## Posting to the Mailing Lists -Don't send email directly to the mailing lists. Rather, use the Trac ticketing system, which will automatically send mail to the correct lists. If you accidentally reply to an email sent by Trac or send mail directly to one of the mailing lists, the message will be delivered to the mailing list maintainer, who will politely remind you to use the Trac system instead. +Don't send email directly to the mailing lists. +Rather, use the Trac ticketing system, which will automatically send mail to the correct lists. +If you accidentally reply to an email sent by Trac or send mail directly to one of the mailing lists, the message will be delivered to the mailing list maintainer, who will politely remind you to use the Trac system instead. diff --git a/constitution.md b/constitution.md index 0bafb64c..bd1d7c23 100644 --- a/constitution.md +++ b/constitution.md @@ -2,171 +2,98 @@ Original from the CF white paper of 2006, amended May 2020. -### Introduction - -The governance arrangements described in this document are intended to -organise and facilitate the work of the CF community -in developing and maintaining the CF metadata standard. -The CF community -embraces a philosophy of producing excellence by maintaining an open and -welcoming culture and an environment that promotes debate and inquiry in a -respectful, bold and intellectually rigorous fashion. This is reflected in the -community's -[Code of Conduct](https://github.com/cf-convention/cf-conventions/blob/master/CODE_OF_CONDUCT.md). Members of the community contribute -by participating in online discussions, -attending meetings, proposing changes, or taking part in any other way they -deem appropriate and useful, on a best-effort basis. - -### Constitution of the CF Governance Panel - -The panel governs the CF standard on behalf of the -user community under the auspices of the WMO/WCRP Working Group on Coupled -Modelling (WGCM). If the WGCM wishes to transfer or share responsibility for CF -with another permanent committee of an international organisation, it may -decide to do so with the agreement of both CF committees. -Any member of the CF community who is dissatisfied with or has suggestions -about the panel's governance -of CF is invited to raise their concerns with the panel or with the WGCM. - -Members of the panel will include, -but not be limited to, members of the WGCM, the -leaders, or their nominees, of organisations contributing significant resources -in support of CF, and the chairs of the CF committees on conventions and -standard names. +## Introduction + +The governance arrangements described in this document are intended to organise and facilitate the work of the CF community in developing and maintaining the CF metadata standard. +The CF community embraces a philosophy of producing excellence by maintaining an open and welcoming culture and an environment that promotes debate and inquiry in a respectful, bold and intellectually rigorous fashion. +This is reflected in the community's [Code of Conduct](code-of-conduct). +Members of the community contribute by participating in online discussions, attending meetings, proposing changes, or taking part in any other way they deem appropriate and useful, on a best-effort basis. + +## Constitution of the CF Governance Panel + +The panel governs the CF standard on behalf of the user community under the auspices of the WMO/WCRP Working Group on Coupled Modelling (WGCM). +If the WGCM wishes to transfer or share responsibility for CF with another permanent committee of an international organisation, it may decide to do so with the agreement of both CF committees. +Any member of the CF community who is dissatisfied with or has suggestions about the panel's governance of CF is invited to raise their concerns with the panel or with the WGCM. + +Members of the panel will include, but not be limited to, members of the WGCM, the leaders, or their nominees, of organisations contributing significant resources in support of CF, and the chairs of the CF committees on conventions and standard names. The panel will elect its own chair from among its members. The panel will appoint its own new members as the need arises. -Its members may serve as long as they are willing, -and may resign at any time. - -### Terms of reference of the CF Governance Panel - -The panel will be responsible for the stewardship of CF, but will not have any -special responsibility for or influence on the technical content of CF. - -The panel will ensure that its own constitution and terms of reference, those -of the CF committees, and the aims and general principles of design of the CF -standard are published. These may be altered by the panel only after -appropriate public debate and with the agreement of both CF committees. - -The panel will promote the use of CF within the community of users who make use -of or could profit from using the CF standard. - -The panel will promote and help integrate the use of CF across WCRP programmes, -the broader programmes of WCRP's sponsors (ICSU, WMO, and IOC), and other -interested communities. In particular the panel will attempt to influence -developing metadata standards of WMO and other international organisations so -that they accommodate the CF standard. +Its members may serve as long as they are willing, and may resign at any time. + +## Terms of reference of the CF Governance Panel + +The panel will be responsible for the stewardship of CF, but will not have any special responsibility for or influence on the technical content of CF. + +The panel will ensure that its own constitution and terms of reference, those of the CF committees, and the aims and general principles of design of the CF standard are published. +These may be altered by the panel only after appropriate public debate and with the agreement of both CF committees. + +The panel will promote the use of CF within the community of users who make use of or could profit from using the CF standard. + +The panel will promote and help integrate the use of CF across WCRP programmes, the broader programmes of WCRP's sponsors (ICSU, WMO, and IOC), and other interested communities. +In particular the panel will attempt to influence developing metadata standards of WMO and other international organisations so that they accommodate the CF standard. + +The panel will encourage continued support of CF by benevolent organisations and explore additional funding mechanisms if necessary. + +The panel will ensure that an annual meeting is organised for discussing issues relevant to the CF standard. + +Once every year, the panel will make a report to the WGCM on the status of CF, and must secure an assurance from the WGCM that in their judgement the present membership of the panel is suitable to meet its terms of reference. +The panel must urgently address any concerns in this regard expressed by either the WGCM or the CF community. + +The panel will appoint people who have nominated themselves or agreed to serve as members of the conventions committee and the standard names committee. +In doing so it will have regard to the expertise and interests relevant to the remit of each committee and will attempt to obtain representation of a variety of communities and a geographical spread of members. +The panel will ensure that the current membership of the two CF committees is published. + +The panel will maintain a permanent public record of debates and of any decisions it makes, except where privacy is essential. + +## Constitution of the CF committees + +Anyone with sufficient time, interest and expertise is qualified to serve as a member of the conventions committee or the standard names committee or both. +Prospective members will nominate themselves. +Members of the committees will be appointed at any time by the CF Governance Panel. +Committee members judged by the panel to have been inactive for an extended period will be asked to resign. +Members may choose to resign at any time and must retire after five years, but may be reappointed. + +Each committee will elect its own chair from among its members. +The chair may resign the office at any time and must retire after three years, but may be reelected. -The panel will encourage continued support of CF by benevolent organisations -and explore additional funding mechanisms if necessary. - -The panel will ensure that an annual meeting is organised -for discussing issues relevant to the CF standard. - -Once every year, the panel will make a report to the WGCM on the status of CF, -and must secure an assurance from the WGCM that in their judgement -the present membership of the panel is suitable to meet its terms of reference. -The panel must urgently address -any concerns in this regard expressed by either the WGCM or the CF community. +Each committee will have authority and responsibility for the development of the aspects of the CF standard within its remit, as detailed in its terms of reference, having regard to the aims and general principles of design of CF. +It will discharge its responsibility by overseeing and contributing to public debate on how the standard should be expanded or altered, and by deciding after debate whether and what changes will be made. -The panel will appoint people who have nominated themselves or agreed to serve -as members of the conventions committee and the standard names committee. In -doing so it will have regard to the expertise and interests relevant to the -remit of each committee and will attempt to obtain representation of a variety -of communities and a geographical spread of members. -The panel will ensure that the current membership of -the two CF committees is published. +Each committee will be assisted in its responsibility by a permanent and funded member of staff, who will be appointed in a manner decided by the CF Governance Panel, and who will be an ex-officio member and secretary of the committee. +The manager of CF conventions will be the secretary of the conventions committee and the manager of CF standard names will be the secretary of the standard names committee. +The committee will propose priorities for work by its secretary. -The panel will maintain a permanent public -record of debates and of any decisions it makes, -except where privacy is essential. +Each committee will ensure that appropriate means are made available for making proposals and carrying out debates in a way which is visible and open to participation by all interested parties, and will maintain a permanent public record of debates and of any decisions made by the committee. -### Constitution of the CF committees +The committees may not devolve responsibility for the CF standard to other bodies, but they may encourage the formation of other permanent or temporary ad-hoc groups to debate issues and propose developments to CF. -Anyone with sufficient time, interest and expertise is qualified to serve as a -member of the conventions committee or the standard names committee or -both. Prospective members will nominate themselves. -Members of the committees will be appointed at any time by the CF Governance -Panel. Committee members judged by the panel to have been inactive for an -extended period will be asked to resign. Members may choose to resign at any -time and must retire after five years, but may be reappointed. +Each committee will ensure that the parts of the standard for which it is responsible, any supporting documents and resources, and the procedures for proposing and deciding changes are kept up-to-date and made publicly available. -Each committee will elect its -own chair from among its members. The chair may resign the office at -any time and must retire after three years, but may be reelected. +The committees may not change their constitutions or terms of reference themselves, but each may propose changes to be made by the CF Governance Panel. -Each committee will have authority and responsibility for the development of -the aspects of the CF standard within its remit, as detailed in its terms of -reference, having regard to the aims and general principles of design of CF. It -will discharge its responsibility by overseeing and contributing to public -debate on how the standard should be expanded or altered, and by deciding after -debate whether and what changes will be made. +## Terms of reference of the conventions committee -Each committee will be assisted in its responsibility by a permanent and funded -member of staff, who will be appointed in a manner decided by the CF Governance -Panel, and who will be an ex-officio member and secretary of the committee. The -manager of CF conventions will be the secretary of the conventions committee -and the manager of CF standard names will be the secretary of the standard -names committee. The committee will propose priorities for work by its -secretary. +The conventions committee will be responsible for the development of the CF conventions constituting the CF netCDF standard, except for the definition of standard names and of any other aspects of controlled vocabulary in the appendices to the standard that it agrees with the standard names committee should be within the remit of that committee. -Each committee will ensure that appropriate means are made available for making -proposals and carrying out debates in a way which is visible and open to -participation by all interested parties, and will maintain a permanent public -record of debates and of any decisions made by the committee. +The conventions committee and standard names committee will together define the format of the standard name table. -The committees may not devolve responsibility for the CF standard to other -bodies, but they may encourage the formation of other permanent or temporary -ad-hoc groups to debate issues and propose developments to CF. +The conventions committee will have an interest in implementation of CF metadata conventions corresponding to the CF standard in other file formats and media apart from netCDF. -Each committee will ensure that the parts of the standard for which it is -responsible, any supporting documents and resources, and the procedures for -proposing and deciding changes are kept up-to-date and made publicly available. +The conventions committee will be responsible for the CF conformance document and for deciding what CF conformance means. -The committees may not change their constitutions or terms of reference -themselves, but each may propose changes to be made by the CF Governance Panel. +The membership of the conventions committee should include representatives of those who maintain widely used software which follows the CF conventions, especially those which the committee regards as reference implementations. +## Terms of reference of the standard names committee -### Terms of reference of the conventions committee +The standard names committee will be responsible for the definition of CF standard names and of any other aspects of controlled vocabulary in the appendices to the CF netCDF standard that it agrees with the conventions committee should be within its remit. -The conventions committee will be responsible for the development of the CF -conventions constituting the CF netCDF standard, except for the definition of -standard names and of any other aspects of controlled vocabulary in the -appendices to the standard that it agrees with the standard names committee -should be within the remit of that committee. +The standard names committee will be responsible for maintaining the standard name table. +The standard names committee and the conventions committee will together define the format of the standard name table. -The conventions committee and standard names committee will together define the -format of the standard name table. +The standard names committee will have an interest in working towards interoperability with other vocabulary maintainers. -The conventions committee will have an interest in implementation of CF -metadata conventions corresponding to the CF standard in other file formats and -media apart from netCDF. - -The conventions committee will be responsible for the CF conformance document -and for deciding what CF conformance means. - -The membership of the conventions committee should include representatives of -those who maintain widely used software which follows the CF conventions, -especially those which the committee regards as reference implementations. - - -### Terms of reference of the standard names committee - -The standard names committee will be responsible for the definition of CF -standard names and of any other aspects of controlled vocabulary in the -appendices to the CF netCDF standard that it agrees with the conventions -committee should be within its remit. +The standard names committee will make proposals for modification of conventions when it appears that names cannot be satisfactorily defined within the prevailing conventions. -The standard names committee will be responsible for maintaining the standard -name table. The standard names committee and the conventions committee will -together define the format of the standard name table. - -The standard names committee will have an interest in working towards -interoperability with other vocabulary maintainers. - -The standard names committee will make proposals for modification of -conventions when it appears that names cannot be satisfactorily defined within -the prevailing conventions. +The membership of the standard names committee should include representatives of the various scientific user communities of the CF standard. -The membership of the standard names committee should include representatives -of the various scientific user communities of the CF standard. +[code-of-conduct]: (https://github.com/cf-convention/cf-conventions/blob/master/CODE_OF_CONDUCT.md) diff --git a/conventions_contributors.md b/conventions_contributors.md index 447545b4..531698cd 100644 --- a/conventions_contributors.md +++ b/conventions_contributors.md @@ -5,15 +5,10 @@ title: Rules # Contributors to the CF Conventions -The following individuals have proposed enhancements or corrections of defects -in the CF conventions, or participated substantially in discussions which led -to agreement on changes being made, or which concluded in no change being made -after detailed consideration. They are listed here in recognition of their -contribution to the development of the CF standard. +The following individuals have proposed enhancements or corrections of defects in the CF conventions, or participated substantially in discussions which led to agreement on changes being made, or which concluded in no change being made after detailed consideration. +They are listed here in recognition of their contribution to the development of the CF standard. -The affiliations are those that the contributors used at the time of their -contribution and are included to identify them, rather than -as current contact information. +The affiliations are those that the contributors used at the time of their contribution and are included to identify them, rather than as current contact information. - Ryan Abernathey, Columbia University - Dave Allured, NOAA diff --git a/discussion.md b/discussion.md index 1e05b279..a5fe20e4 100755 --- a/discussion.md +++ b/discussion.md @@ -6,39 +6,25 @@ group: "navigation" # Discussion -Discussion about CF Metadata takes place on GitHub in three forums, -using [GitHub issues][github_issues]. +Discussion about CF Metadata takes place on GitHub in three forums, using [GitHub issues][github_issues]. * [General discussion and standard names][github_discuss] - For proposing standard names, asking questions or having discussions about the - interpretation and use of the CF conventions, and initial - suggestions for proposals to change or extend the CF conventions. + For proposing standard names, asking questions or having discussions about the interpretation and use of the CF conventions, and initial suggestions for proposals to change or extend the CF conventions. - There is also a separate website detailing the [status of current - proposals for new standard names][current] that have been - initiated on the general discussion forum. + There is also a separate website detailing the [status of current proposals for new standard names][current] that have been initiated on the general discussion forum. * [Conventions][github_conventions] - For proposing enhancements and reporting defects in the CF - conventions, that may or may not have started as conversations on - the general discussion forum. + For proposing enhancements and reporting defects in the CF conventions, that may or may not have started as conversations on the general discussion forum. * [Website and governance][github_website] - For discussing, proposing changes and reporting defects in the [CF - website][website], and for discussion of CF governance. + For discussing, proposing changes and reporting defects in the [CF website][website], and for discussion of CF governance. -No registration with CF is required to contribute; all that is needed -is a freely available [GitHub account][github]. - -Before the CF community migrated to GitHub, -general and standard-name discussion took place on the -[cf-metadata mailing list][archives], and enhancements -to the conventions were proposed -on the [CF Metadata Trac](Data/trac.html) site. +No registration with CF is required to contribute; all that is needed is a freely available [GitHub account][github]. +Before the CF community migrated to GitHub, general and standard-name discussion took place on the [cf-metadata mailing list][archives], and enhancements to the conventions were proposed on the [CF Metadata Trac](Data/trac.html) site. ### Archive links diff --git a/errors.md b/errors.md index f0a31c50..1b633543 100755 --- a/errors.md +++ b/errors.md @@ -5,15 +5,20 @@ title: Errors # Rules for Correcting Errors in CF Documents -

These rules apply to the CF conventions document, the conformance document, the standard name table and its guidelines.

+These rules apply to the CF conventions document, the conformance document, the standard name table and its guidelines. -

Errors in these documents can be corrected under these rules if it is clear that the text as it stands isn't what was agreed, because of a typographical or some other error. These rules can't be followed for making substantive changes. Errors in the standard names can alternatively be pointed out on the CF email list, and implemented by the manager of CF standard names (Alison) as part of a regular update.

+Errors in these documents can be corrected under these rules if it is clear that the text as it stands isn't what was agreed, because of a typographical or some other error. +These rules can't be followed for making substantive changes. +Errors in the standard names can alternatively be pointed out on the CF email list, and implemented by the manager of CF standard names (Alison) as part of a regular update. -

If someone thinks there is an error in a document, they should open a github issue of type "defect" to point it out and to state what should be done to the text in order to correct the error. A corresponding github pull request can also be submitted in addition to the issue.

+If someone thinks there is an error in a document, they should open a github issue of type "defect" to point it out and to state what should be done to the text in order to correct the error. +A corresponding github pull request can also be submitted in addition to the issue. -

The correction is held to have been agreed if three weeks pass without anyone disagreeing with it. After that period, the issue should be closed by the manager of the CF conventions or the manager of CF standard names, who will make the change and/or merge the pull request. No moderator is needed because there cannot be any substantive discussion under these rules.

+The correction is held to have been agreed if three weeks pass without anyone disagreeing with it. +After that period, the issue should be closed by the manager of the CF conventions or the manager of CF standard names, who will make the change and/or merge the pull request. +No moderator is needed because there cannot be any substantive discussion under these rules. -

If anyone disagrees that the correction should be made, because they think the document does have the intended meaning, then a correction cannot be made by these rules, the issue should be closed, and the change should be proposed as an enhancement instead, following the rules for making changes to the CF standard, if the proposer wants to pursue the issue.

+If anyone disagrees that the correction should be made, because they think the document does have the intended meaning, then a correction cannot be made by these rules, the issue should be closed, and the change should be proposed as an enhancement instead, following the rules for making changes to the CF standard, if the proposer wants to pursue the issue. These rules were agreed under github [issue #130][130]. diff --git a/faq.md b/faq.md index f6ce3612..142fe245 100644 --- a/faq.md +++ b/faq.md @@ -3,218 +3,153 @@ layout: default title: Frequently Asked Questions --- - # Frequently Asked Questions (FAQ) about the CF Conventions -This page covers many of the most common questions asked about the Climate and Forecast conventions (and Standard Names). If you have a question that isn't on this list, please ask it of the CF-metadata mail list, so that the CF community can respond. We will use that list as the basis for additional content for this set of questions. - -Note that many links in this FAQ point to previously released versions of the CF specification. However, others point to the currently-released CF-1.10 specification. This may provide better explanations or context, or more advanced capabilities. But generally these specifications do not conflict with one another, so there is no harm in following a link to a previous version. - -The questions are organized by topic. Click on any question to go to its answer. - ------------- -

-# Contents - -## CF Background - -This section includes general background about the CF conventions. - -* [What are the CF conventions, and what do they include?](#what) -* [What are the principles of the CF conventions?](#principles) -* [Who manages the CF conventions?](#who) -* [How long has CF been around? Is it mature?](#when_started) -* [How does CF relate to other conventions/specifications (especially COARDS and netCDF)?](#related_conventions) +This page covers many of the most common questions asked about the Climate and Forecast conventions (and Standard Names). +If you have a question that isn't on this list, please ask it of the CF-metadata mail list, so that the CF community can respond. +We will use that list as the basis for additional content for this set of questions. -## Working with the CF Convention - -Learning about and changing the CF convention. +Note that many links in this FAQ point to previously released versions of the CF specification. +However, others point to the currently-released CF-1.10 specification. +This may provide better explanations or context, or more advanced capabilities. +But generally these specifications do not conflict with one another, so there is no harm in following a link to a previous version. -* [Do the CF conventions stand alone?](#standalone) -* [How do I find previously asked questions about CF?](#research) -* [How do I ask questions about CF?](#ask) -* [How do I propose a change?](#propose) -* [What is the process for accepting a change to the CF convention?](#change_process) -* [What is the process for fixing errors?](#error_correction) -* [When are changes added to the CF Convention?](#when_updated) - -## Common questions about CF details - -* [My file was written using an earlier version of CF. Is it still compliant?](#version_compliance) -* [For vertical coordinates, how does the _positive_ attribute work?](#vertical_coords_positive_attribute) -* [How (and why) does CF specify directions in standard names?](#specifying_directions) -* [How can I encode flag values (or other enumerated lists) with CF?](#flag_values) -* [What good is the auxiliary coordinate axis, how is it different from a regular coordinate axis?](#auxiliary_coordinate_axis) - -## Rich technical questions about CF +The questions are organized by topic. -The detailed and big picture concepts in CF. - -* [My data variables have an unusual coordinate axis, how do I describe it?](#coordinate_axis_unusual) -* [How can I describe a file with multiple time coordinates (e.g., run time AND valid or forecast time)?](#coordinate_axis_time) -* [What are Discrete Sampling Geometries? Do I need to worry about them?](#dsg) -* [If a variable's time is a time range, what should be used for the time coordinate?](#time_gridpoint) -* [My variable depends on the type of surface. How can I specify the surface type?](#surface_type_coordinate) - -## CF Standard Names - -General and specific information about purpose and mechanisms of standard names - -* [What is the official list of standard names?](#stdnames_official) -* [What is the purpose of the standard name?](#stdnames_purpose) -* [How can I find the standard name I need?](#stdnames_find) -* [How do I ask for a new standard name?](#stdnames_ask) -* [How detailed should a standard name be?](#stdnames_detail) -* [What are the components of a standard name?](#stdnames_components) -* [What is the structure of a good standard name?](#stdnames_structure) -* [What can be described in a standard name?](#stdnames_facets) -* [What shouldn't be described in a standard name?](#stdnames_nonos) -* [Are there common standard name phrases that get re-used?](#stdnames_phrases) -* [Is there a grammar for standard names?](#stdnames_grammar) -* [Are there mappings of standard names to other vocabularies?](#stdnames_mappings) -* [What tools exist to work with standard names?](#stdnames_tools) -* [Are standard names ever removed from use? How?](#stdnames_deprecation) - -## CF and COARDS Units (UDUNITS) - -These questions are not strictly part of CF, but CF depends on this understanding. - -* [If my variable has a standard name, must it have the corresponding canonical units?](#canonical) -* [Why does CF use UDUNITS as its standard?](#udunits_why) -* [How do I specify units in CF?](#cf_units) -* [How do units of time work?](#udunits_time) -* [Are there units in CF that aren't in UDUNITS?](#udunits_missing) -* [Are there other good resources about UDUNITS?](#udunits_refs) - -## Maintaining the CF standard - -This section is about the meta-question of procedures involved to update CF standards documentation. - -* [Who physically maintains the standards documentation?](#who_docs) -* [Where is the documentation stored?](#where_docs) -* [Can I fork (get a copy of) the repository?](#access_docs) -* [How can I submit suggested changes?](#update_docs) - -
Up to TOC
- ------------- +* TOC +{:toc} # Questions and Answers ## CF background - - ### What are the CF conventions, and what do they include? -The conventions for CF (Climate and Forecast) metadata are designed to promote the processing and sharing of files created with the NetCDF API. The conventions define metadata that provide a definitive description of what the data in each variable represents, and the spatial and temporal properties of the data. This enables users of data from different sources to decide which quantities are comparable, and facilitates building applications with powerful extraction, regridding, and display capabilities. - +The conventions for CF (Climate and Forecast) metadata are designed to promote the processing and sharing of files created with the NetCDF API. +The conventions define metadata that provide a definitive description of what the data in each variable represents, and the spatial and temporal properties of the data. +This enables users of data from different sources to decide which quantities are comparable, and facilitates building applications with powerful extraction, regridding, and display capabilities. ### What are the principles of the CF conventions? Principles of CF include self-describing data (no external tables needed for understanding); metadata equally readable by humans and software; minimum redundancy and maximum simplicity; and a development process focusing on existing needs. - ### Who manages the CF conventions? -The CF conventions are maintained by volunteers, led by a Governance Panel and assisted by the Conventions Committee and Standard Names Committee. (See [CF Governance](http://cfconventions.org/governance.html).) Changes to the conventions are proposed and settled by the community, using the [CF metadata discussions](https://github.com/cf-convention/discuss) project on Github. Many of the principles of CF operations follow the proposals at these [rules for CF conventions changes](http://cfconventions.org/rules.html). - +The CF conventions are maintained by volunteers, led by a Governance Panel and assisted by the Conventions Committee and Standard Names Committee. +(See [CF Governance](http://cfconventions.org/governance.html).) +Changes to the conventions are proposed and settled by the community, using the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/) and [CF Metadata Trac site](http://kitt.llnl.gov/trac). +Many of the principles of CF operations follow the proposals at these [rules for CF conventions changes](http://cfconventions.org/rules.html). ### How long has CF been around? Is it mature? -Work began on CF in 2001 and [Version 1.0](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.0/build/cf-conventions.html) was released in October 2003. Now at Version 1.10, it has been used for tens of thousands of distinct netCDF products, has an active discussion list with hundreds of participants, and is a mature technical specification. Because it is community-supported and community-driven, turnaround on questions and changes can take a little time, but are generally thoroughly considered. - +Work began on CF in 2001 and [Version 1.0](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.0/build/cf-conventions.html) was released in October 2003. +Now at Version 1.10, it has been used for tens of thousands of distinct netCDF products, has an active discussion list with hundreds of participants, and is a mature technical specification. +Because it is community-supported and community-driven, turnaround on questions and changes can take a little time, but are generally thoroughly considered. ### How does CF relate to other conventions/specifications (especially COARDS and netCDF)? -CF is a convention built on top of the netCDF standard, and it generalizes and extends the netCDF [COARDS conventions](https://ferret.pmel.noaa.gov/noaa_coop/coop_cdf_profile.html). Whereas the netCDF specification is designed to be domain-agnostic, the CF conventions were developed specifically to target climatology and weather forecasting domains. Since then, the CF conventions have targeted earth science domains more broadly, and expanded from a focus on models to include observational data. +CF is a convention built on top of the netCDF standard, and it generalizes and extends the netCDF [COARDS conventions](https://ferret.pmel.noaa.gov/noaa_coop/coop_cdf_profile.html). +Whereas the netCDF specification is designed to be domain-agnostic, the CF conventions were developed specifically to target climatology and weather forecasting domains. +Since then, the CF conventions have targeted earth science domains more broadly, and expanded from a focus on models to include observational data. -The conventions of netCDF and COARDS are assumed and upheld by CF. Where COARDS is adequate, CF does not provide an alternative, while all of CF's extensions to COARDS are optional and provide new functionality. +The conventions of netCDF and COARDS are assumed and upheld by CF. +Where COARDS is adequate, CF does not provide an alternative, while all of CF's extensions to COARDS are optional and provide new functionality. -A motivation for developing CF was the need for extra features not found in netCDF or COARDS. These include conventions for grid-cell boundaries, horizontal grids other than latitude-longitude, recording common statistical operations, standardised identification of physical quantities, non-spatiotemporal axes, climatological statistics and data compression. These needs were driven by the original user community developing the CF conventions, the climatology and weather forecasting science community. -
Up to TOC
- +A motivation for developing CF was the need for extra features not found in netCDF or COARDS. +These include conventions for grid-cell boundaries, horizontal grids other than latitude-longitude, recording common statistical operations, standardised identification of physical quantities, non-spatiotemporal axes, climatological statistics and data compression. +These needs were driven by the original user community developing the CF conventions, the climatology and weather forecasting science community. ## Working with the CF Convention - - ### Do the CF conventions stand alone? -Not entirely; because CF is a netCDF convention, it assumes the netCDF standard is being followed. And it relies on the UDUNITS system of specifying units (see CF and COARDS units below). CF does not replicate the information from these other documents, so to adhere to CF you may need to become familiar with the other specifications as well, particularly the netCDF User's Guide. +Not entirely; because CF is a netCDF convention, it assumes the netCDF standard is being followed. +And it relies on the UDUNITS system of specifying units (see CF and COARDS units below). +CF does not replicate the information from these other documents, so to adhere to CF you may need to become familiar with the other specifications as well, particularly the netCDF User's Guide. -The CF Conventions were originally based on the netCDF convention called the [COARDS conventions](https://ferret.pmel.noaa.gov/noaa_coop/coop_cdf_profile.html) (named for their sponsor, the Cooperative Ocean/Atmosphere Research Data Service), developed in 1995. While there may be a few things in that document that are not documented in CF, working with the CF conventions does not require previous understanding of COARDS. +The CF Conventions were originally based on the netCDF convention called the [COARDS conventions](https://ferret.pmel.noaa.gov/noaa_coop/coop_cdf_profile.html) (named for their sponsor, the Cooperative Ocean/Atmosphere Research Data Service), developed in 1995. +While there may be a few things in that document that are not documented in CF, working with the CF conventions does not require previous understanding of COARDS. -Aside from those references, a CF principle is to be self-contained. So for example the CF Standard Names attempt to be as general and well-defined as possible, so the reader does not have to access outside sources to understand the terms. - +Aside from those references, a CF principle is to be self-contained. +So for example the CF Standard Names attempt to be as general and well-defined as possible, so the reader does not have to access outside sources to understand the terms. ### How do I find previously asked questions about CF? The two main ways to research CF questions are checking this FAQ, and visiting the [mail archives](http://mailman.cgd.ucar.edu/pipermail/cf-metadata), to see if your question has already been asked. -You can use the pipermail search window to see when your topic may have been raised over the years. To follow a particular subject thread, go to the year in which the discussion took place, click on the `by thread` sorting option, and choose the first mail with that subject. The `next message` link will then progress through each of the threads in order. +You can use the pipermail search window to see when your topic may have been raised over the years. +To follow a particular subject thread, go to the year in which the discussion took place, click on the `by thread` sorting option, and choose the first mail with that subject. +The `next message` link will then progress through each of the threads in order. If you are going to work with CF a lot, you may want to download the yearly files from pipermail and import them to your local mail application. - ### How do I ask questions about CF? -First, please see whether your question has already been answered (see [question above](#research)). Questions about the CF Convention, including its Standard Names list, may be asked at the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). CF community members usually respond within a day to simple questions, but allow more time if you have an advanced technical topic. - +First, please see whether your question has already been answered (see [question above](#research)). +Questions about the CF Convention, including its Standard Names list, may be asked at the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). +CF community members usually respond within a day to simple questions, but allow more time if you have an advanced technical topic. ### How do I propose a change? -Changes to the CF standard and the Standard Names are generally proposed first on the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). See [How do I ask for a new standard name?](#stdnames_ask) to learn more about changes to the Standard Names list. +Changes to the CF standard and the Standard Names are generally proposed first on the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). +See [How do I ask for a new standard name?](#stdnames_ask) to learn more about changes to the Standard Names list. A change to the CF standard itself may be brought up on the mailing list, but must be presented and agreed to in detail on the [CF Metadata Trac site](http://kitt.llnl.gov/trac), where the explicit change being requested can be refined. - ### What is the process for accepting a change to the CF convention? -The community discusses requests for changes via the mail list and trac site, and may ask questions or recommend changes. If no one raises objections or concerns about the change (modified as needed to address any issues) for the period of time required for that document, it is considered accepted. The moderators of the list typically make a final statement of acceptance once that stage has been reached. +The community discusses requests for changes via the mail list and trac site, and may ask questions or recommend changes. +If no one raises objections or concerns about the change (modified as needed to address any issues) for the period of time required for that document, it is considered accepted. +The moderators of the list typically make a final statement of acceptance once that stage has been reached. More detailed information can be found in the [Rules for CF Conventions Changes](http://cfconventions.org/rules.html). - ### What is the process for fixing errors? Errors have a simpler workflow, but still use a community process, as described in the [Rules for Correcting Errors in CF Documents](http://cfconventions.org/errors.html). - ### When are changes added to the CF Convention? -Changes to the CF Convention itself are grouped into major releases. Because the proposed changes are visible to the community pending the final release of the convention, major releases may take as long as a year or more to finalize, but users sometimes choose to follow the proposed changes in advance of their release date. -
Up to TOC
- +Changes to the CF Convention itself are grouped into major releases. +Because the proposed changes are visible to the community pending the final release of the convention, major releases may take as long as a year or more to finalize, but users sometimes choose to follow the proposed changes in advance of their release date. ## Common questions about CF details - - ### My file was written using an earlier version of CF. Is it still compliant? -The compliance is determined by the version number you define in the `Conventions` attribute within each file. If your file complies with the specifications of the CF version in that attribute, it stays in compliance with CF even as newer versions of the CF Conventions are released. As a general rule, tools that work with files following the CF Convention should support all versions of the convention. +The compliance is determined by the version number you define in the `Conventions` attribute within each file. +If your file complies with the specifications of the CF version in that attribute, it stays in compliance with CF even as newer versions of the CF Conventions are released. +As a general rule, tools that work with files following the CF Convention should support all versions of the convention. Where possible, and to date, previously defined elements of the CF Conventions are not invalidated by subsequent versions. - ### For vertical coordinates, how does the _positive_ attribute work? If your vertical coordinate is some form of pressure, you won't have to worry about the `positive` attribute -- increasing pressure is always 'down' (closer to the center of the earth). -If your vertical coordinate is anything else, you must provide a positive attribute. This takes a value of 'up' or 'down', indicating whether more positive values are further away from earth center (up), or toward earth center. Many standard names which could be used for vertical coordinates state the convention for positive in their definition. For example, height is defined to have positive direction up, while depth has positive direction down (depth > 0 is below sea level). However, in some data sets (particularly oceanographic ones) depth values take the opposite sign. If you specify a coordinate standard name of depth, and a positive attribute value of up, the variable should be interpreted as having an inverted depth direction. However, this is not recommended; it would be better to use a standard name of height instead. +If your vertical coordinate is anything else, you must provide a positive attribute. +This takes a value of 'up' or 'down', indicating whether more positive values are further away from earth center (up), or toward earth center. +Many standard names which could be used for vertical coordinates state the convention for positive in their definition. +For example, height is defined to have positive direction up, while depth has positive direction down (depth > 0 is below sea level). +However, in some data sets (particularly oceanographic ones) depth values take the opposite sign. +If you specify a coordinate standard name of depth, and a positive attribute value of up, the variable should be interpreted as having an inverted depth direction. +However, this is not recommended; it would be better to use a standard name of height instead. Note that a standard name attribute is not required for the vertical coordinate, but the `positive` attribute is required if the standard name is not 'pressure'. Reference: [Trac ticket #109](http://kitt.llnl.gov/trac/ticket/109) - ### How (and why) does CF specify directions in standard names? -There are just a few names in CF that are dedicated to specific coordinate directions. Beyond those special cases, many CF parameters have directional components (up/down, east/west, clockwise/counterclockwise, etc.). To indicate the positive direction of these parameters' values, CF can include the direction in the standard_name attribute for the variable. These directional standard names are added only as each direction is requested, so you may see many 'eastward' standard names, but no 'westward' ones, for example. Because CF does not want to be prescriptive about how data is filtered, it will generally accept requests to add names 'in the opposite direction'. +There are just a few names in CF that are dedicated to specific coordinate directions. +Beyond those special cases, many CF parameters have directional components (up/down, east/west, clockwise/counterclockwise, etc.). +To indicate the positive direction of these parameters' values, CF can include the direction in the standard_name attribute for the variable. +These directional standard names are added only as each direction is requested, so you may see many 'eastward' standard names, but no 'westward' ones, for example. +Because CF does not want to be prescriptive about how data is filtered, it will generally accept requests to add names 'in the opposite direction'. While it would be possible to separate the directionality of the values from the standard_name (and put it in a 'direction'-style attribute like `positive` for vertical coordinates), this has been avoided, both to simplify compliance and to make interpretation of the values easier for the user. -A list of typical directional components of standard names follows. These lists are not complete, but provide illustrations of the most common terms that are used. +A list of typical directional components of standard names follows. +These lists are not complete, but provide illustrations of the most common terms that are used. Components of standard names that are implicitly signed (note that often there is no standard name for the opposing direction): @@ -230,32 +165,31 @@ Components of standard names that are implicitly signed (note that often there i * downwelling, upwelling * sinking -Some directional components are not necessarily signed, and so may not be specifying a positive direction per se. For example, `horizontal` is indicating a plane rather than a direction, while `bidirectional` indicates a directional mode. +Some directional components are not necessarily signed, and so may not be specifying a positive direction per se. +For example, `horizontal` is indicating a plane rather than a direction, while `bidirectional` indicates a directional mode. * horizontal, xy, vertical * bidirectional, omnidirectional, isotropic * meridional * radial - - ### How can I encode flag values (or other enumerated lists) with CF? -Often data values in an enumerated list are given as string codes ("UP", "GOOD", "Warning"), yet it is more useful to encode these values as integers. CF's [flag_values mechanism](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#flags) can encode strings in numeric data variables, while defining flag_meanings to map the numbers to the meanings. The `flag_values` and `flag_meanings` attributes (and, if necessary, the `flag_masks` attribute) describe a status flag consisting of mutually exclusive coded values. The `flag_values` attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values. The `flag_meanings` attribute is a string whose value is a blank-separated list of descriptive words or phrases, one for each flag value. - +Often data values in an enumerated list are given as string codes ("UP", "GOOD", "Warning"), yet it is more useful to encode these values as integers. +CF's [flag_values mechanism](http://cfconventions.org/cf-conventions.html#flags) can encode strings in numeric data variables, while defining flag_meanings to map the numbers to the meanings. +The `flag_values` and `flag_meanings` attributes (and, if necessary, the `flag_masks` attribute) describe a status flag consisting of mutually exclusive coded values. +The `flag_values` attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values. +The `flag_meanings` attribute is a string whose value is a blank-separated list of descriptive words or phrases, one for each flag value. ### What good is the auxiliary coordinate axis, how is it different from a regular coordinate axis? -In NetCDF, a `coordinate variable` is a one-dimensional variable with the same name as its dimension [e.g., time(time)]; is a numeric data type; has values that are ordered monotonically (always going in one direction); and has no missing values. If you have a variable that contains coordinate values but does not meet these criteria, in CF you can still indicate that it has coordinate values by naming it as an auxiliary coordinate variable. +In NetCDF, a `coordinate variable` is a one-dimensional variable with the same name as its dimension [e.g., time(time)]; is a numeric data type; has values that are ordered monotonically (always going in one direction); and has no missing values. +If you have a variable that contains coordinate values but does not meet these criteria, in CF you can still indicate that it has coordinate values by naming it as an auxiliary coordinate variable. The rules for creating and using auxiliary coordinate variables are described in the [Coordinate Systems](http://cfconventions.org/cf-conventions/cf-conventions.html#coordinate-system) section of the Convention. -
Up to TOC
- ## Rich technical questions about CF - - ### My data variables have an unusual coordinate axis, how do I describe it? CF allows coordinate variables to be used for any quantity that you might regard as an independent variable on which your data variable depends. @@ -268,40 +202,60 @@ CF offers a rich set of options for specifying coordinate axes. Here is a short * Swath coordinates (e.g., 'along-track' and 'across-track' values often obtained from platforms following a path, like satellites, planes, and autonomous underwater vehicles) can be expressed as x,y coordinates that are mapped to latitude and longitude. There are [open proposals](https://github.com/cf-convention/cf-conventions/issues/269) for specifying swath coordinates. * Degree-day integrals are described as integral_of_air_temperature_deficit|excess_wrt_time with a coordinate of air_temperature_threshold. * Electromagnetic radiation at particular wavelengths uses a coordinate of radiation_wavelength or radiation_frequency. - + +*Suggestion for improvement: add a good example for swath coordinates. +The ones in http://kitt.llnl.gov/trac/wiki/SatelliteData don't seem quite illustrative.* + ### How can I describe a file with multiple time coordinates (e.g., run time AND valid or forecast time)? There are several ways that multiple time coordinates may be handled; you may wish to review the details in [this list message](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2006/001008.html). -CF's standard name for the valid or forecast time is `time` (also used for the time of an observation). CF also has a standard name for the time the analysis was performed (its 'run time'): forecast_reference_time. Very briefly, values in either or both of these axes may vary (a single run may have multiple forecast periods, or multiple runs may target a single period, or multiple runs may target multiple periods). If either axis contains just a single value, they are both specified as coordinates. If both are multi-valued, then they are each defined as one-dimensional auxiliary coordinate variables, with a common index dimension. +CF's standard name for the valid or forecast time is `time` (also used for the time of an observation). +CF also has a standard name for the time the analysis was performed (its 'run time'): forecast_reference_time. +Very briefly, values in either or both of these axes may vary (a single run may have multiple forecast periods, or multiple runs may target a single period, or multiple runs may target multiple periods). +If either axis contains just a single value, they are both specified as coordinates. +If both are multi-valued, then they are each defined as one-dimensional auxiliary coordinate variables, with a common index dimension. CF section 5.7 has an [example of the first case](http://cfconventions.org/cf-conventions/cf-conventions.html#scalar-coordinate-variables), with a scalar coordinate variable for forecast_reference_time and a multivalued time axis for the valid time. An example of the second case can be found in the email referenced above. - ### What are Discrete Sampling Geometries? Do I need to worry about them? -Discrete Sampling Geometries, addressed in Section 9 of the CF Conventions, were added to offer greater efficiency and clarity for storing a collection of 'features' in a single file. Here we define a feature by example: it can be a point, a time series, a trajectory, a profile, a time series (of) profile(s), or a trajectory (of) profile(s). All of these can be stored in CF-compliant netCDF files, but there was no consistent way to do so and people and programs could not leverage the features in the files. +Discrete Sampling Geometries, addressed in Section 9 of the CF Conventions, were added to offer greater efficiency and clarity for storing a collection of 'features' in a single file. +Here we define a feature by example: it can be a point, a time series, a trajectory, a profile, a time series (of) profile(s), or a trajectory (of) profile(s). +All of these can be stored in CF-compliant netCDF files, but there was no consistent way to do so and people and programs could not leverage the features in the files. -You don't have to worry about Discrete Sampling Geometries, or DSGs, in order to be CF-compliant. If you have data that correspond to one of these feature types, you can read the the Discrete Sampling Geometry section to learn how to represent those data so that others can fully leverage them. (Note: The `feature_type attribute` is reserved for files that represent a Discrete Sampling Geometry.) - +You don't have to worry about Discrete Sampling Geometries, or DSGs, in order to be CF-compliant. +If you have data that correspond to one of these feature types, you can read the the Discrete Sampling Geometry section to learn how to represent those data so that others can fully leverage them. +(Note: The `feature_type attribute` is reserved for files that represent a Discrete Sampling Geometry.) ### If a variable's time is a time range, what should be used for its time coordinate? -For example, if you have a rainfall accumulation value for a 24-hour period from 20140716 0600 to 20140717 0600, it's obvious these should be the time bounds, but what time coordinate should be used? The answer calls for judgment, and depends on the data's context. (The time coordinate might be used for plotting, and also for differentiating in time.) If the data are simple observations, using the midpoint is reasonable. (Of course if sensors have a measurement or reporting lag, this should be adjusted for in representing the time of the observation.) But if the calculation is performed in the context of a model, and the value is used to trigger calculations based on values at the end boundary, it makes more sense to use the endpoint as the time coordinate. +For example, if you have a rainfall accumulation value for a 24-hour period from 20140716 0600 to 20140717 0600, it's obvious these should be the time bounds, but what time coordinate should be used? +The answer calls for judgment, and depends on the data's context. +(The time coordinate might be used for plotting, and also for differentiating in time.) +If the data are simple observations, using the midpoint is reasonable. +(Of course if sensors have a measurement or reporting lag, this should be adjusted for in representing the time of the observation.) +But if the calculation is performed in the context of a model, and the value is used to trigger calculations based on values at the end boundary, it makes more sense to use the endpoint as the time coordinate. When there is no basis for setting the time to a particular point in the interval, the majority of posters seem to favor the midpoint. -The situation is complicated in the case of a climatology, where the total range of times might include discontinuities. For instance, specifying 19601201 to 19620301 in climatological bounds defines the northern hemisphere winters (DJF) 1960-1961 and 1961-1962. The middle of the bounds is the middle of July 1961, which would be a silly coordinate for plotting a winter statistic. Instead it should be the middle of the *first* time interval to which the climatological statistic applies, making it mid-January 1961. (Or, if the statistic is an accumulation over multiple years, perhaps the middle of the last time interval.) Use your good judgment! - +The situation is complicated in the case of a climatology, where the total range of times might include discontinuities. +For instance, specifying 19601201 to 19620301 in climatological bounds defines the northern hemisphere winters (DJF) 1960-1961 and 1961-1962. +The middle of the bounds is the middle of July 1961, which would be a silly coordinate for plotting a winter statistic. +Instead it should be the middle of the *first* time interval to which the climatological statistic applies, making it mid-January 1961. +(Or, if the statistic is an accumulation over multiple years, perhaps the middle of the last time interval.) +Use your good judgment! ### My variable depends on the type of surface. How can I specify the surface type? CF maintains a vocabulary specifically for specifying surface and area types; it is available on the CF site as the [Area Type Table](http://cfconventions.org/Data/area-type-table/current/build/area-type-table.html), and can also be accessed as a [controlled vocabulary](http://mmisw.org/ont/cf/areatype). -Terms from this vocabulary may be used as specified in the CF Convention [section 7.3.3 Statistics applying to portions of cells](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#statistics-applying-portions). However, it is also possible to describe a data variable by using a named quantity as a coordinate variable, and the area_type is often needed for such a purpose. The area_type can be attached as a dimensioned coordinate variable, or as a scalar coordinate. +Terms from this vocabulary may be used as specified in the CF Convention [section 7.3.3 Statistics applying to portions of cells](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#statistics-applying-portions). +However, it is also possible to describe a data variable by using a named quantity as a coordinate variable, and the area_type is often needed for such a purpose. +The area_type can be attached as a dimensioned coordinate variable, or as a scalar coordinate. If the area_type you need is not in the list, [request a new area_type name](#stdnames_ask) just as you would a standard name (no units required). @@ -350,44 +304,48 @@ surface_temperature(time,y,x); surface_temperature:coordinates = "lat lon surface_type"; ``` -
Up to TOC
- - ## CF Standard Names Reference [section 3.3 of the CF Convention, Standard Names](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#standard-name) - ### What is the official list of standard names? -The CF site contains [the official list of CF standard names](http://cfconventions.org/standard-names). The XML document pointed to from that page is the primary reference, but the HTML and PDF documents are produced automatically from the XML, and should contain the same information. +The CF site contains [the official list of CF standard names](http://cfconventions.org/standard-names). +The XML document pointed to from that page is the primary reference, but the HTML and PDF documents are produced automatically from the XML, and should contain the same information. -Several other sites represent alternative views of knowledge artifacts of the standard names. See the [Standard Names Tools](#stdnames_tools) section for more details. - +Several other sites represent alternative views of knowledge artifacts of the standard names. +See the [Standard Names Tools](#stdnames_tools) section for more details. ### What is the purpose of the standard name? -The purpose of the `standard_name` attribute is to provide a succinct and distinguishing description of a variable, in a way that encourages interoperability. (In this document we often use the phrase 'standard name' to refer to this attribute or its value.) +The purpose of the `standard_name` attribute is to provide a succinct and distinguishing description of a variable, in a way that encourages interoperability. +(In this document we often use the phrase 'standard name' to refer to this attribute or its value.) -The standard name is useful for listing and discussing the contents of a file, providing the kind of answer an expert might give to the non-expert's question "What is in that file?" This helps users share files across disciplines and over time. +The standard name is useful for listing and discussing the contents of a file, providing the kind of answer an expert might give to the non-expert's question "What is in that file?" +This helps users share files across disciplines and over time. -The standard name also make it possible for a computer to assess whether a variables is likely to be comparable to another, mathematically and semantically. This increases interoperability by enabling automated discovery. Variables with different standard names are presumably not directly comparable. (Variables with different (that is, incompatible) canonical units are not mathematically comparable, and so are required to have different standard names.) Of course users must review the details of variables, particularly their `long_name` and `source` attributes, to assess whether they are truly interoperable. +The standard name also make it possible for a computer to assess whether a variables is likely to be comparable to another, mathematically and semantically. +This increases interoperability by enabling automated discovery. +Variables with different standard names are presumably not directly comparable. +(Variables with different (that is, incompatible) canonical units are not mathematically comparable, and so are required to have different standard names.) +Of course users must review the details of variables, particularly their `long_name` and `source` attributes, to assess whether they are truly interoperable. References: * J Gregory, 2008: [what standard names are for](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2008/052334.html) - - ### How can I find the standard name I need? -To find standard names that describe your data, open up the latest [Standard Name table](http://cfconventions.org/standard-names.html) (as HTML or XML) and search through it for words typically used for your data. (Because standard names contain no blanks, you may want to search for one word at a time, or even part of a word, rather than a full phrase like "air temperature".) If you can not find any matches, you can browse the table to see the kinds of names that exist -- names strongly lean toward environmental modeling and observation data, especially in atmosphere and ocean science. +To find standard names that describe your data, open up the latest [Standard Name table](http://cfconventions.org/standard-names.html) (as HTML or XML) and search through it for words typically used for your data. +(Because standard names contain no blanks, you may want to search for one word at a time, or even part of a word, rather than a full phrase like "air temperature".) +If you can not find any matches, you can browse the table to see the kinds of names that exist -- names strongly lean toward environmental modeling and observation data, especially in atmosphere and ocean science. -If you can't find any matches, send an email to the CF-Metadata list describing your variables. (See the [question on asking for a new standard name](#stdnames_ask).) - +If you can't find any matches, send an email to the CF-Metadata list describing your variables. +(See the [question on asking for a new standard name](#stdnames_ask).) ### How do I ask for a new standard name? -You ask for a new standard name by sending an email to the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). You should sign up to the mailing list before sending your email, so you can follow the discussion of your request. +You ask for a new standard name by sending an email to the [CF-Metadata Mailing List](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/). +You should sign up to the mailing list before sending your email, so you can follow the discussion of your request. In the email specify the following for each standard name you want to request: @@ -396,28 +354,32 @@ In the email specify the following for each standard name you want to request: * its canonical units. Use other examples from the Standard Names table to model your request, or review past requests in the mail list archives. - ### How detailed should a standard name be? -This depends on the application -- there can be standard names for very narrowly defined quantities, and standard names for broad concepts. The appropriate choice depends on which distinctions need to be made to decide whether another quantity is comparable to the one being defined. +This depends on the application -- there can be standard names for very narrowly defined quantities, and standard names for broad concepts. +The appropriate choice depends on which distinctions need to be made to decide whether another quantity is comparable to the one being defined. -Of course, this broad guideline could result in extraordinarily detailed standard names that will rarely be useful to others. Because the goal of standard names is to encourage interoperability, there are [several qualifier types that are actively discouraged](#stdnames_nonos). - +Of course, this broad guideline could result in extraordinarily detailed standard names that will rarely be useful to others. +Because the goal of standard names is to encourage interoperability, there are [several qualifier types that are actively discouraged](#stdnames_nonos). ### What are the components of a standard name? A CF standard name is a unique text string, which is associated in the CF Standard Names table to other attributes. -The text string is made up of two parts: the name (from the CF Standard Names table), and optionally, following the name and one or more blanks, a standard name modifier. The name contains no white space (underscores separate the words, in practice) and identifies the physical quantity. The modifier is used to describe a quantity which is related to another variable with the modified standard name. Details are provided in the convention section on [Standard Name](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#standard-name), and examples of modifiers are given in [Appendix C](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#standard-name-modifiers). +The text string is made up of two parts: the name (from the CF Standard Names table), and optionally, following the name and one or more blanks, a standard name modifier. +The name contains no white space (underscores separate the words, in practice) and identifies the physical quantity. +The modifier is used to describe a quantity which is related to another variable with the modified standard name. +Details are provided in the convention section on [Standard Name](http://cfconventions.org/1.6.html#standard-name), and examples of modifiers are given in [Appendix C](http://cfconventions.org/1.6.html#standard-name-modifiers). -Several attributes are required for every standard name: the canonical units, which are *typical* units of the physical quantity, and the description, which clarifies related quantities and meanings of the standard name (but is not strictly a definition per se). Older standard names may not have a description. +Several attributes are required for every standard name: the canonical units, which are *typical* units of the physical quantity, and the description, which clarifies related quantities and meanings of the standard name (but is not strictly a definition per se). +Older standard names may not have a description. In addition, standard names that come from certain sources may have GRIB parameter code(s) and/or AMIP identifiers; these are not generally required. - ### What is the structure of a good standard name? -A good standard name will typically include several characteristics that, together, characterize your variable. Common characteristics, or *facets*, include (with examples in parentheses): +A good standard name will typically include several characteristics that, together, characterize your variable. +Common characteristics, or *facets*, include (with examples in parentheses): * medium or realm of the entity (land, or sea_ice), * a transformation component (flux, or concentration_of), @@ -425,14 +387,16 @@ A good standard name will typically include several characteristics that, togeth * a state, qualifying the substance or process (atomic, or frozen), and * a quantity being measured. -The order is not rule-based; the goal is to make the name as clear and natural as possible. An example standard name with most of the above is mole_concentration_of_atomic_nitrogen_in_air (quantity-transformation-state-substance-medium). +The order is not rule-based; the goal is to make the name as clear and natural as possible. +An example standard name with most of the above is mole_concentration_of_atomic_nitrogen_in_air (quantity-transformation-state-substance-medium). -Several structural analyses have been performed on standard names. For more information, check out [What can be described in a standard name?](#stdnames_facets). - +Several structural analyses have been performed on standard names. +For more information, check out [What can be described in a standard name?](#stdnames_facets). ### What can be described in a standard name? -Most of the descriptive terms central to the nature of a substance or concept, including its relation to environmental context, can be described in the CF standard name. During the review process, the community attempts to normalize the terms to achieve the readability and interoperability goals of the vocabulary. +Most of the descriptive terms central to the nature of a substance or concept, including its relation to environmental context, can be described in the CF standard name. +During the review process, the community attempts to normalize the terms to achieve the readability and interoperability goals of the vocabulary. For an example, one list of the existing standard name facets, based on Raskin SWEET mapping and subsequent re-analysis by Graybeal, is as follows: @@ -451,8 +415,6 @@ above | below | accumulated in | Statistics Condition | assuming (Condition) | due to | excluding for | by | reported on | Artifact State - - ### What shouldn't be described in a standard name? The standard name should not include: @@ -463,19 +425,22 @@ The standard name should not include: * acronyms, or * geospatial location or similar deployment information, for example wind_speed_at_10_meter_platform. -In many cases the standard name is qualified by a specific detail, for example area_type, whose value may change from one set of observations to another or one observation to another. In these cases the definition for the standard name references one or more attributes or variables where the additional qualifying information may be found. ([Standard name *modifiers*](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#standard-name-modifiers) and [cell_methods](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#cell-methods) may also be used for this purpose.) In this way the divergence of the standard names is minimized, and interoperability increased. - - +In many cases the standard name is qualified by a specific detail, for example area_type, whose value may change from one set of observations to another or one observation to another. +In these cases the definition for the standard name references one or more attributes or variables where the additional qualifying information may be found. +([Standard name *modifiers*](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#standard-name-modifiers) and [cell_methods](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#cell-methods) may also be used for this purpose.) +In this way the divergence of the standard names is minimized, and interoperability increased. ### Are there common standard name phrases that get re-used? -Yes, there are phrases and patterns that reappear in different names. If you have to build a lot of standard names for different types of variables, some existing analyses may be helpful; send a note to the CF-Metadata list for guidance. If you are creating just a few standard names, it will be easiest to send an initial request using your best guess for the names; the list members will perform the needed comparison to existing usage. - - +Yes, there are phrases and patterns that reappear in different names. +If you have to build a lot of standard names for different types of variables, some existing analyses may be helpful; send a note to the CF-Metadata list for guidance. +If you are creating just a few standard names, it will be easiest to send an initial request using your best guess for the names; the list members will perform the needed comparison to existing usage. ### Is there a grammar for standard names? -There is no adopted grammar for the standard names. Many investigations or partial forays into a standard grammar have been made. Among these efforts: +There is no adopted grammar for the standard names. +Many investigations or partial forays into a standard grammar have been made. +Among these efforts: * Karl Taylor ([list post](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2008/052705.html)): A different approach to standard name construction * Robert Muetzelfeldt ([list post](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2010/053657.html)): [A grammar for CF standard names](http://envarml.pbworks.com/w/page/8988920/FrontPage) / 1103 names @@ -485,20 +450,18 @@ There is no adopted grammar for the standard names. Many investigations or parti * John Graybeal (no list post): [auto-generated pseudo-CF names from CF components](https://github.com/graybealski/cf-conventions-work/blob/master/CF_SWEET_201401_Redacted.xlsx) (Excel) / 2523 names * Michael Piasecki/Peng Ji ([list post](http://mailman.cgd.ucar.edu/pipermail/cf-metadata/2012/055875.html)): [CF standard names organized by facets](http://edscvs.ccny.cuny.edu/cf/index.php?tema=4448) (TemaTres) / 9981 concepts - - ### Are there mappings of the standard name terms to other terms? -_This answer needs further development, to confirm these details and provide reference links. Please feel free to offer improvements._ +_This answer needs further development, to confirm these details and provide reference links. +Please feel free to offer improvements._ -Yes, perhaps most important of these is a mapping within the CF standard names vocabulary performed by a team at BODC. This provides SKOS-based relationships among CF terms, for example broader and narrower relations. +Yes, perhaps most important of these is a mapping within the CF standard names vocabulary performed by a team at BODC. +This provides SKOS-based relationships among CF terms, for example broader and narrower relations. The CF standard names also have been mapped to the Global Change Master Directory science keywords, and to terms from the SWEET Ontology. As of 2014, none of these mappings are regularly updated as new versions of the CF standard names are released. - - ### What tools exist to work with standard names? In addition to the results mentioned in the [mappings](#stdnames_mappings), other tools include: @@ -508,48 +471,45 @@ In addition to the results mentioned in the [mappings](#stdnames_mappings), othe * MMI Ontology Registry and Repository (RDF/SPARQL): http://mmisw.org/ont/cf/parameter * MMI's prototype CF Standard Name search service: https://mmisw.org/ont/mmi/cfonmap -These have been derived from the original XML, and as of this writing (2014) are being updated quickly whenever the original XML is changed. In fact, the NERC Vocabulary Server is updated simultaneously with the publication of the original XML document. - - - +These have been derived from the original XML, and as of this writing (2014) are being updated quickly whenever the original XML is changed. +In fact, the NERC Vocabulary Server is updated simultaneously with the publication of the original XML document. ### Are standard names ever removed from use? How? -Standard names can be 'deprecated' to indicate they are no longer recommended for use. Existing uses of the name will not cause an error, but new applications should not use a deprecated name. +Standard names can be 'deprecated' to indicate they are no longer recommended for use. +Existing uses of the name will not cause an error, but new applications should not use a deprecated name. Standard names are deprecated when their use becomes ambiguous or confusing, or to say it another way, when they are replaced by one or more terms that are more appropriate (as determined by the standard names community). -The technical process involving deprecation of a standard name is that it is turned into an alias in the standard names XML file. The alias includes a pointer to the standard name most closely replacing the deprecated name. The alias is not shown in the HTML table of standard names. (As of August 2014, vocabulary servers typically do not show deprecated standard names in their term list, though the NERC Vocabulary Server has a separate list of the deprecated terms.) - -
Up to TOC
- - +The technical process involving deprecation of a standard name is that it is turned into an alias in the standard names XML file. +The alias includes a pointer to the standard name most closely replacing the deprecated name. +The alias is not shown in the HTML table of standard names. +(As of August 2014, vocabulary servers typically do not show deprecated standard names in their term list, though the NERC Vocabulary Server has a separate list of the deprecated terms.) ## Units in CF (UDUNITS) - - ### Why does CF use UDUNITS as its standard? -[UDUNITS](http://www.unidata.ucar.edu/software/udunits/) was specified in the original COARDS convention ("Where possible the units attribute should be formatted as per the recommendations in the Unidata udunits package"), and is a widely used standard with many tools and libraries. The package contains an extensive unit database, which is in XML format and user-extensible (though the extensions will not be compliant with CF). +[UDUNITS](http://www.unidata.ucar.edu/software/udunits/) was specified in the original COARDS convention ("Where possible the units attribute should be formatted as per the recommendations in the Unidata udunits package"), and is a widely used standard with many tools and libraries. +The package contains an extensive unit database, which is in XML format and user-extensible (though the extensions will not be compliant with CF). There are a few units CF allows that do not appear in UDUNITS; see [the related FAQ question](#udunits_missing). Note that CF depends on UDUNITS as a standard for formatting the units string, but not as a software package. - - ### Must a variable have the same units as its standard name's canonical units? -No, not exactly. If you have a variable with a standard name, its units must be *compatible with* (that is, convertible to) the canonical units of the standard name; but your variable's units do not have to be *the same* as the canonical units. For example, a variable with standard name wind_speed could have units miles/hour, since those can be converted to the canonical units of meters/second. +No, not exactly. +If you have a variable with a standard name, its units must be *compatible with* (that is, convertible to) the canonical units of the standard name; but your variable's units do not have to be *the same* as the canonical units. +For example, a variable with standard name wind_speed could have units miles/hour, since those can be converted to the canonical units of meters/second. If the units of the variable are not convertible to the standard name's canonical units, this indicates the variable is not really of the same type as the standard name. - - ### How do I specify units in CF? -UDUNITS has a small set of base units and another set of 'common' aliases that can be used as base units. It also specifies a large set of prefixes that can be prepended to the base units. (All of the components can be specified by their full strings, or by their 'symbol' abbreviations.) +UDUNITS has a small set of base units and another set of 'common' aliases that can be used as base units. +It also specifies a large set of prefixes that can be prepended to the base units. +(All of the components can be specified by their full strings, or by their 'symbol' abbreviations.) These combinations can be combined as follows in CF: @@ -561,21 +521,20 @@ You can review [basic examples in the UDUNITS documentation](https://www.unidata More complicated examples of units can be found in the CF Standard Names table, which lists the canonical units for each standard name. -UDUNITS terms can be found in XML on the [UDUNITS github pages](https://github.com/Unidata/UDUNITS-2), specifically in the files udunits2-*.xml under the [lib path](https://github.com/Unidata/UDUNITS-2/tree/master/lib). The terms can be easily viewed in the MMI ORR repository referenced in the [UDUNITS resources question](#udunits_refs). - - +UDUNITS terms can be found in XML on the [UDUNITS github pages](https://github.com/Unidata/UDUNITS-2), specifically in the files udunits2-*.xml under the [lib path](https://github.com/Unidata/UDUNITS-2/tree/master/lib). +The terms can be easily viewed in the MMI ORR repository referenced in the [UDUNITS resources question](#udunits_refs). ### How do units of time work? -Most time units in CF are specified as being of the form 'time-unit since timestamp', where time-unit is often 'seconds', and the most often used timestamp is '1970-01-01T00:00:00'. The prefixes specified for UDUNITS prefixes may be applied to the time-unit, for example `milliseconds since 1970-01-01T00:00:00` is a valid unit of time. - - +Most time units in CF are specified as being of the form 'time-unit since timestamp', where time-unit is often 'seconds', and the most often used timestamp is '1970-01-01T00:00:00'. +The prefixes specified for UDUNITS prefixes may be applied to the time-unit, for example `milliseconds since 1970-01-01T00:00:00` is a valid unit of time. ### Are there units in CF that aren't in UDUNITS? _This answer may need updating to reflect current content of UDUNITS._ -There are two units acceptable to CF that are not in the UDUNITS library: `sverdrup`, and `decibel` or `dB`. These have been requested for inclusion in future versions of the UDUNITS library. +There are two units acceptable to CF that are not in the UDUNITS library: `sverdrup`, and `decibel` or `dB`. +These have been requested for inclusion in future versions of the UDUNITS library. The unit `PSU` or `practical salinity unit` was used for salinity terms in CF, but is no longer used; rather, this is considered a dimensionless quantity (unit of 1). @@ -584,8 +543,6 @@ Details of the CF units not in UDUNITS: * sverdrup: measure of volume transport, equivalent to 1 million cubic metres per second (264,000,000 USgal/s). Its symbol is Sv, which conflicts with the SI unit symbol for sievert. * decibel: a logarithmic measure of relative acoustic or energy intensity; symbol dB, db, or dbel (the reference level, needed for logarithmic units, is specified in the standard names that use this canonical unit) - - ### Are there other good resources about UDUNITS? The [UDUNITS-2 GitHub repository](https://github.com/Unidata/UDUNITS-2) contains working code and documentation. @@ -604,36 +561,27 @@ The strings (names) corresponding to accepted UDUNITS can be found in the UDUNIT The repository also contains codes for each of the defined units in UDUNITS, which can be used if a unique identifier is needed to refer to a specific UDUNITS unit. -
Up to TOC
- - - ## Maintaining the CF standard - - ### Who physically maintains the standards documentation? Alison Pamment of the [Science and Technologies Facility Council](http://stfc.ac.uk) maintains the CF Standard Names documentation. -A team at Lawrence Livermore National Lab maintains documents and content on the CF web site; Matthew Harris is the primary updater of that site. As the site is maintained in a GitHub repository (see [this item](#where_docs), other members of the community may contribute modifications for inclusion on the site. - - +A team at Lawrence Livermore National Lab maintains documents and content on the CF web site; Matthew Harris is the primary updater of that site. +As the site is maintained in a GitHub repository (see [this item](#where_docs), other members of the community may contribute modifications for inclusion on the site. ### Where is the documentation stored? The documentation is stored on [this GitHub repository](https://github.com/cf-convention/cf-convention.github.io), and its format is converted using Jekyll to present it on the CF web site. - - ### Can I fork (get a copy of) the repository? -Yes, the repository is public and can be forked. We suggest you contact CF via the CF-metadata mail list before making pull requests, however. There are various maintenance processes going on behind the scenes to update the various CF content, so changing files directly may not produce the desired results. - - +Yes, the repository is public and can be forked. +We suggest you contact CF via the CF-metadata mail list before making pull requests, however. +There are various maintenance processes going on behind the scenes to update the various CF content, so changing files directly may not produce the desired results. ### How can I submit suggested changes? -Once you understand the procedure by which your suggested changes should be approved (e.g., email approval on the CF-metadata list, a trac ticket, or some other arrangement), you can submit suggested changes as a pull request on the appropriate content. However, as noted above, this should first be agreed with the person overseeing that content. +Once you understand the procedure by which your suggested changes should be approved (e.g., email approval on the CF-metadata list, a trac ticket, or some other arrangement), you can submit suggested changes as a pull request on the appropriate content. +However, as noted above, this should first be agreed with the person overseeing that content. -
Up to TOC
diff --git a/index.md b/index.md index 4b796a58..ad412377 100755 --- a/index.md +++ b/index.md @@ -20,7 +20,8 @@ The CF convention includes a standard name table, which defines strings that ide --- -CF is developed through open discussion on GitHub. If you would like to propose a change, make a suggestion, report a problem or ask a question, please [see here][discussion]. +CF is developed through open discussion on GitHub. +If you would like to propose a change, make a suggestion, report a problem or ask a question, please [see here][discussion]. Changes are decided according to the CF [governance arrangements][governance]. The CF community embraces a philosophy of producing excellence by maintaining an open and welcoming culture and an environment that promotes debate and inquiry in a respectful, bold and intellectually rigorous fashion. diff --git a/latest.md b/latest.md index 51865751..52b40111 100755 --- a/latest.md +++ b/latest.md @@ -5,6 +5,4 @@ title: Latest # Latest CF Conventions Documents -Please see the [conventions page](conventions.html) for the CF conventions -and the [standard name page](standard-names.html) for the CF standard name -table and other CF controlled vocabulary. \ No newline at end of file +Please see the [conventions page](conventions.html) for the CF conventions and the [standard name page](standard-names.html) for the CF standard name table and other CF controlled vocabulary. diff --git a/rules.md b/rules.md index 27995946..036d874b 100755 --- a/rules.md +++ b/rules.md @@ -5,37 +5,52 @@ title: Rules # Rules for CF Conventions Changes -

New proposals are to be made in github issues using the template, including verbatim changes proposed to the text of standard document and the conformance document.

+New proposals are to be made in github issues using the template, including verbatim changes proposed to the text of standard document and the conformance document. -

A member of the conventions committee, or another suitably qualified person, volunteers to moderate the discussion. If no-one volunteers, the chairman of the committee will ask someone to do it.

+A member of the conventions committee, or another suitably qualified person, volunteers to moderate the discussion. +If no-one volunteers, the chairman of the committee will ask someone to do it. -

The discussion takes place on github issues and all may participate.

+The discussion takes place on github issues and all may participate. -

The moderator periodically summarises discussion on github, keeps it moving forward and tries to achieve a consensus. It is expected that everyone with an interest will contribute to the discussion and to achieving a consensus during this stage. During the discussion, if an objection is raised, answered and not reasserted, the moderator will assume the objection has been dropped. However, since consensus is the best outcome, it will be helpful if anyone who expresses an objection explicitly withdraws it on changing their mind or deciding to accept the majority view.

+The moderator periodically summarises discussion on github, keeps it moving forward and tries to achieve a consensus. +It is expected that everyone with an interest will contribute to the discussion and to achieving a consensus during this stage. +During the discussion, if an objection is raised, answered and not reasserted, the moderator will assume the objection has been dropped. +However, since consensus is the best outcome, it will be helpful if anyone who expresses an objection explicitly withdraws it on changing their mind or deciding to accept the majority view. -

The moderator is encouraged to organize conference calls and/or webex-type interactions if this might help resolve an issue more quickly.

+The moderator is encouraged to organize conference calls and/or webex-type interactions if this might help resolve an issue more quickly. -

It will be helpful if a test netCDF file is provided as early as possible during the discussion. However, several variants of the proposal may be discussed, and the proposer may not be able to provide test netCDF files for all of them.

+It will be helpful if a test netCDF file is provided as early as possible during the discussion. +However, several variants of the proposal may be discussed, and the proposer may not be able to provide test netCDF files for all of them. -

When three weeks have passed with no contributions being made, the moderator should attempt to move toward a decision on the proposal by summarising the discussion and indicating the outcome as consensus, near consensus, or not near consensus (see below) on making the proposed change. Since several versions of the proposal might have been discussed, the summary should make clear which one, if any, would be adopted. The moderator will then invite further comment on the proposal, as summarised. If further comments are made i.e. the discussion restarts, this step is repeated.

+When three weeks have passed with no contributions being made, the moderator should attempt to move toward a decision on the proposal by summarising the discussion and indicating the outcome as consensus, near consensus, or not near consensus (see below) on making the proposed change. +Since several versions of the proposal might have been discussed, the summary should make clear which one, if any, would be adopted. +The moderator will then invite further comment on the proposal, as summarised. +If further comments are made i.e. the discussion restarts, this step is repeated. -

Once the summary has been made, if the test netCDF file does not yet exist, it must be created (unless the summary suggests the proposal should be rejected). When three weeks have passed with no contributions following a summary, and providing a test file exists (if appropriate), a decision is reached in one of the following ways:

+Once the summary has been made, if the test netCDF file does not yet exist, it must be created (unless the summary suggests the proposal should be rejected). +When three weeks have passed with no contributions following a summary, and providing a test file exists (if appropriate), a decision is reached in one of the following ways: -

Consensus: Accept the proposal if there is no outstanding objection, and at least three contributors have expressed support for it, including at least two members of the conventions committee. If the moderator personally expresses support, he or she can be counted among the supporters.

+Consensus: Accept the proposal if there is no outstanding objection, and at least three contributors have expressed support for it, including at least two members of the conventions committee. +If the moderator personally expresses support, he or she can be counted among the supporters. -

Near consensus: If the conditions for consensus are not met but the moderator's summary is that consensus has nearly been achieved, accept the proposal if all, or all but one, of the conventions committee vote in favour of it. The moderator will call for votes and all members should vote.

+Near consensus: If the conditions for consensus are not met but the moderator's summary is that consensus has nearly been achieved, accept the proposal if all, or all but one, of the conventions committee vote in favour of it. +The moderator will call for votes and all members should vote. -

Not near consensus: No change to standard.

+Not near consensus: No change to standard. -

The github issue is then closed by the moderator stating the outcome.

+The github issue is then closed by the moderator stating the outcome. -

If the change is accepted, the standard document should be updated, the CF convention version number incremented, and the conformance document updated.

+If the change is accepted, the standard document should be updated, the CF convention version number incremented, and the conformance document updated. -

The author of the proposal should be added to the list of contributing authors of the CF convention.

+The author of the proposal should be added to the list of contributing authors of the CF convention. -

If the change, once implemented in the conventions, subsequently turns out to be materially flawed, meaning that data written following the convention could be somehow erroneous or ambiguous, a github issue should urgently be opened to discuss whether to revoke the change. If this is agreed by a majority of the committee, a new version of the conventions will be prepared immediately, with the second digit of the version number incremented, and will be recommended to be used instead of the flawed version. The flawed version will be deprecated by a statement in the standard document and the conformance document. However, any data written with the flawed version will not be invalidated, although it may be problematic for users. Errors or lack of clarity in wording, when the convention itself is not at fault, can be corrected by defect tickets on the usual schedule.

+If the change, once implemented in the conventions, subsequently turns out to be materially flawed, meaning that data written following the convention could be somehow erroneous or ambiguous, a github issue should urgently be opened to discuss whether to revoke the change. +If this is agreed by a majority of the committee, a new version of the conventions will be prepared immediately, with the second digit of the version number incremented, and will be recommended to be used instead of the flawed version. +The flawed version will be deprecated by a statement in the standard document and the conformance document. +However, any data written with the flawed version will not be invalidated, although it may be problematic for users. +Errors or lack of clarity in wording, when the convention itself is not at fault, can be corrected by defect tickets on the usual schedule. -

All versions of the standard and conformance document should be kept available online, with their github issues and a history of changes.

+All versions of the standard and conformance document should be kept available online, with their github issues and a history of changes. ## Additional rules relating to the CF data model @@ -43,12 +58,16 @@ The CF data model will guide the development of CF by providing a framework for All new proposals will be assessed to see if the new features defined in the proposal map onto the CF data model. -The assessment will be carried out by a member of the conventions committee or another suitably qualified person. If no-one volunteers, the chairman of the committee will ask someone to do it. +The assessment will be carried out by a member of the conventions committee or another suitably qualified person. +If no-one volunteers, the chairman of the committee will ask someone to do it. If the proposal maps onto the existing CF data model then no modifications to the data model are required. Otherwise an attempt must be made to modify the proposal so that its new features do map onto the CF data model, and in such a way that the proposal's intent is not compromised. -If the proposal cannot be acceptably modified to conform to the existing data model, then the data model will need to be modified to accommodate the new features. If the data model may be extended or generalised in some way that allows the new features but does not affect its existing constructs and relationships, the proposal is considered backwards compatible. This is the preferred solution. +If the proposal cannot be acceptably modified to conform to the existing data model, then the data model will need to be modified to accommodate the new features. +If the data model may be extended or generalised in some way that allows the new features but does not affect its existing constructs and relationships, the proposal is considered backwards compatible. +This is the preferred solution. -Any changes to the data model must be described verbatim as part of the proposal discussion, including any modified or new data model diagrams. However, to facilitate the progress of a proposal that requires data model changes, it is sufficient for the general nature of the data model modifications to be identified, on the understanding that the data model text will be updated in detail at a later date, possibly after the proposal has been accepted. \ No newline at end of file +Any changes to the data model must be described verbatim as part of the proposal discussion, including any modified or new data model diagrams. +However, to facilitate the progress of a proposal that requires data model changes, it is sufficient for the general nature of the data model modifications to be identified, on the understanding that the data model text will be updated in detail at a later date, possibly after the proposal has been accepted. diff --git a/software.md b/software.md index cfa0c286..08ddc854 100644 --- a/software.md +++ b/software.md @@ -4,14 +4,13 @@ title: Software that "Understands" CF Data --- # Software that "Understands" CF Data + This page lists sofware packages that "understand" CF Data. -If you have any additions or corrections for this page, -please submit an issue on the [CF Website GitHub repo][website-repo] -(see the [Contributing Guide][website-contrib] for more details). +If you have any additions or corrections for this page, please submit an issue on the [CF Website GitHub repo][website-repo] (see the [Contributing Guide][website-contrib] for more details). For a software package to be listed on this page, it must .... -The description of each software package should give some indication -of the level of support for CF. + +The description of each software package should give some indication of the level of support for CF. [website-repo]: https://github.com/cf-convention/cf-convention.github.io [website-contrib]: https://github.com/cf-convention/cf-convention.github.io/blob/master/CONTRIBUTING.md @@ -19,89 +18,71 @@ of the level of support for CF. ## CF Compliance Checkers ### cf-checker - Python Tool for Compliance Checking + The [cf-checker](https://github.com/cedadev/cf-checker) is a python tool to check compliance of netCDF files against the CF Convention. -It can be run as a command-line tool, via a web interface (available at [NCAS](https://github.com/cedadev/cf-checker) -and [CEDA](http://wps-web1.ceda.ac.uk/submit/form?proc_id=CFChecker)) or imported as a python library. -The cf-checker verifies conformance according to the requirements and recommendations laid out in the -[CF Conformance Document](https://cfconventions.org/cf-conventions/conformance.html). +It can be run as a command-line tool, via a web interface (available at [NCAS](https://github.com/cedadev/cf-checker) and [CEDA](http://wps-web1.ceda.ac.uk/submit/form?proc_id=CFChecker)) or imported as a python library. +The cf-checker verifies conformance according to the requirements and recommendations laid out in the [CF Conformance Document](https://cfconventions.org/cf-conventions/conformance.html). It is possible to check conformance against any CF version. ### IOOS Compliance Checker -The [IOOS Compliance Checker](https://github.com/ioos/compliance-checker) -is a python based tool for data providers to check for completeness -and community standard compliance of local or remote netCDF files against CF, -[ACDD](http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery_1-3), -and [IOOS Metadata Profile](https://ioos.github.io/ioos-metadata) file standards. -The Compliance Checker can be used as a command-line tool or as a library -that can be integrated into other software. - -The Compliance Checker also includes a [web-based version](https://data.ioos.us/compliance/index.html) -that enables a broader audience and improve accessibility for the checker. -With the web version, providers can simply provide a link or upload their datasets -and get the full suite of capabilities that Compliance Checker offers. +The [IOOS Compliance Checker](https://github.com/ioos/compliance-checker) is a python based tool for data providers to check for completeness and community standard compliance of local or remote netCDF files against CF, [ACDD](http://wiki.esipfed.org/index.php/Attribute_Convention_for_Data_Discovery_1-3), and [IOOS Metadata Profile](https://ioos.github.io/ioos-metadata) file standards. +The Compliance Checker can be used as a command-line tool or as a library that can be integrated into other software. + +The Compliance Checker also includes a [web-based version](https://data.ioos.us/compliance/index.html) that enables a broader audience and improve accessibility for the checker. +With the web version, providers can simply provide a link or upload their datasets and get the full suite of capabilities that Compliance Checker offers. ## Free and Open Source Software Packages ### cfdm - Python CF Data Model Package -The [cfdm Python package](https://ncas-cms.github.io/cfdm) implements -the [CF data model](https://doi.org/10.5194/gmd-10-4619-2017) -for its internal data structures and so is able to process any CF-compliant dataset. -It is not strict about CF-compliance, however, so that partially conformant datasets -may be ingested from existing datasets and written to new datasets. + +The [cfdm Python package](https://ncas-cms.github.io/cfdm) implements the [CF data model](https://doi.org/10.5194/gmd-10-4619-2017) for its internal data structures and so is able to process any CF-compliant dataset. +It is not strict about CF-compliance, however, so that partially conformant datasets may be ingested from existing datasets and written to new datasets. This is so that datasets which are partially conformant may nonetheless be modified in memory. ### cf-python - CF Python Package -The [Python cf package, "cf-python"](https://ncas-cms.github.io/cf-python/), -is an Earth Science data analysis library. -It is built on [cfdm](#cfdm---python-cf-data-model-package) and implements the CF data model -for its internal data structures so is able to process any CF-compliant dataset. -It can read, write and inspect field constructs and manipulate the data and metadata therein -by means of statistical operations, collapsing, subspacing, regridding and more. + +The [Python cf package, "cf-python"](https://ncas-cms.github.io/cf-python/), is an Earth Science data analysis library. +It is built on [cfdm](#cfdm---python-cf-data-model-package) and implements the CF data model for its internal data structures so is able to process any CF-compliant dataset. +It can read, write and inspect field constructs and manipulate the data and metadata therein by means of statistical operations, collapsing, subspacing, regridding and more. Field constructs from cf can also be visualised with the [cf-plot package](#cf-plot---cf-python-plotting-package). ### cf-plot - CF Python Plotting package -cf-plot is a set of Python functions for making common contour, vector -and line plots that climate researchers use. -cf-plot generally uses [cf-python](#cf-python---cf-python-package) -to present the data and CF attributes for plotting. -It can also use numpy arrays of data as the input fields -making for flexible plotting of data. + +cf-plot is a set of Python functions for making common contour, vector and line plots that climate researchers use. +cf-plot generally uses [cf-python](#cf-python---cf-python-package) to present the data and CF attributes for plotting. +It can also use numpy arrays of data as the input fields making for flexible plotting of data. cf-plot uses the Python numpy, matplotlib and scipy libraries. ### Iris - Python library for analysing and visualising Earth science data -[Iris](https://scitools.org.uk/iris/docs/latest/) implements a data model based on the CF conventions -giving you a powerful, format-agnostic interface for working with your data. -It excels when working with multi-dimensional Earth Science data, -where tabular representations become unwieldy and inefficient. -CF Standard names, units, and coordinate metadata are built into Iris, -giving you a rich and expressive interface for maintaining an accurate representation of your data. +[Iris](https://scitools.org.uk/iris/docs/latest/) implements a data model based on the CF conventions giving you a powerful, format-agnostic interface for working with your data. +It excels when working with multi-dimensional Earth Science data, where tabular representations become unwieldy and inefficient. + +CF Standard names, units, and coordinate metadata are built into Iris, giving you a rich and expressive interface for maintaining an accurate representation of your data. ### netCDF Flattener - Flatten netCDF files -The [netCDF Flattener](https://gitlab.eumetsat.int/open-source/netcdf-flattener/) Python package takes netCDF objects that use groups and flattens them -while preserving references as described in the [Groups section](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#groups) -of the CF Conventions. + +The [netCDF Flattener](https://gitlab.eumetsat.int/open-source/netcdf-flattener/) Python package takes netCDF objects that use groups and flattens them while preserving references as described in the [Groups section](http://cfconventions.org/Data/cf-conventions/cf-conventions-1.10/cf-conventions.html#groups) of the CF Conventions. The resulting object is logically equivalent to the original, and can be processed by software that isn't able to work with files that use netCDF-4 groups. ### netCDF-Java Library + The [netCDF Java library](https://www.unidata.ucar.edu/software/netcdf-java/) provides an interface for scientific data access. It can be used to read scientific data from a variety of file formats including netCDF, HDF, GRIB, BUFR, and many others, as well as a variety of remote data access protocols. -It implements the [Unidata Common Data Model](https://docs.unidata.ucar.edu/netcdf-java/current/userguide/common_data_model_overview.html) -which uses CF and other metadata convention in its Coordinate System and Scientific Feature Type layers. +It implements the [Unidata Common Data Model](https://docs.unidata.ucar.edu/netcdf-java/current/userguide/common_data_model_overview.html) which uses CF and other metadata convention in its Coordinate System and Scientific Feature Type layers. NetCDF-Java can write netCDF-3/4 files that conform to the CF Metadata Conventions. ### THREDDS Data Server (TDS) -The [THREDDS Data Server (TDS)](https://www.unidata.ucar.edu/software/tds/) is a web server that provides metadata and data access for scientific datasets, -using OPeNDAP, OGC WMS and WCS, HTTP, and other remote data access protocols. + +The [THREDDS Data Server (TDS)](https://www.unidata.ucar.edu/software/tds/) is a web server that provides metadata and data access for scientific datasets, using OPeNDAP, OGC WMS and WCS, HTTP, and other remote data access protocols. It is also capable of mapping CF metadata to ISO-19115 though the use of ncISO. The TDS can use the NetCDF Markup Language (NcML) to modify datasets in-memory to aid in CF conformance without the need to rewrite the files as stored on disk. The NetCDF Subset Service allows users to subset CF compliant datasets in coordinate space using a REST API. The service returns subsets as CF compliant netCDF-3/4 files, in addition to other formats. ### xarray - Python Package for working with n-D labeled arrays -[Xarray](http://xarray.pydata.org/) is a python package designed for working with -labelled, multi-dimensional array data, built around the netCDF data model. -It uses CF conventions in several ways, such as encoding / decoding variables -and interpreting metadata for visualization. + +[Xarray](http://xarray.pydata.org/) is a python package designed for working with labelled, multi-dimensional array data, built around the netCDF data model. +It uses CF conventions in several ways, such as encoding / decoding variables and interpreting metadata for visualization. ## Commercial Software Packages diff --git a/standard_name_rules.md b/standard_name_rules.md index f6bfc4c3..343664cb 100644 --- a/standard_name_rules.md +++ b/standard_name_rules.md @@ -5,46 +5,56 @@ title: Vocabulary rules # Rules for Changes to CF Standard Names, Area Types and Standardized Region List Vocabularies -

These rules apply only to changes in CF controlled vocabularies. The rules for changes to the CF conventions themselves are given here.

+**These rules apply only to changes in CF controlled vocabularies. +The rules for changes to the CF conventions themselves are given [here](http://cfconventions.org/rules.html).** -

New proposals are made by opening a new issue in the cf-convention/discuss github repository. The 'Standard Names' template should be used, even if the proposal relates to one of the other vocabularies.

+New proposals are made by opening a new issue in the cf-convention/discuss github repository. +The 'Standard Names' template should be used, even if the proposal relates to one of the other vocabularies. -

Proposals may be for: -
(a) new term(s) to be added; -
(b) change to existing term(s) i.e. creation of alias(es) -
(c) clarification/correction of description or units of existing term(s).

+Proposals may be for: +- new term(s) to be added; +- change to existing term(s) i.e. creation of alias(es) +- clarification/correction of description or units of existing term(s). -

The discussion will be moderated by the CF standard names secretary, or another person familiar with the information management procedures for maintaining the published vocabularies.

+The discussion will be moderated by the CF standard names secretary, or another person familiar with the information management procedures for maintaining the published vocabularies. -

The discussion takes place on github issues and all may participate.

+The discussion takes place on github issues and all may participate. -

A status page summarizing the progress of standard name proposals through the discussion process may also be viewed in the CEDA vocabulary editor.

+A status page summarizing the progress of standard name proposals through the discussion process may also be viewed in the +[CEDA vocabulary editor](http://cfeditor.ceda.ac.uk/proposals/1?status=active&namefilter=&proposerfilter=&descfilter=&filter+and+display=filter). -

If a proposal is received for a new vocabulary term that follows the same syntactic patterns as existing terms, and whose description can also be based on existing term descriptions, the proposal can be accepted after brief discussion, subject to checking by the moderator.

+If a proposal is received for a new vocabulary term that follows the same syntactic patterns as existing terms, and whose description can also be based on existing term descriptions, the proposal can be accepted after brief discussion, subject to checking by the moderator. -

For proposals that require more discussion, the moderator periodically summarises the current status on github, keeps it moving forward and tries to achieve a consensus. It is expected that everyone with an interest will contribute to the discussion and to achieving a consensus during this stage. During the discussion, if an objection is raised, answered and not reasserted, the moderator will assume the objection has been dropped. However, since consensus is the best outcome, it will be helpful if anyone who expresses an objection explicitly withdraws it on changing their mind or deciding to accept the majority view.

+For proposals that require more discussion, the moderator periodically summarises the current status on github, keeps it moving forward and tries to achieve a consensus. +It is expected that everyone with an interest will contribute to the discussion and to achieving a consensus during this stage. +During the discussion, if an objection is raised, answered and not reasserted, the moderator will assume the objection has been dropped. +However, since consensus is the best outcome, it will be helpful if anyone who expresses an objection explicitly withdraws it on changing their mind or deciding to accept the majority view. -

If a consensus, or near consensus, view can not be achieved by discussion the moderator can ask the standard names committee to vote on a proposal. The committee's decision is final.

+If a consensus, or near consensus, view can not be achieved by discussion the moderator can ask the standard names committee to vote on a proposal. +The committee's decision is final. -

If three weeks have passed with no contributions being made the moderator should attempt to reinvigorate the discussion so that a conclusion can be reached.

+If three weeks have passed with no contributions being made the moderator should attempt to reinvigorate the discussion so that a conclusion can be reached. -

The moderator will summarize the outcome of the discussion of each vocabulary term proposal.

+The moderator will summarize the outcome of the discussion of each vocabulary term proposal. -

A proposal will be accepted if one of the following is true: -
(a) it is similar to existing terms and has been checked for conistency by the moderator; -
(b) consensus has been reached in favour of the proposal; -
(c) the moderator's summary indicates that consensus in favour of the proposal has nearly been achieved; -
(d) a majority of the standard names committee vote to accept the proposal.

+A proposal will be accepted if one of the following is true: +- it is similar to existing terms and has been checked for conistency by the moderator; +- consensus has been reached in favour of the proposal; +- the moderator's summary indicates that consensus in favour of the proposal has nearly been achieved; +- a majority of the standard names committee vote to accept the proposal. -

A proposal will be rejected if one of the following is true: -
(a) it duplicates an existing vocabulary term; -
(b) consensus has been reached against the proposal; -
(c) the moderator's summary indicates that consensus against the proposal has nearly been achieved; -
(d) a majority of the standard names committee vote to reject the proposal; -
(e) the proposer withdraws the proposal.

+A proposal will be rejected if one of the following is true: +- it duplicates an existing vocabulary term; +- consensus has been reached against the proposal; +- the moderator's summary indicates that consensus against the proposal has nearly been achieved; +- a majority of the standard names committee vote to reject the proposal; +- the proposer withdraws the proposal. -

The published vocabularies are updated approximately every 1 - 2 months. The publication date will be announced ahead of time via a github issue. Any names that have been formally accepted will be included in the next update, thus the period between acceptance and publication may vary from a few weeks to as little as a day.

+The published vocabularies are updated approximately every 1 - 2 months. +The publication date will be announced ahead of time via a github issue. +Any names that have been formally accepted will be included in the next update, thus the period between acceptance and publication may vary from a few weeks to as little as a day. -

The author of an accepted proposal should be added to the list of standard name contributors.

+The author of an accepted proposal should be added to the +[list of standard name contributors](http://cfconventions.org/Data/cf-standard-names/docs/standard-name-contributors.html). -

All versions of the CF controlled vocabularies should be kept available online, along with their github discussion issues.

+All versions of the CF controlled vocabularies should be kept available online, along with their github discussion issues. diff --git a/wkt-proj-4.md b/wkt-proj-4.md index cdf39082..0cf9c5c6 100755 --- a/wkt-proj-4.md +++ b/wkt-proj-4.md @@ -12,32 +12,25 @@ If you spot any errors or omissions, please email the authors (Phil Bentley and In Tables 1 and 2 the names of WKT PARAMETER elements follow the names of coordinate operation parameters defined in the [EPSG geodetic parameter registry](http://www.epsg-registry.org). -The following tables list translations of projection parameter names between CF and various other representations (such as OGC WKT, EPSG and PROJ.4). The information was obtained from various sources. +The following tables list translations of projection parameter names between CF and various other representations (such as OGC WKT, EPSG and PROJ.4). +The information was obtained from various sources. The various representations listed are: * **CF** The CF-1.6 (and possibly CF-1.7) parameter names - * **OGC WKT** The names following OGC WKT specification (used by GDAL/OGR and CadCorp(?)) - * **PROJ.4** The names used in the PROJ.4 software (​http://trac.osgeo.org/proj) - * **EPSG** The names and codes used in the EPSG Geodetic Parameter Dataset (http://www.epsg.org and http://www.epsg-registry.org) - * **GeoTIFF ID** The names used in the GeoTIFF raster format (http://trac.osgeo.org/geotiff) The following files are provided to list the various possible Datum, Ellipsoid and Prime Meridian names (in support of CF trac ticket [80](http://cf-trac.llnl.gov/trac/ticket/80)) * horiz_datum.csv - horizontal datum parameters for use as reference for CF-1.7 (source: GDAL/OGR, modified by Etienne Tourigny) - * ellipsoid.csv - Ellipsoid parameters from the EPSG database (source: GDAL/OGR) - * prime_meridian.csv - Prime Meridian parameters from the EPSG database (source: GDAL/OGR) - ### Table 1 - Existing (CF-1.6) CF Grid Mapping Attributes - | **CF Grid Mapping Attribute** | **Corresponding WKT Syntax** (1) | | earth_radius | SPHEROID["", , 0.0, ...] | false_easting | PARAMETER["False easting", ] @@ -99,7 +92,6 @@ The following files are provided to list the various possible Datum, Ellipsoid a ### Table 4 - Specific projection parameter names - --- |**Projection** |**Name** |**CF** |**OGC WKT** |**PROJ.4** |**EPSG name** |**EPSG code** |**GeoTIFF ID** |**Note** @@ -202,58 +194,59 @@ The following files are provided to list the various possible Datum, Ellipsoid a ### Units Information -Translation of units depends on if the crs is geographic or projected +Translation of units depends on if the crs is geographic or projected. -For a geographic crs (grid_mapping_name # "latitude_longitude"), units are angular. GEOGCS contains a UNIT node which gives the conversion to radians. When the crs is in degrees the following node is used: UNIT["degree",0.0174532925199433]. For a more complete description, see CT 1.0 section "7.3.19 UNIT" +For a geographic crs (grid_mapping_name # "latitude_longitude"), units are angular. +GEOGCS contains a UNIT node which gives the conversion to radians. +When the crs is in degrees the following node is used: UNIT["degree",0.0174532925199433]. +For a more complete description, see CT 1.0 section "7.3.19 UNIT" CF requires all value to be in degrees, which is specified in the dimension's units attribute ( lon:units # "degrees_east" / lat:units # "degrees_north" ), the udunits packages allows to transform from radians. -For a projected crs, units are linear. PROJCS must contains a UNIT node which gives the conversion into meters. For example, if the units are in kilometers the following node is used: UNIT["kilometre",1000]]. +For a projected crs, units are linear. +PROJCS must contains a UNIT node which gives the conversion into meters. +For example, if the units are in kilometers the following node is used: UNIT["kilometre",1000]]. In CF, units are given in the dimension's units attribute (xc:units # "m"). - ### Projection-specific notes EPSG codes below correspond to "EPSG dataset coordinate operation method" codes. - #### Lambert conformal 1SP / 2SP -The 1SP variant corresponds to EPSG code 9801 - Lambert Conic Conformal (1SP), with CF latitude_of_projection_origin#standard_parallel and WKT scale_factor#1. A scale factor less than 1 means that there are 2 standard parallels, but it cannot be translated to the CF 1SP variant, therefore the 2SP variant should be used instead. The 2SP variant corresponds to EPSG code 9802 - Lambert Conic Conformal (2SP). - +The 1SP variant corresponds to EPSG code 9801 - Lambert Conic Conformal (1SP), with CF latitude_of_projection_origin#standard_parallel and WKT scale_factor#1. +A scale factor less than 1 means that there are 2 standard parallels, but it cannot be translated to the CF 1SP variant, therefore the 2SP variant should be used instead. +The 2SP variant corresponds to EPSG code 9802 - Lambert Conic Conformal (2SP). #### Lambert cylindrical equal area -The scale_factor_at_projection_origin variant is not recommended as it does not translate to and from WKT/PROJ.4. Snyder formulas 10-2b and 10-2 can be used to relate scale_factor_at_projection_origin, standard_parallel1 and latitude_of_projection_origin but the latter is not part of this projection's parameters. It has been proposed to deprecate or remove this variant from the CF spec (see CF trac ticket [75](http://cf-trac.llnl.gov/trac/ticket/75)). - +The scale_factor_at_projection_origin variant is not recommended as it does not translate to and from WKT/PROJ.4. +Snyder formulas 10-2b and 10-2 can be used to relate scale_factor_at_projection_origin, standard_parallel1 and latitude_of_projection_origin but the latter is not part of this projection's parameters. +It has been proposed to deprecate or remove this variant from the CF spec (see CF trac ticket [75](http://cf-trac.llnl.gov/trac/ticket/75)). #### Mercator 1SP / 2SP The scale_factor_at_projection_origin variant corresponds to EPSG code 9804 - Mercator (1SP) or Mercator (variant A), and the standard_parallel variant corresponds to EPSG code 9805 - Mercator (2SP) or Mercator (variant B). - #### Polar stereographic -The standard_parallel variant corresponds to EPSG code 9829 - Polar Stereographic (Variant B), while the scale_factor_at_projection_origin variant corresponds to EPSG code 9810 - Polar Stereographic (Variant A). As WKT/PROJ.4 require the standard parallel, [Snyder] formula 21-7 can be used to compute it from scale_factor_at_projection_origin if that variant is used. - +The standard_parallel variant corresponds to EPSG code 9829 - Polar Stereographic (Variant B), while the scale_factor_at_projection_origin variant corresponds to EPSG code 9810 - Polar Stereographic (Variant A). +As WKT/PROJ.4 require the standard parallel, [Snyder] formula 21-7 can be used to compute it from scale_factor_at_projection_origin if that variant is used. #### Transverse Mercator Transverse Mercator can be translated to PROJ.4 using either +proj#tmerc (Transverse Mercator) or +proj#utm (Universal Transverse Mercator) by computing zone number from longitude_of_central_meridian. For example, a TM projection with longitude_of_central_meridian#-117 would have the corresponding PROJ.4 string: '+proj#utm +zone#11 +datum#NAD27 +units#m +no_defs ' - ## Mapping from CF Grid Mapping Attributes to CRS WKT Elements (previous table by Phil Bentley, Oct 2011) These __provisional__ mappings have been compiled to support, among other things, CF proposal [69](http://cfconventions.org/Data/Trac-tickets/69.html). If you spot any errors or omissions, please email the author or the CF mailing list, or else update this wiki page. -Mappings are only listed for the current set of CF grid mapping attributes -- there are a number of WKT elements, -and many CRS PARAMETERs, for which there are no corresponding CF attributes. +Mappings are only listed for the current set of CF grid mapping attributes -- there are a number of WKT elements, and many CRS PARAMETERs, for which there are no corresponding CF attributes. The order of attributes follows Table F.1 in the CF conventions document. -The names of WKT PARAMETER elements follow the names of coordinate operation parameters -defined in the [​EPSG geodetic parameter registry](http://www.epsg-registry.org). +The names of WKT PARAMETER elements follow the names of coordinate operation parameters defined in the [​EPSG geodetic parameter registry](http://www.epsg-registry.org). ---