Text data files

Text data files are provided primarily to allow you to export data values from Echoview, process them using another application. Some exported .csv files may be added to the Filesets window. You may need to create a new fileset. Echoview supports the UTF-8 character encoding system for text data files.

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 fileset, 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.

Date and time format

When importing text data files, we recommend you use the yyyy-MM-dd format for date and HH:mm:ss for time.

However, Echoview can interpret a range of other common date and time formats.

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

Boolean

.boolean.csv

File format

Refer to Single beam, split beam, dual beam and current velocity data value exports.

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.

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 data point (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 data point (measured at the center of that data point) 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 (e.g. 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

Refer to Multibeam data value exports.

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.

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 data point (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 data point (measured at the center of that data point) is,

Range = Range_start + (n + 0.5) * (Range_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 (e.g., 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

yyyy-MM-dd

Ping_time

HH:mm:ss

Ping_milliseconds (optional)

Millisecond (ms) component of Ping_time

Target_on_axis_depth

The on axis 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 (optional)

The uncompensated target strength (dB re 1m2) of a single target.

See also: Single target analysis variable TS_uncomp.

Angle_minor_axis (optional)

The Minor-axis angle (degrees) of a single target. See also the Minor-axis angle (degrees) of a target derived from multibeam data.

Angle_major_axis (optional)

The Major-axis angle (degrees) of a single target. See also the Major-axis angle (degrees) of a target derived from multibeam data.

PulseLengthDeterminationLevel (optional)

The pulse length determination level (PLDL) used for calculating single target properties.

See also: Single target analysis variable PulseLengthDeterminationLevel.

Samples_above_PLDL (optional)

The number of samples in a single target pulse with a value above the pulse length determination level (PLDL).

StandDev_angles_minor_axis (optional)

The standard deviation of the Minor-axis angles of all samples within a single target pulse determined relative to the PLDL.

StandDev_angles_major_axis (optional)

The standard deviation of the Major-axis angles of all samples within a single target pulse determined relative to the PLDL.

PulseLength_normalized_6dB (optional)

The length of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (no units).

PulseLength_normalized_12dB (optional)

The length of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (no units).

PulseLength_normalized_18dB (optional)

The length of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (no units).

PulseLength_normalized_PLDL (optional)

The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (no units).

Pulse_start_normalized_6dB (optional)

The distance between the start and peak of a single target pulse (at 6dB down from the peak) normalized to the transmitted pulse length (no units).

Pulse_start_normalized_12dB (optional)

The distance between the start and peak of a single target pulse (at 12dB down from the peak) normalized to the transmitted pulse length (no units).

Pulse_start_normalized_18dB (optional)

The distance between the start and peak of a single target pulse (at 18dB down from the peak) normalized to the transmitted pulse length (no units).

Pulse_start_normalized_PLDL (optional)

The length of a single target pulse (at the PLDL) normalized to the transmitted pulse length (no units).

Pulse_duration (optional)

The pulse duration (ms) is used in the calculation of transmitted pulse length. Pulse length is used to normalize PulseLengthDeterminationLevel, and PLDL and Pulse related variables.

Target_length (optional)

The length (cm) of a single target. Within Echoview, Target_length can be estimated from single targets data or multibeam targets data.

Target_length_uncompensated (optional)

The length (cm) of a single target that has been calculated using uncompensated TS in the target_length_calculator_algorithm.

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_on_axis_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_on_axis_depth column and change the field title Target_on_axis_depth to Target_range. See also About depth, range and altitude.
    • 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:
  • Transducer geometry and platform depth settings can affect 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_on_axis_depth or Target_range. The combined outcome of the above settings means that transducer geometry and platform depth will affect the Target_on_axis_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_on_axis_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

yyyy-MM-dd

Ping_time

HH:mm:ss

Ping_milliseconds (optional)

Millisecond (ms) component of Ping_time

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, assigned 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 for this variable

A string of comma-separated

  • range (m),

  • mean Sv (dB re 1m-1),

  • major-axis angle (degrees),

  • minor-axis angle (degrees)1, and

  • status:

    • 1 = excluded from the echogram by the thresholds on the Data page of the Variable Properties dialog box
    • 0 = included on the echogram

values comprising each target according to the format (the line breaks for clarity only):

<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>

where n = Number_of_targets - 1.

1The minor-axis angle is optional to maintain backward compatibility with Echoview 3.20.

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 to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.gps.csv.

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 (optional)

Millisecond (ms) component of GPS_time

Latitude

degrees

Longitude

degrees

Notes:

Vessel log data

Text data files may contain vessel log data.

A .logs prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.logs.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

Millisecond (ms) component of Log_time

Log_distance

Distance (nmi)

Notes

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 (optional)

Millisecond (ms) component of Heading_time

Bearing

Degrees measured clockwise from north, i.e. 0 is north and 90 is east.

Notes:

Roll data

Text data files may contain roll data.

A .roll prefix is added to 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 (optional)

Millisecond (ms) component of Roll_time

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:

Pitch data

Text data files may contain pitch data.

A .pitch prefix is added to 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 (optional)

Millisecond (ms) component for Pitch_time

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:

Line data

Text data files may contain line data.

See Exporting line data for more information on available line export file formats.

Length data

Text data files may contain length data that are derived as a length variable.

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

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

Variable

Description

Length_date

yyyy-MM-dd

Length_time

HH:mm:ss

Length_milliseconds (optional)

Millisecond (ms) component of Length_time

Length_meters

Length (m)

Notes:

Speed data

Text data files may contain water current speed data that are derived as a speed variable.

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

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

Variable

Description

Speed_date

yyyy-MM-dd

Speed_time

HH:mm:ss

Speed_milliseconds (optional)

Millisecond (ms) component of Speed_time

Speed_meters_per_second

Speed (ms-1)

Notes:

Depth data

Text data files contain line segment depth data from which Echoview can derive a raw line variable.

The .depth prefix is added to the *.csv file extension to distinguish these files from other .csv files, e.g. filename.speed.csv.

Variable

Description

Depth_date

yyyy-MM-dd

Depth_time

HH:mm:ss

Depth_milliseconds (optional)

Millisecond (ms) component of Depth_time

Depth_meters

Depth for the line segment in meters.

Depth_status

Line status for the line segment.

0 = none

1 = unverified

2 = bad

3 = good

Notes:

Transect data

Echoview reads *.transect.csv files containing transects. For example

Transect_ID,Transect_Name,Start_time,Stop_time,Notes

1,Transect A, 2023-09-24 15:34:46.7361, 2023-09-24 15:35:55.4332,

2,Transect B, 2023-09-24 15:39:24.5337, 2023-09-24 15:40:02.3309,

  

The first line in the file is the header. Subsequent comma-separated lines define individual transects. Refer to the table below for details on each field.

If the Notes field for the final transect is empty, Echoview requires an empty line    at the end of your .transect.csv file.

Field

Description

Transect_ID

A unique integer representing the index or transect number.

Transect_Name

A label for the transect.

Start_time

yyyy-MM-dd HH:mm:ss.ssss (refer to Start_time and Stop_time format below)

Stop_time

yyyy-MM-dd HH:mm:ss.ssss (refer to Start_time and Stop_time format below)

Notes

A description for the transect. (optional)

\r\n inserts a new line in the note.

Start_time and Stop_time format

The software you use to generate the Start_time and Stop_time may encode the timestamp, making it unverifiable by Echoview.

To circumvent this insert a single whitespace prefix e.g., ' 2023-02-01 03:09:01.0013' (without quotes).

Echoview rounds the time to the nearest 0.1 millisecond. Refer to the Transect section in the details dialog box.

See also

Raw variables derived from text data files
Calibration settings for text data
Export file formats
Exporting data
Exporting GPS fixes

Echoview Help file 14.0.129 for Echoview 14, 30 October 2023

Copyright © Echoview Software Pty Ltd 2023. All rights reserved. Echoview is a registered trademark of Echoview Software Pty Ltd. Other brands and trademarks are the property of their respective owners.

Please report any errors or omissions to support@echoview.com.