Echoview calibration supplement files

The Echoview calibration supplement file (ECS file) enables you to change calibration values used in calculations for your data. The ECS file is a text file that is added to a fileset using the Calibration section of the Filesets window. The file can be edited in a plain text editor (like Notepad) and may contain settings that modify Calibration sources. Only acoustic variables that belong to the fileset associated with the ECS file will have access to the calibration settings the ECS file defines.

The Calibration section of the Calibration page of the Variable Properties dialog box is where you can:

  1. read the variable's Calibration source name
  2. view the calibration values applied to an acoustic variable

Appropriate calibration values, from an ECS file can be applied automatically or specifically, and allow your data to be analyzed quantitatively.

Echoview offers a process in which a templated ECS file is created and tailored to your data; this file can contain (source) Calibration values that are used, and file administration comments.

Notes:

Order of override ability for calibration settings

Override order for calibration settings

Figure 1. Order of precedence for Echoview calibration values.

Settings to the right override those to the left. For example Data file settings override Default settings. Fileset, SourceCal and LocalCal settings are specified in an ECS file. LocalCal ECS values require a deliberate direction for use via the LocalCal list setting on the Calibration page of the Variable Properties dialog box. See also Calibration data workflow.                 

Grammar

Valid characters in the file

[a...z], [A...Z], [0...9]

Decimal point

Punctuation, Braces, other characters

Calibration setting names are limited to alphanumeric characters.

All alphabet text is case insensitive. To improve readability, use words delineated by capitalized initials (CamelCase).

 

#

Use # before text to indicate a comment.

The file can contain other information as comments (in any language). A comment starts with the comment character #, and continues to the end of the line. A comment can occur on a line by itself or follow text used by Echoview. Comments are ignored by Echoview.

For example:

# This is a comment
SoundSpeed = 1496.333 # Too much precision

Keywords

Version, SourceCal, LocalCal

Note: LocalCal names support international characters.

Calibration source name Calibration source name
Calibration setting name Calibration settings
an equals sign [ = ] Used between a calibration setting name and the setting's value.
a space

Spaces are ignored unless they break up a name or number.

Spaces are also used to separate values in an array.

a value

A calibration setting's value. Often, this is a numerical value but some calibration settings are specified by a string of text.

Calibration source

Keywords: SourceCal, LocalCal

An ECS template lists suggested calibration settings for the SourceCal Calibration source name. Every acoustic variable has an assigned Calibration source.

Data file derived Calibration sources

Every raw variable has a source from which it derives its calibration. Calibration sources are derived from data files in the fileset. The name of this source is the familiar description, derived from the transducer and channel names, added to the end of the raw variable name. For example:

The raw variable Sv Ping T1 uses the Calibration source T1.

The ME70 raw variable Sv pings formed beams uses the Calibration source "formed beams".

Even if no calibration data is available in the file, a Calibration source still exists, but it is empty. Where a calibration setting is required for a calculation and a data file setting is absent then a default setting is used.

A fileset can have more than one (data-derived) Calibration source. Multiple Calibration sources may arise because the data is multiplexed into channels or records more than one frequency.

To modify calibration

Any saved changes to the parameters in an ECS file recalculates variables and updates any displayed echograms. You can modify calibration with an ECS file in the following ways:

Echoview Calibration Supplement feature Action

Fileset
List of calibration settings at the beginning of the ECS file.

 

CalibrationName = value

 

Calibration settings that are added at the start of the ECS file are fileset-level calibration values. Fileset-level settings override settings of the same name in all fileset Calibration sources.

For example:

SoundSpeed = 1496.3

This gives a value for sound speed for all Calibration sources (and hence all variables) in the fileset, even those not named in the ECS file. If values for sound speed are given in the data files they are ignored. The value can be modified again by using SourceCal or LocalCal.

Each calibration setting is on a line by itself. The setting consists of a calibration name (which is all one word), an equals, and a value (in this case a number). Calibration names are case insensitive.

SourceCal NameOfExistingSource

followed by a list of

 

CalibrationName = value

The keyword SourceCal defines a section where suitable calibration settings are listed for the named Calibration source. This allows the settings to supplement or over-ride the settings for the Calibration source read from the echosounder data file.

For example:

In an ECS file

On the Calibration page of the Variable Properties dialog box

SourceCal T1
Absorption = 0.01

ExistingSet supplement value

Figure 2. SourceCal calibration source name on the Calibration page of the Variable Properties dialog box.

This gives values for absorption to be used with the settings in Calibration source T1. If the data files have values for absorption or pulse length for Calibration source T1, the specified values will override the pre-existing values. A warning is given if no such Calibration source is found.

The SourceCal declaration is on a line by itself. SourceCal and the Calibration source name are not case sensitive.

LocalCal NewName

followed by a list of

 

CalibrationName = value

The keyword LocalCal specifies a group of calibration settings which can be used to override the source calibration for a single variable. This is in contrast to SourceCal which overrides or supplements values for all variables that use the calibration source.

For example:

LocalCal MySet
Absorption = 0.001
PulseLength = 1

MySet appears under the LocalCal list on the Calibration page of the Variable Properties dialog box. The LocalCal settings override any other matching settings.

The scope of LocalCal is limited. LocalCal settings apply only to the variables to which they are explicitly specified and LocalCal is ignored for a derived virtual variable.

The LocalCal declaration is on a line by itself. LocalCal and the name are not case sensitive. The use of LocalCal is described in the Example.

  • It is an error to give a LocalCal set the name of a Calibration source.
  • It is an error to create more than one LocalCal set with the same name.

The calibration settings that Echoview uses can be viewed and modified when you use:

Notes:

Calibration settings

Each calibration setting is on a line by itself. The setting consists of a name (which is all one word), an equals, and a value. Calibration setting names are not case sensitive. New ECS files may list compatible calibration settings.

Note: Information includes Calibration name, Help file terminology, Default value, Decimal places, Minimum value and Maximum value.

See also: Calibration setting pages for file formats.

Version number

Keywords: Version

An ECS file created by New on the Filesets window, starts with a version declaration, For example:

Version 1.00

The version number affects error handling.

Warnings and errors

Echoview may display diagnostic warnings and error messages about the content of an ECS file. Such messages are sent to the Messages dialog box. Any errors cause the ECS file to be ignored. An ECS file that Echoview can't read is flagged (in the Filesets window) with a red cross and a message in the Message dialog box, and causes raw variables to become unavailable.

Warnings

Warnings are of the form:

Calibration file 'FileName', on line N (Cal): Message

where:

Particular warnings

Errors

Errors are of the form:

Ignored calibration file 'FileName' because on line N (Cal): Message

where:

An example ECS file

parts on an *.ecs file "ECS template suggestions"

Figure 3. An example ECS file.

ECS and Calibration page

Figure 4. Calibration values used by Echoview (i.e. Value column) on the Calibration page of the Variable Properties dialog box for the ECS example. The Calibration file column lists values read from the ECS file. The Data file column lists values read from the echosounder data file.

For variables that use T1:

Supplemental calibration settings from

Calibration settings used by Echoview under the Value column

FILESET SETTINGS

The values under the FILESET section of the ECS file are applied to all variables in the fileset regardless of calibration source. In effect they are global values.

  • The Calibration page specification of LocalCal as MyCal causes the value of 1470 to override the Data file value (1500) and override the FILESET value (1495).
  • AbsorptionCoefficient of 0.0100000 is used by Echoview. It is a FILESET value and is read from the ECS file. It overrides the Data file value.

SOURCECAL SETTINGS

SourceCal T1

Echoview respects the FILESET values and then uses SOURCECAL T1 values followed by T1 calibration source values that have not been overridden by LOCALCAL MyCal values.

  • The Calibration page specification of LocalCal as MyCal causes the value of 1470 to override the Data file value (1500) and override the FILESET value (1495).
  • AbsorptionCoefficient of 0.0100000 is used by Echoview. It is a FILESET value and is read from the ECS file. It overrides the Data file value.
  • Ek60TransducerGain of 26.7 is used by Echoview and is read from the SOURCECAL T1 section of the ECS file. It overrides the Data file value.
  • Remaining settings specified by the calibration source T1.

LOCALCAL SETTINGS

LocalCal MyCal

Echoview respects the FILESET values and then uses SOURCECAL T1 values followed by T1 calibration source values that have not been overridden by LOCALCAL MyCal values.

  • The Calibration page specification of LocalCal as MyCal causes the value of 1470 to override the Data file value (1500) and override the FILESET value (1495).
  • AbsorptionCoefficient of 0.0100000 is a FILESET value and overrides the Data file value
  • Ek60TransducerGain of 26.7 is used by Echoview and is read from the SOURCECAL T1 section of the ECS file. It overrides the Data file value.
  • Remaining settings specified by the calibration source T1.

Variables with other calibration sources (e.g., T2) will not be affected by SourceCal T1 values. The variable's Variable Properties will list MyCal as a LocalCal option and the variables will also respect the ECS Fileset calibration values.

If you change a calibration setting in the ECS file but the Calibration page of the Variable Properties dialog box does not change and no error or warning message appears, check that you have removed the hash symbol in front of the setting. Echoview ignores any text after a hash symbol.

Figure 5. ECS template - suggested values preceded by hash symbols.

See also

About calibration settings
ECS and new EV files
ECS and pre-version 5.0 EV files
ECS file error handling
Calibration settings for data formats
Calibration settings for virtual variables