Exchange CTD files follow all the common format specifications with the addition of some header information. They MUST only contain one profile per file.
Additional CTD Headers¶
Rather than encode information which would remain constant throughout the cast with the Data Lines, Exchange CTD files store this information in headers that appear after the Optional Comment Lines, but before the Parameter and Unit Lines. These headers follow the basic form:
PARAM = VALUE
PARAM is some parameter name (e.g.
DEPTH) and the
VALUE is the value for that parameter (e.g.
PARAM, with the exception of NUMBER_HEADERS, MAY be any parameter in the Parameters section.
The format of
VALUE must conform to the data type listed for the parameter in the Parameters section.
VALUE are separated by a EQUALS SIGN (U+003D)
=, there is no meaning to any whitespace.
Each param-value pair ends end with a line-ending character.
There is no limit to how many headers may be present, as long the NUMBER_HEADERS value is set correctly.
Any parameter which has a constant value for the entire cast MAY appear in the CTD Headers.
Here is an example of a complete set of CTD headers (note that we have included line numbers, these are not part of the header):
1 2 3 4 5 6 7 8 9 10
NUMBER_HEADERS = 10 EXPOCODE = 318M20130321 SECT_ID = P02W STNNBR = 1 CASTNO = 2 DATE = 20130322 TIME = 2205 LATITUDE = 32.5068 LONGITUDE = 133.0297 DEPTH = 166
Notice three things: the special
NUMBER_HEADERS parameter, the parameter names are all caps, and none of the parameters have units.
The units for each parameter are defined by convention rather than explicitly stated in each file, see the CTD required headers for information on which headers are required.
CTD required headers¶
TIME is not a required parameter, this is not an omission from the list above.
There is no support for including units in the CTD headers it is not recommended that any parameters which could have multiple units be included in the CTD headers.
Usually the optional DEPTH parameter is the only one with units commonly found in CTD headers, it MUST be in meters when included in the CTD headers.
NUMBER_HEADERS parameter is an integer describing how many lines the headers will be before the parameter and unit lines.
The value of
NUMBER_HEADERS includes itself it is REQUIRED and MUST be the first line after any Optional Comment Lines.
The most common mistake with Exchange CTD Headers is not including the
NUMBER_HEADERS line in the calculation of the number of lines the headers occupy.
It would be incorrect in the above example to have
NUMBER_HEADERS = 9.
CTD Optional Headers¶
The following CTD headers are optional, but encountered frequently within ctd exchange files:
Preferred Header Order¶
The only header which must come first is
Other header parameters may come in any order, however, there is a preferred order.
The preferred order after
EXPOCODE SECT_ID STNNBR CASTNO DATE TIME LATITUDE LONGITUDE DEPTH
Any additional CTD headers may be included as long as they follow the
PARAM = VALUE form specified above and the
NUMBER_HEADERS value is set correctly.
This may include headers which may only be of use to the data originator, or any other parameter.
Authors of software which both read and write exchange CTD files SHOULD pass through any undocumented headers without modification.
Example CTD Data¶
Here is an example of a complete exchange CTD file (though a very shallow profile):
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
CTD,20130709ODF # REPORTED CAST DEPTH IS CTD_DEPTH + DISTANCE_ABOVE_BOTTOM AT MAX PRESSURE NUMBER_HEADERS = 10 EXPOCODE = 318M20130321 SECT_ID = P02W STNNBR = 1 CASTNO = 2 DATE = 20130322 TIME = 2205 LATITUDE = 32.5068 LONGITUDE = 133.0297 DEPTH = 166 CTDPRS,CTDPRS_FLAG_W,CTDTMP,CTDTMP_FLAG_W,CTDSAL,CTDSAL_FLAG_W,CTDOXY,CTDOXY_FLAG_W DBAR,,ITS-90,,PSS-78,,UMOL/KG, 2.0,2, 19.1840,2, 34.6935,2, 220.8,2 4.0,2, 19.1992,2, 34.6924,2, 220.7,2 6.0,2, 19.2002,2, 34.6922,2, 220.5,2 8.0,2, 19.2022,2, 34.6919,2, 220.5,2 10.0,2, 19.2033,2, 34.6918,2, 220.6,2 12.0,2, 19.2039,2, 34.6919,2, 220.8,2 14.0,2, 19.2033,2, 34.6919,2, 220.9,2 16.0,2, 19.2029,2, 34.6916,2, 220.6,2 END_DATA
The structure is:
Structure of ZIP CTD Archives¶
Since exchange CTD files only contain one profile, it is convent to package them into entire an archive containing an entire cruise. The archive format exchange uses is zip, specifically PKZIP 2.0. The zip archive allows for a large variety of structure so it is necessary to define the structure here.
Exchange CTD zip files MUST contain a flattened structure, that is, only files with no directory paths.
The files within the zip SHOULD be in the same order in which the stations were done.
Usually this means the filenames contain numerical information regarding the station order.
All the files within the zip MUST have the
_ct1.csv file extension.
Here is an example a correct ctd exchange zip archive (the output of
Archive: 33RO20131223_ct1.zip Length Date Time Name -------- ---- ---- ---- 401802 04-10-14 17:27 33RO20131223_00001_00002_ct1.csv 388950 04-10-14 17:27 33RO20131223_00002_00001_ct1.csv 385278 04-10-14 17:27 33RO20131223_00003_00002_ct1.csv 400573 04-10-14 17:27 33RO20131223_00004_00001_ct1.csv 395069 04-10-14 17:27 33RO20131223_00005_00002_ct1.csv -------- ------- 1971672 5 files
Notice the lack of directory paths in the archive names, it is simply filenames.
The following is an example of an incorrectly packaged archive, which has archive names containing directory structure (notice the
/ in the names):
Archive: 33RO20131223_ct1.zip Length Date Time Name -------- ---- ---- ---- 401802 04-10-14 17:27 33RO20131223_ct1/33RO20131223_00001_00002_ct1.csv 388950 04-10-14 17:27 33RO20131223_ct1/33RO20131223_00002_00001_ct1.csv 385278 04-10-14 17:27 33RO20131223_ct1/33RO20131223_00003_00002_ct1.csv 400573 04-10-14 17:27 33RO20131223_ct1/33RO20131223_00004_00001_ct1.csv 395069 04-10-14 17:27 33RO20131223_ct1/33RO20131223_00005_00002_ct1.csv -------- ------- 1971672 5 files
Currently, the behavior when other files or directories are present is undefined. The recommended behavior when encountering directories or other (non _ct1.csv) files is to ignore the extra files while warning the user of their presence.