-
Notifications
You must be signed in to change notification settings - Fork 3
/
NCCSV.html
951 lines (841 loc) · 47.8 KB
/
NCCSV.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
<!DOCTYPE html>
<html lang="en-US">
<head>
<title>NCCSV</title>
<meta charset="UTF-8">
<link rel="shortcut icon" href="https://coastwatch.pfeg.noaa.gov/erddap/images/favicon.ico">
<link href="../images/erddap2.css" rel="stylesheet" type="text/css">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<div class="standard_width">
<h1 style="text-align:center">NCCSV -
<br>A NetCDF-Compatible, UTF-8, CSV File Specification,
<br>Version 1.20</h1>
<span style="text-align:center;">Bob Simons <erd.data at noaa.gov> and Steve Hankin
<br>"NCCSV" by Bob Simons and Steve Hankin is licensed under
<a rel="bookmark" href="https://creativecommons.org/licenses/by/4.0/"
>CC BY 4.0</a></span>
<h2><a class="selfLink" id="Contents" href="#Contents" rel="bookmark">Contents</a></h2>
<ul>
<li><a rel="bookmark" href="#Introduction">Introduction</a>
<li><a rel="bookmark" href="#FileStructure">File Structure</a>
<li><a rel="bookmark" href="#TheMetadataSection">The Metadata Section</a>
<li><a rel="bookmark" href="#TheDataSection">The Data Section</a>
<li><a rel="bookmark" href="#DSGFeatureTypes">DSG Feature Types</a>
<li><a rel="bookmark" href="#SampleFile">Sample File</a>
<li><a rel="bookmark" href="#Spreadsheets">Spreadsheets</a>
<li><a rel="bookmark" href="#Problems">Problems/Warnings</a>
<li><a rel="bookmark" href="#Changes">Changes</a>
</ul>
<p>
<h2><a class="selfLink" id="Introduction" href="#Introduction" rel="bookmark">Introduction</a></h2>
This document specifies a UTF-8 CSV text file format that can contain
all of the information (metadata and data) that can be found in a NetCDF .nc
file that contains a CSV-file-like table of data. The file extension for a
UTF-8 CSV text file following this specification must be .csv so that
it can be read easily and correctly into spreadsheet programs like
Excel and Google Sheets. Bob Simons will write software to convert an
NCCSV file into a NetCDF-3 (and perhaps also a NetCDF-4) .nc file,
and the reverse, with no loss of information.
Bob Simons has modified
<a rel="bookmark" href="https://coastwatch.pfeg.noaa.gov/erddap/index.html"
>ERDDAP™</a>
to support reading and writing this type of file.
<p>The NCCSV format is designed so that spreadsheet software such as Excel
and Google Sheets can import an NCCSV file as a csv file, with all of the
information in the spreadsheet's cells ready for editing. Or, a spreadsheet
can be created from scratch following the NCCSV conventions.
Regardless of the source of the spreadsheet,
if it is then exported as a .csv file,
it will conform to the NCCSV specification and no information will be lost.
The only differences between NCCSV files and the analogous spreadsheet
files which follow these conventions are:
<ul>
<li>NCCSV files have values on a line separated by commas.
<br>Spreadsheets have values on a line in adjacent cells.
<li>Strings in NCCSV files are often surrounded by double quotes.
<br>Strings in spreadsheets are never surrounded by double quotes.
<li>Internal double quotes ( " ) in Strings in NCCSV files appear
as 2 double quotes.
<br>Internal double quotes in spreadsheets appear as 1 double quote.
</ul>
<p>See the <a rel="bookmark" href="#Spreadsheets">Spreadsheet</a>
section below for more information.
<p><a class="selfLink" id="Streamable" href="#Streamable" rel="bookmark"><strong>Streamable</strong></a> —
Like CSV files in general, NCCSV files are streamable.
Thus, if an NCSV is generated on-the-fly by a data server such as
<a rel="bookmark" href="https://coastwatch.pfeg.noaa.gov/erddap/index.html"
>ERDDAP™</a>,
the server can start to stream data to the requester before all of the data
has been gathered. This is a useful and desirable feature. NetCDF files,
by contrast, are not streamable.
<p><a class="selfLink" id="ERDDAP" href="#ERDDAP" rel="bookmark"><strong>ERDDAP™</strong></a> —
This specification is designed so that NCCSV files and the .nc files
that can be created from them can be used by an
<a rel="bookmark" href="https://coastwatch.pfeg.noaa.gov/erddap/index.html"
>ERDDAP™ data server</a>
(via the
<a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#EDDTableFromNccsvFiles"
>EDDTableFromNccsvFiles</a>
and
<a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#EDDTableFromNcFiles"
>EDDTableFromNcFiles</a> dataset types),
but this specification is external to ERDDAP.
ERDDAP™ has several required global attributes and many recommended global
and variable attributes, mostly based on CF and ACDD attributes (see
<br><a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#globalAttributes"
>https://erddap.github.io/setupDatasetsXml.html#globalAttributes</a>).
<p><a class="selfLink" id="Balance" href="#Balance" rel="bookmark"><strong>Balance</strong></a> —
The design of the NCCSV format is a balance of several requirements:
<ul>
<li>The files must contain all of the data and metadata that would be in a
tabular NetCDF file, including specific data types.
<li>The files must be able to be read into and then written out of a
spreadsheet with no loss of information.
<li>The files must be easy for humans to create, edit, read, and understand.
<li>The files must be able to be unambiguously parsed by computer programs.
</ul>
If some requirement in this document seems odd or picky,
it is probably needed to meet one of these requirements.
<p><a class="selfLink" id="OtherSpecifications" href="#OtherSpecifications" rel="bookmark"><strong>Other Specifications</strong></a> -
This specification refers to several other specifications and libraries
that it is designed to work with, but this specification is not a part of
any of those other specifications, nor does it need any changes to them,
nor does it conflict with them.
If a detail related to one of these standards is not specified here,
see the related specification. Notably, this includes:
<ul>
<li>The Attribute Convention for Dataset Discovery (ACDD) metadata standard:
<br><a rel="bookmark"
href="https://wiki.esipfed.org/Attribute_Convention_for_Data_Discovery_1-3"
>https://wiki.esipfed.org/Attribute_Convention_for_Data_Discovery_1-3<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a> .
<li>The Climate and Forecast (CF) metadata standard:
<br><a rel="bookmark"
href="https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html"
>https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a> .
<li>The NetCDF User Guide (NUG):
<br><a rel="bookmark"
href="https://docs.unidata.ucar.edu/netcdf-java/current/userguide/index.html"
>https:///docs.unidata.ucar.edu/netcdf-java/current/userguide/index.html<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a> .
<li>The NetCDF software libraries like NetCDF-java and NetCDF-c:
<br><a rel="bookmark"
href="https://www.unidata.ucar.edu/software/netcdf/"
>https://www.unidata.ucar.edu/software/netcdf/<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a> .
These libraries cannot read NCCSV files,
but they can read .nc files created from NCCSV files.
<li>JSON:
<a rel="bookmark" href="https://www.json.org/"
>https://www.json.org/<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a>
</ul>
<p><a class="selfLink" id="Notation" href="#Notation" rel="bookmark"><strong>Notation</strong></a> -
In this specification, brackets, [ ], denote optional items.
<p>
<h2><a class="selfLink" id="FileStructure" href="#FileStructure" rel="bookmark">File Structure</a></h2>
A complete NCCSV file consists of two sections: the metadata section,
followed by the data section.
<p>NCCSV files may contain any UCS-2 characters
(i.e., 2-byte Unicode characters, as in Java) encoded via UTF-8.
ERDDAP™ reads and writes NCCSV files using the UTF-8 encoding.
<p>NCCSV files may use either newline (\n)
(which is common on Linux and Mac OS X computers)
or carriageReturn plus newline (\r\n) (which is common on Windows computers)
as end-of-line markers, but not both.
<p><a class="selfLink" id="nccsvMetadata" href="#nccsvMetadata" rel="bookmark">.nccsvMetadata</a> —
When both the creator and the reader are expecting it,
it is also possible and sometimes useful to make a variant of an NCCSV file
which contains just the metadata section (including the <kbd>*END_METADATA*</kbd> line).
The result provides a complete description of the file's attributes,
variable names, and data types,
thus serving the same purpose as the .das plus .dds responses
from an OPeNDAP server. ERDDAP™ will return this variation
if you request <kbd>fileType=.nccsvMetadata</kbd> from an ERDDAP™ dataset.
<p>
<h2><a class="selfLink" id="TheMetadataSection" href="#TheMetadataSection" rel="bookmark">The Metadata Section</a></h2>
In an NCCSV file, each line of the metadata section
uses the format
<br><kbd><a rel="help" href="#variableName">variableName</a>,<a rel="help" href="#attributeName">attributeName</a>,<a rel="help" href="#value">value1</a>[,value2][,value3][,value4][...]</kbd>
<br>Spaces before or after items are not allowed because they cause problems
when importing the file into spreadsheet programs.
<p><a class="selfLink" id="Conventions" href="#Conventions" rel="bookmark">Conventions</a> -
The first line of an NCCSV file is the first line of the metadata section and
must have a <a rel="help" href="#GLOBAL"><kbd>*GLOBAL*</kbd></a>
<kbd>Conventions</kbd> attribute listing all of the
conventions used in the file as a String containing a CSV list, for example:
<br><kbd>*GLOBAL*,Conventions,"COARDS, CF-1.6, ACDD-1.3, NCCSV-1.2"</kbd>
<br>One of the conventions listed must be <kbd>NCCSV-1.2</kbd>,
which refers to the current version of this specification.
<p><a class="selfLink" id="END_METADATA" href="#END_METADATA" rel="bookmark">*END_METADATA*</a> -
The end of the metadata section of an NCCSV file must be denoted by a
line with only
<br><kbd>*END_METADATA*</kbd>
<p>It is recommended but not required that all of the attributes for a
given variable appear on adjacent lines of the metadata section.
If an NCCSV file is converted into a NetCDF file, the order that the
variableNames first appear in the metadata section will be the order of
the variables in the NetCDF file.
<p>Optional blank lines are allowed in the metadata section after the required
first line with
<kbd><a rel="help" href="#GLOBAL">*GLOBAL*</a> <a rel="help" href="#Conventions">Conventions</a></kbd>
information (see below)
and before the required last line with <kbd>*END_METADATA*</kbd>.
<p>If a spreadsheet is created from an NCCSV file,
the metadata data section will appear with variable names in column A,
attribute names in column B, and values in column C.
<p>If a spreadsheet following these conventions is saved as a CSV file,
there will often be extra commas at the end of the lines in the metadata
section. The software that converts NCCSV files into .nc files will ignore
the extra commas.
<h3><a class="selfLink" id="variableName" href="#variableName" rel="bookmark">variableName</a></h3>
<i>variableName</i> is the case-sensitive name of a variable in the data file.
All variable names must begin with a 7-bit ASCII letter or underscore and
be composed of 7-bit ASCII letters, underscores, and 7-bit ASCII digits.
The special variableName
<a class="selfLink" id="GLOBAL" href="#GLOBAL" rel="bookmark"><kbd>*GLOBAL*</kbd></a> is used to denote global metadata.
<h3><a class="selfLink" id="attributeName" href="#attributeName" rel="bookmark">attributeName</a></h3>
<i>attributeName</i> is the case-sensitive name of an attribute
associated with a variable or <a rel="help" href="#GLOBAL"><kbd>*GLOBAL*</kbd></a>.
All attribute names must begin with a 7-bit ASCII letter or
underscore and be composed of 7-bit ASCII letters, underscores,
and 7-bit ASCII digits.
<p><a class="selfLink" id="SCALAR" href="#SCALAR" rel="bookmark"><kbd><strong>*SCALAR*</strong></kbd></a> —
The special attributeName <kbd>*SCALAR*</kbd>
can be used to create a
scalar data variable and define its value.
The data type of the <kbd>*SCALAR*</kbd> defines the data type
for the variable,
so do not specify a <kbd>*DATA_TYPE*</kbd> attribute for scalar variables.
Note that there must not be data for the scalar variable in the Data Section
of the NCCSV file.
<p>For example, to create a scalar variable named "ship"
with the value "Okeanos Explorer" and a <kbd>cf_role</kbd> attribute, use:
<br><kbd>ship,*SCALAR*,"Okeanos Explorer"
<br>ship,cf_role,trajectory_id</kbd>
<br>When a scalar data variable is read into ERDDAP™,
the scalar value is converted into a column in the data table with the
same value on every row.
<h3><a class="selfLink" id="value" href="#value" rel="bookmark">value</a></h3>
<p><i>value</i> is the value of the metadata attribute
and must be an array with one or more of either a
<kbd>byte, ubyte, short, ushort, int, uint, long, ulong, float, double, String,</kbd> or <kbd>char</kbd>.
No other data types are supported. Attributes with no value will be ignored.
If there is more than one sub-value, the sub-values must all be of the
same data type.
For data types other than Strings, the values MUST be separated by commas, for example:
<br><kbd>sst,actual_range,0.17f,23.58f</kbd>
<br>For Strings, use a single String with
<kbd>\n</kbd> (newline) characters separating the substrings.
<p>The definitions of the attribute data types are:
<ul>
<li><a class="selfLink" id="byte" href="#byte" rel="bookmark"><kbd><strong>byte</strong></kbd></a>
attribute values (8-bit, signed) must be written with the
suffix 'b', e.g., -7b, 0b, 7b . The range of valid byte values is -128 to 127.
A number that looks like a byte but is invalid (e.g., 128b)
will be converted to a missing value or generate an error message.
<br>
<li><a class="selfLink" id="ubyte" href="#ubyte" rel="bookmark"><kbd><strong>ubyte</strong></kbd></a>
attribute values (8-bit, unsigned) must be written with the
suffix 'ub', e.g., 0ub, 7ub, 250ub . The range of valid byte values is 0 to 255.
A number that looks like a ubyte but is invalid (e.g., 256ub)
will be converted to a missing value or generate an error message.
When possible, use byte instead of ubyte, because many systems don't support
unsigned bytes (e.g., attributes in NetCDF-3 files).
<br>
<li><a class="selfLink" id="short" href="#short" rel="bookmark"><kbd><strong>short</strong></kbd></a>
attribute values (16-bit, signed) must be written with the
suffix 's', e.g., -30000s, 0s, 30000s. The range of valid short values is
-32768 to 32767. A number that looks like a short but is invalid (e.g., 32768s)
will be converted to a missing value or generate an error message.
<br>
<li><a class="selfLink" id="ushort" href="#ushort" rel="bookmark"><kbd><strong>ushort</strong></kbd></a>
attribute values (16-bit, unsigned) must be written with the
suffix 'us', e.g., 0us, 30000us, 60000us. The range of valid short values is
0 to 65535. A number that looks like a ushort but is invalid (e.g., 65536us)
will be converted to a missing value or generate an error message.
When possible, use short instead of ushort, because many systems don't support
unsigned bytes (e.g., attributes in NetCDF-3 files).
<br>
<li><a class="selfLink" id="int" href="#int" rel="bookmark"><kbd><strong>int</strong></kbd></a>
attribute values (32-bit, signed) must be written as JSON ints
without a decimal point or exponent, but with the suffix 'i',
e.g., -12067978i, 0i, 12067978i. The range of valid int values is
-2147483648 to 2147483647. A number that looks like an int but is invalid
(e.g., 2147483648i)
will be converted to a missing value or generate an error message.
<br>
<li><a class="selfLink" id="uint" href="#uint" rel="bookmark"><kbd><strong>uint</strong></kbd></a>
attribute values (32-bit, unsigned) must be written as JSON ints
without a decimal point or exponent, but with the suffix 'ui',
e.g., 0ui, 12067978ui, 4123456789ui. The range of valid int values is
0 to 4294967295. A number that looks like a uint but is invalid
(e.g., 2147483648ui)
will be converted to a missing value or generate an error message.
When possible, use int instead of uint, because many systems don't support
unsigned bytes (e.g., attributes in NetCDF-3 files).
<br>
<li><a class="selfLink" id="long" href="#long" rel="bookmark"><kbd><strong>long</strong></kbd></a>
attribute values (64-bit, signed, currently supported by
NUG and ERDDAP™ but not yet supported by CF) must be written without
a decimal point and with the suffix 'L',
e.g., -12345678987654321L, 0L, 12345678987654321L .
If you use the converting software to convert an NCCSV file with long
values into a NetCDF-3 file, any long values will be converted to double values.
The range of valid long values is -9223372036854775808 to 9223372036854775807.
A number that looks like a long but is invalid (e.g., 9223372036854775808L)
will be converted to a missing value or generate an error message.
When possible, use double instead of ulong, because many systems don't support
long (e.g., NetCDF-3 files).
<br>
<li><a class="selfLink" id="ulong" href="#ulong" rel="bookmark"><kbd><strong>ulong</strong></kbd></a>
attribute values (64-bit, unsigned, currently supported by
NUG and ERDDAP™ but not yet supported by CF) must be written without
a decimal point and with the suffix 'uL',
e.g., 0uL, 12345678987654321uL, 9007199254740992uL .
If you use the converting software to convert an NCCSV file with long
values into a NetCDF-3 file, any long values will be converted to double values.
The range of valid long values is 0 to 18446744073709551615.
A number that looks like a ulong but is invalid (e.g., 18446744073709551616uL)
will be converted to a missing value or generate an error message.
When possible, use double instead of ulong, because many systems don't support
signed or unsigned long (e.g., NetCDF-3 files).
<br>
<li><a class="selfLink" id="float" href="#float" rel="bookmark"><kbd><strong>float</strong></kbd></a>
attribute values (32-bit) must be written with the suffix 'f'
and may have a decimal point and/or an exponent,
e.g., 0f, 1f, 12.34f, 1e12f, 1.23e+12f, 1.23e12f, 1.87E-7f.
Use <kbd>NaNf</kbd> for a float NaN (missing) value.
The range of floats is approximately
+/-3.40282347E+38f (~7 significant decimal digits).
A number that looks like a float but is invalid (e.g., 1.0e39f)
will be converted to a missing value or generate an error message.
<br>
<li><a class="selfLink" id="double" href="#double" rel="bookmark"><kbd><strong>double</strong></kbd></a>
attribute values (64-bit) must be written
with the suffix 'd' and may have a decimal point and/or an exponent,
e.g., 0d, 1d, 12.34d, 1e12d, 1.23e+12d, 1.23e12d, 1.87E-7d.
Use <kbd>NaNd</kbd> for a double NaN (missing) value.
The range of doubles is approximately +/-1.79769313486231570E+308d
(~15 significant decimal digits).
A number that looks like a double but is invalid (e.g., 1.0e309d)
will be converted to a missing value or generate an error message.
<br>
<li><a class="selfLink" id="String" href="#String" rel="bookmark"><kbd><strong>String</strong></kbd></a>
attribute values are a sequence of UCS-2 characters
(i.e., 2-byte Unicode characters, as in Java),
which must be written as JSON-like strings.
<ul>
<li>Double quotes (") within a String value must be encoded as two double
quotes (<kbd>""</kbd>). That's what spreadsheet programs require when
reading .csv files. That's what spreadsheet programs write when
you save a spreadsheet as a .csv file.
<li>The special JSON backslash-encoded characters within a String value must be encoded as
in JSON (notably \n (newline), \\ (backslash),
\f (formfeed), \t (tab), \r (carriage return) or with the
<a rel="help" href="#uhhhh">\u<i>hhhh</i></a> syntax. In a spreadsheet,
don't use Alt Enter to specify a new line within a text cell;
instead, use \n (2 characters: backslash and 'n') to indicate a new line.
<li><a class="selfLink" id="uhhhh" href="#uhhhh" rel="bookmark">\u<i>hhhh</i></a> -
All other characters less than character #32 must be encoded with the syntax
<kbd>\u<i>hhhh</i></kbd>, where hhhh is the 4-digit hexadecimal
number of the character.
<li>All printable characters greater than character #126, e.g., the Euro sign,
may appear unencoded, e.g., € (the Euro character), or encoded with the
<a rel="help" href="#uhhhh">\u<i>hhhh</i></a> syntax, e.g., <kbd>\u20AC</kbd>.
See the code pages referenced at
<a rel="bookmark" href="https://en.wikipedia.org/wiki/Unicode"
>https://en.wikipedia.org/wiki/Unicode<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a>
to find the hexadecimal numbers associated with specific Unicode characters,
or use a software library.
Note that some ERDDAP™ output file types, e.g., .csv, use the ISO 8859-1 character set,
so Unicode characters above #255 will be lost when these data values are written to those file types.
<li>All non-printable characters greater than character #126, e.g., character #127,
are STRONGLY DISCOURAGED, but you SHOULD use the \u<i>hhhh</i> syntax if you do include them.
<li>If the String has a space at the beginning or end, or includes <kbd>"</kbd>
(double quote) or a comma, or contains values that would otherwise be
interpreted as some other data type (e.g., an int), or is the word "null",
the entire String must
be enclosed in double quotes; otherwise, unlike JSON,
the enclosing double quotes are optional.
We recommend: when in doubt, enclose the entire String in double quotes.
Spaces at the beginning or end of a String are strongly discouraged.
<br>
</ul>
<li><a class="selfLink" id="char" href="#char" rel="bookmark"><kbd><strong>char</strong></kbd></a>
attribute values are a single UCS-2 character
(i.e., 2-byte Unicode characters, as in Java).
Printable characters (other than special characters like newline, ", ', and \)
can be written as is.
Special characters (e.g., newline) and other unprintable characters (e.g., #127)
must be written with the
<a rel="help" href="#uhhhh">\u<i>hhhh</i></a> syntax.
Char attribute values must be enclosed in single quotes (the inner quotes)
and double quotes (the outer quotes), e.g., <kbd>"'a'", "'""'"</kbd>
(a double quote character),
<kbd>"'\''"</kbd> (a single quote character), <kbd>"'\t'"</kbd> (a tab),
<kbd>"'\u007F'"</kbd> (the delete 'character'), and
<kbd>"'€'"</kbd> (the Euro character). This system of using
single and double quotes is odd and cumbersome, but it is a way to
distinguish char values from Strings in a way that works with spreadsheets.
A value that looks like a char but is invalid will generate an error message.
Note that some ERDDAP™ output file types, e.g., .csv, use the ISO 8859-1 character set,
so Unicode characters above #255 will be lost when these data values are written to those file types.
</ul>
<p><a class="selfLink" id="Suffix" href="#Suffix" rel="bookmark"><strong>Suffix</strong></a> —
Note that in the attributes section of an NCCSV file,
all numeric attribute values must have a suffix letter (e.g., 'b')
to identify the numeric data type (e.g., byte).
But in the data section of an NCCSV file,
numeric data values must never have these suffix letters
(with the exception of 'L' for long integers and 'uL' for ulong integers) —
the data type is specified by the <kbd>*DATA_TYPE*</kbd> attribute for the variable.
<p><a class="selfLink" id="DATA_TYPE" href="#DATA_TYPE" rel="bookmark"><strong>*DATA_TYPE*</strong></a> -
The data type for each non-<a rel="help" href="#SCALAR">scalar</a>
variable must be specified by a
<kbd>*DATA_TYPE*</kbd> attribute which can have a value of
<kbd>byte, ubyte, short, ushort, int, uint, long, ulong, float, double, String,</kbd> or <kbd>char</kbd>
(case insensitive). For example,
<br><kbd>qc_flag,*DATA_TYPE*,byte</kbd>
<br>WARNING: Specifying the correct <kbd>*DATA_TYPE*</kbd> is your responsibility.
Specifying the wrong data type (e.g., <kbd>int</kbd> when you should have
specified <kbd>float</kbd>) will not generate an error message and may cause
information to be lost (e.g., float values will be rounded to ints)
when the NCCSV file is read by ERDDAP™ or converted into a NetCDF file.
<p><a class="selfLink" id="charDiscouraged" href="#charDiscouraged" rel="bookmark"><kbd>char</kbd> Discouraged</a> -
The use of <kbd>char</kbd> data values is discouraged because they are not widely
supported in other file types. <kbd>char</kbd> values may be written in the
data section as single characters or as Strings (notably, if you need to
write a special character). If a String is found, the first character of the
String will be used as the char's value. Zero length Strings and missing values
will be converted to character \uFFFF. Note that NetCDF files only support
single byte chars, so any chars greater than char #255 will be converted to
'?' when writing NetCDF files. Unless a <kbd>charset</kbd> attribute is used
to specify a different charset for a char variable, the ISO-8859-1 charset
will be used.
<p><a class="selfLink" id="longDiscouraged" href="#longDiscouraged" rel="bookmark"
><kbd>long</kbd> and Unsigned Types Are Discouraged</a> -
Although many file types (e.g., NetCDF-4 and json) and ERDDAP™ support
<kbd>long</kbd> and unsigned (ubyte, ushort, uint, ulong) values,
the use of <kbd>long</kbd> and unsigned values in
NCCSV files is currently discouraged because they are currently
not supported by Excel, CF and NetCDF-3 files.
If you want to specify <kbd>long</kbd> or unsigned values in an NCCSV file
(or in the corresponding Excel spreadsheet),
you must use the suffix 'L' so that Excel doesn't treat the numbers as
floating point numbers with lower precision.
Currently, if an NCCSV files is converted into a NetCDF-3 .nc file,
<kbd>long</kbd> and <kbd>ulong</kbd> data values will be converted into <kbd>double</kbd> values,
causing a loss of precision for very large values
(less than -2^53 for long, or greater than 2^53 for long and ulong).
In NetCDF-3 .nc files, ubyte, ushort, and uint variables appear as
byte, short, and int with the <kbd>_Unsigned=true</kbd> metadata attribute.
In NetCDF-3 .nc files, ubyte, ushort, and uint attributes appear as
byte, short, and int attributes containing the corresponding two's-complement value
(e.g., 255ub appears as -1b). This is obviously trouble, so signed
data types should be used instead of unsigned data types whenever possible.
<p><a class="selfLink" id="ERDDAP_Metadata" href="#ERDDAP_Metadata" rel="bookmark"><strong>CF, ACDD, and ERDDAP™ Metadata</strong></a> -
Since it is envisioned that most NCCSV files, or the .nc files
created from them, will be read into ERDDAP,
it is strongly recommended that NCCSV files include the metadata attributes
which are required or recommended by ERDDAP™ (see
<br><a rel="bookmark" href="https://erddap.github.io/setupDatasetsXml.html#globalAttributes"
>https://erddap.github.io/setupDatasetsXml.html#globalAttributes</a>).
The attributes are almost all from the CF and ACDD metadata standards and
serve to properly describe the dataset (who, what, when, where, why, how)
to someone who otherwise knows
nothing about the dataset. Of particular importance,
almost all numeric variables should have a <kbd>units</kbd>
attribute with a UDUNITS-compatible value, e.g.,
<br><kbd>sst,units,degree_C</kbd>
<p>It is fine to include additional attributes which are not from the
CF or ACDD standards or from ERDDAP.
<p>
<h2><a class="selfLink" id="TheDataSection" href="#TheDataSection" rel="bookmark">The Data Section</a></h2>
<h3><a class="selfLink" id="Structure" href="#Structure" rel="bookmark">Structure</a></h3>
The first line of the data section must have a case-sensitive,
comma-separated list of variable names.
All of the variables in this list must be described in the metadata section,
and vice versa (other than <a rel="help" href="#GLOBAL"><kbd>*GLOBAL*</kbd></a> attributes
and <a rel="help" href="#SCALAR"><kbd>*SCALAR*</kbd></a> variables).
<p>The second through the penultimate lines of the data section must
have a comma-separated list of values.
Each row of data must have the same number of values as the comma-separated
list of variable names.
Spaces before or after values are not allowed because they cause problems
when importing the file into spreadsheet programs.
Each column in this section must contain only values of the <kbd>*DATA_TYPE*</kbd>
specified for that variable by the <kbd>*DATA_TYPE*</kbd>
attribute for that variable.
Unlike in the attributes section, numeric values in the data section
must not have suffix letters to denote the data type.
Unlike in the attributes section, char values in the data section
may omit the enclosing single quotes if they are not needed for disambiguation
(thus, ',' and '\'' must be quoted as shown here).
There may be any number of these data rows in an NCCSV file,
but currently ERDDAP™ can only read NCCSV files with up to
about 2 billion rows.
In general, it is recommended that you split large datasets into
multiple NCCSV data files with fewer than 1 million rows each.
<p><a class="selfLink" id="END_DATA" href="#END_DATA" rel="bookmark"><kbd>*END_DATA*</kbd></a> -
The end of the data section must be denoted by a line with only
<br><kbd>*END_DATA*</kbd>
<p>If there is additional content in the NCCSV file after the
<kbd>*END_DATA*</kbd> line, it will be ignored when the NCCSV file is
converted into an .nc file. Such content is therefore discouraged.
<p>In a spreadsheet following these conventions,
the variable names and data values will be in multiple columns.
See the example below.
<h3><a class="selfLink" id="MissingValues" href="#MissingValues" rel="bookmark">Missing Values</a></h3>
<p>Numeric missing values may be written as a numeric value identified by a
<kbd>missing_value</kbd> or <kbd>_FillValue</kbd> attribute for that variable.
For example, see the second value on this data row:
<br><kbd>Bell M. Shimada,99,123.4</kbd>
<br>This is the recommended way to handle missing values for
byte, ubyte, short, ushort, int, uint, long, and ulong variables.
<p>float or double NaN values may be written as <kbd>NaN</kbd>.
For example, see the second value on this data row:
<br><kbd>Bell M. Shimada,NaN,123.4</kbd>
<p>String and numeric missing values may be indicated by an empty field.
For example, see the second value on this data row:
<br><kbd>Bell M. Shimada,,123.4</kbd>
<p>For byte, ubyte, short, ushort, int, uint, long, and ulong variables,
the NCCSV converter utility and ERDDAP™ will convert an empty field
into the maximum allowed value for that data type (e.g., 127 for bytes).
If you do this, be sure to add a <kbd>missing_value</kbd> or
<kbd>_FillValue</kbd> attribute for that variable to identify this value,
e.g.,
<br><kbd><i>variableName</i>,_FillValue,127b</kbd>
<br>For float and double variables, an empty field will be converted to NaN.
<h3><a class="selfLink" id="DateTimeValues" href="#DateTimeValues" rel="bookmark">DateTime Values</a></h3>
DateTime values (including date values that don't have a time component)
may be represented as numbers or as Strings in NCCSV files.
A given dateTime variable may only have String values or only numeric values,
not both. The NCCSV software will convert String dateTime values into numeric
dateTime values when creating .nc files (as required by CF).
String dateTime values have the advantage of being easily readable by humans.
<p>DateTime values represented as numeric values must have a
<kbd>units</kbd> attribute which specifies the "<i>units</i> since <i>dateTime</i>"
as required by CF and specified by UDUNITS, e.g.,
<br><kbd>time,units,seconds since 1970-01-01T00:00:00Z</kbd>
<p>DateTime values represented as String values must have a
String <kbd>*DATA_TYPE*</kbd> attribute and a <kbd>units</kbd> attribute
which specifies a dateTime pattern as specified by the
Java DateTimeFormatter class
<br>(<a rel="bookmark"
href="https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html"
>https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a>). For example,
<br><kbd>time,units,yyyy-MM-dd'T'HH:mm:ssZ</kbd>
<br>All dateTime values for a given data variable must use the same format.
<br>In most cases, the dateTime pattern you need for the <kbd>units</kbd>
attribute will be a variation of one of these formats:
<ul>
<li>yyyy-MM-dd'T'HH:mm:ss.SSSZ — which is the ISO 8601:2004(E) dateTime format.
You may need a shortened version of this,
e.g., yyyy-MM-dd'T'HH:mm:ssZ (the only recommended format) or yyyy-MM-dd.
If you are changing the format of your dateTime values,
NCCSV strongly recommends that you change to this format (perhaps shortened).
This is the format that ERDDAP™ will use when it writes NCCSV files.
<li>yyyyMMddHHmmss.SSS — which is the compact version of the ISO 8601:2004
dateTime format. You may need a shortened version of this, e.g., yyyyMMdd.
<li>M/d/yyyy H:mm:ss.SSS — which handles US-style dates and dateTimes like
"3/23/2017 16:22:03.000". You may need a shortened version of this,
e.g., M/d/yyyy .
<li>yyyyDDDHHmmssSSS — which is the year plus the zero-padded
day of the year (e.g, 001 = Jan 1, 365 = Dec 31 in a non-leap year;
this is sometimes erroneously called the Julian date).
You may need a shortened version of this, e.g., yyyyDDD .
</ul>
<p><a class="selfLink" id="Precision" href="#Precision" rel="bookmark">Precision</a> —
When a software library converts an .nc file into an NCCSV file,
all dateTime values will be written as Strings with the
ISO 8601:2004(E) dateTime format, e.g., 1970-01-01T00:00:00Z .
You can control the precision with the ERDDAP-specific attribute
<kbd>time_precision</kbd>. See
<br><a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#time_precision"
>https://erddap.github.io/setupDatasetsXml.html#time_precision</a>.
<p><a class="selfLink" id="TimeZone" href="#TimeZone" rel="bookmark">Time Zone</a> —
The default time zone for dateTime values is the Zulu (or GMT)
time zone, which has no daylight saving time periods.
If a dateTime variable has dateTime values from a different time zone,
you must specify this with the ERDDAP-specific attribute <kbd>time_zone</kbd>.
This is a requirement for ERDDAP™ (see
<br><a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#time_zone"
>https://erddap.github.io/setupDatasetsXml.html#time_zone</a>).
<h3><a class="selfLink" id="DegreeValues" href="#DegreeValues" rel="bookmark">Degree Values</a></h3>
As required by CF, all degree values (e.g., for longitude and latitude)
must be specified as decimal-degree double values,
not as a degree°min'sec" String or as separate variables for
degrees, minutes, seconds.
The direction designators N, S, E, and W are not allowed.
Use negative values for West longitudes and for South latitudes.
<p>
<h2><a class="selfLink" id="DSGFeatureTypes" href="#DSGFeatureTypes" rel="bookmark">DSG Feature Types</a></h2>
An NCCSV file may contain CF Discrete Sampling Geometry
<br>(<a rel="bookmark" href="https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#discrete-sampling-geometries"
>https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#discrete-sampling-geometries<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a>) data. It is the attributes that make this work:
<ol>
<li>As required by CF, the NCCSV file must include a line in the
metadata section identifying the <a rel="help" href="#GLOBAL"><kbd>*GLOBAL*</kbd></a>
featureType attribute, e.g.,
<br><kbd>*GLOBAL*,featureType,trajectory</kbd>
<li>For use in ERDDAP™, the NCCSV file must include a line or lines
in the metadata section identifying the <kbd>cf_role=..._id</kbd> variables, e.g.,
<br><kbd>ship,cf_role,trajectory_id</kbd>
<br>This is optional for CF, but required in NCCSV.
<li>For use in ERDDAP™, the NCCSV file must include a line or lines
in the metadata section identifying which variables are associated
with each timeSeries, trajectory, or profile as required by ERDDAP™ (see
<br><a rel="bookmark"
href="https://erddap.github.io/setupDatasetsXml.html#cdm_data_type"
>https://erddap.github.io/setupDatasetsXml.html#cdm_data_type</a>), e.g.,
<br><kbd>*GLOBAL*,cdm_trajectory_variables,"ship"</kbd>
<br>or
<br><kbd>*GLOBAL*,cdm_timeseries_variables,"station_id,lat,lon"</kbd>
</ol>
<p>
<h2><a class="selfLink" id="SampleFile" href="#SampleFile" rel="bookmark">Sample File</a></h2>
Here is a sample file which demonstrates many of the features of an NCCSV file:
<pre>
*GLOBAL*,Conventions,"COARDS, CF-1.6, ACDD-1.3, NCCSV-1.2"
*GLOBAL*,cdm_trajectory_variables,"ship"
*GLOBAL*,creator_email,erd.data@noaa.gov
*GLOBAL*,creator_name,Bob Simons
*GLOBAL*,creator_type,person
*GLOBAL*,creator_url,https://www.pfeg.noaa.gov
*GLOBAL*,featureType,trajectory
*GLOBAL*,infoUrl,https://erddap.github.io/NCCSV.html
*GLOBAL*,institution,"NOAA NMFS SWFSC ERD, NOAA PMEL"
*GLOBAL*,license,"""NCCSV Demonstration"" by Bob Simons and Steve Hankin is
licensed under CC BY 4.0, https://creativecommons.org/licenses/by/4.0/ ."
*GLOBAL*,keywords,"NOAA, sea, ship, sst, surface, temperature, trajectory"
*GLOBAL*,standard_name_vocabulary,CF Standard Name Table v55
*GLOBAL*,subsetVariables,"ship"
*GLOBAL*,summary,"This is a paragraph or two describing the dataset."
*GLOBAL*,title,"NCCSV Demonstration"
ship,*DATA_TYPE*,String
ship,cf_role,trajectory_id
time,*DATA_TYPE*,String
time,standard_name,time
time,units,"yyyy-MM-dd'T'HH:mm:ssZ"
lat,*DATA_TYPE*,double
lat,units,degrees_north
lon,*DATA_TYPE*,double
"lon","units","degrees_east"
status,*DATA_TYPE*,char
status,comment,"From http://some.url.gov/someProjectDocument , Table C"
testByte,*DATA_TYPE*,byte
testByte,units,1
testUByte,*DATA_TYPE*,ubyte
testUByte,units,1
testLong,*DATA_TYPE*,long
testLong,units,1
testULong,*DATA_TYPE*,ulong
testULong,units,1
sst,*DATA_TYPE*,float
sst,standard_name,sea_surface_temperature
sst,actual_range,0.17f,23.58f
sst,units,degree_C
sst,missing_value,99f
sst,testBytes,-128b,0b,127b
sst,testShorts,-32768s,0s,32767s
sst,testInts,-2147483648i,0i,2147483647i
sst,testLongs,-9223372036854775808L,0L,9223372036854775807L
sst,testFloats,-3.40282347e38f,0f,3.40282347E+38f
sst,testDoubles,-1.79769313486231570e308d,0d,1.79769313486231570E+308d
sst,testChars,"','","'""'","'€'"
sst,testStrings," a~,\n'z""\u20AC"
sst,testUBytes,0ub,127ub,255ub
sst,testUInts,0ui,2147483647ui,4294967295ui
sst,testULongs,0uL,9223372036854775807uL,18446744073709551615uL
sst,testUShorts,0us,32767us,65535us
*END_METADATA*
ship,time,lat,lon,status,testByte,testUByte,testLong,testULong,sst
Bell M. Shimada,2017-03-23T00:45:00Z,28.0002,-130.2576,A,-128, 0,-9223372036854775808L,0uL,10.9
Bell M. Shimada,2017-03-23T01:45:00Z,28.0003,-130.3472,\u20AC,0,127,-9007199254740992L,9223372036854775807uL,10.0
"Bell M. Shimada","2017-03-23T02:45:00Z",28.0001,-130.4305,"'\t'",126,254,9223372036854775806L,18446744073709551614uL,99
"Bell M. Shimada",2017-03-23T12:45:00Z,27.9998,-131.5578,"'""'",127,255,9223372036854775807L,18446744073709551615uL,NaN
<!-- the lines in sample.csv with invalid values or "" for mv integers are omitted here because they aren't the recommended approach -->
</pre>
<p>Notes:
<ul>
<li>This sample file includes many difficult cases (e.g., <kbd>char</kbd> and
<kbd>long</kbd> variables and difficult String values).
Most NCCSV files will be much simpler.
<li>The <kbd>license</kbd> line is broken into two lines here, but is just
one line in the sample file.
<li>\u20ac is the \uhhhh encoding of €. \u00FC is the \uhhhh encoding of ü.
You can also use the unencoded characters directly.
<li>Many Strings in the example are enclosed by double quotes
even though they don't have to be,
e.g., many global attributes including the title, the <kbd>lon units</kbd>
attribute, and the 3rd line of data.)
<li>It would be clearer and better if the units attribute
for the testLong variable were written in double quotes indicating
it is a String value. But the current representation (<kbd>1</kbd>,
without quotes) will be interpreted correctly as a String,
not an integer, because there is no 'i' suffix.
<li>Unlike other numeric data types, the <kbd>long</kbd> values
in the data section have the suffix ('L') that identifies
their numeric data type.
This is required to prevent spreadsheets from interpreting the
values as floating point numbers and thus losing precision.
</ul>
<p>
<h2><a class="selfLink" id="Spreadsheets" href="#Spreadsheets" rel="bookmark">Spreadsheets</a></h2>
In a spreadsheet, as in an NCCSV file:
<ul>
<li>Write numeric attribute values as specified for NCCSV files
(e.g., with a suffix letter, e.g., 'f', to identify attribute's data type).
<li>In Strings, all non-printable and special characters must be written
as either a JSON-like backslashed character
(e.g., <kbd>\n</kbd> for newline) or as the hexadecimal Unicode character number
(case insensitive) with the syntax
<a rel="help" href="#uhhhh"><kbd>\u<i>hhhh</i></kbd></a>.
Notably, use <kbd>\n</kbd> (2 characters: backslash and 'n')
to indicate a new line within a String, not Alt Enter.
All printable characters may be written unencoded or with the syntax
<a rel="help" href="#uhhhh"><kbd>\u<i>hhhh</i></kbd></a>.
</ul>
<p>The only differences between NCCSV files and the analogous spreadsheet
which follow these conventions are:
<ul>
<li>NCCSV files have values on a line separated by commas.
<br>Spreadsheets have values on a line in adjacent cells.
<li>Strings in NCCSV files are often surrounded by double quotes.
<br>Strings in spreadsheets are never surrounded by double quotes.
<li>Internal double quotes ( " ) in Strings in NCCSV files appear as
2 double quotes.
<br>Internal double quotes in spreadsheets appear as 1 double quote.
</ul>
<p>If a spreadsheet following these conventions is saved as a CSV file,
there will often be extra commas at the end of many of the lines.
The software that converts NCCSV files into .nc files will ignore the extra commas.
<h3><a class="selfLink" id="Excel" href="#Excel" rel="bookmark">Excel</a></h3>
<p>To import an NCCSV file into Excel:
<ol>
<li>Choose <kbd>File : Open</kbd> .
<li>Change the file type to <kbd>Text Files (*.prn; *.txt; *.csv)</kbd> .
<li>Search the directories and click on the NCCSV .csv file.
<li>Click <kbd>Open</kbd> .
</ol>
<p>To create an NCCSV file from an Excel spreadsheet:
<ol>
<li>Choose <kbd>File : Save As</kbd> .
<li>Change the <kbd>Save as type:</kbd> to be <kbd>CSV (Comma delimited) (*.csv)</kbd> .
<li>In response to the compatibility warning, click <kbd>Yes</kbd> .
<li>The resulting .csv file will have extra commas at the end
of all the rows other than the CSV rows. You can ignore them.
</ol>
<p>In Excel, the sample NCCSV file above appears as
<p>
<img alt="sampleExcel.png" src="sampleExcel.png" title="">
<h3><a class="selfLink" id="GoogleSheets" href="#GoogleSheets" rel="bookmark">Google Sheets</a></h3>
To import an NCCSV file into Google Sheets:
<ol>
<li>Choose <kbd>File : Import</kbd> .
<li>Choose to <kbd>Upload</kbd> a file and click on
<kbd>Upload a file from your computer</kbd> .
Select the file, then click <kbd>Open</kbd> .
<br>
<br>Or, choose <kbd>My Drive</kbd> and change the file type drop down
selection to <kbd>All file types</kbd> .
Select the file, then click <kbd>Open</kbd> .
</ol>
<p>To create an NCCSV file from a Google Sheets spreadsheet:
<ol>
<li>Choose <kbd>File : Save As</kbd> .
<li>Change the <kbd>Save as type:</kbd> to be <kbd>CSV (Comma delimited) (*.csv)</kbd> .
<li>In response to the compatibility warning, click <kbd>Yes</kbd> .
<li>The resulting .csv file will have extra commas at the end of all the rows
other than the CSV rows. Ignore them.
</ol>
<p>
<h2><a class="selfLink" id="Problems" href="#Problems" rel="bookmark">Problems/Warnings</a></h2>
<ul>
<li>If you create an NCCSV file with a text editor or if you create an
analogous spreadsheet in a spreadsheet program, the text editor
or the spreadsheet program will not check that you followed these
conventions correctly. It is up to you to follow these conventions correctly.
<li>The conversion of a spreadsheet following this convention
into a csv file (thus, an NCCSV file) will lead to extra commas
at the end of all the rows other than the CSV data rows.
Ignore them.
The software then converts NCCSV files into .nc files will ignore them.
<li>If an NCCSV file has excess commas at the end of rows,
you can remove them by converting the NCCSV file into a NetCDF file
and then converting the NetCDF file back into a NCCSV file.
<li>When you try to convert an NCCSV file into a NetCDF file, some errors
will be detected by the software and will generate error messages,
causing the conversion to fail.
Other problems are hard or impossible to catch and will not
generate error messages or warnings. Other problems
(e.g., excess commas at the end of rows) will be ignored.
The file converter will do only minimal checking of correctness
of the resulting NetCDF file, e.g., in regards to CF compliance.
It is the file creator's and file user's responsibility to check
that the results of the conversion are as desired and correct.
Two ways to check are:
<ul>
<li>Print the contents of the .nc file with ncdump
<br>(<a href="https://linux.die.net/man/1/ncdump"
>https://linux.die.net/man/1/ncdump<img
src="../images/external.png" alt=" (external link)"
title="This link to an external website does not constitute an endorsement."></a>
).
<li>View the contents of the data in ERDDAP.
</ul>
</ul>
<p>
<h2><a class="selfLink" id="Changes" href="#Changes" rel="bookmark">Changes</a></h2>
The original version was <a rel="bookmark" href="./NCCSV_1.00">NCCSV v1.00</a> (in ERDDAP™ v1.76, released 2017-05-12)
<ul>
<li>Changes introduced in <a rel="bookmark" href="./NCCSV_1.10">NCCSV v1.10</a> (in ERDDAP™ v2.10, released 2020-11-05):
<ul>
<li>Added support for ubyte, ushort, uint, ulong.
Thanks to CF for adding support for these data types in CF.
</ul>
<li>Changes introduced in v1.20 (in ERDDAP™ v2.23, released 2023-02-27):
<ul>
<li>Switched from ASCII character encoding to UTF-8 encoding for NCCSV .csv files.
<ul>
<li>ERDDAP™ can still read files from all previous and current versions of NCCSV.
<li>ERDDAP™ now always writes NCCSV v1.20 files.
<li>If you wrote a client to read NCCSV files, change it so it treats all NCCSV files as UTF-8 files.
That will work with older NCCSV files because ASCII is a subset of the UTF-8 character encoding.
<li>Thanks to Pauline Chauvet, Nate, and Thomas Gardiner.
</ul>
</ul>
</ul>
<br>
<hr>
<h2><a class="selfLink" id="contact" href="#contact" rel="bookmark">Contact</a></h2>
Questions, comments, suggestions? Please send an email to
<kbd>erd dot data at noaa dot gov</kbd> .
<br>
<hr>
<p>ERDDAP, Version 2.25
<br><a rel="bookmark" href="https://coastwatch.pfeg.noaa.gov/erddap/legal.html">Disclaimers</a> |
<a rel="bookmark" href="https://coastwatch.pfeg.noaa.gov/erddap/legal.html#privacyPolicy">Privacy Policy</a>
</div>
</body>
</html>