| Title: | Echogram Visualisation and Analysis |
|---|---|
| Description: | Easily import multi-frequency acoustic data stored in 'HAC' or 'RAW' files (see <http://biblio.uqar.ca/archives/30005500.pdf> for more information on the format), and produce echogram visualisations with predefined or customized color palettes. It is also possible to merge consecutive echograms; mask or delete unwanted echogram areas; model and subtract background noise; and more important, develop, test and interpret different combinations of frequencies in order to perform acoustic filtering of the echogram's data. |
| Authors: | Héctor Villalobos [aut, cre] |
| Maintainer: | Héctor Villalobos <[email protected]> |
| License: | GPL-3 |
| Version: | 1.0.0 |
| Built: | 2025-02-20 02:58:23 UTC |
| Source: | https://github.com/hvillalo/echogram |
This function allows addition or subtraction of Sv data matrices of corresponding echograms from two frequencies in the linear or logarithmic domain.
add.echogram(echogram1, echogram2, operator = c("plus", "minus"), domain = c("linear", "dB"))add.echogram(echogram1, echogram2, operator = c("plus", "minus"), domain = c("linear", "dB"))
echogram1 |
an object of |
echogram2 |
an object of |
operator |
a string indicating addition (“plus”) or subtraction (“minus”). May be abbreviatted. |
domain |
a string indicating the domain where the operation will be performed (see details). |
Corresponding echograms refers to data acquired at the same time with different acoustic frequencies. In order to add echograms, the Sv data matrices must have the same dimensions. If they don't, match.echogram can be used for this purpose. It is also important to mask undesired echoes beforehand, as those belonging to the bottom and below. When domain = "dB" (the default), the Sv matrices are added as they are. When domain = "linear", the Sv values are transformed with 10^(Sv/10) before addition, and the result (X) is then back transformed to dB (10*log10(X)).
An object of class “echogram” where the Sv component is the result of the performed operation.
Héctor Villalobos
# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) echo2.120 <- read.echogram(hacfile, channel = 2) ## Not run: # attempting to add the two frequencies with unequal number of pings gives an error add.echogram(echo2.038, echo2.120, "plus", "dB") ## End(Not run) # running match.echogram() solves this tmp <- match.echogram(echo2.038, echo2.120) str(tmp) # both frequencies are in a list, need to split echo2.038 <- tmp$echogram1 echo2.120 <- tmp$echogram2 # we don't want to add bottom echoes, mask bottom and surface from both frequencies echo2.038m <- mask.echogram(echo2.038, surf.off = 2, bott.off = 0.2) echo2.120m <- mask.echogram(echo2.120, surf.off = 2, bott.off = 0.2) # adding Sv values and plot result echo.sum <- add.echogram(echo2.038m, echo2.120m, "plus", "dB") Min <- min(as.vector(echo.sum$Sv), na.rm=TRUE) # useful to set Sv threshold echogram(echo.sum, Svthr=floor(Min), scheme = "EK500") # subtract 38 from 120 kHz echo.minus <- add.echogram(echo2.120m, echo2.038m, "minus", "dB") Min <- min(as.vector(echo.minus$Sv), na.rm=TRUE) echogram(echo.minus, Svthr=floor(Min), scheme = "EK500")# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) echo2.120 <- read.echogram(hacfile, channel = 2) ## Not run: # attempting to add the two frequencies with unequal number of pings gives an error add.echogram(echo2.038, echo2.120, "plus", "dB") ## End(Not run) # running match.echogram() solves this tmp <- match.echogram(echo2.038, echo2.120) str(tmp) # both frequencies are in a list, need to split echo2.038 <- tmp$echogram1 echo2.120 <- tmp$echogram2 # we don't want to add bottom echoes, mask bottom and surface from both frequencies echo2.038m <- mask.echogram(echo2.038, surf.off = 2, bott.off = 0.2) echo2.120m <- mask.echogram(echo2.120, surf.off = 2, bott.off = 0.2) # adding Sv values and plot result echo.sum <- add.echogram(echo2.038m, echo2.120m, "plus", "dB") Min <- min(as.vector(echo.sum$Sv), na.rm=TRUE) # useful to set Sv threshold echogram(echo.sum, Svthr=floor(Min), scheme = "EK500") # subtract 38 from 120 kHz echo.minus <- add.echogram(echo2.120m, echo2.038m, "minus", "dB") Min <- min(as.vector(echo.minus$Sv), na.rm=TRUE) echogram(echo.minus, Svthr=floor(Min), scheme = "EK500")
This function imports, for a given acoustic channel, the detected bottom range stored in the ping tuple of an HAC file.
bottom.hac(hac, channel = NULL, plot = FALSE, maxDepth = NULL)bottom.hac(hac, channel = NULL, plot = FALSE, maxDepth = NULL)
hac |
name of an HAC file. |
channel |
acoustic channel number. |
plot |
logical. if |
maxDepth |
maximum depth (in m) represented in the plot. |
The acoustic channel is an integer, normally between 1 and n, where n is the number of frequencies used during data acquisition. When channel = 1, data from the lowest acoustic frequency is imported, while channel = n refers to the highest frequency present in the HAC file. By default, the function finds out the smallest channel number, because in some HAC files channel = 0. When a graphical representation is desired (plot = TRUE), the maximum displayed in the echogram depth can be provided as a negative integer with argument maxDepth.
A data frame with two variables where every row represents one emitted ping:
pingTime |
time of emitted ping. |
detBottom |
detected depth range in m. |
Héctor Villalobos
hacfile <- system.file("extdata", "D20150510-T202221.hac", package="echogram") bottom.hac( hacfile ) bottom.hac( hacfile, plot = TRUE )hacfile <- system.file("extdata", "D20150510-T202221.hac", package="echogram") bottom.hac( hacfile ) bottom.hac( hacfile, plot = TRUE )
Convert angles in imported EK60 raw files from electrical to mechanical.
convertAngles(ekraw)convertAngles(ekraw)
ekraw |
Imported EK60 data, as returned by |
A four dimensions array [depth samples, pings, transceivers, 2] with mechanical angles.
Héctor Villalobos
if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) angles <- convertAngles(ek) dim(angles) }if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) angles <- convertAngles(ek) dim(angles) }
Convert acoustic power from imported EK60 raw files to Sv or TS data.
convertPower(ekraw, frequency = NULL, output = "Sv", saCorr)convertPower(ekraw, frequency = NULL, output = "Sv", saCorr)
ekraw |
Imported EK60 data, as returned by |
frequency |
An integer corresponding to index of the transceiver in the data to convert. |
output |
A string indicating whether the power should be converted to acoustic backscattering strength (“Sv”) or to target strength (“TS”). |
saCorr |
sa correction value from calibration |
While the function operates on the EK60 data, it should be preferable
used through ek2echogram, which will convert the ek data to echogram.
A two dimensions array [depth samples, pings] with the desired output.
Héctor Villalobos.
ek2echogram.
if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) Sv <- convertPower(ek, output = "Sv") image(Sv) }if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) Sv <- convertPower(ek, output = "Sv") image(Sv) }
Extract datagram time and convert it to POSIXct.
dgTime(raw, ini)dgTime(raw, ini)
raw |
A raw vector imported via |
ini |
Initial byte with time data. |
The cpu time is stored in the first 8 bytes of every datagram,
after its name. It is assumed that the time zone is UTC, which may not
be the case. By comparig with gps time in nmea data, a correction may
be applied if needed. The index (ini) comes from output of get_dgIdx
function. This function should not be called directly by the user.
datagram time in POSIXct format.
Héctor Villalobos.
Echogram for background noise estimation.
data("echo.noise")data("echo.noise")
For this echogram, recording range (500 m) has been set above the sea bottom, and there is no evident presence of biological scatteres in order to facilitate the background noise estimation.
data("echo.noise") echogram(echo.noise)data("echo.noise") echogram(echo.noise)
This function allows to produce echogram visualisations from imported hac data. The user can define the visualisation Sv threshold and select between two built-in color schemes or define a custom scheme.
echogram(echogram, Svthr = -70, Svmax = 0, col.sep = NULL, col.nb = NULL, scheme = NULL, depth.grid = NULL, x.grid = NULL, x.ref = c("pings", "nmi", "seconds"), seabed = FALSE, depth.max = NULL, ping.ini = NULL, ping.max = NULL, colbar=TRUE, main = NULL, tformat = "%H:%M", restore.par = TRUE, ...)echogram(echogram, Svthr = -70, Svmax = 0, col.sep = NULL, col.nb = NULL, scheme = NULL, depth.grid = NULL, x.grid = NULL, x.ref = c("pings", "nmi", "seconds"), seabed = FALSE, depth.max = NULL, ping.ini = NULL, ping.max = NULL, colbar=TRUE, main = NULL, tformat = "%H:%M", restore.par = TRUE, ...)
echogram |
an object of |
Svthr |
Sv visualisation threshold, in decibels (dB). |
Svmax |
maximum Sv visualisation value, in dB. |
col.sep |
separation between colors. Defaults to 1 dB. |
col.nb |
number of colors. |
scheme |
color scheme for echogram, “parula” (the default), “EK500”, or “echov”. It can also be a vector of valid color names, or a function generating color names. |
depth.grid |
spacing between depth labels (in m). |
x.grid |
spacing between labels in the horizontal dimension according to x.ref. |
x.ref |
horizontal reference in echogram: “pings” (the default), “nmi” or “seconds”. |
seabed |
logical. When |
depth.max |
maximum depth to visualise. |
ping.ini |
initial ping to visualise. |
ping.max |
last ping to visualise. |
colbar |
logical. If |
main |
the acoustic frequency, by default. |
tformat |
time format for annotating when horizontal dimension when x.ref = 'seconds'. |
restore.par |
logical. If |
... |
other options to |
Besides the two built-in color schemes, the user can define its own by specifying a vector of valid color names (see examples). This function uses imageScale function from sinkr package by Marc Taylor.
Héctor Villalobos
# import hac file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile) # echogram by default echogram(echo2.038) # using alternative color schemes echogram(echo2.038, Svthr = -70, col.sep = 1.5, scheme = "EK500") echogram(echo2.038, Svthr = -70, col.sep = 3, scheme = c("white", "blue", "grey", "black"))# import hac file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile) # echogram by default echogram(echo2.038) # using alternative color schemes echogram(echo2.038, Svthr = -70, col.sep = 1.5, scheme = "EK500") echogram(echo2.038, Svthr = -70, col.sep = 3, scheme = c("white", "blue", "grey", "black"))
Convert imported EK60 raw data to class “echogram”.
ek2echogram( ekraw, frequency = 1, data = "Sv", environment = NULL, calibration = NULL )ek2echogram( ekraw, frequency = 1, data = "Sv", environment = NULL, calibration = NULL )
ekraw |
Imported EK60 data, as returned by |
frequency |
An integer corresponding to index of the transceiver in the data to be converted. |
data |
A string indicating the desired data: acoustic backscattering strength (“Sv”) or target strength (“TS”). |
environment |
An optional list with two elements: “soundVelocity” and “absorptionCoeff” calculated according to sea temperature and salinity measured during data collection. |
calibration |
A list as above, with “gain” and “saCorr” obtained from the echosounder calibration. |
This function calls the sampleRange and convertPower
functions to produce an object of class “echogram”.
A vector with sample range (m).
Héctor Villalobos.
read.echogram.
if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) eco <- ek2echogram(ek, frequency = 1, data = "Sv") echogram(eco) }if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) eco <- ek2echogram(ek, frequency = 1, data = "Sv") echogram(eco) }
Read the echosounder configuration information stored in CON0 datagram.
get_CON0(raw)get_CON0(raw)
raw |
A raw vector imported via |
While it can be used for reading the configuration data from an EK60 raw file, this function is not meant to be called directly by the user.
A list with two data frames: Header, containing survey-, transect- and sounder names, software version, and number of transceivers; Transceiver, with channel ID, beamtypes, frequency, gain, equivalent beam angle, etc. for each transceiver.
Héctor Villalobos.
if(interactive()){ config <- get_CON0("D20130504-T083828.raw") config }if(interactive()){ config <- get_CON0("D20130504-T083828.raw") config }
Find the datagram types and lengths, and their respective indices in EK* raw files.
get_dgIdx(raw)get_dgIdx(raw)
raw |
A raw vector imported via |
In EK* raw files, the first 4 bytes before every datagram contain its length (dgLen), which is repeated after the datagram data and before the length of the next datagram. So, for skipping from one datagram to the next, it takes 4 + dgLen + 4 + 1. Within each datagram, the first 4 bytes give its name (dgType: CON0, NME0, RAW0, etc.), followed by the time (next 8 bytes), and then the datagram data according to its type. The output of this fuction is key for extracting configuration data (header and transceiver information), nmea sentences, and acoustic raw data (received power and angles).
A data frame with datagram types (CON0, NME0, RAW0, etc.) and lengths, and most importantly, the indices where each datagram is located.
Héctor Villalobos.
if(interactive()){ dgIdx <- get_dgIdx("D20130504-T083828.raw") head(dgIdx) }if(interactive()){ dgIdx <- get_dgIdx("D20130504-T083828.raw") head(dgIdx) }
Read the NMEA sentences stored in NME0 datagrams.
get_NME0(raw)get_NME0(raw)
raw |
A raw vector imported via |
The GPS data stored in the output of this function needs to be parsed
to be useful. This is done with parse.nmea() function.
A data frame with CPU time and corresponding NMEA sentences as text strings.
Héctor Villalobos.
parse.nmea
if(interactive()){ nmea <- get_NME0("D20130504-T083828.raw") head(nmea) }if(interactive()){ nmea <- get_NME0("D20130504-T083828.raw") head(nmea) }
Read the acoustic sample data stored in RAW0 datagrams.
get_RAW0(raw, angles)get_RAW0(raw, angles)
raw |
A raw vector imported via |
angles |
Logical. If |
This function is not meant to be called directly by the user.
A list with pings data, which includes a sample data table, and
received power in a three dimensions array corresponding to the
number of depth samples, number of pings, and number of transceivers.
When angles = TRUE, alongship and athwartship electrical
angles are also returned as an array with an extra dimension.
Héctor Villalobos.
This function allows to join two echograms.
join.echogram(echogram1, echogram2)join.echogram(echogram1, echogram2)
echogram1 |
an object of |
echogram2 |
an object of |
This function is designed to join echograms of the same acoustic frequency, giving an error if frequencies differ. Desirably, echograms should be contiguous in space and time, but as this is not verified, it is possible to join non-contiguous echograms.
An object of class “echogram” resulting from the merging operation.
Héctor Villalobos
# import 38 kHz data from two consecutive HAC files hacfile1 <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1.038 <- read.echogram(hacfile1, channel = 1) hacfile2 <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile2, channel = 1) # join into one echogram echo.038 <- join.echogram(echo1.038, echo2.038) str(echo.038) echogram(echo.038)# import 38 kHz data from two consecutive HAC files hacfile1 <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1.038 <- read.echogram(hacfile1, channel = 1) hacfile2 <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile2, channel = 1) # join into one echogram echo.038 <- join.echogram(echo1.038, echo2.038) str(echo.038) echogram(echo.038)
This function creates, and optionally applies, a mask by “blanking” portions of the Sv data matrix of an echogram.
mask.echogram(echogram, surf.off = NULL, bott.off = NULL, mask = TRUE)mask.echogram(echogram, surf.off = NULL, bott.off = NULL, mask = TRUE)
echogram |
an object of |
surf.off |
surface offset in m defining the upper layer (refered to the surface) to be masked. |
bott.off |
bottom offset in m defining the bottom layer (refered to the bottom) to be masked. |
mask |
logical. If |
The masking process consists in producing a matrix of the same dimensions as the original Sv data matrix with NA's in the masked portion and 1's otherwise. The product of both matrices gives the masked echogram.
When mask = FALSE, a masking matrix is returned. When mask = TRUE (the default), an object of class “echogram” with the mask applied.
Héctor Villalobos
# import 38 kHz data from HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) # make a copy of the original echogram tmp <- echo2.038 # Create a mask, which is a matrix with 1's and NA's mask <- mask.echogram(tmp, surf.off = 1, bott.off = -1, mask = FALSE) image(t(mask[nrow(mask):1, ])) # Apply mask to echogram tmp$Sv <- tmp$Sv * mask echogram(tmp) # By default, the function returns the masked echogram echo2.038mask <- mask.echogram(echo2.038, surf.off = 2, bott.off = 0.2) echogram(echo2.038mask)# import 38 kHz data from HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) # make a copy of the original echogram tmp <- echo2.038 # Create a mask, which is a matrix with 1's and NA's mask <- mask.echogram(tmp, surf.off = 1, bott.off = -1, mask = FALSE) image(t(mask[nrow(mask):1, ])) # Apply mask to echogram tmp$Sv <- tmp$Sv * mask echogram(tmp) # By default, the function returns the masked echogram echo2.038mask <- mask.echogram(echo2.038, surf.off = 2, bott.off = 0.2) echogram(echo2.038mask)
This function verifies ping times between corresponding echograms from two frequencies, eliminating non-matching and duplicated pings.
match.echogram(echogram1, echogram2)match.echogram(echogram1, echogram2)
echogram1 |
an object of |
echogram2 |
an object of |
Corresponding echograms refers to data acquired at the same time with different acoustic frequencies. Unmatching pings, i.e. those present in only one frequency, and duplicated pings, are identified by it's associated time and subsequently eliminated.
A list with the two matched echograms.
Héctor Villalobos and Violeta E. González-Maynez
# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1.038 <- read.echogram(hacfile, channel = 1) echo1.120 <- read.echogram(hacfile, channel = 2) # Sv matrices have different number of pings dim(echo1.038$Sv); dim(echo1.120$Sv) # Apply match ping times tmp <- match.echogram(echo1.038, echo1.120) # split the list in the two echograms echo1.038 <- tmp$echogram1 echo1.120 <- tmp$echogram2 # number of pings and ping times are now the same for both frequencies dim(echo1.038$Sv); dim(echo1.120$Sv)# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1.038 <- read.echogram(hacfile, channel = 1) echo1.120 <- read.echogram(hacfile, channel = 2) # Sv matrices have different number of pings dim(echo1.038$Sv); dim(echo1.120$Sv) # Apply match ping times tmp <- match.echogram(echo1.038, echo1.120) # split the list in the two echograms echo1.038 <- tmp$echogram1 echo1.120 <- tmp$echogram2 # number of pings and ping times are now the same for both frequencies dim(echo1.038$Sv); dim(echo1.120$Sv)
Internal function called by read.echogram and merge.echogram.
mergeSvmat(m1, m2)mergeSvmat(m1, m2)
m1 |
First Sv data matrix. |
m2 |
Second Sv data matrix. |
Héctor Villalobos
This function allows to estimate a model of the background noise in an echogram by fitting the equation proposed by De Robertis and Higginbottom (2007).
noise.echogram(echogram, ping = NULL, dB1m = NULL, alpha = NULL, plot = TRUE, out = FALSE)noise.echogram(echogram, ping = NULL, dB1m = NULL, alpha = NULL, plot = TRUE, out = FALSE)
echogram |
an object of |
ping |
ping number for which the Sv values are to be modeled. |
dB1m |
noise level at 1m from the face of the transducer. |
alpha |
absortion coefficient of sound in sea water for echogram's frequency. |
plot |
logical. If |
out |
logical. If |
The estimation of an ambient noise model for a particular acoustic frequency, eventually allows the “cleaning” of echograms by subtracting this noise.
When plot = TRUE and out = FALSE (the default), only a plot is produced. With out = TRUE, the function returns an object of class “echogram” with the noise modelled.
Héctor Villalobos
De Robertis, A. and I. Higginbottom. 2007. A post-processing technique to estimate the signal-to-noise ratio and remove echosounder background noise 64:1282–1291.
# load echogram for noise estimation at 120 kHz (deep waters, no scatterers) data("echo.noise") attr(echo.noise$Sv, "frequency") echogram(echo.noise, xref = "ping") # a first look to the Sv values at ping 2 noise.echogram(echo.noise, ping = 2) # To better adjust the model, we need to provide the absortion coefficient for 120 kHz and adjust # the dB1m parameter. For this example, using data from a nearby CTD profile, alpha was calculated # as being 0.03550554, while -131 dB is choosen for dB1m noise <- noise.echogram(echo.noise, ping = 2, dB1m = -131, alpha = 0.03550554, out = TRUE) echogram(noise)# load echogram for noise estimation at 120 kHz (deep waters, no scatterers) data("echo.noise") attr(echo.noise$Sv, "frequency") echogram(echo.noise, xref = "ping") # a first look to the Sv values at ping 2 noise.echogram(echo.noise, ping = 2) # To better adjust the model, we need to provide the absortion coefficient for 120 kHz and adjust # the dB1m parameter. For this example, using data from a nearby CTD profile, alpha was calculated # as being 0.03550554, while -131 dB is choosen for dB1m noise <- noise.echogram(echo.noise, ping = 2, dB1m = -131, alpha = 0.03550554, out = TRUE) echogram(noise)
This function allows to design and visualise color palettes to be used in echograms.
palette.echogram(Svthr, Svmax, col.sep = NULL, col.nb = NULL, scheme = NULL, visu = FALSE)palette.echogram(Svthr, Svmax, col.sep = NULL, col.nb = NULL, scheme = NULL, visu = FALSE)
Svthr |
lower visualisation limit in decibels (dB). |
Svmax |
upper visualisation limit in dB. |
col.sep |
separation between colors in dB. |
col.nb |
number of colors. |
scheme |
color scheme for echogram, “parula” (the default), “EK500”, or “echov”. It can also be a vector of valid color names, or a function generating color names. |
visu |
logical. If |
This function is mainly intended to be called by plot.echogram, however it is possible to use it directly in order to have a first impression of a custom color palette.
A list with two elements
palette |
a vector of colors |
breaks |
a vector of color breaks |
Héctor Villalobos
palette.echogram() palette.echogram(Svthr=-75, col.sep=1.5, scheme="EK500", visu=TRUE) palette.echogram(Svthr=-81, col.sep=3, scheme=c("white", "blue", "black"), visu=TRUE)palette.echogram() palette.echogram(Svthr=-75, col.sep=1.5, scheme="EK500", visu=TRUE) palette.echogram(Svthr=-81, col.sep=3, scheme=c("white", "blue", "black"), visu=TRUE)
Find and parse GPS data from NMEA sentences.
parse.nmea(nmea, sentence = NULL, returnAll = FALSE)parse.nmea(nmea, sentence = NULL, returnAll = FALSE)
nmea |
A data frame with CPU time and corresponding NMEA sentences
as returned by |
sentence |
A string identifying the NMEA sentence to process. It can be one of "GPRMC", "GPGGA", "INGGA", or "GPGLL". |
returnAll |
logical. If |
This function looks first for the "GPRMC" sentence, if not found
it tries then with "GPGGA", "INGGA", or "GPGLL", and process the one with
more information (more GPS fixes). Be aware that sometimes strings may be
corrupted, in which case, it is possible to choose manually the sentence
to process. This is why get_NME0 does not automatically parse the
NMEA strings by default.
When one of "GPVTG", "INVTG", "GNVTG", or "IIVTG" sentences is found, vessel
speed and bearing are also parsed and returned.
Differences in time.cpu and time.gps may reveal wrong clock settings in the
data aquisition computer.
A data frame with cpu time, gps time (includes miliseconds if found), longitude, and latitude. Additionally, vessel speed and bearing are returned if found in the data.
Héctor Villalobos.
NMEA sentences structure can be seen in: https://gpsd.gitlab.io/gpsd/NMEA.html
get_NME0.
if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", angles = FALSE) gps <- parse.nmea(ek$nmea) head(gps) }if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", angles = FALSE) gps <- parse.nmea(ek$nmea) head(gps) }
This function imports time and geographic positions recorded by a GPS in an HAC file during data acquisition.
position.hac(hac)position.hac(hac)
hac |
name of an HAC file |
The function looks for the Position tuple (20) in the HAC file, and if found, imports the time, latitude and longitude of GPS fixes stored in the digital echogram, as well as the CPU time of the acquisition PC.
A data frame with four variables:
time.gps |
date and time from the GPS during data acquisition. |
time.cpu |
date and time from the computer CPU during data acquisition. |
lon |
longitudes. |
lat |
latitudes. |
If during acoustic data acqusition the PC clock is set to UTC time, as recomended, time.gps and time.cpu will be approximately equal, because a fraction of a second is added to time.cpu to obtain a precision of 0.0001 s.
Héctor Villalobos
ICES, 2005. Description of the ICES HAC Standard Data Exchange Format, Version 1.60. Technical Report 278, ICES Cooperative Research Report.
hacfile <- system.file("extdata", "D20150510-T202221.hac", package="echogram") pos <- position.hac( hacfile ) poshacfile <- system.file("extdata", "D20150510-T202221.hac", package="echogram") pos <- position.hac( hacfile ) pos
This function imports from different tuples in the HAC file, the necessary information to visualise and analyse an echogram in R.
read.echogram(hac, channel = NULL)read.echogram(hac, channel = NULL)
hac |
name of an HAC file. |
channel |
acoustic channel number. |
This function calls internally other echogram's functions (postion.hac, navigation.hac and bottom.hac) to import data from an HAC file. The acoustic channel is an integer, normally between 1 and n, where n is the number of frequencies used during data acquisition. When channel = 1, data from the lowest acoustic frequency is imported, while channel = n refers to the highest frequency present in the HAC file. By default, the function finds out the smallest channel number, because in some HAC files channel = 0. A text string with the frequency value (in kilohertz) is stored as an attribute of the Sv matrix (see examples below).
An object of class “echogram” (a list) with components:
depth |
a vector of mean sample depth (in m) of length p. |
Sv |
a p by k matrix of sampled values, currently the mean volume backscattering strength (Sv, in dB). |
pings |
a k by four data frame with ping time, detected bottom depth, vessel speed and cummulated traveled distance. |
Currently, read.echogram has been successfully tested importing HAC data from the following ping tuples: 10000 (U-32); 10030 (U-16) and 10040 (C-16).
Héctor Villalobos
ICES, 2005. Description of the ICES HAC Standard Data Exchange Format, Version 1.60. Technical Report 278, ICES Cooperative Research Report.
hacfile <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1 <- read.echogram(hacfile, channel = 1) class(echo1) str(echo1) attr(echo1$Sv, "frequency") echogram(echo1)hacfile <- system.file("extdata", "D20150510-T202221.hac", package = "echogram") echo1 <- read.echogram(hacfile, channel = 1) class(echo1) str(echo1) attr(echo1$Sv, "frequency") echogram(echo1)
This function will read Simrad BOT0 datagrams with bottom depth data.
read.EK_bot(file)read.EK_bot(file)
file |
EK60 bot file name. |
This function read the bot file by calling read.EK_raw,
and get_dgIdx functions. From the datagram index, it finds the BOT0
datagrams, and then extracts ping times and depth(s) associated with
all the transceiver(s) in the file.
A data frame with ping times and detected bottom depth for every transceiver in the file.
Héctor Villalobos.
read.EK_idx.
fn <- system.file("extdata", "demo-D20130504-T083828.bot", package = "echogram") depth <- read.EK_bot(fn) head(depth) plot(depth[, 1:2], type = "l", ylim = rev(c(0, max(depth[,2]))))fn <- system.file("extdata", "demo-D20130504-T083828.bot", package = "echogram") depth <- read.EK_bot(fn) head(depth) plot(depth[, 1:2], type = "l", ylim = rev(c(0, max(depth[,2]))))
This function will read Simrad IDX0 datagrams with ping data.
read.EK_idx(file)read.EK_idx(file)
file |
EK* idx file name. |
This function calls read.EK_raw, and get_dgIdx functions
to read the idx file, find the IDX0 datagrams, and then extracts ping information.
A data frame with ping data: ping number, vessel distance, latitude, longitude, and fileoffset.
Héctor Villalobos.
read.EK_bot.
fn <- system.file("extdata", "demo-D20130504-T083828.idx", package = "echogram") pings <- read.EK_idx(fn) head(pings) plot(pings$lon, pings$lat)fn <- system.file("extdata", "demo-D20130504-T083828.idx", package = "echogram") pings <- read.EK_idx(fn) head(pings) plot(pings$lon, pings$lat)
This function imports Simrad EK60 or EK80 raw files as raw bytes.
read.EK_raw(file)read.EK_raw(file)
file |
EK* raw file name. |
This function will return raw bytes as hex digits, therefore is not
intended to be called directly by the user. Instead, read.EK_raw is
called by other echogram's functions that also convert the various datagrams
in EK60 files to their appropriate type.
A vector of class “raw”.
Héctor Villalobos.
read.EK60_raw, get_CON0, get_NME0, and
get_RAW0.
This function imports all data in EK60 raw files.
read.EK60_raw(file, parseNMEA = FALSE, angles = TRUE)read.EK60_raw(file, parseNMEA = FALSE, angles = TRUE)
file |
EK60 raw file name. |
parseNMEA |
logical. When false (the default) all the nmea sentences found
in the raw file are returned as text strings. If |
angles |
logical. If |
This function imports the file as raw bytes with read.EK_raw.
Then, the configuration information is obtained from datagram CON0 with
get_CON0, nmea sentences (NME0) with get_NME0, and finally
acoustic data in RAW0 datagrams with get_RAW0.
A three elements list: (1) configuration, with Header and Transceiver(s)
information; (2) nmea sentences (full or parsed); and (3) pings data,
which includes at least a sample data table, and received power in a
three dimensions array [depth samples, pings, transceivers].
When angles = TRUE, alongship and athwartship electrical angles
are also returned as an array with an extra dimension.
Héctor Villalobos.
read.EK_raw, get_CON0, get_NME0, and get_RAW0
if(interactive()){ ekraw <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) # Header ekraw$config$Header # Transceivers ekraw$config$Transceiver # GPS data head(ekraw$nmea) }if(interactive()){ ekraw <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) # Header ekraw$config$Header # Transceivers ekraw$config$Transceiver # GPS data head(ekraw$nmea) }
This function allows to select individual pixels from an echogram and returns the Sv value, ping time and depth of the sampled pixel.
sample.echogram(echogram, plot = TRUE, coords = NULL, col = "black")sample.echogram(echogram, plot = TRUE, coords = NULL, col = "black")
echogram |
an object of |
plot |
logical. If |
coords |
(x, y) coordinates (in plot units) of the desired samples. They could result from previous sampling of another frequency. |
col |
color for the sampled points pixels. |
The selection of pixels to sample can be done by clicking on the echogram or by passing the coordinates of the desired pixels to the function. The coordinates should be in plot units, and therefore, these typically come from a previous selection by clicking on another frequency's echogram (see examples).
sample.echogram makes use of locator function, and therefore it only works in devices supported by the latter, such as X11, windows and quartz.
A data frame with seven variables:
id |
pixel id. |
x |
x coordinate in plot units. |
y |
y coordinate in plot units. |
d |
distance in plot units from the selected location to a valid pixel. |
pingTime |
time of sampled ping. |
depth |
depth of the sample. |
Sv |
Sv value. |
Héctor Villalobos
# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) echo2.120 <- read.echogram(hacfile, channel = 2) # plot 38 kHz echogram echogram(echo2.038) ## Not run: # select points coordinates with the mouse # click to select several locations and escape when done pts038 <- sample.echogram(echo2.038) pts038 # plot 120 kHz echogram echogram(echo2.120) # use the points previously selected for 38 kHz pts120 <- sample.echogram(echo2.120, coords = pts038[ , 2:3]) pts120 ## End(Not run)# import 38 and 120 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) echo2.120 <- read.echogram(hacfile, channel = 2) # plot 38 kHz echogram echogram(echo2.038) ## Not run: # select points coordinates with the mouse # click to select several locations and escape when done pts038 <- sample.echogram(echo2.038) pts038 # plot 120 kHz echogram echogram(echo2.120) # use the points previously selected for 38 kHz pts120 <- sample.echogram(echo2.120, coords = pts038[ , 2:3]) pts120 ## End(Not run)
Calculate sample range according to sound speed and sample interval for imported EK60 raw files.
sampleRange(ekraw, frequency = NULL)sampleRange(ekraw, frequency = NULL)
ekraw |
Imported EK60 data, as returned by |
frequency |
An integer corresponding to index of the transceiver in the data for which to obtain the sample range. |
While the function operates on the EK60 data, it should be preferable
used through ek2echogram, which will convert the ek data to echogram.
A vector with sample range (m).
Héctor Villalobos.
ek2echogram.
if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) R <- sampleRange(ek, frequency = 1) R }if(interactive()){ ek <- read.EK60_raw("D20130504-T083828.raw", parseNMEA = TRUE, angles = TRUE) R <- sampleRange(ek, frequency = 1) R }
This function allows to trim an echogram by depth or ping number by actually trimming the underlying data matrices and vectors.
trim.echogram(echogram, depth.max = NULL, ping.ini = 1, ping.end = NULL)trim.echogram(echogram, depth.max = NULL, ping.ini = 1, ping.end = NULL)
echogram |
an object of |
depth.max |
maximum depth to keep in the echogram. |
ping.ini |
start ping to keep. |
ping.end |
end ping to keep. |
This funcion has been conceived to discard undesired data below a given depth (e.g. the sea bottom), therefore, the initial depth is always the surface, so the vertical trimming is limited to select the maximum depth.
An object of class “echogram”.
Héctor Villalobos
# import 38 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) # echogram by default echogram(echo2.038) # trim the echogram echo.tmp <- trim.echogram(echo2.038, depth.max = 70, ping.end = 250) echogram(echo.tmp)# import 38 kHz data from an HAC file hacfile <- system.file("extdata", "D20150510-T202500.hac", package = "echogram") echo2.038 <- read.echogram(hacfile, channel = 1) # echogram by default echogram(echo2.038) # trim the echogram echo.tmp <- trim.echogram(echo2.038, depth.max = 70, ping.end = 250) echogram(echo.tmp)
Find and extract transceiver configuration information from imported EK60 raw files.
xcvrConf(raw, ini)xcvrConf(raw, ini)
raw |
A raw vector imported via |
ini |
Initial byte with transceiver data |
The index (ini) comes from output of get_dgIdx
function. This function should not be called directly by the user.
a data frame with transceiver configuration: channel ID, beamtypes, frequency, gain, equivalent beam angle, etc. for each transceiver.
Héctor Villalobos