APPENDIX A: Description of input and output files for ARTOA-II

1. Input Files

The ARTOA-II configuration file

   The `.ini' file is the main configuration file for the program.  It
connects the modules to the directory for each kind of file and its
extension  If the program is not called with an alternative name, it will
try to load the standard file called `artoa.ini' which it expects in the
same directory as the software.

   Note:  directory names are machine-dependent.  The example below is from
    a UNIX machine.  A sample directory from a PC might be:
                      C:\data\tracktest\new_exp\

[files]
soundsourcefile /home/rafos/data/soso.dat     % location ofthe sound source file
projectfile     /home/rafos/data/default.prj  %location of the project file (not used yet)

[directory] 
session     /home/rafos/           %directory to store the current session (not used yet)
argos       /home/rafos/argos/            %directory to store the Argos files
header      /home/rafos/argos/            %directory to find header information
sts         /home/rafos/argos/            %directory to find/store status records
sfc         /home/rafos/argos/            %directory to find/store surface navigation
interim     /home/rafos/interm/           %directory to store the "itm" files
rfb         /home/rafos/interm/           %directory to store the "rfb" files
trj4        /home/rafos/final/     % directory to store the "trj4" files ("simple rfc format")
rfc         /home/rafos/final/            % directory to store the "rfc" files

[filemask]
session               *.sel               % filemask for the session files (not used yet)
argos                 *.arg               % filemask for the Argos files
header                *.hdr               % filemask for the header files
sts                   *.sts               % filemask for the status files
sfc                   *.sfc               % filemask for the surface-navigation files
rfb                   *.rfb               % filemask for the "rfb" files
itm                   *.itm               % filemask for the "itm" files
rfc                   *.rfc               % filemask for the "rfc" files
trj4                  *.trj4              % filemask for the "trj4" files

[load]
savesession                  0            % not used yet
cycledelimiter               -            % filename delimiter for multi-cycle floats

The sound-source file

   The sound-source file contains the parameters in key/value pairs.  The
source file consists of the following information for each source:

[SQ1]                                     % reference

-sourcename      SQ1                      % name (same as reference)

-sourcetype      WEBB                     % type

-sourceowner     IfM Kiel                 % owner

-position     38.383  -19.021             % mooring position of thesound source
                              (Latitude positive north; longitude positive east)
-depth          1000                      % depth of the sound source (meters)

-begemis     1995 10 21 00 00             % deployment or "begin emission"(year,
                                            month,day,hour,min)
-endemis     1998 10 01 00 00             % retrieval or "end emission" (year,
                                            month,day,hour,min)
-offset      1995 10 21 0                 % offset (year,month,day,offset in
                                            seconds), usually an initial offset.
-drift         0.034                      % drift in seconds per pong-interval
                                            or "schedule"
-reftime       01 30                      % pong time (hour min)

-schedule       24                        % hours between pongs

-signallength   80                        % time (secs) for correlation of source

-add_offset            NaN                % additional constant offset in seconds

-sound_speed  1480                        % sound velocity in meters per second

   The source clock offset and source clock drift, if positive, will be
subtracted from the TOA value; if negative, they will be added to the TOA
value. This reflects the fact that a positive source clock offset means
that the source clock shows a time in advance of GMT, therefore the TOA
will be too long, and should be reduced by the time difference between the
source clock and GMT.  Similarly, a positive source clock drift, under this
convention, indicates that the source clock is becoming faster.

ARGOS input file: .arg

   Previously, Service Argos used only 20-bit ID's and you received 32 data
bytes per message.  If you wanted to check on data-transmission, you needed
to include a checksum.  In the new Argos messages, there is a CRC, and
28-bit ID's are permitted.  In this format, if you are using a 20-bit ID,
Service Argos will transmit 32 bytes of data.  If you are using a 28-bit
ID, you will have only 31 bytes in the data field.  In the new Argos
messages the CRC is calculated on the 4 bytes of hex address (0hhhhhhh) and
29 bytes of data.

   Note in each case below that the first record is the Argos location
record, containing program ID, PTT ID (decimal), record-count for this
pass, number of variables, satellite ID (alpha), and - if available -
quality code, date/time of location, latitude, longitude, altitude, and
frequency (estimated transmission frequency).  In samples a) and c), the
observation times are reported to the thousandth of a second.  This
happens when "accurate time-coding" is requested from Service Argos.
ARTOA-II can cope with either option.

a) Sample data from a 20-bit-ID float, no CRC (note location of 07FF in
status message - record 2):

02294 24247   5  8 J 3 2002-08-31 13:42:10  12.888   54.606  0.000 401647240
  2002-08-31 13:38:25.570  1   8843A83A     506F20AD     5D228334     C8F6118C
                               D20B4419     2832143F     A09C2165     87040200
  2002-08-31 13:41:32.573  1   6607FF02     6001F400     1C8A2D19     58656500
                               402C02DA      2600335     1A00095E     A8596665

b) Sample data from a 28-bit-ID float with 20-bit identifier and CRC (note
location of FF  E0 in status message - record 1):

02683 25316   5  8 D 2 2004-04-11 18:32:09  41.799  310.404  0.000 401650277
      2004-04-11 18:29:36  1     209DFF     E00C0300     D7200C0E     60496D6E
                                 2C0015      C230455     1E000F14     1E495F60
      2004-04-11 18:35:25  1     28BB8A     6D71529A     8CD34440     6A704506
                               38C61473     867E3481     83063237     7A2AD691

c) Sample data from a 28-bit-ID float with 28-bit identifier and CRC (note
location of FFE0 in status message - record 1):

02683 37545   5  8 K
  2004-08-03 22:30:49.422  1   E3F8FFE0      C9500D7     FFFD5821     63686800
                               2C00010C     9501E91B     FFFD56CA       636868
  2004-08-03 22:31:36.408  1   38F0001B     1D7082E1      6D8E9B1     D70836C7
                               5C20DB1D     70837FEC     10800000           00

Main float file: rfbnnn.rfb

Header file: .hdr

   The float parameters are given in key/value pairs.  Service Argos uses
"ptt" to stand for "platform transmitter terminal", or transmitter.
ARTOA-II expects the "-floatname" to be five characters with the float
number (nnn) in the last three; trouble creating an output file may be
traced to this.

Note:  as described for the source file, a clock offset or drift that is
"fast" will be expressed by a negative number.

rfb164.rfb                                % file name

-floatname            RF164               % float name

-type              20-bit DLD             % float type (for DLD, must include
                                            20 or 28)
-projectname       EUROFLOAT              % project name - see below for special use.

-pttdec             12620                 % ptt decimal identifier

-ptthex             3f4b2                 % ptt hexadecimal identifier

-pttrep              69                   % ptt repetition rate in seconds

-launchpos     32.164  -22.022            % launch position (lat,lon)

-launchtime    1995 10 13 12 00           % launch date/time (year,month,day,
                                            hour,min)
-recoverpos    30.259  -24.958            % surfacing position (lat,lon)

-recovertime   1996 01 28 02 30           % surfacing date/time (year,month,day,
                                            hour,min)
-offset        1995 10 13 12 00 -60.9     % offset at the beginning of the mission
                                        (year,month,day,hour,min,offset in seconds)
-offset        1996 01 28 02 30 -82.6     % offset at the end of the mission
                                        (year,month,day,hour,min,offset in seconds)
%Second offset should be 0.00 for raw data - ARTOA-II will insert derived offset.

-cycle   1 32.165 -22.022 1995 10 12 00 00 30.259 -24.958 1996 01 28 00 00

% cycle information = beginning and end of the cycle (first and last listening phase)
% (cycle number lat lon year month day hour min lat lon year month day hour min)
% For example, the float above started its first listening phase the 12th of October 
% 1995 at midnight (00:00) and had its last listening phase the 28th January 1996
% at midnight.
% The positions at the beginning and the end are, for RAFOS floats, normally the same
% as the launch and surface positions.  Note: this does not exactly match the float 
% turn-on time.  For Marvor floats they are the last/first reported Argos positions at 
% the end/beginning of each cycle.

-progdepth                 1000            % programmed depth

-progtemp                    12            % programmed temperature

-progsal                      0            % programmed salinity (not used yet)

-phasespercycle             300            % number of phases per cycle (for RAFOS 
                                             cycle and mission are the same thing)
-schedule                    24            % listening schedule in hours
                                             (time between phases)
-field                    CCCPCCCP         % defines schedule of float for
                                             decoding (see below)
-signal_length               80            % seconds required for signal correlation

-phasereftime                00 00         % reference time (normally 00 00)

-windowsperphase         3                 % windows per listening phase 
                                             (RAFOS record)
-toaperwindow            2                 % times of arrival per window

-toaperphase                6              % times of arrival stored for each
                                             phase (product of previous two)
-correlationrange         0 3              % range of the correlation
                                             heights (0 to 170 for DLD2)
-windowrange              0 2              % range of the window
                                             numbering (i.e., 3 windows)
-windowstart          30 60 90             % minutes from the reference time
                                             to start of each window
-windowlength         25 25 25             % length of each window (minutes)

-tempequation  1./(tc(1) + tc(2)*log(temp)) - 273.2   % formula for
                                             converting counts to degrees
                                             (use "temp" if none)
-tempcoeff      0.001409  0.00027024001    % the coefficients for the above
                                             formula (use "1" if none)
-presequation     pc(2)./pres - pc(1)      % formula for converting counts to
                                             pressure data (use "pres" if none)
-prescoeff        291.89001  1374300       % the coefficients for the pressure
                                             (use "1" if none)
-comment            Poseidon               % comments (usually ship name)
                                             Comment lines are unlimited - start 
                                             each "-comment"
-edited_by            C Wooding            % person who created header

-edited_on            2000 11 14           % date created

-variables            17                   % total number of columns

[VARIABLE_LIST]

-line_number            1                  % column number
                                             for the record-count
-time_of_arrival     3 5 7 9 11 13         % for times of arrival

-correlation_height  2 4 6 8 10 12         % for correlation heights

-pressure               17                 % for pressure
                                             (engineering units)
-temperature            16                 % for temperature
                                             (engineering units)
-pres_counts            14                 % for pressure (raw counts)
                                             - not transmitted for DLD
-temp_counts            15                 % for temperature (raw counts)
                                             - not transmitted for DLD
[DATA]
  1 20 0 20 0   40 10931  20    18  40 4185 20 10691 4086 4086 2.950 818.80
  2 20 0 20 0   60  5713  40  2825 120 3806 20  9861 4086 4086 5.100 895.10
  3 20 0 20 0  120  3397 100  5642  80 3822 40 12177 4086 4086 5.080 907.30
  4 20 0 20 0   80  5621  20 11026 120 3871 40    18 4086 4086 5.134 909.00
...
897 20 0 20 0   60  9501  40  7057  60 5587 60 12346 4086 4086 5.270 913.90
898 20 0 20 0   60  9507  40  1949 100 5599 40  8090 4086 4086 5.270 911.30
899 20 0 20 0  100  7090  60   950  80 5590 80 12349 4086 4086 5.270 914.60
900 20 0 20 0   40  9520  40  1562  80 5590 40    18 4086 4086 5.253 912.40

   The data columns are: cycle or line number, window 1 (correlation 1, TOA
1 in deciseconds, correlation 2, TOA 2 in deciseconds), window 2 (as window
1), window 3 (as window 1), pressure counts (null value), temperature
counts (null value), pressure, temperature.

   In order for ARTOA-II to work properly, each line of the rfb file must
contain only a single set of windows.  A float might be set up to store six
windows in a day, three just after midnight, say, and three just after
noon.  ARTOA-II would plot this as six windows and there would be no way to
integrate the noon pongs with the midnight pongs.  If this situation
occurs, the user must reformat the data so that each line contains only the
data from half a day.

   Note: The rfb data file must start with line number 1 as the first line,
and increase monotonically.

ARTOA-II has been known to corrupt an rfb file - it is a good idea to have
backup copies in another directory.

Header notes

   "-field" describes the programming of the float.  "D" indicates pressure
and temperature recorded as two fields of 12 bits, with the pressure
expressed in centibars and temperature in millidegrees C. "C" represents a
field of 15 bits corresponding to the "-toaperwindow" highest correlation
values collected during a listening window. The first 3 bits represent the
amplitude on a scale of 0 to 7, and the next 12 bits the delay expressed in
sample period.  The sample period is .3075 sec for the 260-Hz receivers and
.1846 sec for the 780-Hz receivers.  ARTOA-II currently uses .3075 as the
default (see `newparse.m') but uses .1846 if the program name includes the
letters "red".

   Temperature and pressure coefficients and algorithms used to be required
to calculate tempera-ture and pressure from the raw counts.  The pressure
and temperature calculations are now done in the conversion software,
before ARTOA-II is run, or, in the case of DLD floats, in the float
itself.  Therefore, the coefficients can still be included, but are not
currently used.  If the float didn't record temperature or pressure, use a
column-number larger than the limit of the "-variables" value.

2. Output Files

Status messages rfnnn.sts

   DLD floats produce a status message every ten messages, which contains
information on the state of the instrument.  It contains two separate
fields.  The first one contains data acquired at the time the burn wire was
first activated; the second, data for the current time - the time of the
Argos transmission.  The first field contains message number (FFE0 or 07FF
depending on type); day at release time; minutes ( 1 day = 1440 min ),
(seconds at release time), pressure in cBars, temperature in millidegrees,
vacuum reading ( 0 to 100 ), controller battery voltage ( dV ), PTT battery
voltage ( dV ), SYSTAT variable, STATUS variable, and total number of
cycles acquired.

   The second field contains the current day, minutes, and seconds;
pressure in cBars, temperature in millidegrees, vacuum reading, controller
battery voltage, and PTT battery voltage.

   The SYSTAT variable contains a set of flags that report fault
conditions.  If more than one fault occurred, the following would be
summed.  The values in decimal are:

        1  Clock module failed to address at least once
        2  Receiver module failed to address at least once
        4  PTMOD module failed to address at least once
        8  Argos-transmitter module failed to address at least once
       32  Low-battery fault condition
       64  Surface fault condition
      128  Too-deep fault condition

Example:

STATUS MESSAGES

Release day,min,sec,P,T,Vac,CBat,PBat,SyStat,Stat,NoCyc

Current day,min,sec,P,T,Vac,CBat,PBat

 789: 1220: 0 856.8 14.970   88  102  101    0   64   44  730
 790:  171:14   1.7 27.130   89  102  102
 789: 1220: 0 856.8 14.970   88  102  101    0   64   44  730
 790:  534:22   1.6 27.257   89  102  102

Surface navigation information rfnnn.sfc

Main float output file: rfcnnn.rfc

   This is the commonly-used output format for the tracked data.  Most
header variables are explained by their labels.  The sound source
combinations are delimited by truncated Julian dates.  (Julian days, called
`Message Date' during the earlier phases of processing, are now called
`Rafos days')  .The reference position is usually the launch position.  The
sound velocities are taken from the sound source file, although a different
method of determination may actually have been used. The line with a single
asterisk, followed by an "l" is an additional comment line (it is vestigial
- the launch date used to be required here).  The velocities and header are
calculated by `svdata.m'.

** Float:   RF022
** variables :InterpFlag LineNum RafosDay  Temp  Pres  Lat  Lon U    V     W
** Units     :   #          #       #  degC   dbar  deg  deg  cm/s  cm/s  mm/s
** Dummies:     NA         NA      NA  -9.99 -999   999  999  999   999   999
** Cycle: 1
** Launch position (Cycle Start position):   9.179     -52.439
** Surface position (Cycle End position) : 12.633     -52.287
** Cycle Start time  : 1999    2    19     0    0     0 (RAFOS day 11229)
** Launch time       : 1999    2    19    12   53     0  (RD 11229)
** Cycle End time    : 2000    5    14    14    0     0 (RD 11678.5833)
** First surface Position time  : 2000    5    13    14   31    0 (RD 11678)
** -------
** Tracking method: Least Square
** Interpolation method: Spline
** Interpolation step size: 12 hours
** Interpolation gap size: 10
** Doppler correction: yes
** -------
** Sound source combinations: (rafos day, sound sources, reference
position, sound speed)
**    11229.5 to 11542: 69 77 B1    9.179     -52.439  1.484  1.484  1.484
**    11542.5 to 11573.5: 69 77 185  9.179     -52.439  1.484  1.484  1.484
**    11574 to 11678.5: 69 404    9.179     -52.439  1.484  1.484  1.484
** -------
** Additional Float clock offsets, seconds (beginning, end): 0   0
** -------
 *   l  ----------
 0   1 11229.50  7.622 -999.0     9.184  -52.444    -10.35   19.63  999.00
 0   2 11230.00  7.640  551.5     9.260  -52.473     -1.37   19.52  999.00
 0   3 11230.50  7.519  542.0     9.326  -52.462      2.54   11.88    0.14
 0   4 11231.00  7.510  542.6     9.348  -52.467     -4.17    0.61   -0.19
-1   5 11231.50  7.655  552.4     9.342  -52.482     -1.63   -2.13   -0.09
 0   6 11232.00  7.580  550.4     9.338  -52.478      2.23    0.12    0.00

   The data columns are: quality flag, cycle or line number, "Rafos day"
(truncated Julian day with decimal part), temperature, pressure, latitude,
longitude, velocities (east, north, vertical).  See units listed in the
third header line, and "Dummies" or null values in the fourth line.

   The quality flag, located in the first column, gives information about
interpolation.  If the flag is zero (0), then no points in the TOA records
used to calculate this track location were interpolated.  If the flag is a
positive number, it corresponds to the number of interpolated sources used
in com-puting this point.

   The east and north velocities are calculated from the latitudes and
longitudes, so they are influenced by the interpolation applied to the
TOAs.  The method is set by default to "spline" in the routine `horvelo.m';
but it could be changed by altering `uitc.m'.  Method "spline" uses the
func-tion `csape.m' from the Matlab Spline Toolbox (see Matlab
documentation for more information).  The location data is interpolated to
two-hour intervals, and then resampled to the requested data rate.  The
vertical velocity is determined using a splined pressure record and the
analytical derivative of the spline, as described for the north and east
velocities.  The first and last vertical velocities should be nulls.  There
will be no vertical velocity if a pressure value is missing, or if a
portion of the trajectory can't be computed (bad geometry, e.g.), even if
pressure and temperature are available.  No interpolation is applied to
temperature and pressure.

Simplified RFC file: nnn .trj4