forked from cf-convention/cf-convention.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
cf-conventions.html
executable file
·3598 lines (3513 loc) · 259 KB
/
cf-conventions.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>NetCDF Climate and Forecast (CF) Metadata Conventions</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><meta name="description" content="Abstract This document describes the CF conventions for climate and forecast metadata designed to promote the processing and sharing of files created with the netCDF Application Programmer Interface . The conventions define metadata that provide a definitive description of what the data in each variable represents, and of 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 CF conventions generalize and extend the COARDS conventions . The extensions include metadata that provides a precise definition of each variable via specification of a standard name, describes the vertical locations corresponding to dimensionless vertical coordinate values, and provides the spatial coordinates of non-rectilinear gridded data. Since climate and forecast data are often not simply representative of points in space/time, other extensions provide for the description of coordinate intervals, multidimensional cells and climatological time coordinates, and indicate how a data value is representative of an interval or cell. This standard also relaxes the COARDS constraints on dimension order and specifies methods for reducing the size of datasets."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="idm48159441408"></a>NetCDF Climate and Forecast (CF) Metadata Conventions</h1></div><div><h2 class="subtitle">Version 1.0, 28 October, 2003</h2></div><div><div class="authorgroup"><div class="author"><h3 class="author"><span class="firstname">Brian</span> <span class="surname">Eaton</span></h3><div class="affiliation"><span class="orgname"> NCAR <br></span></div></div><div class="author"><h3 class="author"><span class="firstname">Jonathan</span> <span class="surname">Gregory</span></h3><div class="affiliation"><span class="orgname"> Hadley Centre, UK Met Office <br></span></div></div><div class="author"><h3 class="author"><span class="firstname">Bob</span> <span class="surname">Drach</span></h3><div class="affiliation"><span class="orgname"> PCMDI, LLNL <br></span></div></div><div class="author"><h3 class="author"><span class="firstname">Karl</span> <span class="surname">Taylor</span></h3><div class="affiliation"><span class="orgname"> PCMDI, LLNL <br></span></div></div><div class="author"><h3 class="author"><span class="firstname">Steve</span> <span class="surname">Hankin</span></h3><div class="affiliation"><span class="orgname"> PMEL, NOAA <br></span></div></div></div></div><div><div class="othercredit"><h3 class="othercredit"></h3></div></div><div><div class="abstract"><p class="title"><b>Abstract</b></p><p>
This document describes the CF conventions for
climate and forecast metadata designed to promote
the processing and sharing of files created
with the netCDF Application Programmer Interface
[<a href="#netcdf" class="biblioref" title="[NetCDF]"><abbr class="abbrev">NetCDF</abbr></a>].
The conventions define metadata that
provide a definitive description of what the data
in each variable represents, and of 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.
</p><p>
The CF conventions generalize and extend the
COARDS conventions [<a href="#coards" class="biblioref" title="[COARDS]"><abbr class="abbrev">COARDS</abbr></a>].
The extensions
include metadata that provides a precise
definition of each variable via specification of
a standard name, describes the vertical locations
corresponding to dimensionless vertical coordinate
values, and provides the spatial coordinates of
non-rectilinear gridded data. Since climate and
forecast data are often not simply representative
of points in space/time, other extensions provide
for the description of coordinate intervals,
multidimensional cells and climatological time
coordinates, and indicate how a data value is
representative of an interval or cell. This
standard also relaxes the COARDS constraints
on dimension order and specifies methods for
reducing the size of datasets.
</p></div></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="preface"><a href="#idm48159438688">Preface</a></span></dt><dt><span class="chapter"><a href="#idm48159337920">1.
Introduction
</a></span></dt><dd><dl><dt><span class="section"><a href="#idm48159337184">1.1. Goals</a></span></dt><dt><span class="section"><a href="#terminology">1.2. Terminology</a></span></dt><dt><span class="section"><a href="#idm48159300752">1.3. Overview</a></span></dt><dt><span class="section"><a href="#coards-relationship">1.4. Relationship to the COARDS Conventions</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm48159165120">2.
NetCDF Files and Components
</a></span></dt><dd><dl><dt><span class="section"><a href="#idm48159162784">2.1. Filename</a></span></dt><dt><span class="section"><a href="#idm48159160992">2.2. Data Types</a></span></dt><dt><span class="section"><a href="#idm48159152864">2.3. Naming Conventions</a></span></dt><dt><span class="section"><a href="#dimensions">2.4. Dimensions</a></span></dt><dt><span class="section"><a href="#variables">2.5. Variables</a></span></dt><dd><dl><dt><span class="section"><a href="#missing-data">2.5.1. Missing Data</a></span></dt></dl></dd><dt><span class="section"><a href="#idm48159119552">2.6. Attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#identification-of-conventions">2.6.1. Identification of Conventions</a></span></dt><dt><span class="section"><a href="#description-of-file-contents">2.6.2. Description of file contents</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#idm48159018080">3.
Description of the Data
</a></span></dt><dd><dl><dt><span class="section"><a href="#units">3.1. Units</a></span></dt><dt><span class="section"><a href="#long-name">3.2. Long Name</a></span></dt><dt><span class="section"><a href="#standard-name">3.3. Standard Name</a></span></dt><dt><span class="section"><a href="#ancillary-data">3.4. Ancillary Data</a></span></dt><dt><span class="section"><a href="#flags">3.5. Flags</a></span></dt></dl></dd><dt><span class="chapter"><a href="#coordinate-types">4.
Coordinate Types
</a></span></dt><dd><dl><dt><span class="section"><a href="#latitude-coordinate">4.1. Latitude Coordinate</a></span></dt><dt><span class="section"><a href="#longitude-coordinate">4.2. Longitude Coordinate</a></span></dt><dt><span class="section"><a href="#vertical-coordinate">4.3. Vertical (Height or Depth) Coordinate</a></span></dt><dd><dl><dt><span class="section"><a href="#idm48139872768">4.3.1. Dimensional Vertical Coordinate</a></span></dt><dt><span class="section"><a href="#dimensionless-vertical-coordinate">4.3.2. Dimensionless Vertical Coordinate</a></span></dt></dl></dd><dt><span class="section"><a href="#time-coordinate">4.4. Time Coordinate</a></span></dt><dd><dl><dt><span class="section"><a href="#calendar">4.4.1. Calendar</a></span></dt></dl></dd></dl></dd><dt><span class="chapter"><a href="#coordinate-system">5.
Coordinate Systems
</a></span></dt><dd><dl><dt><span class="section"><a href="#idm48139630144">5.1. Independent Latitude, Longitude, Vertical, and Time Axes</a></span></dt><dt><span class="section"><a href="#idm48139624288">5.2. Two-Dimensional Latitude, Longitude, Coordinate Variables</a></span></dt><dt><span class="section"><a href="#reduced-horizontal-grid">5.3. Reduced Horizontal Grid</a></span></dt><dt><span class="section"><a href="#idm48139604784">5.4. Timeseries of Station Data</a></span></dt><dt><span class="section"><a href="#idm48139598768">5.5. Trajectories</a></span></dt><dt><span class="section"><a href="#grid-mappings-and-projections">5.6. Grid Mappings and Projections</a></span></dt><dt><span class="section"><a href="#scalar-coordinate-variables">5.7. Scalar Coordinate Variables</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm48139484736">6.
Labels and Alternative Coordinates
</a></span></dt><dd><dl><dt><span class="section"><a href="#labels">6.1. Labels</a></span></dt><dd><dl><dt><span class="section"><a href="#geographic-regions">6.1.1. Geographic Regions</a></span></dt></dl></dd><dt><span class="section"><a href="#alternative-coordinates">6.2. Alternative Coordinates</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm48139448688">7.
Data Representative of Cells
</a></span></dt><dd><dl><dt><span class="section"><a href="#cell-boundaries">7.1. Cell Boundaries</a></span></dt><dt><span class="section"><a href="#cell-measures">7.2. Cell Measures</a></span></dt><dt><span class="section"><a href="#cell-methods">7.3. Cell Methods</a></span></dt><dt><span class="section"><a href="#climatological-statistics">7.4. Climatological Statistics</a></span></dt></dl></dd><dt><span class="chapter"><a href="#idm48139154416">8.
Reduction of Dataset Size
</a></span></dt><dd><dl><dt><span class="section"><a href="#packed-data">8.1. Packed Data</a></span></dt><dt><span class="section"><a href="#compression-by-gathering">8.2. Compression by Gathering</a></span></dt></dl></dd><dt><span class="appendix"><a href="#attribute-appendix">A. Attributes</a></span></dt><dt><span class="appendix"><a href="#standard-name-table-format">B. Standard Name Table Format</a></span></dt><dt><span class="appendix"><a href="#standard-name-modifiers">C. Standard Name Modifiers</a></span></dt><dt><span class="appendix"><a href="#dimensionless-v-coord">D. Dimensionless Vertical Coordinates</a></span></dt><dt><span class="appendix"><a href="#appendix-cell-methods">E. Cell Methods</a></span></dt><dt><span class="appendix"><a href="#appendix-grid-mappings">F. Grid Mappings</a></span></dt><dt><span class="appendix"><a href="#revhistory">G. Revision History</a></span></dt><dt><span class="bibliography"><a href="#idm48141692320">Bibliography</a></span></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>3.1. <a href="#idm48158996000">Supported Units</a></dt><dt>A.1. <a href="#idm48139082720">Attributes</a></dt><dt>C.1. <a href="#idm48138701040">Standard Name Modifiers</a></dt><dt>E.1. <a href="#idm48142038384">Cell Methods</a></dt><dt>F.1. <a href="#idm48141866512">Grid Mapping Attributes</a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>3.1. <a href="#idm48140043712">Use of <code class="varname">standard_name</code></a></dt><dt>3.2. <a href="#idm48140034128">Instrument data</a></dt><dt>3.3. <a href="#idm48140028816">A flag variable</a></dt><dt>4.1. <a href="#idm48139908384">Latitude axis</a></dt><dt>4.2. <a href="#idm48139894928">Longitude axis</a></dt><dt>4.3. <a href="#idm48139856544">Atmosphere sigma coordinate</a></dt><dt>4.4. <a href="#idm48139829888">Time axis</a></dt><dt>4.5. <a href="#idm48139804704">Perpetual time axis</a></dt><dt>4.6. <a href="#idm48139791440">Paleoclimate time axis</a></dt><dt>5.1. <a href="#idm48139628864">Independent coordinate variables</a></dt><dt>5.2. <a href="#idm48139622464">Two-dimensional coordinate variables</a></dt><dt>5.3. <a href="#idm48139611456">Reduced horizontal grid</a></dt><dt>5.4. <a href="#idm48139603456">Timeseries of station data</a></dt><dt>5.5. <a href="#idm48139597472">Trajectories</a></dt><dt>5.6. <a href="#idm48139584720">Rotated pole grid</a></dt><dt>5.7. <a href="#lambert-conformal-projection">Lambert conformal projection</a></dt><dt>5.8. <a href="#multiple-forecasts-from-single-analysis">Multiple forecasts from a single analysis</a></dt><dt>6.1. <a href="#idm48139480544">Several parcel trajectories</a></dt><dt>6.2. <a href="#idm48139474176">Northward heat transport in Atlantic Ocean</a></dt><dt>6.3. <a href="#idm48139469776">Model level numbers</a></dt><dt>7.1. <a href="#idm48139416384"> Cells on a latitude axis</a></dt><dt>7.2. <a href="#idm48139410672"> Cells in a non-rectangular grid</a></dt><dt>7.3. <a href="#idm48139395040"> Cell areas for a spherical geodesic grid</a></dt><dt>7.4. <a href="#idm48139378560"> Methods applied to a timeseries </a></dt><dt>7.5. <a href="#idm48139358720">Surface air temperature variance</a></dt><dt>7.6. <a href="#idm48139319152">Climatological seasons</a></dt><dt>7.7. <a href="#idm48139316320">Decadal averages for January</a></dt><dt>7.8. <a href="#idm48139312992">Temperature for each hour of the average day</a></dt><dt>7.9. <a href="#idm48139309616">Temperature for each hour of the typical climatological day</a></dt><dt>7.10. <a href="#idm48139306160">Monthly-maximum daily precipitation totals</a></dt><dt>8.1. <a href="#idm48139134000">Horizontal compression of a three-dimensional array</a></dt><dt>8.2. <a href="#idm48139126496">Compression of a three-dimensional field</a></dt><dt>B.1. <a href="#idm48138743968">A name table containing three entries</a></dt><dt>D.1. <a href="#atmosphere-natural-log-pressure-coordinate"> Atmosphere natural log pressure coordinate </a></dt><dt>D.2. <a href="#idm48138645344"> Atmosphere sigma coordinate </a></dt><dt>D.3. <a href="#idm48138635312"> Atmosphere hybrid sigma pressure coordinate </a></dt><dt>D.4. <a href="#atmosphere-hybrid-height-coordinate"> Atmosphere hybrid height coordinate </a></dt><dt>D.5. <a href="#idm48138589920"> Atmosphere smooth level vertical (SLEVE) coordinate </a></dt><dt>D.6. <a href="#idm48138576464"> Ocean sigma coordinate </a></dt><dt>D.7. <a href="#idm48138565936"> Ocean s-coordinate </a></dt><dt>D.8. <a href="#idm48138554000"> Ocean sigma over z coordinate </a></dt><dt>D.9. <a href="#idm48138541984"> Ocean double sigma coordinate </a></dt><dt>F.1. <a href="#idm48141981872"> Albers Equal Area</a></dt><dt>F.2. <a href="#azimuthal-equidistant">Azimuthal equidistant</a></dt><dt>F.3. <a href="#lambert-azimuthal-equal-area">Lambert azimuthal equal area</a></dt><dt>F.4. <a href="#idm48141938112">Lambert conformal</a></dt><dt>F.5. <a href="#polar-stereographic">Polar stereographic</a></dt><dt>F.6. <a href="#idm48141908000">Rotated pole</a></dt><dt>F.7. <a href="#idm48141896224">Stereographic</a></dt><dt>F.8. <a href="#idm48141881488">Transverse Mercator</a></dt></dl></div><div class="preface"><div class="titlepage"><div><div><h1 class="title"><a name="idm48159438688"></a>Preface</h1></div></div></div><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Home page:</span></dt><dd><p>
Contains links to: previous draft and current
working draft documents; applications for processing
CF conforming files; email list for discussion
about interpretation, clarification, and proposals
for changes or extensions to the current conventions.
<a class="ulink" href="http://www-pcmdi.llnl.gov/cf/" target="_top">http://www-pcmdi.llnl.gov/cf/</a>
</p></dd><dt><span class="term">Revision history:</span></dt><dd><p>
This document will updated as required to correct mistakes
or add new material required for completeness or clarity.
See <a class="xref" href="#revhistory" title="Appendix G. Revision History">Appendix G, <i>Revision History</i></a> for the full revision history.
Changes in the document use the following
mark-up style: <span class="newtext">new text</span>,
<span class="deletedtext">deleted text</span>, and
<span class="commenttext">[a comment]</span>.
</p></dd></dl></div><p>
</p></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idm48159337920"></a>Chapter 1.
Introduction
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#idm48159337184">1.1. Goals</a></span></dt><dt><span class="section"><a href="#terminology">1.2. Terminology</a></span></dt><dt><span class="section"><a href="#idm48159300752">1.3. Overview</a></span></dt><dt><span class="section"><a href="#coards-relationship">1.4. Relationship to the COARDS Conventions</a></span></dt></dl></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159337184"></a>1.1. Goals</h2></div></div></div><p>
The NetCDF library [<a href="#netcdf" class="biblioref" title="[NetCDF]"><abbr class="abbrev">NetCDF</abbr></a>] is
designed to read
and write data that has been structured according
to well-defined rules and is easily ported across
various computer platforms. The netCDF interface
enables but does not require the creation of
<span class="emphasis"><em>self-describing</em></span> datasets.
The purpose of the CF
conventions is to require conforming datasets
to contain sufficient metadata that they are
self-describing in the sense that each variable
in the file has an associated description of
what it represents, including physical units if
appropriate, and that each value can be located
in space (relative to earth-based coordinates)
and time.
</p><p>
An important benefit of a convention is that it
enables software tools to display data and perform
operations on specified subsets of the data
with minimal user intervention. It is possible
to provide the metadata describing how a field
is located in time and space in many different
ways that a human would immediately recognize as
equivalent. The purpose in restricting how the
metadata is represented is to make it practical
to write software that allows a machine to parse
that metadata and to automatically associate each
data value with its location in time and space. It
is equally important that the metadata be easy
for human users to write and to understand.
</p><p>
This standard is intended for use with climate
and forecast data, for atmosphere, surface and
ocean, and was designed with model-generated data
particularly in mind. We recognise that there are
limits to what a standard can practically cover;
we restrict ourselves to issues that we believe to
be of common and frequent concern in the design of
climate and forecast metadata. Our main purpose
therefore, is to propose a clear, adequate and
flexible definition of the metadata needed for
climate and forecast data. Although this is
specifically a netCDF standard, we feel that
most of the ideas are of wider application. The
metadata objects could be contained in file
formats other than netCDF. Conversion of the
metadata between files of different formats will
be facilitated if conventions for all formats
are based on similar ideas.
</p><p>
This convention is designed to be backward
compatible with the COARDS conventions [<a href="#coards" class="biblioref" title="[COARDS]"><abbr class="abbrev">COARDS</abbr></a>],
by which we mean that a conforming COARDS dataset
also conforms to the CF standard. Thus new
applications that implement the CF conventions
will be able to process COARDS datasets.
</p><p>
We have also striven to maximize conformance
to the COARDS standard, that is, wherever the
COARDS metadata conventions provide an adequate
description we require their use. Extensions to
COARDS are implemented in a manner such that the
content that doesn't depend on the extensions
is still accessible to applications that adhere
to the COARDS standard.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="terminology"></a>1.2. Terminology</h2></div></div></div><p>
The terms in this document that refer to
components of a netCDF file are defined in the
NetCDF User's Guide (NUG)
[<a href="#nug" class="biblioref" title="[NUG]"><abbr class="abbrev">NUG</abbr></a>] NUG.
Some of those
definitions are repeated below for convenience.
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">auxiliary coordinate variable</span></dt><dd><p>
Any netCDF variable that contains
coordinate data, but is not a coordinate
variable (in the sense of that term defined by the NUG
and used by this standard - see below). Unlike
coordinate variables, there is no relationship
between the name of an auxiliary coordinate
variable and the name(s) of its dimension(s).
</p></dd><dt><span class="term">boundary variable</span></dt><dd><p>
A boundary variable is associated with a variable that contains
coordinate data. When a data value provides information about
conditions in a cell occupying a region of space/time or some
other dimension, the boundary variable provides a description
of cell extent.
</p></dd><dt><span class="term">CDL syntax</span></dt><dd><p>
The ascii format used to describe the contents of a netCDF
file is called CDL (network Common Data form Language). This
format represents arrays using the indexing conventions of
the C programming language, i.e., index values start at 0, and in
multidimensional arrays, when indexing over the elements of
the array, it is the last declared dimension that is the fastest
varying in terms of file storage order. The netCDF utilities ncdump
and ncgen use this format (see
<a class="ulink" href="http://www.unidata.ucar.edu/packages/netcdf/guidef/guidef-15.html#HEADING15-0" target="_top">
chapter 10 of the NUG
</a>
). All examples
in this document use CDL syntax.
</p></dd><dt><span class="term">cell</span></dt><dd><p>
A region in one or more dimensions whose boundary can be described by a set of vertices. The term <span class="emphasis"><em>interval</em></span> is sometimes used for one-dimensional cells.
</p></dd><dt><span class="term">coordinate variable</span></dt><dd><p>
We use this term precisely as it is defined in section
<a class="ulink" href="http://www.unidata.ucar.edu/packages/netcdf/guidef/guidef-7.html#HEADING7-67" target="_top">
2.3.1 of the NUG
</a>
. It is a one-dimensional variable with the
same name as its dimension [e.g., <code class="varname">time(time)</code>], and
it is defined as a numeric data type with values
that are ordered monotonically. Missing values
are not allowed in coordinate variables.
</p></dd><dt><span class="term">grid mapping variable</span></dt><dd><p>
A variable used as a container for attributes that define a specific grid mapping. The type of the variable is arbitrary since it contains no data.
</p></dd><dt><span class="term">latitude dimension</span></dt><dd><p>
A dimension of a netCDF variable that has an associated latitude coordinate variable.
</p></dd><dt><span class="term">longitude dimension</span></dt><dd><p>
A dimension of a netCDF variable that has an associated longitude coordinate variable.
</p></dd><dt><span class="term">multidimensional coordinate variable</span></dt><dd><p>
An auxiliary coordinate variable that is multidimensional.
</p></dd><dt><span class="term">recommendation</span></dt><dd><p>
Recommendations in this convention are meant to provide advice that may be helpful for reducing common mistakes. In some cases we have recommended rather than required particular attributes in order to maintain backwards compatibility with COARDS. An application must not depend on a dataset's adherence to recommendations.
</p></dd><dt><span class="term">scalar coordinate variable</span></dt><dd><p>
A scalar variable that contains coordinate data. Functionally equivalent to either a size one coordinate variable or a size one auxiliary coordinate variable.
</p></dd><dt><span class="term">spatiotemporal dimension</span></dt><dd><p>
A dimension of a netCDF variable that is used to identify a location in time and/or space.
</p></dd><dt><span class="term">time dimension</span></dt><dd><p>
A dimension of a netCDF variable that has an associated time coordinate variable.
</p></dd><dt><span class="term">vertical dimension</span></dt><dd><p>
A dimension of a netCDF variable that has an associated vertical coordinate variable.
</p></dd></dl></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159300752"></a>1.3. Overview</h2></div></div></div><p>
No variable or dimension names are standardized
by this convention. Instead we follow the lead
of the NUG
and standardize only the names
of attributes and some of the values taken by
those attributes. The overview provided in this
section will be followed with more complete
descriptions in following sections.
<a class="xref" href="#attribute-appendix" title="Appendix A. Attributes">Appendix A, <i>Attributes</i></a>
contains a summary of all the attributes used
in this convention.
</p><p>
We recommend that the NUG defined attribute
<code class="varname">Conventions</code>
be given the string value "<code class="varname">CF-1.0</code>"
to identify datasets that conform to these
conventions.
</p><p>
The general description of a file's contents
should be contained in the following attributes:
<code class="varname">title</code>,
<code class="varname">history</code>,
<code class="varname">institution</code>,
<code class="varname">source</code>,
<code class="varname">comment</code>
and
<code class="varname">references</code>
(<a class="xref" href="#description-of-file-contents" title="2.6.2. Description of file contents">Section 2.6.2, “Description of file contents”</a>).
For backwards compatibility with COARDS none
of these attributes is required, but their
use is recommended to provide human readable
documentation of the file contents.
</p><p>
Each variable in a netCDF file has an associated
description which is provided by the attributes
<code class="varname">units</code>,
<code class="varname">long_name</code>, and
<code class="varname">standard_name</code>. The
<code class="varname">units</code>,
and <code class="varname">long_name</code>
attributes are defined in the NUG and the
<code class="varname">standard_name</code> attribute is
defined in this document.
</p><p>
The
<code class="varname">units</code>
attribute is required for all variables
that represent dimensional quantities (except for
boundary variables defined in
<a class="xref" href="#cell-boundaries" title="7.1. Cell Boundaries">Section 7.1, “Cell Boundaries”</a>.
The values of the
<code class="varname">units</code>
attributes are character
strings that are recognized by UNIDATA's Udunits
package
[<span class="citation"><a class="link" href="#udunits" title="UDUNITS Software Package">UDUNITS</a></span>],
(with exceptions allowed as discussed in
<a class="xref" href="#units" title="3.1. Units">Section 3.1, “Units”</a>).
</p><p>
The
<code class="varname">long_name</code>
and
<code class="varname">standard_name</code>
attributes are
used to describe the content of each variable. For
backwards compatibility with COARDS neither
is required, but use of at least one of them
is strongly recommended. The use of standard
names will facilitate the exchange of climate
and forecast data by providing unambiguous
identification of variables most commonly
analyzed.
</p><p>
Four types of coordinates receive special
treatment by these conventions: latitude,
longitude, vertical, and time. Every variable
must have associated metadata that allows
identification of each such coordinate that is
relevant. Two independent parts of the convention
allow this to be done. There are conventions that
identify the variables that contain the coordinate
data, and there are conventions that identify
the type of coordinate represented by that data.
</p><p>
There are two methods used to identify variables
that contain coordinate data. The first is to
use the NUG-defined "coordinate variables." <span class="emphasis"><em>The
use of coordinate variables is required for all
dimensions that correspond to one dimensional
space or time coordinates</em></span>. In cases where
coordinate variables are not applicable,
the variables containing coordinate data are
identified by the
<code class="varname">coordinates</code>
attribute.
</p><p>
Once the variables containing coordinate data are
identified, further conventions are required to
determine the type of coordinate represented by
each of these variables. Latitude, longitude,
and time coordinates are identified solely by
the value of their
<code class="varname">units</code>
attribute. Vertical
coordinates with units of pressure may also
be identified by the
<code class="varname">units</code>
attribute. Other
vertical coordinates must use the attribute
<code class="varname">positive</code>
which determines whether the direction of
increasing coordinate value is up or down. Because
identification of a coordinate type by its units
involves the use of an external software package
[<a href="#udunits" class="biblioref" title="[UDUNITS]"><abbr class="abbrev">UDUNITS</abbr></a>],
we provide the optional attribute
<code class="varname">axis</code>
for a direct identification of coordinates
that correspond to latitude, longitude, vertical,
or time axes.
</p><p>
Latitude, longitude, and time are defined
by internationally recognized standards,
and hence, identifying the coordinates of
these types is sufficient to locate data
values uniquely with respect to time and a
point on the earth's surface. On the other
hand identifying the vertical coordinate is
not necessarily sufficient to locate a data
value vertically with respect to the earth's
surface. In particular a model may output data
on the dimensionless vertical coordinate used
in its mathematical formulation. To achieve the
goal of being able to spatially locate all data
values, this convention includes the definitions
of common dimensionless vertical coordinates in
<a class="xref" href="#dimensionless-v-coord" title="Appendix D. Dimensionless Vertical Coordinates">Appendix D, <i>Dimensionless Vertical Coordinates</i></a>.
These definitions provide a mapping
between the dimensionless coordinate values
and dimensional values that can be uniquely
located with respect to a point on the earth's
surface. The definitions are associated with
a coordinate variable via the
<code class="varname">standard_name</code>
and
<code class="varname">formula_terms</code>
attributes. For backwards
compatibility with COARDS use of these attributes
is not required, but is strongly recommended.
</p><p>
It is often the case that data values are not
representative of single points in time and/or
space, but rather of intervals or multidimensional
cells. This convention defines a
<code class="varname">bounds</code>
attribute
to specify the extent of intervals or cells. When
data that is representative of cells can be
described by simple statistical methods, those
methods can be indicated using the
<code class="varname">cell_methods</code>
attribute. An important application of this
attribute is to describe climatological and
diurnal statistics.
</p><p>
Methods for reducing the total volume of data
include both packing and compression. Packing
reduces the data volume by reducing the precision
of the stored numbers. It is implemented using
the attributes
<code class="varname">add_offset</code>
and
<code class="varname">scale_factor</code>
which
are defined in the NUG. Compression on the other
hand loses no precision, but reduces the volume by
not storing missing data. The attribute
<code class="varname">compress</code>
is defined for this purpose.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="coards-relationship"></a>1.4. Relationship to the COARDS Conventions</h2></div></div></div><p>
These conventions generalize and extend the
COARDS conventions
[<a href="#coards" class="biblioref" title="[COARDS]"><abbr class="abbrev">COARDS</abbr></a>].
A major design goal
has been to maintain <span class="emphasis"><em>backward compatibility</em></span> with
COARDS. Hence applications written to process
datasets that conform to these conventions
will also be able to process COARDS conforming
datasets. We have also striven to maximize
<span class="emphasis"><em>conformance</em></span> to the COARDS standard so that
datasets that only require the metadata that was
available under COARDS will still be able to be
processed by COARDS conforming applications. But
because of the extensions that provide new
metadata content, and the relaxation of some
COARDS requirements, datasets that conform
to these conventions will not necessarily
be recognized by applications that adhere to
the COARDS conventions. The features of these
conventions that allow writing netCDF files that
are not COARDS conforming are summarized below.
</p><p>
COARDS standardizes the description of grids
composed of independent latitude, longitude,
vertical, and time axes. In addition
to standardizing the metadata required to
identify each of these axis types COARDS
restricts the axis (equivalently dimension)
ordering to be longitude, latitude, vertical,
and time (with longitude being the most rapidly
varying dimension). Because of I/O performance
considerations it may not be possible for models
to output their data in conformance with the
COARDS requirement. The CF convention places no
rigid restrictions on the order of dimensions,
however we encourage data producers to make the
extra effort to stay within the COARDS standard
order. The use of non-COARDS axis ordering will
render files inaccessible to some applications
and limit interoperability. Often a buffering
operation can be used to miminize performance
penalties when axis ordering in model code does
not match the axis ordering of a COARDS file.
</p><p>
COARDS addresses the issue of identifying
dimensionless vertical coordinates, but does
not provide any mechanism for mapping the
dimensionless values to dimensional ones that
can be located with respect to the earth's
surface. For backwards compatibility we continue
to allow (but do not require) the
<code class="varname">units</code>
attribute of dimensionless vertical coordinates to take the
values "level", "layer", or "sigma_level." But we
recommend that the
<code class="varname">standard_name</code> and
<code class="varname">formula_terms</code>
attributes be used to identify the appropriate
definition of the dimensionless vertical
coordinate (see
<a class="xref" href="#dimensionless-vertical-coordinate" title="4.3.2. Dimensionless Vertical Coordinate">Section 4.3.2, “Dimensionless Vertical Coordinate”</a>).
</p><p>
The CF conventions define attributes which
enable the description of data properties
that are outside the scope of the COARDS
conventions. These new attributes do not violate
the COARDS conventions, but applications that
only recognize COARDS conforming datasets will not
have the capabilities that the new attributes are
meant to enable. Briefly the new attributes allow:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Identification of quantities using standard names. </p></li><li class="listitem"><p> Description of dimensionless vertical coordinates. </p></li><li class="listitem"><p> Associating dimensions with auxiliary coordinate variables. </p></li><li class="listitem"><p> Linking data variables to scalar coordinate variables. </p></li><li class="listitem"><p> Associating dimensions with labels. </p></li><li class="listitem"><p>Description of intervals and cells. </p></li><li class="listitem"><p> Description of properties of data defined on intervals and cells. </p></li><li class="listitem"><p> Description of climatological statistics. </p></li><li class="listitem"><p> Data compression for variables with missing values. </p></li></ul></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idm48159165120"></a>Chapter 2.
NetCDF Files and Components
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#idm48159162784">2.1. Filename</a></span></dt><dt><span class="section"><a href="#idm48159160992">2.2. Data Types</a></span></dt><dt><span class="section"><a href="#idm48159152864">2.3. Naming Conventions</a></span></dt><dt><span class="section"><a href="#dimensions">2.4. Dimensions</a></span></dt><dt><span class="section"><a href="#variables">2.5. Variables</a></span></dt><dd><dl><dt><span class="section"><a href="#missing-data">2.5.1. Missing Data</a></span></dt></dl></dd><dt><span class="section"><a href="#idm48159119552">2.6. Attributes</a></span></dt><dd><dl><dt><span class="section"><a href="#identification-of-conventions">2.6.1. Identification of Conventions</a></span></dt><dt><span class="section"><a href="#description-of-file-contents">2.6.2. Description of file contents</a></span></dt></dl></dd></dl></div><p>
The components of a netCDF file are described in section 2
of the NUG
[<a href="#nug" class="biblioref" title="[NUG]"><abbr class="abbrev">NUG</abbr></a>].
In this section we describe conventions
associated with filenames and the basic components of
a netCDF file. We also introduce new attributes for
describing the contents of a file.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159162784"></a>2.1. Filename</h2></div></div></div><p>
NetCDF files should have the file name extension "<code class="filename">.nc</code>".
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159160992"></a>2.2. Data Types</h2></div></div></div><p>
The netCDF data types <code class="varname">char</code>, <code class="varname">byte</code>,
<code class="varname">short</code>, <code class="varname">int</code>,
<code class="varname">float</code> or <code class="varname">real</code>, and <code class="varname">double</code>
are all acceptable. The
<code class="varname">char</code> type is not intended for numeric data. One
byte numeric data should be stored using the
<code class="varname">byte</code> data type. All integer types are treated by
the netCDF interface as signed. It is possible
to treat the <code class="varname">byte</code> type as unsigned by using the
NUG convention of indicating the unsigned range
using the
<code class="varname">valid_min</code>,
<code class="varname">valid_max</code>,
or
<code class="varname">valid_range</code>
attributes.
</p><p>
NetCDF does not support a character string
type, so these must be represented as character
arrays. In this document, a one dimensional array
of character data is simply referred to as a
"string". An n-dimensional array of strings
must be implemented as a character array of
dimension (n,max_string_length), with the last
(most rapidly varying) dimension declared large
enough to contain the longest string in the
array. All the strings in a given array are
therefore defined to be equal in length. For
example, an array of strings containing the
names of the months would be dimensioned (12,9)
in order to accommodate "September", the month
with the longest name.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159152864"></a>2.3. Naming Conventions</h2></div></div></div><p>
Variable, dimension and attribute names should
begin with a letter and be composed of letters,
digits, and underscores. Note that this is in
conformance with the COARDS conventions, but is
more restrictive than the netCDF interface which
allows use of the hyphen character. The netCDF
interface also allows leading underscores in
names, but the NUG states that this is reserved
for system use.
</p><p>
Case is significant in netCDF names, but it is
recommended that names should not be distinguished
purely by case, i.e., if case is disregarded,
no two names should be the same. It is also
recommended that names should be obviously
meaningful, if possible, as this renders the
file more effectively self-describing.
</p><p>
This convention does not standardize any variable
or dimension names. Attribute names and their
contents, where standardized, are given in
English in this document and should appear in
English in conforming netCDF files for the sake
of portability. Languages other than English
are permitted for variables, dimensions, and
non-standardized attributes. The content of some
standardized attributes are string values that
are not standardized, and thus are not required
to be in English. For example, a description
of what a variable represents may be given
in a non-English language using the
<code class="varname">long_name</code>
attribute
(see <a class="xref" href="#long-name" title="3.2. Long Name">Section 3.2, “Long Name”</a>)
whose contents are not standardized, but a description given by
the
<code class="varname">standard_name</code>
attribute
(see <a class="xref" href="#standard-name" title="3.3. Standard Name">Section 3.3, “Standard Name”</a>)
must be taken from the standard name table which
is in English.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="dimensions"></a>2.4. Dimensions</h2></div></div></div><p>
A variable may have any number of dimensions,
including zero, and the dimensions must all have
different names. <span class="emphasis"><em>COARDS strongly recommends
limiting the number of dimensions to four,
but we wish to allow greater flexibility</em></span>. The
dimensions of the variable define the axes of
the quantity it contains. Dimensions other than
those of space and time may be included. Several
examples can be found in this document. Under
certain circumstances, one may need more than
one dimension in a particular quantity. For
instance, a variable containing a two-dimensional
probability density function might correlate the
temperature at two different vertical levels,
and hence would have temperature on both axes.
</p><p>
If any or all of the dimensions of a variable
have the interpretations of "date or time"
(<code class="varname">T</code>), "height or depth" (<code class="varname">Z</code>), "latitude"
(<code class="varname">Y</code>), or "longitude" (<code class="varname">X</code>) then we recommend,
but do not require
(see <a class="xref" href="#coards-relationship" title="1.4. Relationship to the COARDS Conventions">Section 1.4, “Relationship to the COARDS Conventions”</a>),
those
dimensions to appear in the relative order <code class="varname">T</code>,
then <code class="varname">Z</code>, then <code class="varname">Y</code>, then <code class="varname">X</code> in the CDL definition
corresponding to the file. All other dimensions
should, whenever possible, be placed to the left
of the spatiotemporal dimensions.
</p><p>
Dimensions may be of any size, including
unity. When a single value of some coordinate
applies to all the values in a variable, the
recommended means of attaching this information
to the variable is by use of a dimension
of size unity with a one-element coordinate
variable. It is also acceptable to use a scalar
coordinate variable which eliminates the need
for an associated size one dimension in the data
variable. The advantage of using a coordinate
variable is that all its attributes can be
used to describe the single-valued quantity,
including boundaries. For example, a variable
containing data for temperature at 1.5 m above the
ground has a single-valued coordinate supplying
a height of 1.5 m, and a time-mean quantity has a
single-valued time coordinate with an associated
boundary variable to record the start and end
of the averaging period.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="variables"></a>2.5. Variables</h2></div></div></div><p>
This convention does not standardize variable names.
</p><p>
NetCDF variables that contain coordinate data are
referred to as <span class="emphasis"><em>coordinate variables</em></span>, <span class="emphasis"><em>auxiliary
coordinate variables</em></span>,
<span class="emphasis"><em>scalar coordinate variables</em></span>,
or
<span class="emphasis"><em>multidimensional coordinate variables</em></span>.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="missing-data"></a>2.5.1. Missing Data</h3></div></div></div><p>
The NUG conventions
(<a class="ulink" href="http://www.unidata.ucar.edu/packages/netcdf/guidef/guidef-13.html#HEADING13-12" target="_top">NUG section 8.1</a>)
provide the
<code class="varname">_FillValue</code>,
<code class="varname">valid_min</code>,
<code class="varname">valid_max</code>, and
<code class="varname">valid_range</code> attributes
to indicate missing data.
</p><p>
The NUG conventions for missing data
changed significantly between version
2.3 and version 2.4. Since version 2.4
the NUG defines missing data as all
values outside of the
<code class="varname">valid_range</code>,
and specifies how the
<code class="varname">valid_range</code>
should be defined from the
<code class="varname">_FillValue</code> (which has
library specified default values) if it
hasn't been explicitly specified. If
only one missing value is needed for
a variable then we strongly recommend
that this value be specified using
the
<code class="varname">_FillValue</code>
attribute. Doing this guarantees that the missing value will
be recognized by generic applications
that follow either the before or after
version 2.4 conventions.
</p><p>
The scalar attribute with the name
<code class="varname">_FillValue</code>
and of the same type as its
variable is recognized by the netCDF
library as the value used to pre-fill
disk space allocated to the variable. This
value is considered to be a special value
that indicates undefined or missing data,
and is returned when reading values that
were not written. The
<code class="varname">_FillValue</code>
should be
outside the range specified by
<code class="varname">valid_range</code>
(if used) for a variable. The netCDF
library defines a default fill value
for each data type
(<a class="ulink" href="http://www.unidata.ucar.edu/packages/netcdf/guidef/guidef-12.html#HEADING12-1381" target="_top">NUG section 7.16</a>).
</p><p>
The
<code class="varname">missing_value</code>
attribute is considered
deprecated by the NUG and we do not
recommend its use. However for backwards
compatibility with COARDS this standard
continues to recognize the use of the
<code class="varname">missing_value</code>
attribute to indicate undefined or missing data.
</p><p>
The missing values of a variable with
<code class="varname">scale_factor</code>
and/or
<code class="varname">add_offset</code>
attributes
(see section <a class="xref" href="#packed-data" title="8.1. Packed Data">Section 8.1, “Packed Data”</a>) are interpreted
relative to the variable's external
values, i.e., the values stored in the
netCDF file. Applications that process
variables that have attributes to indicate
both a transformation (via a scale and/or
offset) and missing values should first
check that a data value is valid, and
then apply the transformation. Note that
values that are identified as missing
should not be transformed. Since the
missing value is outside the valid
range it is possible that applying
a transformation to it could result
in an invalid operation. For example,
the default
<code class="varname">_FillValue</code>
is very close to
the maximum representable value of IEEE
single precision floats, and multiplying
it by 100 produces an "Infinity" (using
single precision arithmetic).
</p></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm48159119552"></a>2.6. Attributes</h2></div></div></div><p>
This standard describes many attributes (some
mandatory, others optional), but a file may
also contain non-standard attributes. Such
attributes do not represent a violation of this
standard. Application programs should ignore
attributes that they do not recognise or which
are irrelevant for their purposes. Conventional
attribute names should be used wherever
applicable. Non-standard names should be as
meaningful as possible. Before introducing
an attribute, consideration should be given
to whether the information would be better
represented as a variable. In general, if a
proposed attribute requires ancillary data to
describe it, is multidimensional, requires any of
the defined netCDF dimensions to index its values,
or requires a significant amount of storage,
a variable should be used instead. When this
standard defines string attributes that may take
various prescribed values, the possible values
are generally given in lower case. However,
applications programs should not be sensitive
to case in these attributes. Several string
attributes are defined by this standard to
contain "blank-separated lists". Consecutive
words in such a list are separated by one or more
adjacent spaces. The list may begin and end with
any number of spaces. See
<a class="xref" href="#attribute-appendix" title="Appendix A. Attributes">Appendix A, <i>Attributes</i></a>
for a list
of attributes described by this standard.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="identification-of-conventions"></a>2.6.1. Identification of Conventions</h3></div></div></div><p>
We recommend that netCDF files that
follow these conventions indicate
this by setting the NUG defined global
attribute
<code class="varname">Conventions</code>
to the string value "<code class="varname">CF-1.0</code>". The string is interpreted as a
directory name relative to a directory
that is a repository of documents
describing sets of discipline-specific
conventions. The conventions directory
name is currently interpreted relative to
the directory
<code class="filename">pub/netcdf/Conventions/</code>
on the host machine
<code class="computeroutput">ftp.unidata.ucar.edu</code>. The
web based versions of this
document are linked from the
<a class="ulink" href="http://www.unidata.ucar.edu/packages/netcdf/conventions.html" target="_top">
netCDF Conventions web page
</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="description-of-file-contents"></a>2.6.2. Description of file contents</h3></div></div></div><p>
The following attributes are intended
to provide information about where the
data came from and what has been done to
it. This information is mainly for the
benefit of human readers. The attribute
values are all character strings. For
readability in ncdump outputs it is
recommended to embed newline characters
into long strings to break them into
lines. For backwards compatibility with
COARDS none of these global attributes
is required.
</p><p>
The NUG defines <code class="varname">title</code> and <code class="varname">history</code>
to be global attributes. We wish to
allow the newly defined attributes,
i.e., <code class="varname">institution</code>, <code class="varname">source</code>,
<code class="varname">references</code>,
and <code class="varname">comment</code>, to be either global or
assigned to individual variables. When
an attribute appears both globally and
as a variable attribute, the variable's
version has precedence.
</p><p>
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> <code class="varname"> title </code> </span></dt><dd><p>
A succinct description of what is in the dataset.
</p></dd><dt><span class="term"> <code class="varname"> institution </code> </span></dt><dd><p>
Specifies where the original data was produced.
</p></dd><dt><span class="term"> <code class="varname"> source </code> </span></dt><dd><p>
The method of production of the original data. If it was model-generated,
<code class="varname">source</code>
should name the model and
its version, as specifically as
could be useful. If it
is observational,
<code class="varname">source</code>
should characterize it (e.g., "<code class="varname">surface observation</code>" or "<code class="varname">radiosonde</code>").
</p></dd><dt><span class="term"> <code class="varname"> history </code> </span></dt><dd><p>
Provides an audit trail for modifications to the
original data. Well-behaved generic netCDF
filters will automatically append their name
and the parameters with which they were invoked to
the global history attribute of an input
netCDF file. We recommend that each line begin
with a timestamp indicating the date and time of day
that the program was executed.
</p></dd><dt><span class="term"> <code class="varname"> references </code> </span></dt><dd><p>
Published or web-based references that
describe the data or methods used to produce it.
</p></dd><dt><span class="term"> <code class="varname"> comment </code> </span></dt><dd><p>
Miscellaneous information about the data or methods used to produce it.
</p></dd></dl></div><p>
</p></div></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="idm48159018080"></a>Chapter 3.
Description of the Data
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#units">3.1. Units</a></span></dt><dt><span class="section"><a href="#long-name">3.2. Long Name</a></span></dt><dt><span class="section"><a href="#standard-name">3.3. Standard Name</a></span></dt><dt><span class="section"><a href="#ancillary-data">3.4. Ancillary Data</a></span></dt><dt><span class="section"><a href="#flags">3.5. Flags</a></span></dt></dl></div><p>
The attributes described in this section are used to
provide a description of the content and the units
of measurement for each variable. We continue to
support the use of the
<code class="varname">units</code>
and
<code class="varname">long_name</code> attributes
as defined in COARDS. We extend COARDS by adding the
optional
<code class="varname">standard_name</code>
attribute which is used to provide
unique identifiers for variables. This is important for
data exchange since one cannot necessarily identify a
particular variable based on the name assigned to it by
the institution that provided the data.
</p><p>
The
<code class="varname">standard_name</code>
attribute can
be used to identify variables that contain coordinate
data. But since it is an optional attribute, applications
that implement these standards must continue to be
able to identify coordinate types based on the COARDS
conventions.
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="units"></a>3.1. Units</h2></div></div></div><p>
The <code class="varname">units</code> attribute is required for all variables
that represent dimensional quantities (except for boundary variables
defined in <a class="xref" href="#cell-boundaries" title="7.1. Cell Boundaries">Section 7.1, “Cell Boundaries”</a> and climatology variables
defined in <a class="xref" href="#climatological-statistics" title="7.4. Climatological Statistics">Section 7.4, “Climatological Statistics”</a>). The value of
the <code class="varname">units</code> attribute is a string that can be
recognized by UNIDATA"s Udunits package [<a href="#udunits" class="biblioref" title="[UDUNITS]"><abbr class="abbrev">UDUNITS</abbr></a>],
with a few exceptions that are given below.
The <a class="ulink" href="http://www.unidata.ucar.edu/software/udunits/" target="_top">Udunits package</a> includes a file
<code class="filename">udunits.dat</code>,
which lists its supported unit names. Note that case is significant in the <code class="varname">units</code> strings.
</p><p>
The COARDS convention prohibits the unit
<code class="constant">degrees</code> altogether, but this unit is not
forbidden by the CF convention because it may in fact be appropriate
for a variable containing, say, solar zenith angle. The unit
<code class="constant">degrees</code> is also allowed on coordinate variables
such as the latitude and longitude coordinates of a transformed grid.
In this case the coordinate values are not true latitudes and
longitudes which must always be identified using the more specific
forms of <code class="constant">degrees</code> as described in
<a class="xref" href="#latitude-coordinate" title="4.1. Latitude Coordinate">Section 4.1, “Latitude Coordinate”</a> and <a class="xref" href="#longitude-coordinate" title="4.2. Longitude Coordinate">Section 4.2, “Longitude Coordinate”</a>.
</p><p>
Units are not required for dimensionless quantities. A variable with no units attribute is assumed to be dimensionless. However, a units attribute specifying a dimensionless unit may optionally be included. The Udunits package defines a few dimensionless units, such as <code class="constant">percent</code>, but is lacking commonly used units such as ppm (parts per million). This convention does not support the addition of new dimensionless units that are not udunits compatible. The conforming unit for quantities that represent fractions, or parts of a whole, is "1". The conforming unit for parts per million is "1e-6". Descriptive information about dimensionless quantities, such as sea-ice concentration, cloud fraction, probability, etc., should be given in the <code class="varname">long_name</code> or <code class="varname">standard_name</code> attributes (see below) rather than the <code class="varname">units</code>.
</p><p>
The units <code class="constant">level</code>, <code class="constant">layer</code>, and <code class="constant">sigma_level</code> are allowed for dimensionless vertical coordinates to maintain backwards compatibility with COARDS. These units are not compatible with Udunits and are deprecated by this standard because conventions for more precisely identifying dimensionless vertical coordinates are introduced (see <a class="xref" href="#dimensionless-vertical-coordinate" title="4.3.2. Dimensionless Vertical Coordinate">Section 4.3.2, “Dimensionless Vertical Coordinate”</a>).
</p><p>
The Udunits syntax that allows scale factors and offsets to be applied to
a unit is not supported by this standard. The application of any scale
factors or offsets to data should be indicated by the
<code class="varname">scale_factor</code> and <code class="varname">add_offset</code>
attributes. Use of these attributes for data packing,
which is their most important application,
is discussed in detail in <a class="xref" href="#packed-data" title="8.1. Packed Data">Section 8.1, “Packed Data”</a>.
</p><p>
Udunits recognizes the following prefixes and their abbreviations.
</p><div class="table"><a name="idm48158996000"></a><p class="title"><b>Table 3.1. Supported Units</b></p><div class="table-contents"><table summary="Supported Units" border="1"><colgroup><col><col><col><col><col><col><col></colgroup><thead><tr><th align="left">Factor</th><th align="left">Prefix</th><th align="left">Abbreviation</th><th align="left"> </th><th align="left">Factor</th><th align="left">Prefix</th><th align="left">Abbreviation</th></tr></thead><tbody><tr><td align="left">1e1</td><td align="left">deca,deka</td><td align="left">da</td><td align="left"> </td><td align="left">1e-1</td><td align="left">deci</td><td align="left">d</td></tr><tr><td align="left">1e2</td><td align="left">hecto</td><td align="left">h</td><td align="left"> </td><td align="left">1e-2</td><td align="left">deci</td><td align="left">c</td></tr><tr><td align="left">1e3</td><td align="left">kilo</td><td align="left">k</td><td align="left"> </td><td align="left">1e-3</td><td align="left">milli</td><td align="left">m</td></tr><tr><td align="left">1e6</td><td align="left">mega</td><td align="left">M</td><td align="left"> </td><td align="left">1e-6</td><td align="left">micro</td><td align="left">u</td></tr><tr><td align="left">1e9</td><td align="left">giga</td><td align="left">G</td><td align="left"> </td><td align="left">1e-9</td><td align="left">nano</td><td align="left">n</td></tr><tr><td align="left">1e12</td><td align="left">tera</td><td align="left">T</td><td align="left"> </td><td align="left">1e-12</td><td align="left">pico</td><td align="left">p</td></tr><tr><td align="left">1e15</td><td align="left">peta</td><td align="left">P</td><td align="left"> </td><td align="left">1e-15</td><td align="left">femto</td><td align="left">f</td></tr><tr><td align="left">1e18</td><td align="left">exa</td><td align="left">E</td><td align="left"> </td><td align="left">1e-18</td><td align="left">atto</td><td align="left">a</td></tr><tr><td align="left">1e21</td><td align="left">zetta</td><td align="left">Z</td><td align="left"> </td><td align="left">1e-21</td><td align="left">zepto</td><td align="left">z</td></tr><tr><td align="left">1e24</td><td align="left">yotta</td><td align="left">Y</td><td align="left"> </td><td align="left">1e-24</td><td align="left">yocto</td><td align="left">y</td></tr></tbody></table></div></div><p><br class="table-break">
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="long-name"></a>3.2. Long Name</h2></div></div></div><p>
The <code class="varname">long_name</code> attribute is defined by the NUG to contain a long descriptive name which may, for example, be used for labeling plots. For backwards compatibility with COARDS this attribute is optional. But it is highly recommended that either this or the <code class="varname">standard_name</code> attribute defined in the next section be provided to make the file self-describing. If a variable has no <code class="varname">long_name</code> attribute then an application may use, as a default, the <code class="varname">standard_name</code> if it exists, or the variable name itself.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="standard-name"></a>3.3. Standard Name</h2></div></div></div><p>
A fundamental requirement for exchange of scientific data is the ability to describe precisely the physical quantities being represented. To some extent this is the role of the <code class="varname">long_name</code> attribute as defined in the NUG. However, usage of <code class="varname">long_name</code> is completely ad-hoc. For some applications it would be desirable to have a more definitive description of the quantity, which would allow users of data from different sources to determine whether quantities were in fact comparable. For this reason an optional mechanism for uniquely associating each variable with a standard name is provided.
</p><p>
A standard name is associated with a variable via the attribute <code class="varname">standard_name</code> which takes a string value comprised of a standard name optionally followed by one or more blanks and a standard name modifier (a string value from <a class="xref" href="#standard-name-modifiers" title="Appendix C. Standard Name Modifiers">Appendix C, <i>Standard Name Modifiers</i></a>).
</p><p>
The set of permissible standard names is contained in the standard name table. The table entry for each standard name contains the following:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">standard name</span></dt><dd><p>
The name used to identify the physical quantity. A standard name contains no whitespace and is case sensitive.
</p></dd><dt><span class="term">canonical units</span></dt><dd><p>
Representative units of the physical quantity. Unless it is dimensionless, a variable with a <code class="varname">standard_name</code> attribute must have units which are physically equivalent (not necessarily identical) to the canonical units, possibly modified by an operation specified by either the standard name modifier (see below and <a class="xref" href="#standard-name-modifiers" title="Appendix C. Standard Name Modifiers">Appendix C, <i>Standard Name Modifiers</i></a>) or by the <code class="varname">cell_methods</code> attribute (see <a class="xref" href="#cell-methods" title="7.3. Cell Methods">Section 7.3, “Cell Methods”</a> and <a class="xref" href="#appendix-cell-methods" title="Appendix E. Cell Methods">Appendix E, <i>Cell Methods</i></a>).
</p></dd><dt><span class="term">description</span></dt><dd><p>
The description is meant to clarify the qualifiers of the fundamental quantities such as which surface a quantity is defined on or what the flux sign conventions are. We don"t attempt to provide precise definitions of fundumental physical quantities (e.g., temperature) which may be found in the literature.
</p></dd></dl></div><p>
When appropriate, the table entry also contains the corresponding GRIB parameter code(s) (from ECMWF and NCEP) and AMIP identifiers.
</p><p>
The standard name table is located at
<a class="ulink" href="http://cf-pcmdi.llnl.gov/documents/cf-standard-names/current/cf-standard-name-table.xml" target="_top">http://cf-pcmdi.llnl.gov/documents/cf-standard-names/current/cf-standard-name-table.xml</a>
, written in compliance with the XML format, as described in
<a class="xref" href="#standard-name-table-format" title="Appendix B. Standard Name Table Format">Appendix B, <i>Standard Name Table Format</i></a>.
Knowledge of the XML format is only necessary for application
writers who plan to directly access the table. A formatted text
version of the table is provided at
<a class="ulink" href="http://cf-pcmdi.llnl.gov/documents/cf-standard-names/current/cf-standard-name-table.html" target="_top">http://cf-pcmdi.llnl.gov/documents/cf-standard-names/current/cf-standard-name-table.html</a>
, and this table may be consulted in order to find the standard
name that should be assigned to a variable.
</p><p>
Standard names by themselves are not always sufficient to describe a quantity. For example, a variable may contain data to which spatial or temporal operations have been applied. Or the data may represent an uncertainty in the measurement of a quantity. These quantity attributes are expressed as modifiers of the standard name. Modifications due to common statistical operations are expressed via the <code class="varname">cell_methods</code> attribute (see <a class="xref" href="#cell-methods" title="7.3. Cell Methods">Section 7.3, “Cell Methods”</a> and <a class="xref" href="#appendix-cell-methods" title="Appendix E. Cell Methods">Appendix E, <i>Cell Methods</i></a>). Other types of quantity modifiers are expressed using the optional modifier part of the <code class="varname">standard_name</code> attribute. The permissible values of these modifiers are given in <a class="xref" href="#standard-name-modifiers" title="Appendix C. Standard Name Modifiers">Appendix C, <i>Standard Name Modifiers</i></a>.
</p><div class="example"><a name="idm48140043712"></a><p class="title"><b>Example 3.1. Use of <code class="varname">standard_name</code></b></p><div class="example-contents"><pre class="programlisting">
float psl(lat,lon) ;
psl:long_name = "mean sea level pressure" ;
psl:units = "hPa" ;
psl:standard_name = "air_pressure_at_sea_level" ;
</pre><p>
The description in the standard name table entry for <code class="varname">air_pressure_at_sea_level</code> clarifies that "sea level" refers to the mean sea level, which is close to the geoid in sea areas.
</p></div></div><br class="example-break"><p>
Here are lists of equivalences between the CF standard names and the standard names from the
<a class="ulink" href="http://www.cgd.ucar.edu/cms/eaton/cf-metadata/ECMWF.html" target="_top">ECMWF GRIB tables</a>, the
<a class="ulink" href="http://www.cgd.ucar.edu/cms/eaton/cf-metadata/NCEP.html" target="_top">NCEP GRIB tables</a>, and the
<a class="ulink" href="http://www.cgd.ucar.edu/cms/eaton/cf-metadata/PCMDI.html" target="_top">PCMDI tables</a>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ancillary-data"></a>3.4. Ancillary Data</h2></div></div></div><p>
When one data variable provides metadata about the individual values of another data variable it may be desirable to express this association by providing a link between the variables. For example, instrument data may have associated measures of uncertainty. The attribute <code class="varname">ancillary_variables</code> is used to express these types of relationships. It is a string attribute whose value is a blank separated list of variable names. The nature of the relationship between variables associated via <code class="varname">ancillary_variables</code> must be determined by other attributes. The variables listed by the <code class="varname">ancillary_variables</code> attribute will often have the standard name of the variable which points to them including a modifier (<a class="xref" href="#standard-name-modifiers" title="Appendix C. Standard Name Modifiers">Appendix C, <i>Standard Name Modifiers</i></a>) to indicate the relationship.
</p><div class="example"><a name="idm48140034128"></a><p class="title"><b>Example 3.2. Instrument data</b></p><div class="example-contents"><pre class="programlisting">
float q(time) ;
q:standard_name = "specific_humidity" ;
q:units = "g/g" ;
q:ancillary_variables = "q_error_limit q_detection_limit" ;
float q_error_limit(time)
q_error_limit:standard_name = "specific_humidity standard_error" ;
q_error_limit:units = "g/g" ;
float q_detection_limit(time)
q_detection_limit:standard_name = "specific_humidity detection_minimum" ;
q_detection_limit:units = "g/g" ;
</pre></div></div><br class="example-break"></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="flags"></a>3.5. Flags</h2></div></div></div><p>
The attributes <code class="varname">flag_values</code> and <code class="varname">flag_meanings</code> are intended to make variables that contain flag values self describing. The <code class="varname">flag_values</code> attribute is the same type as the variable to which it is attached, and contains a list of the possible flag values. The <code class="varname">flag_meanings</code> attribute is a string whose value is a blank separated list of descriptive words or phrases, one for each flag value. If multi-word phrases are used to describe the flag values, then the words within a phrase should be connected with underscores.
</p><div class="example"><a name="idm48140028816"></a><p class="title"><b>Example 3.3. A flag variable</b></p><div class="example-contents"><pre class="programlisting">
byte current_speed_qc(time, depth, lat, lon) ;
current_speed_qc:long_name = "Current Speed Quality" ;
current_speed_qc:_FillValue = -128b ;
current_speed_qc:valid_range = -127b, 127b ;
current_speed_qc:flag_values = 0b, 1b, 2b ;
current_speed_qc:flag_meanings = "quality_good sensor_nonfunctional
outside_valid_range" ;
</pre></div></div><br class="example-break"></div></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="coordinate-types"></a>Chapter 4.
Coordinate Types
</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="#latitude-coordinate">4.1. Latitude Coordinate</a></span></dt><dt><span class="section"><a href="#longitude-coordinate">4.2. Longitude Coordinate</a></span></dt><dt><span class="section"><a href="#vertical-coordinate">4.3. Vertical (Height or Depth) Coordinate</a></span></dt><dd><dl><dt><span class="section"><a href="#idm48139872768">4.3.1. Dimensional Vertical Coordinate</a></span></dt><dt><span class="section"><a href="#dimensionless-vertical-coordinate">4.3.2. Dimensionless Vertical Coordinate</a></span></dt></dl></dd><dt><span class="section"><a href="#time-coordinate">4.4. Time Coordinate</a></span></dt><dd><dl><dt><span class="section"><a href="#calendar">4.4.1. Calendar</a></span></dt></dl></dd></dl></div><p>
Four types of coordinates receive special treatment by these
conventions: latitude, longitude, vertical, and time.
We continue to support the special role that the
<code class="varname">units</code> and <code class="varname">positive</code> attributes
play in the COARDS convention to identify coordinate type.
We extend COARDS by providing explicit definitions of dimensionless
vertical coordinates. The definitions are associated with a coordinate
variable via the <code class="varname">standard_name</code> and
<code class="varname">formula_terms</code> attributes. For backwards compatibility
with COARDS use of these attributes is not required, but is strongly recommended.
</p><p>
Because identification of a coordinate type by its units is complicated
by requiring the use of an external software
package [<a href="#udunits" class="biblioref" title="[UDUNITS]"><abbr class="abbrev">UDUNITS</abbr></a>], we provide two optional
methods that yield a direct identification.
The attribute <code class="varname">axis</code> may be attached to a coordinate
variable and given one of the values <code class="varname">X</code>, <code class="varname">Y</code>,
<code class="varname">Z</code> or <code class="varname">T</code> which stand for a longitude,
latitude, vertical, or time axis respectively.
Alternatively the <code class="varname">standard_name</code> attribute may be used
for direct identification. But note that these optional
attributes are in addition to the required COARDS metadata.
</p><p>
Coordinate types other than latitude, longitude, vertical, and time
are allowed. To identify generic spatial coordinates we recommend
that the <code class="varname">axis</code> attribute be attached to these
coordinates and given one of the values <code class="varname">X</code>,
<code class="varname">Y</code> or <code class="varname">Z</code>. We attach no
specific meaning to the <code class="varname">axis</code> values in this case,
but note that they may provide a useful hint to an application that
plots spatially oriented data. We strongly recommend that coordinate
variables be used for all coordinate types whenever they are applicable.
</p><p>
The methods of identifying coordinate types described in this
section apply both to coordinate variables and to auxiliary
coordinate variables named by the <code class="varname">coordinates</code>
attribute (see <a class="xref" href="#coordinate-system" title="Chapter 5. Coordinate Systems">Chapter 5, <i>
Coordinate Systems
</i></a>).
</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="latitude-coordinate"></a>4.1. Latitude Coordinate</h2></div></div></div><p>
Variables representing latitude must always explicitly include the
<code class="varname">units</code> attribute; there is no default value.
The <code class="varname">units</code> attribute will be a string formatted
as per the
<a class="ulink" href="http://www.unidata.ucar.edu/software/udunits/" target="_top"><code class="filename">udunits.dat</code></a> file.
The recommended unit of latitude
is <code class="varname">degrees_north</code>. Also acceptable
are <code class="varname">degree_north</code>, <code class="varname">degree_N</code>,
<code class="varname">degrees_N</code>, <code class="varname">degreeN</code>,
and <code class="varname">degreesN</code>.
</p><div class="example"><a name="idm48139908384"></a><p class="title"><b>Example 4.1. Latitude axis</b></p><div class="example-contents"><pre class="programlisting">
float lat(lat) ;
lat:long_name = "latitude" ;
lat:units = "degrees_north" ;
lat:standard_name = "latitude" ;
</pre></div></div><br class="example-break"><p>
Application writers should note that the Udunits package does not
recognize the directionality implied by the "north" part of the unit
specification. It only recognizes its size, i.e., 1 degree is defined
to be pi/180 radians. Hence, determination that a coordinate is a
latitude type should be done via a string match between the given unit
and one of the acceptable forms of <code class="varname">degrees_north</code>.
</p><p>
Optionally, the latitude type may be indicated additionally by providing
the <code class="varname">standard_name</code> attribute with the value
<code class="varname">latitude</code>, and/or the <code class="varname">axis</code> attribute
with the value <code class="varname">Y</code>.
</p><p>
Coordinates of latitude with respect to a rotated pole should be given
units of <code class="varname">degrees</code>, not <code class="varname">degrees_north</code>
or equivalents, because applications which use the units to identify
axes would have no means of distinguishing such an axis from real
latitude, and might draw incorrect coastlines, for instance. It would
also not generally be appropriate to attach an axis attribute to a
rotated-latitude coordinate variable. Such a variable can be identified
by a <code class="varname">standard_name</code> of <code class="varname">grid_latitude</code>.
</p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="longitude-coordinate"></a>4.2. Longitude Coordinate</h2></div></div></div><p>
Variables representing longitude must always explicitly include
the <code class="varname">units</code> attribute; there is no default value.