Text data files

Text data files are provided primarily to allow you to export data values from Echoview, process them using another application, and then add the resulting data files to Echoview for display and analysis. Echoview supports these character encoding systems for text data files: UTF8, UTF-16 and ASCII.

Text data files do not have to originate from Echoview exports and may be created manually or from data exported from other applications. Regardless of the creation method, a text data file must be a comma-separated values (.csv) file that conforms to relevant file format described below.

When adding data from text data files, Echoview looks at the header line of the file for fields in the list of required and optional fields and then notes the column number associated with each name. Columns it does not recognize are generally ignored (see notes below). Echoview reads each line and pulls out required fields. Therefore you can insert any number of other columns with sensible headers, and Echoview ignores them. These can be interspersed among the expected columns. The order of the columns is not important.

When adding data, it is also particularly important to specify dates in a clear and unambiguous way e.g. 06/Jun/2008 or Jun/02/2008. Ambiguity and errors arise when the numerical day and month transpose due to changes in Microsoft Windows Regional settings for Regional and Language Options in the Control Panel.

Notes:

Prior to Echoview 4.80, text data files and CSV-format text data files only supported the ASCII format.
Some "text data CSV file formats" are supported as an exported data format and as a file format for adding to a fileset. There can be differences between the exported file and the equivalent "text data CSV file format". Such differences arise from the support for optional columns. Export file formats can include optional data columns. "Text data CSV files" (of any origin) can include optional data columns. When a file is added to a filest, optional columns are ignored unless stated otherwise by the "text data CSV file format".

The following file types are supported:

Note: Prior to Echoview 4.90 a bug was associated with using field names from .csv files. The bug fix can affect pre-Echoview 4.90 EV files that use field names. For more information refer to the bug fix documentation.

Data columns

Echoview uses the column header to identify and locate required columns in .csv files. Columns Echoview does not recognize are generally ignored. The exception is the case of single target .csv files which are used with the TS substitution operator. This operator can use values from "unrecognized" custom columns.

The files produced when exporting data from Echoview contain all required data columns. It is therefore possible to export data, modify it, and add it again to Echoview for further processing. Note however, that files containing underlying data exported from Echoview cannot meaningfully be added to Echoview as data files.

To add text data files to an existing EV file, you may need to create a new fileset.

Data values from single beam, split beam and dual beam variables

Text data files may contain data values from single beam, split beam and dual beam variables.

Data types

A prefix is added to the .csv file extension to identify what type of data is contained in a file.

Data type	File extension
Sv	.sv.csv
TS	.ts.csv
Angular position	.angles.csv
Linear	.linear.csv

File format

The first line of the *.csv file lists the names of the variables that appear in subsequent lines (these will be used as column headings if the file is loaded into a spreadsheet program). No column heading is provided for the list of data values. Each subsequent line contains the value for each variable for a single ping and the data value for each sample in the ping.

The following columns are expected.

Variable	Description
Ping_date	yyyy-mm-dd
Ping_time	hh:mm:ss
Ping_milliseconds	ms (optional column, may be left out)
Range_start	m
Range_stop	m
Sample_count	Number of samples to follow
List of data values	Sample values (separated by commas)

Notes:

See Data columns for more information.
If there is not the correct number of samples specified by Sample_count then the ping is considered invalid and all data for that ping are ignored (it will appear as a no data gap in an echogram).
The start and stop range and the number of samples may change for every line of data (ping).
In the resulting echogram, each datapoint (sample) is assigned a range so that the data is evenly spaced based over the ping, using the Sample_count, Range_start and Range_stop.

That is, the range of each datapoint (measured at the center of that datapoint) is,

Range = Range_start + (n + 0.5) * (Range_stop - Range_start) / Sample_count)

Where n = 0, 1, 2, 3, 4 … Sample_count-1

The data values must be in units appropriate to the data type identified in the name of the data file (eg. Sv must be dB re 1m-1 and TS dB re 1m2).

Data values from multibeam variables

Text data files may contain data values from multibeam variables. See Exporting data for more information.

Data types

A prefix is added to the .csv file extension to identify what type of data is contained in a file.

Data type	File extension
magnitude (beamformed)	.mag.mb.csv
phase (beamformed)	.phase.mb.csv
Sv	.sv.mb.csv
unspecified dB	.db.mb.csv
TS	.ts.mb.csv
Boolean	.boolean.mb.csv
color	.color.mb.csv

Note: files containing underlying data values exported from Echoview cannot be added to Echoview as data files.

File format

Variable	Description
Ping_date	The date (yyyy-mm-dd) on which the ping was transmitted
Ping_time	The time (hh:mm:ss) at which the ping was transmitted
Ping_milliseconds	The millisecond (0..999) at which the ping was transmitted (optional column, may be left out)
Range_start	Range (m) of the closest sample (measured along the beam-axis)
Range_stop	Range (m) of the farthest sample (measured along the beam-axis). Range_stop must be greater than Range_start.
Ping_mode	A number identifying the ping mode (optional column, may be left out, defaults to 1).
Ping_group	A number identifying the ping group (optional column, may be left out, defaults to 0).
Sector_angle	Angle (degrees) scribed between the outer edges of the two outer beams. Angle must be greater than 0.001.
Tilt_angle	The tilt angle of the ping (optional column, necessary only if ping_mode is 3 or 5).
Bearing_angle	The bearing angle of the ping (optional column, necessary only if ping_mode is 4 or 5).
Number_of_beams	Number of beams in the ping. There must be at least 2 beams. If you have only 1 beam please consider using the single beam text data file format.
Samples_per_beam	Number of samples in each beam
Data values Note: No title in the header row of the file	On the remainder of this line, the data value for each sample arranged as follows (for x+1 samples and y+1 beams): <beam0 sample0>, <beam1 sample0> ... <beamy sample0>, <beam0 sample1>, <beam1 sample1> ... <beamy sample1>, ... <beam0 samplex>, <beam1 samplex> ... <beamy samplex> Note: For "color" variables, the red, green and blue color intensities of each datapoint is encoded in a single number. The number is a decimal representation of a six digit hexadecimal number 'bbggrr'; where 'bb' represents the intensity of blue, 'gg' represents the intensity of green, and 'rr' represents the intensity of red. The intensity range is 0 (00) to 255 (FF). There must be at least one datapoint.

Notes:

See Data columns for more information.
The start and stop range, number of beams and samples per beam may all change for every line of data (ping)
In the resulting echogram, each datapoint (sample) is assigned a range so that the data is evenly spaced based over the ping, using the Samples_per_beam, Range_start and Range_stop.

That is, the range of each datapoint (measured at the center of that datapoint) is,

Range = Range_start + (n + 0.5) * (Ra nge_stop - Range_start) / Samples_per_beam)

Where n = 0, 1, 2, 3, 4 … Samples_per_beam-1 (for all the samples in any one beam)

The data values must be in units appropriate to the data type identified in the name of the data file (eg. Sv must be dB re 1m-1 and TS dB re 1m2).

Single targets (.target.csv)

Text data files may contain single beam targets. The .target prefix is added to the csv tile extension (e.g. filename.target.csv) to identify single beam targets files from other text data files.

The first line of the file is a header row that contains the names of the variables in the file. Each additional row contains the corresponding variables for a single ping. Echoview can read the following single target variables:

Variable	Description
Ping_date	The date (yyyy-mm-dd) on which the ping was transmitted.
Ping_time	The time (hh:mm:ss) at which the ping was transmitted.
Ping_milliseconds	The millisecond (0..999) at which the ping was transmitted (optional column, may be left out).
Target_depth	The depth (m) of a single target. When adding single target data to an EV file consider the issues raised in Notes.
Target_range	The range (m) of a single target.
TS_comp	The compensated target strength (dB re 1m2) of a single target . See also: Single target analysis variable TS_comp.
TS_uncomp	The uncompensated target strength (dB re 1m2) of a single target (optional column, may be left out). See also: Single target analysis variable TS_uncomp.
Angle_minor_axis	The Minor-axis angle (degrees) of a single target (optional column, may be left out). The Minor-axis angle (degrees) of a multibeam target.
Angle_major_axis	The Major-axis angle (degrees) of a single target (optional column, may be left out). The Major-axis angle (degrees) of a multibeam target.
PulseLengthDeterminationLevel	The pulse length determination level (PLDL) used for calculating single target properties (optional column, may be left out). See also: Single target analysis variable PulseLengthDeterminationLevel.
Samples_above_PLDL	The number of samples in a single target pulse with a value above the pulse length determination level (PLDL). (Optional column, may be left out.)
StandDev_angles_minor_axis	The standard deviation of the Minor-axis angles of all samples within a single target pulse determined relative to the PLDL. (Optional column, may be left out.)
StandDev_angles_major_axis	The standard deviation of the Major-axis angles of all samples within a single target pulse determined relative to the PLDL. (Optional column, may be left out.)
PulseLength_normalized_6dB	The length of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
PulseLength_normalized_12dB	The length of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
PulseLength_normalized_18dB	The length of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
PulseLength_normalized_PLDL	The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
Pulse_start_normalized_6dB	The distance between the start and peak of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
Pulse_start_normalized_12dB	The distance between the start and peak of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
Pulse_start_normalized_18dB	The distance between the start and peak of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
Pulse_start_normalized_PLDL	The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (-). (Optional column, may be left out.)
Transmitted_pulse_length	The transmitted pulse length (ms) against which pulse dimensions are normalized. (Optional column, may be left out.)
Target_length	The length (cm) of a single target. Within Echoview, Target_length can be estimated from single targets data or multibeam targets data. (Optional column, may be left out.)
Target_length_uncompensated	The length (cm) of a single target that has been calculated using uncompensated TS in the target_length_calculator_algorithm. (Optional column, may be left out.)
Target_length_manual	See Target length manual. Only relevant for multibeam targets.
Target_perimeter	See Target perimeter. Only relevant for multibeam targets.
Target_area	See Target area. Only relevant for multibeam targets.
Target_intensity_variation	See Target intensity variation. Only relevant for multibeam targets.
Target_compactness	See Target compactness. Only relevant for multibeam targets.
Target_thickness	See Target thickness. Only relevant for multibeam targets.
Target_length_across_beams	See Target length across beams . Only relevant for multibeam targets.
Target_range_extent	See Target range extent . Only relevant for multibeam targets.
Target_class	See Target class. Only relevant for multibeam targets.
Target_orientation	See Target orientation. Only relevant for multibeam targets.
Ping number	The ping number of a single target.

Notes:

Prior to Echoview 4.90 *.target.csv files contained only Target_depth values if the EV file was set to Echogram mode > Depth. When such a file is added to a new EV file in Echoview 5.0, an error is flagged in the Messages dialog box. In Echoview 5.0 Target_range is a required variable.

To correct the situation:
- When there is a transducer geometry where the range is identical to the depth, you can edit the .target.csv file. Duplicate the Target_depth column and change the field title Target_depth to Target_range. See also About depth and range.
- Alternatively, you can re-export the .target.csv file using the most up to date release.
Echoview expects that within each ping the targets appear in the .targets.csv file in order of their range or depth. Fish tracking will not perform as expected if this condition is not met.
When exporting and adding Single Targets data it is important to be aware of the effect of the following settings in Echoview:
- the Vertical offset setting on the Location page of the Transducer Properties dialog box.
- the Echogram mode setting on the Echogram page of the EV File Properties dialog box.
Transducer geometry and platform depth settings can affect the the position of single targets in an echogram. In the simple case where you have a transducer vertical offset, and the elevation and the water level are zero, Depth = Range + Vertical offset.
The Echogram mode setting controls the display of Depth or Range in the echogram and determines the output of the Single Targets data export variable for target position; either Target_Depth or Target_range. The combined outcome of the above settings means that transducer geometry and platform depth will affect the Target_depth.
Unfortunately, the Single Targets export does not record the Vertical offset or any other geometry settings that are used to calculate the Depth or Target_depth. As a result, Echoview displays the imported data as is, in the EV file's default Echogram mode, without reference to previously set geometry or set Echogram mode. In effect, the imported Single Targets data may have positions that are different from the initial single targets echogram.
Solutions to this problem are:
- Export the Single Targets data from a range-mode echogram. When imported, set the Echogram mode to Range. Set the Vertical offset to your initial value. The Range and Depth values should be the same as the initial Single Target data.
- Export the Single Targets data from a depth-mode echogram. When imported, set the Echogram mode to Depth. To avoid counting the offset twice, use a Vertical offset of zero for the Transducer location. Depth is the only mode that you can work in - depths will the same as the initial Single Targets data, however you have effectively lost the range data.

Multibeam targets (.targets.mb.csv)

Text data files may contain multibeam targets. The targets.mb. prefix is added to the csv file extension (e.g. filename.targets.mb.csv) to identify multibeam targets files from other text data files.

The first line of the file is a header row that contains the names of the variables in the file (see below). Each additional row contains the corresponding variables for a single ping.

Variable	Description
Ping_index	Sequential ping number Note: In Echoview, pings are renumbered sequentially beginning with 0
Distance_gps	Distance (nmi) from the first GPS fix in the data file
Distance_vl	Vessel log (nmi) at the time the ping was transmitted
Ping_date	The date (yyyy-mm-dd) on which the ping was transmitted
Ping_time	The time (hh:mm:ss) at which the ping was transmitted
Ping_milliseconds	The millisecond (0..999) at which the ping was transmitted (optional column, may be left out)
Latitude	The latitude (degrees) of the GPS antenna at the time the ping was transmitted
Longitude	The longitude (degrees) of the GPS antenna at the time the ping was transmitted
Heading	The heading of the platform at the time the ping was transmitted Note: Heading values are taken from the heading source selected on the Attitude_page of the Platform Properties dialog box.
Range_start	Minimum range (m) of the sector plot on which the targets will be displayed.
Range_stop	Maximum range (m) of the sector plot on which the targets will be displayed.
Sector_angle	Angle (degrees) between outer edges of the sector plot on which the targets will be displayed.
Number_of_beams	Number of beams in this ping (ignored by Echoview)
Number_of_targets	Number of targets in this ping
Ping_mode	Ping mode of the multibeam target variable.
Variable_name	Name of multibeam target variable.
Datafile_ping_number	The number, if any, asssigned to the ping in the original data file from which Echoview read the data.
Target values Note: No title in the header row of the file	Five (or four) values are provided for each target target range (m) target mean Sv (dB re 1m-1) target major-axis angle (degrees) target minor-axis angle (degrees) - optional target status: 1 = excluded from the echogram by the thresholds on the Data page of the Variable Properties dialog box 0 = included on the echogram The values expected are as follows: <target 0 range>, <target 0 mean Sv >, <target 0 major-axis angle>, <target 0 minor-axis angle>, <target 0 status>, <target 1 range>, <target 1 mean Sv >, <target 1 major-axis angle>, <target 1 minor-axis angle>, <target 1 status>, ... <target n range>, <target n mean Sv >, <target n major-axis angle>, <target n minor-axis angle>, <target n status> For Number_of_targets=n+1. Note: The minor-axis angle may be omitted. Echoview version 3.20 did not export this and created such files with multibeam target exports. Echoview will expect the minor-axis if the number of target values is equal to 5 times the number of targets, and not if the it is 4 times the number of targets.

Notes:

See Data columns for more information.
The start and stop range, and sector angle may all change for every line of data (ping), and are only used for displaying the background sector plot.

GPS fixes data

Text data files may contain GPS fixes.

A .gps prefix is added the *.csv file extension to distinguish these files from other .csv files.

The first line lists the variables in the file. Each subsequent line contains the following values for a single GPS fix:

Variable	Description
GPS_date	yyyy-mm-dd
GPS_time	hh:mm:ss
GPS_milliseconds	ms (optional column, may be left out)
Latitude	degrees
Longitude	degrees

Notes:

See Data columns for more information.

Vessel Log Data

Text data files may contain vessel log data.

A .log prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.log.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single log position:

Variable	Description
Log_data	A sequential number
Log _date	yyyy-mm-dd
Log_time	hh:mm:ss
Log_milliseconds	ms
Log_distance	distance in nautical miles

Notes

See Data columns for more information

Heading Data

Text data files may contain heading data.

A .heading prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.heading.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single heading determination:

Variable	Description
Heading_date	yyyy-mm-dd
Heading_time	hh:mm:ss
Heading_milliseconds	ms (optional column, may be left out)
Bearing	degrees. Measured clockwise from north, i.e. 0 is north and 90 is east.

Notes:

See Data columns for more information.

Roll Data

Text data files may contain roll data.

A .roll prefix is added the *.csv file extension to distinguish these files from other .csv files, e.g. filename.roll.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single roll determination:

Variable	Description
Roll_date	yyyy-mm-dd
Roll_time	hh:mm:ss
Roll_milliseconds	ms (optional column, may be left out)
Roll_angle	degrees. Measured as a clockwise rotation of the platform about the alongship axis when viewed towards the bow. 0 degrees indicates a horizontal platform.

Notes:

See Data columns for more information.

Pitch Data

Text data files may contain pitch data.

A .pitch prefix is added the *.csv file extension to distinguish these files from other .csv files, e.g. filename.pitch.csv.

The first line lists the variables in the file. Each subsequent line contains the following values for a single pitch determination:

Variable	Description
Pitch_date	yyyy-mm-dd
Pitch_time	hh:mm:ss
Pitch_milliseconds	ms (optional column, may be left out)
Pitch_angle	degrees. Measured as a clockwise rotation of the platform about the athwartship axis when viewed towards the bow. 0 degrees indicates a horizontal platform.

Notes:

See Data columns for more information.

Text data files

Data columns

Data values from single beam, split beam and dual beam variables

Data types

File format

Data values from multibeam variables

Data types

File format

Single targets (.target.csv)

Multibeam targets (.targets.mb.csv)

GPS fixes data

Vessel Log Data

Heading Data

Roll Data

Pitch Data

See also