Add variable Sv attributes to output dataset from compute_Sv

[emiliom]

The Sv DataArray generated by calibrate.compute_Sv has no variable attributes; see an example here. Add the usual set:

• long_name: "Volume backscattering strength (Sv)"
• units: "dB"
• actual_range: Generated from the data min & max values (valid_min and valid_max are not applicable)

There doesn't seem to be a CF standard_name for Sv.

576 and #481 are somewhat related, though focused on MVBS (mean Sv)

[emiliom]

@leewujung could you clarify what the units of Sv are? I've seen different versions. In this issue I wrote dB, from something I saw I forget where; but in other recent echopype inline comments I've seen "dB re 1 m^-1". BTW, what's "re" in those units?

I assume the units for MVBS identical, but please confirm.

[leewujung]

@emiliom : yes, the units for Sv is "dB re 1 m^-1" The "re" here is "in reference to," since dB is a relative scale, like this: That's why people always write "re" when using dB as units, like sound pressure level (SPL) often is in units "dB re 1 uPa."

And yes the units for MVBS is identical to Sv since it is mean Sv.

[emiliom]

Thanks! I'm adding this reference to the "re" notation: https://en.wikipedia.org/wiki/Decibel#Suffixes_and_reference_values. I wasn't familiar with that notation. FYI, it doesn't look like there's support for it in the udunits package that CF refers to for units strings, though I didn't look very deeply. The CF FAQ has this entry about decibel and reference "levels": "decibel: a logarithmic measure of relative acoustic or energy intensity; symbol dB, db, or dbel (the reference level, needed for logarithmic units, is specified in the standard names that use this canonical unit)"

[emiliom]

The Sv attributes can be added in a single module, right about here: https://github.com/OSOceanAcoustics/echopype/blob/dev/echopype/calibrate/api.py#L60

[emiliom]

I suppose we should be doing the same (checking for and adding missing attributes) for the output dataset from compute_Sp ...

[leewujung]

the output dataset from compute_Sp ...

Yeah, it is (mostly) the same thing...

[emiliom]

Just when I thought I could close this issue .... We still need to add Sp variable attributes to compute_Sp. For reference, that's in _compute_cal, in calibrate/api.py.

@leewujung for the Sp variable, does this look ok:

• "long_name": "Point backscattering strength (Sp) "
• "units": "dB re 1 m-1"

I assume the attributes for range_sample and echo_range are the same as with Sv, but please confirm:

• sv_dataset["range_sample"].attrs = {"long_name": "Along-range sample number, base 0"}
• sv_dataset["echo_range"].attrs = {"long_name": "Range distance", "units": "m"}

[leewujung]

"long_name": "Point backscattering strength (Sp) "

"Point backscattering strength" is the terminology from Simrad so I think it is worth some discussion here. Below is from the Echoview glossary:

Point backscattering strength data logged with Simrad ER60 software. Known as TS in Echoview. For such data, Simrad now define TS as the subset of Sp data that has been confirmed (via single target detection) to correspond to a single target.

Target strength (TS) is a clearly defined term in scattering physics but as explained above, it is only valid when corresponding to a single target (instead of a group of targets in a volume).

However, since TS is defined and widely used, I wonder if we should change compute_Sp to compute_TS, and in the docstring clearly state that it is only valid when the echo is associated with a single target.

The units for TS is "dB re 1 m^2"

And yes, the attributes for range_sample and echo_range are the same as with Sv.

[gavinmacaulay]

Just a note: the formal definition of TS doesn't require that the echo come from a single target - it is the fisheries acoustic community that has the convention that TS is from a single target.

Another thing I've recently become aware of: the units of log variables is just dB. The reference value is better as part of the quantity name. The new convention in some acoustic fields is to put the reference value after the variable name like this: TS (re 1m^2) = xx dB, which also fits better with CF and the udunits library. A good presentation of this is available in section 11 of this report (link seems down at the moment - an alternative). The next version of SONAR-netCDF4 will migrate to this form.

[leewujung]

@gavinmacaulay : thanks for chiming in! By formal definition do you mean TS = 10 * log10(backscattering cross section), and that the scattering cross section can be generally defined?

[gavinmacaulay]

yes - TS is the log form of backscattering cross section, and that is defined as the ratio of backscattered and incident acoustic intensities (plus r^2 and an absorption factor) - no need for the backscattered intensity to be from a target (although that is a common extra constraint). The fisheries acoustics definitions are available here, although some of those definitions may change due to the more recent and authorative ISO 18405-2017.

[leewujung]

Great, thanks for the clarification. I am familiar with these definitions and the MacLennan reference. :) It's good to know about ISO 18405-2017, I didn't know about that.

[emiliom]

However, since TS is defined and widely used, I wonder if we should change compute_Sp to compute_TS, and in the docstring clearly state that it is only valid when the echo is associated with a single target.

So ... do we stick with compute_Sp or rename to compute_TS? If the latter, what would be the long_name, exactly? "Target strength (TS re 1 m^2)", and units in "dB"?

[leewujung]

@emiliom : I think we should rename this to compute_TS and have the output data variable TS with long_name: "Target strength (TS re 1 m^2)" and units: "dB" following @gavinmacaulay's suggestion.

[emiliom]

@leewujung: will do. I've started making the changes. It turns out that the string "point backscattering strength" is also used in many comments and doc strings in echopype. I'll change all of them to "target strength".

[emiliom]

re: the change from compute_Sp to compute_TS: the string "Sp" is used in quite a few places as the "calibration type" label (vs "Sv") that determines further processing decisions. So, I'll change all its occurrences to "TS".

[leewujung]

Sounds good. I can review these and add additional notes in the docstring.

[emiliom]

We've completed this issue. Closing