Пропустить основной контент

NCCSV -

А.NetCDFСовместимость, UTF-8, CSV Спецификация файлов, Версия 1.20

Боб Саймонс и Стив Хэнкин «NCCSV» Боба Саймонса и Стива Хэнкина лицензированаCC BY 4.0

Введение​

Этот документ определяет формат текстового файла UTF-8 CSV, который может содержать всю информацию. (метаданные и данные) которые можно найти вNetCDF .ncФайл, содержащий CSV-файлоподобную таблицу данных. Расширение файла для текстового файла UTF-8 CSV после этой спецификации должно быть .csv, чтобы его можно было легко и правильно читать в программах электронных таблиц, таких как Excel и Google Sheets. Боб Саймонс напишет программное обеспечение для преобразования файла NCCSV вNetCDF-3 (А также, возможно, иNetCDF-4) .ncФайл и обратно, без потери информации. Боб Саймонс изменилсяERDDAP™Поддерживать чтение и написание этого типа файлов.

Формат NCCSV разработан таким образом, что программное обеспечение для электронных таблиц, такое как Excel и Google Sheets, может импортировать файл NCCSV в виде файла csv, причем вся информация в ячейках электронных таблиц готова к редактированию. Или электронная таблица может быть создана с нуля после конвенций NCCSV. Независимо от источника электронной таблицы, если она затем экспортируется в виде файла .csv, она будет соответствовать спецификации NCCSV и никакая информация не будет потеряна. Единственными различиями между файлами NCCSV и аналогичными файлами электронных таблиц, которые следуют этим конвенциям, являются:

  • Файлы NCCSV имеют значения на строке, разделенной запятыми. Электронные таблицы имеют значения на линии в соседних ячейках.
  • Струны в файлах NCCSV часто окружены двойными цитатами. Струны в электронных таблицах никогда не окружены двойными цитатами.
  • Внутренние двойные цитаты (") В строках в файлах NCCSV отображаются 2 двойные цитаты. Внутренние двойные котировки в электронных таблицах выглядят как 1 двойная цитата.

Видишь?Электронная таблицаРаздел ниже для получения дополнительной информации.

потоковый​

Как и файлы CSV в целом, файлы NCCSV являются потоковыми. Таким образом, если NCSV генерируется на лету сервером данных, таким какERDDAP™Сервер может начать передавать данные запрашивающему лицу до того, как все данные будут собраны. Это полезная и желательная особенность.NetCDFФайлы, напротив, не являются потоковыми.

ERDDAP​

Эта спецификация разработана таким образом, что файлы NCCSV и.ncФайлы, которые могут быть созданы из них, могут быть использованыERDDAP™сервер данных (черезEDDTable FromNccsvFilesиEDDTable FromNcFilesТипы наборов данных) Но эта спецификация является внешней дляERDDAP.ERDDAP™имеет несколько требуемых глобальных атрибутов и многие рекомендуемые глобальные и переменные атрибуты, в основном основанные на атрибутах CF и ACDD (см. /docs/server-admin/datasets#глобальные атрибуты).

Баланс​

Конструкция формата NCCSV представляет собой баланс нескольких требований:

  • Файлы должны содержать все данные и метаданные, которые будут в табличке.NetCDFФайлы, включая конкретные типы данных.
  • Файлы должны быть в состоянии быть прочитаны, а затем написаны из электронной таблицы без потери информации.
  • Файлы должны быть простыми для создания, редактирования, чтения и понимания.
  • Файлы должны быть однозначно разобраны компьютерными программами.

Если какое-то требование в этом документе кажется странным или придирчивым, оно, вероятно, необходимо для удовлетворения одного из этих требований.

Другие спецификации​

Эта спецификация относится к нескольким другим спецификациям и библиотекам, с которыми она предназначена для работы, но эта спецификация не является частью какой-либо из этих других спецификаций, и она не нуждается в каких-либо изменениях в них и не конфликтует с ними. Если деталь, связанная с одним из этих стандартов, не указана здесь, см. соответствующую спецификацию. Примечательно, что это включает в себя:

Запись​

В этой спецификации, скобки,\[ \], обозначают факультативные пункты.

Файловая структура​

Полный файл NCCSV состоит из двух разделов: раздела метаданных, за которым следует раздел данных.

Файлы NCCSV могут содержать любые символы UCS-2 (2-байтовые символы Unicode, как вJava) Кодируется через UTF-8.ERDDAP™читает и записывает файлы NCCSV с помощью кодирования UTF-8.

Файлы NCCSV могут использовать любую новую строку (\n) (который распространен на компьютерах Linux и Mac OS X) Возврат плюс новая линия (\r\n) (Что распространено на компьютерах Windows) как конечные маркеры, но не оба.

.nccsvМетаданные​

Когда и создатель, и читатель ожидают этого, также возможно и иногда полезно сделать вариант файла NCCSV, который содержит только раздел метаданных. (включая\*ЭНД _МЕТАДАТА\*линия) . Результат обеспечивает полное описание атрибутов файла, имен переменных и типов данных, таким образом, служа той же цели, что и ответы .das + .dds от одного и того же файла.OPeNDAPСервер.ERDDAP™Вы вернете эту вариацию, если запросите файл Тип =.nccsvМетаданные из одногоERDDAP™набор данных.

Раздел Метаданные​

В файле NCCSV каждая строка раздела метаданных использует формат. переменный Имя,атрибут Имя,значение 1\[значение 2\]\[значение 3\]\[значение 4\]\[...\]
Пространства до или после элементов не допускаются, поскольку они вызывают проблемы при импорте файла в программы электронных таблиц.

Конвенции​

Первая строка файла NCCSV является первой строкой раздела метаданных и должна иметь\Глобал\Конвенции приписывают перечисление всех конвенций, используемых в файле, в качестве строки, содержащей список CSV, например: \*Глобал\*Конвенции,COARDS, CF-1.6, ACDD-1.3, NCCSV-1.2". Одной из перечисленных конвенций должна быть NCCSV-1.2, которая относится к текущей версии этой спецификации.

Конец метаданных​

Конец раздела метаданных файла NCCSV должен обозначаться строкой, содержащей только \ЭНД _МЕТАДАТА\

Рекомендуется, но не требуется, чтобы все атрибуты данной переменной отображались на соседних линиях раздела метаданных. Если файл NCCSV преобразуется вNetCDFфайл, порядок первого появления переменных имен в разделе метаданных будет порядком переменных вNetCDFФайл.

Необязательные пустые строки допускаются в разделе метаданных после требуемой первой строки.\Глобал\ Конвенцииинформация (см. ниже) Перед требуемой последней строкой\ЭНД _МЕТАДАТА\.

Если электронная таблица создается из файла NCCSV, появится раздел данных метаданных с переменными именами в столбце A, именами атрибутов в столбце B и значениями в столбце C.

Если таблица, следующая этим конвенциям, сохраняется в виде файла CSV, в конце строк в разделе метаданных часто будут дополнительные запятые. Программное обеспечение, которое преобразует файлы NCCSV в.ncФайлы будут игнорировать дополнительные запятые.

переменный Имя​

переменный Имя является чувствительным к регистру именем переменной в файле данных. Все переменные имена должны начинаться с 7-битной буквы ASCII или подчеркивания и состоять из 7-битных букв ASCII, подчеркиваний и 7-битных цифр ASCII.

Глобал​

Специальное переменное имя\Глобал\Используется для обозначения глобальных метаданных.

атрибут Имя​

атрибут Имя является чувствительным к регистру именем атрибута, связанного с переменной или\Глобал\. Все имена атрибутов должны начинаться с 7-битной буквы ASCII или подчеркивания и состоять из 7-битных букв ASCII, подчеркиваний и 7-битных цифр ASCII.

СКАЛАР​

Особый атрибут Имя\*СКАЛАР\*Может использоваться для создания скалярной переменной данных и определения ее значения. Тип данных для\*СКАЛАР\*определяет тип данных для переменной, поэтому не указывайте\*Данные _TYPE\*атрибут для скалярных переменных. Обратите внимание, что в разделе данных файла NCCSV не должно быть данных для скалярной переменной.

Например, для создания скалярной переменной под названием «корабль» со значением «Okeanos Explorer» и атрибутом cf\_role используйте: корабль,\СКАЛАР\«Okeanos Explorer» Корабль, cf\_role,trajectory\_id Когда скалярная переменная данных читается вERDDAP™, скалярное значение преобразуется в столбец в таблице данных с одинаковым значением на каждой строке.

ценность​

ценность является значением атрибута метаданных и должен быть массивом с одним или несколькими байтами, убайтами, короткими, короткими, int, uint, длинными, ulong, плавающими, двойными, струнными или char. Другие типы данных не поддерживаются. Атрибуты, не имеющие ценности, будут игнорироваться. Если существует более одного суб-значения, все суб-значения должны быть одного и того же типа данных. Для типов данных, отличных от строк, значения должны быть разделены запятыми, например: sst,actual\_range0.17f,23.58f Для струн используйте одну струну с\n (новая линия) Персонажи, разделяющие подстроки.

Определения типов данных атрибутов:

байт​

  • значения атрибутов байта (8-битный, подписанный) должно быть написано с суффиксом 'b', например, -7b, 0b, 7b. Диапазон допустимых значений байта составляет -128 до 127. Число, которое выглядит как байт, но является недействительным (Например, 128b) преобразуется в недостающее значение или генерирует сообщение об ошибке.  

убайт​

  • значения атрибутов ubyte (8-битный, неподписанный) должны быть написаны с суффиксом «ub», например, 0ub, 7ub, 250ub. Диапазон допустимых значений байта составляет от 0 до 255. Число, которое выглядит как убайт, но является недействительным (Например, 256ub) Преобразуется в недостающее значение или генерирует сообщение об ошибке. Когда это возможно, используйте байт вместо убайт, потому что многие системы не поддерживают неподписанные байты. (Например, атрибуты вNetCDF-3 файла) .  

короткий​

  • короткие значения атрибутов (16-битный, подписанный) должны быть написаны с суффиксом 's', например, -30000s, 0s, 30000s. Диапазон допустимых коротких значений составляет -32768-32767. Число, которое выглядит как короткое, но недействительно (Например, 32768) преобразуется в недостающее значение или генерирует сообщение об ошибке.  

низкорослый​

  • значения атрибутов ushort (16-битный, неподписанный) должно быть написано с суффиксом «нас», например, 0us, 30000us, 60000us. Диапазон допустимых коротких значений составляет от 0 до 65535. Число, которое выглядит как короткое, но недействительно (Например, 65536us) Преобразуется в недостающее значение или генерирует сообщение об ошибке. По возможности используйте короткие, а не короткие, потому что многие системы не поддерживают неподписанные байты. (Например, атрибуты вNetCDF-3 файла) .  

байт​

  • значения атрибутов int (32-битный, подписанный) должны быть записаны как JSON ints без десятичной точки или показателя, но с суффиксом 'i', например, -12067978i, 0i, 12067978i. Диапазон допустимых значений int составляет -2147483648 до 2147483647. Число, которое выглядит как int, но является недействительным (например, 2147483648i) преобразуется в недостающее значение или генерирует сообщение об ошибке.  

uint​

  • значения атрибутов uint (32-разрядный, неподписанный) должны быть записаны как JSON ints без десятичной точки или показателя, но с суффиксом ui, например, 0ui, 12067978ui, 4123456789ui. Диапазон допустимых значений int составляет от 0 до 4294967295. Число, которое выглядит как uint, но является недействительным (например, 2147483648ui) Преобразуется в недостающее значение или генерирует сообщение об ошибке. По возможности используйте int вместо uint, потому что многие системы не поддерживают неподписанные байты. (Например, атрибуты вNetCDF-3 файла) .  

длинный​

  • Длинные значения атрибутов (64-разрядный, подписанный, в настоящее время поддерживаемый NUGERDDAP™Пока не поддерживается CF) должны быть написаны без десятичной точки и с суффиксом 'L', например, -12345678987654321L, 0L, 12345678987654321L. Если вы используете преобразующее программное обеспечение для преобразования файла NCCSV с длинными значениями вNetCDF-3 файл, любые длинные значения будут преобразованы в двойные значения. Диапазон допустимых значений длины -9223372036854775808 до 9223372036854775807. Число, которое выглядит как длинное, но недействительно (например, 9223372036854775808L) Преобразуется в недостающее значение или генерирует сообщение об ошибке. Когда это возможно, используйте двойной вместо ulong, потому что многие системы не поддерживают долго. (например,NetCDF-3 файла) .  

улун​

  • значения атрибутов ulong (64-разрядный, неподписанный, в настоящее время поддерживается NUGERDDAP™Пока не поддерживается CF) должны быть написаны без десятичной точки и с суффиксом 'uL', например, 0uL, 12345678987654321uL, 9007199254740992uL. Если вы используете преобразующее программное обеспечение для преобразования файла NCCSV с длинными значениями вNetCDF-3 файл, любые длинные значения будут преобразованы в двойные значения. Диапазон действительных длинных значений составляет от 0 до 18446744073709551615. Число, которое выглядит как улонг, но является недействительным (например, 18446744073709551616uL) Преобразуется в недостающее значение или генерирует сообщение об ошибке. Когда это возможно, используйте двойной вместо ulong, потому что многие системы не поддерживают подписанные или неподписанные долго. (например,NetCDF-3 файла) .  

плавать​

  • значение атрибута float (32-битный) должны быть записаны с суффиксом 'f' и могут иметь десятичную точку и/или показатель, например, 0f, 1f, 12.34f, 1e12f, 1.23e+12f, 1.23e12f, 1.87E-7f. Используйте NaNf для поплавка NaN (пропавший) ценность. Диапазон поплавков составляет приблизительно +/-3.40282347E+38f (~7 существенных десятичных цифр) . Число, которое выглядит как поплавок, но является недействительным (Например, 1.0e39f) преобразуется в недостающее значение или генерирует сообщение об ошибке.  

двойной​

  • двойные значения атрибутов (64-битный) должны быть записаны с суффиксом 'd' и могут иметь десятичную точку и/или показатель, например, 0d, 1d, 12.34d, 1e12d, 1.23e+12d, 1.23e12d, 1.87E-7d. Использование NaNd для двойного NaN (пропавший) ценность. Диапазон двойников составляет приблизительно +/-1.79769313486231570E+308d (~15 существенных десятичных цифр) . Число, которое выглядит как двойное, но является недействительным. (Например, 1.0e309d) преобразуется в недостающее значение или генерирует сообщение об ошибке.  

Струна​

  • Значения атрибутов струн представляют собой последовательность символов UCS-2 (2-байтовые символы Unicode, как вJava) которые должны быть записаны как JSON-подобные строки.
    • Двойные цитаты (") внутри струнного значения должно быть закодировано как две двойные цитаты. ("") . Именно этого требуют программы электронных таблиц при чтении файлов .csv. Это то, что пишут программы электронных таблиц, когда вы сохраняете электронную таблицу в виде файла .csv.
    • Специальные символы, кодируемые обратной косой чертой JSON, должны быть закодированы как в JSON (в частности).\n(newline), \\ (backslash), \f (formfeed), \t (tab), \r (carriage return) или с помощью\u hhhh Синтаксис. В электронной таблице не используйте Alt Enter для указания новой строки в текстовой ячейке; вместо этого используйте Alt Enter.\n (2 персонажа: backslash и 'n ") Чтобы указать новую линию.
uhhhh​
  • Все остальные символы меньше символа #32 должны быть закодированы синтаксисом \u hhhh где hhhh — 4-значное шестнадцатеричное число персонажа.
  • Все печатные символы, превышающие символ #126, например, знак евро, могут казаться незакодированными, например, € (Характер евро) или закодировано с помощью\u hhhh Синтаксис, например, \u20AC. Смотрите страницы кода, на которые ссылаются https://en.wikipedia.org/wiki/Unicode найти шестнадцатеричные числа, связанные с определенными символами Unicode, или использовать библиотеку программного обеспечения. Обратите внимание, что некоторыеERDDAP™выходные типы файлов, например, .csv, используют набор символов ISO 8859-1, поэтому символы Unicode выше 255 будут потеряны, когда эти значения данных будут записаны на эти типы файлов.
  • Все непечатаемые символы, превышающие символ #126, например, символ #127, сильно искажены, но вы должны использовать hhhh Синтаксис, если вы включаете их.
  • Если струна имеет место в начале или конце или включает в себя " (двойная цитата) или запятой, или содержит значения, которые иначе интерпретировались бы как какой-либо другой тип данных (Например, Int) Вся строка должна быть заключена в двойные цитаты, иначе, в отличие от JSON, прилагаемые двойные цитаты являются необязательными. Рекомендуем: когда сомневаетесь, вложите всю Струну в двойные цитаты. Пространства в начале или конце струны сильно обескуражены.  

шар​

  • Значения атрибутов char являются одним символом UCS-2. (2-байтовые символы Unicode, как вJava) . Печатные символы (кроме специальных символов, таких как Newline, ', ' и ') Можно писать как есть. Особые персонажи (Например, Newline) и другие непечатные персонажи (Например, #127) должны быть написаны вместе с\u hhhh Синтаксис. Значения атрибутов Char должны быть заключены в единичные котировки. (Внутренние цитаты) и двойные цитаты (Внешние цитаты) , например, "a", """ (Двойной символ цитаты) "''''" (Один символ цитаты) "''t'" (вкладка) "\\u007F'" (Удалить «характер» ") и "€" (Характер евро) . Эта система использования одиночных и двойных котировок является странной и громоздкой, но это способ отличить значения шара от строк таким образом, который работает с электронными таблицами. Значение, которое выглядит как шар, но является недействительным, будет генерировать сообщение об ошибке. Обратите внимание, что некоторыеERDDAP™выходные типы файлов, например, .csv, используют набор символов ISO 8859-1, поэтому символы Unicode выше 255 будут потеряны, когда эти значения данных будут записаны на эти типы файлов.

суффикс​

Обратите внимание, что в разделе атрибутов файла NCCSV все числовые значения атрибутов должны иметь букву суффикса. (Например, "b") Для идентификации типа числовых данных (например, байт) . Но в разделе данных файла NCCSV числовые значения данных никогда не должны иметь эти буквы суффикса. (за исключением «L» для длинных целых чисел и «uL» для ulong целых чисел) - тип данных определяется\*Данные _TYPE\*атрибут для переменной.

Тип данных​

Тип данных для каждого не-скалярныйпеременная должна быть указана в\*Данные _TYPE\*атрибут, который может иметь значение байта, убита, короткого, короткого, int, uint, длинного, ulong, плавающего, двойного, струнного или char (бесчувственный случай) . Например, qc_flag,\*Данные _TYPE\*байт Предупреждение: указать правильное\*Данные _TYPE\*Это твоя ответственность. Определение неправильного типа данных (Например, int, когда вы должны были указать float.) не будет генерировать сообщение об ошибке и может привести к потере информации; (Например, значения поплавков будут округлены до ints) когда файл NCCSV читаетсяERDDAP™или преобразованы вNetCDFФайл.

Чар разочарован​

Использование значений данных char не рекомендуется, поскольку они не поддерживаются в других типах файлов. Значения char могут быть записаны в разделе данных в виде отдельных символов или строк. (Особенно, если вам нужно написать специальный персонаж.) . Если струна найдена, первый символ струны будет использоваться в качестве значения шара. Струны нулевой длины и недостающие значения будут преобразованы в символ \uFFFF. Обратите внимание, чтоNetCDFФайлы поддерживают только однобайтовые чары, поэтому любые чары, превышающие char #255, будут преобразованы в «?».NetCDFФайлы. Если атрибут charset не используется для указания другого charset для переменной char, используется charset ISO-8859-1.

Длинный и неподписанный разочарованный​

Длинные и неподписанные типы не поощряются. Хотя многие типы файлов (например,NetCDF-4 и Джейсон) иERDDAP™Долгая и неподписанная поддержка (ubyte, ushort, uint, ulong) Использование длинных и неподписанных значений в файлах NCCSV в настоящее время не рекомендуется, потому что они в настоящее время не поддерживаются Excel, CF и NCCSV.NetCDF-3 файла. Если вы хотите указать длинные или неподписанные значения в файле NCCSV (или в соответствующей электронной таблице Excel) Вы должны использовать суффикс «L», чтобы Excel не рассматривал числа как числа с плавающей запятой с более низкой точностью. В настоящее время, если файлы NCCSV преобразованы вNetCDF-3.ncфайловые, длинные и длинные значения данных будут преобразованы в двойные значения, что приведет к потере точности для очень больших значений. (менее -2^53 в течение длительного времени или более 2^53 в течение длительного времени) . вNetCDF-3.ncФайлы, ubyte, ushort и uint переменные отображаются как байт, короткая и int с атрибутом \_Unsigned=true metadata. вNetCDF-3.ncФайлы, ubyte, ushort и uint атрибуты появляются как байт, короткие и int атрибуты, содержащие соответствующее значение двух комплементов. (Например, 255ub выглядит как -1b.) . Очевидно, что это проблема, поэтому по возможности следует использовать подписанные типы данных вместо неподписанных.

CF, ACDD иERDDAP™Метаданные​

Поскольку предполагается, что большинство файлов NCCSV или.ncФайлы, созданные из них, будут прочитаныERDDAPнастоятельно рекомендуется, чтобы файлы NCCSV включали атрибуты метаданных, которые требуются или рекомендуютсяERDDAP™(см. /docs/server-admin/datasets#глобальные атрибуты). Атрибуты почти все из стандартов метаданных CF и ACDD и служат для правильного описания набора данных. (Кто, что, когда, где, почему, как) для тех, кто в противном случае ничего не знает о наборе данных. Особое значение имеет то, что почти все числовые переменные должны иметь атрибут единицы.UDUNITS-совместимая стоимость, например, sst, единицы, степень _C

Хорошо включать дополнительные атрибуты, которые не соответствуют стандартам CF или ACDD.ERDDAP.

Раздел данных​

Структура​

Первая строка раздела данных должна иметь чувствительный к регистру, разделенный запятой список переменных имен. Все переменные в этом списке должны быть описаны в разделе метаданных. (кроме других\Глобал\атрибуты и\СКАЛАР\переменные) .

Второй через предпоследние строки раздела данных должен иметь раздельный список значений. Каждая строка данных должна иметь такое же количество значений, как и отдельный список переменных имен. Пространства до или после значений не допускаются, поскольку они вызывают проблемы при импорте файла в программы электронных таблиц. Каждая колонка в этом разделе должна содержать только значения\*Данные _TYPE\*указанной переменной посредством\*Данные _TYPE\*атрибут для этой переменной. В отличие от раздела атрибутов, числовые значения в разделе данных не должны иметь букв суффикса для обозначения типа данных. В отличие от раздела атрибутов, значения char в разделе данных могут опустить прилагаемые единичные цитаты, если они не нужны для однозначности. (Таким образом, ',' и ''' должны быть процитированы, как показано здесь.) . В файле NCCSV может быть любое количество этих строк данных, но в настоящее времяERDDAP™Считывать файлы NCCSV можно только в 2 миллиардах строк. В общем, рекомендуется разделить большие наборы данных на несколько файлов данных NCCSV с менее чем 1 миллионом строк каждый.

Конечные данные​

Конец раздела данных должен обозначаться строкой, содержащей только \Окончание_DATA\

Если в файле NCCSV после\*Окончание_DATA\*строка, она будет проигнорирована при преобразовании файла NCCSV в.ncФайл. Поэтому такое содержание не рекомендуется.

В электронной таблице, следующей за этими конвенциями, имена переменных и значения данных будут в нескольких столбцах. Смотрите пример ниже.

Недостающие ценности​

Численные недостающие значения могут быть записаны как числовое значение, идентифицированноеmissing\_valueили \_FillValue атрибут для этой переменной. Например, см. второе значение в этом строке данных: Белл М. Шимада, 99,123,4 Это рекомендуемый способ обработки отсутствующих значений для байтов, убайт, коротких, коротких, int, uint, длинных и ulong переменных.

Поплавковые или двойные значения NaN могут быть записаны как NaN. Например, см. второе значение в этом строке данных: Белл М. Шимада, NaN, 123.4

Струнные и числовые недостающие значения могут обозначаться пустым полем. Например, см. второе значение в этом строке данных: Белл М. Шимада, 123,4

Для байтовых, убайтовых, коротких, укороченных, int, uint, длинных и ulong переменных утилита преобразователя NCCSV иERDDAP™преобразует пустое поле в максимально допустимое значение для данного типа данных. (Например, 127 для байтов) . Если вы это сделаете, обязательно добавьтеmissing\_valueили атрибут \_FillValue для этой переменной для идентификации этого значения, например, переменный Имя Полная стоимость,127b Для поплавковых и двойных переменных пустое поле преобразуется в NaN.

Значения DateTime​

Значения даты (Включая значения даты, которые не имеют компонента времени) могут быть представлены в виде чисел или строк в файлах NCCSV. Заданная переменная времени может иметь только значения струн или только числовые значения, а не оба. Программное обеспечение NCCSV преобразует значения String dateTime в числовую дату Ценности времени при создании.ncфайлы (В соответствии с требованиями CF) . Значения даты имеют то преимущество, что их легко читать людям.

Значения DateTime, представленные в виде числовых значений, должны иметь атрибут единицы, который определяет " единицы с тех пор дата Время "в соответствии с требованиями CF и указаннымиUDUNITSНапример, время, единицы, секунды с 197001-01T00:00:00Z

Значения DateTime, представленные как струнные значения, должны иметь струну\*Данные _TYPE\*атрибут и атрибут единицы, определяющий дату Паттерн времени, указанный вJavaКласс DateTimeFormatter ( https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html ) . Например, Время, единицы,yyyy-MM-ddTHH:mm:ssZ Все значения времени даты для данной переменной данных должны использовать один и тот же формат. В большинстве случаев шаблон времени даты, который вам нужен для атрибута единицы, будет вариацией одного из этих форматов:

  • yyyy-MM-ddT'HH:mm:ss. SSSZ — ISO 8601:2004 (Е) дата Формат времени. Вам может понадобиться сокращенная версия, например,yyyy-MM-ddTHH:mm:ssZ (Единственный рекомендуемый формат) илиyyyy-MM-dd. Если вы меняете формат значений даты, NCCSV настоятельно рекомендует вам перейти на этот формат. (Возможно, сокращенный) . Это формат, которыйERDDAP™Используется при записи файлов NCCSV.
  • yyyyMMddHHmmss.SSS — компактная версия ISO 8601:2004 Формат времени. Вам может понадобиться сокращенная версия этого, например, yyyyMMdd.
  • M/d/yyyy H:mm:ss. SSS, которая обрабатывает даты в американском стиле и даты, такие как «3/23/2017 16:22:03.000». Вам может понадобиться сокращенная версия этого, например, M/d/yyyy.
  • yyyyDDHHmmssSSS — это год плюс нулевой день года (Например, 001 = 1 января 365 = 31 декабря в не високосный год; иногда ошибочно называют юлианскую дату.) . Вам может понадобиться сокращенная версия этого, например, yyyyDDD.

точность​

Когда библиотека программного обеспечения преобразует.ncфайл в файл NCCSV, все даты Значения времени будут записаны как строки с ISO 8601:2004 (Е) дата Формат времени, например, 1970-01-01T00:00:00Z. Вы можете контролировать точность с помощьюERDDAP-специфический атрибутtime\_precision. Видишь? /docs/server-admin/datasets#time\_precision.

Часовой пояс​

Часовой пояс по умолчанию для даты Значения времени — этоZulu (или GMT) часовой пояс, в котором нет дневных периодов экономии времени. Если переменная Дата Время имеет значения Дата Время из другого часового пояса, вы должны указать это с помощьюERDDAP-специфический атрибутtime\_zone. Это требование дляERDDAP™(см. /docs/server-admin/datasets#time\_zone).

Степень ценности​

В соответствии с требованиями CF, все значения степени (Например, для долготы и широты) должны быть указаны как двойные значения десятичной степени, а не как струна градуса мин или как отдельные переменные для градусов, минут, секунд. Указатели направления N, S, E и W не допускаются. Используйте отрицательные значения для западных и южных широт.

DSG Типы признаков​

Файл NCCSV может содержать CF дискретную геометрию выборки ( https://cfconventions.org/Data/cf-conventions/cf-conventions-1.8/cf-conventions.html#discrete-sampling-geometries ) данные. Именно атрибуты делают эту работу:

  1. В соответствии с требованиями CF файл NCCSV должен содержать строку в разделе метаданных, идентифицирующую\Глобал\ featureTypeатрибут, например, \Глобал\,featureTypeтраектория
  2. Для использования вERDDAP™, файл NCCSV должен содержать строку или строки в разделе метаданных, идентифицирующие переменные cf\_role=...\_id, например, Корабль, cf\_role,trajectory\_id Это необязательно для CF, но требуется в NCCSV.
  3. Для использования вERDDAP™, файл NCCSV должен содержать строку или строки в разделе метаданных, идентифицирующие, какие переменные связаны с каждыми временными рядами, траекторией или профилем, как того требуютERDDAP™(см. /docs/server-admin/datasets#cdm\_data\_type), например, \Глобал\,cdm\_trajectory\_variables "корабль" или \Глобал\,cdm\_timeseries\_variables",station\_id,lat,lon"

Образец файла​

Вот пример файла, который демонстрирует многие особенности файла NCCSV:

\\*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/docs/user/nccsv-1.20
\\*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

Примечания:

  • Этот файл включает в себя множество сложных случаев. (Например, char и длинные переменные и сложные значения струн) . Большинство файлов NCCSV намного проще.
  • Лицензионная линия здесь разбита на две строки, но это всего лишь одна строка в файле образца.
  • u20ac является\uhhhh кодирование €. \u00FC - это\uhhhh кодирование ü. Вы также можете использовать незакодированные символы напрямую.
  • Многие Струны в примере заключены двойными цитатами, даже если они не должны быть, например, многими глобальными атрибутами, включая заголовок, атрибут lon и 3-ю строку данных.
  • Было бы яснее и лучше, если бы атрибут единиц для переменной testLong был записан в двойных кавычках, указывающих, что это значение струны. Но нынешнее представительство (1, без котировок) Он будет правильно интерпретироваться как струна, а не целое число, потому что нет суффикса «i».
  • В отличие от других типов числовых данных, длинные значения в разделе данных имеют суффикс. ("Л") идентифицирует их числовой тип данных. Это необходимо для предотвращения того, чтобы электронные таблицы интерпретировали значения как числа с плавающей запятой и, таким образом, теряли точность.

Электронные таблицы​

В электронной таблице, как в файле NCCSV:

  • Записать числовые значения атрибутов, указанные для файлов NCCSV (например, с буквой суффикса, например, 'f', для идентификации типа данных атрибута) .
  • В строках все непечатные и специальные символы должны быть написаны как похожие на JSON персонажи с обратной косой чертой. (например,\nдля Newline) или как шестнадцатеричный номер символа Unicode (бесчувственный случай) с синтаксисом\u hhhh . В частности, использовать\n (2 персонажа: backslash и 'n ") Указать новую строку в строке, а не Alt Enter. Все печатные символы могут быть написаны незакодированными или с синтаксисом.\u hhhh .

Единственные различия между файлами NCCSV и аналогичными электронными таблицами, которые следуют этим конвенциям:

  • Файлы NCCSV имеют значения на строке, разделенной запятыми. Электронные таблицы имеют значения на линии в соседних ячейках.
  • Струны в файлах NCCSV часто окружены двойными цитатами. Струны в электронных таблицах никогда не окружены двойными цитатами.
  • Внутренние двойные цитаты (") В строках в файлах NCCSV отображаются 2 двойные цитаты. Внутренние двойные котировки в электронных таблицах выглядят как 1 двойная цитата.

Если таблица, следующая этим конвенциям, сохраняется в виде файла CSV, в конце многих строк часто будут дополнительные запятые. Программное обеспечение, которое преобразует файлы NCCSV в.ncФайлы будут игнорировать дополнительные запятые.

Отлично.​

Для импорта файла NCCSV в Excel:

  1. Выберите файл: Открыть.
  2. Измените тип файла на текстовые файлы (\.prn;\.txt; \*.csv) .
  3. Найдите каталоги и нажмите на файл NCCSV .csv.
  4. Нажмите Открыть.

Чтобы создать файл NCCSV из электронной таблицы Excel:

  1. Выберите файл: Сохранить как.
  2. Изменить тип сохранения: быть CSV (Комма разграничена) (*.csv) .
  3. В ответ на предупреждение о совместимости нажмите Да.
  4. Полученный файл .csv будет иметь дополнительные запятые в конце всех строк, кроме строк CSV. Вы можете игнорировать их.

В Excel образец файла NCCSV выше выглядит как

ОбразецExcel.png

Google листы​

Чтобы импортировать файл NCCSV в Google Sheets:

  1. Выберите файл: Импорт.
  2. Выберите Загрузить файл и нажмите на Загрузить файл с вашего компьютера. Выберите файл, затем нажмите Open.

Или выберите My Drive и измените выбор типа файла на все типы файлов. Выберите файл, затем нажмите Open.

Чтобы создать файл NCCSV из таблицы Google Sheets:

  1. Выберите файл: Сохранить как.
  2. Изменить тип сохранения: быть CSV (Комма разграничена) (*.csv) .
  3. В ответ на предупреждение о совместимости нажмите Да.
  4. Полученный файл .csv будет иметь дополнительные запятые в конце всех строк, кроме строк CSV. Игнорируйте их.

Проблемы/предупреждения​

  • Если вы создаете файл NCCSV с текстовым редактором или создаете аналогичную электронную таблицу в программе электронной таблицы, текстовый редактор или программа электронной таблицы не будут проверять, что вы правильно следовали этим конвенциям. Вы должны правильно следовать этим соглашениям.
  • Преобразование электронной таблицы после этой конвенции в файл csv (Таким образом, файл NCCSV) Это приведет к дополнительным запятым в конце всех строк, кроме строк данных CSV. Игнорируйте их. Программное обеспечение преобразует файлы NCCSV в.ncФайлы будут их игнорировать.
  • Если файл NCCSV имеет избыточные запятые в конце строк, вы можете удалить их, преобразовав файл NCCSV вNetCDFфайл, а затем конвертироватьNetCDFФайл обратно в файл NCCSV.
  • При попытке конвертировать файл NCCSV вNetCDFфайл, некоторые ошибки будут обнаружены программным обеспечением и будут генерировать сообщения об ошибках, в результате чего конверсия выйдет из строя. Другие проблемы трудно или невозможно поймать и не будут генерировать сообщения об ошибках или предупреждения. Другие проблемы (Например, избыточные запятые в конце строк) будут проигнорированы. Преобразователь файлов будет делать только минимальную проверку правильности полученного результата.NetCDFФайл, например, в отношении соответствия CF. Ответственность создателя и пользователя файла заключается в проверке того, что результаты преобразования являются желаемыми и правильными. Два способа проверки:

Изменения​

Оригинальная версия былаNCCSV v1.00 (вERDDAP™v1.76, выпущен 2017-05-12)

  • Изменения, внесенные вNCCSV v1.10 (вERDDAP™v2.10, выпущен 2020-11-05) :
    • Добавлена поддержка ubyte, ushort, uint, ulong. Благодаря CF появилась поддержка этих типов данных в CF.
  • Изменения, внесенные в v1.20 (вERDDAP™v2.23, выпущен 2023-02-27) :
    • Переключен с кодирования символов ASCII на кодирование UTF-8 для файлов NCCSV .csv.
      • ERDDAP™Вы можете читать файлы всех предыдущих и текущих версий NCCSV.
      • ERDDAP™Теперь всегда пишет файлы NCCSV v1.20.
      • Если вы написали клиенту для чтения файлов NCCSV, измените его так, чтобы он рассматривал все файлы NCCSV как файлы UTF-8. Это будет работать с более старыми файлами NCCSV, поскольку ASCII является подмножеством кодирования символов UTF-8.
      • Спасибо Полин Шове, Нейту и Томасу Гардинеру.