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
Settings to the right override those to the left. For example Data file settings override Default settings. Fileset (aka Global), SourceCal and LocalCal settings are specified in an ECS file.                           

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

The Calibration source for an acoustic variable is listed under the SouceCal in the Calibration section of the Calibration page of the Variable Properties dialog box.

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

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 associates the following calibration settings with the named Calibration source, allowing them to supplement or over-ride the existing settings from that source.

For example:

In an ECS file

On the Calibration page of the Variable Properties dialog box

SourceCal T1
Absorption = 0.01
ExistingSet supplement value

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.

Note: Information includes Calibration name, Help file terminology, ECS example, 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

For variables that use T1:

Supplemental calibration settings from

Calibration settings used

SourceCal T1

SourceCal T1 respects the fileset settings and then uses SourceCal T1 values followed by T1 values that have not been over-ridden.

  • SoundSpeed of 1495
  • AbsorptionCoefficient of 0.003 (override the fileset setting)
  • Frequency of 38.8 (correct the T1 setting)
  • Remaining settings specified by T1.

LocalCal MyCal

MyCal respects fileset and SourceCal T1 settings and then uses the MyCal values followed by the variable's Calibration Source values that have not been over-ridden.

  • TvgRangeCorrection of BySamples
  • SoundSpeed of 1495
  • AbsorptionCoefficient of 0.003 (override the Fileset setting)
  • Frequency of 38.8 (correct the T1 setting)
  • Remaining settings specified by T1 (given that T1 is the Calibration source for the variable).

Variables with other calibration sources (e.g., T2) will not be affected by SourceCal T1, but will list MyCal and be influenced by the Fileset calibration settings.

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, then it may be that you have not removed the hash symbol in front of the setting. Echoview ignores any text after a hash.

Common hash error

See also

About calibration settings
About entering 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