read.event: Extracts variables from acoustic events.

In arnejohannesholmin/sonR: Library for reading, processing and converting sonar data to the TSD format

Extracts variables from acoustic events.

Description

Extracts variables from acoustic events.

Usage

read.event(
  event = 1,
  var = "pings",
  t = 1,
  cruise = 2009116,
  TIME = FALSE,
  adds = NULL,
  esnm = "MS70",
  TVG = TRUE,
  TVG.exp = 2,
  ideal = TRUE,
  cs = "g",
  seabed = -12000,
  rot = 2,
  compensation = c("pitch", "roll"),
  exact = FALSE,
  origin = 1,
  dir.data = NULL,
  drop.out = TRUE,
  strip.out = TRUE,
  dir.out = FALSE,
  mask = TRUE,
  Paout = TRUE,
  bgns = TRUE,
  pdns = TRUE,
  nrns = TRUE,
  hins = TRUE,
  kern = NULL,
  merge = TRUE,
  msg = TRUE,
  segpar = NULL,
  pamkpar = list(),
  nsind = 0.75,
  hins_add = 10,
  pdns_scale = 1e-14,
  TOV = 0,
  allow.old = FALSE,
  ggsz = 10,
  pad = TRUE,
  split = TRUE,
  cal = 1,
  fanWidth = "b2",
  onestep = TRUE,
  other = FALSE,
  fill = NA,
  info.out = FALSE,
  ...
)

Arguments

event	is the identifier of the event, either given as the number of the event, a string contained in the name of the event, or the path of the event directory.
var	is a string vector representing the variables to return. The function searches for the variables in the files contained in the event directory. The legal variable names are listed below:
t	is either a vector of the numbers of the pings to be returned, as listed from 1 to the number of pings in the event, or a vector of time points given as strings "yyyymmddHHMMSS.FFF" or "HHMMSS.FFF" from which the range of the time points to be read is extracted. If t == "all", all files are read and if t == "none" an empty list is returned.
cruise	is either the idenfication number of the cruise, given as specified by the IMR (yyyynnn), or the path to the directory containing the event to be read.
TIME	is an optional list as returned from UNIX_time() (speed up reading).
adds	is an optional list of variables overriding the variables located in the event directory, used when calculating the positions and volumes of the voxels. Elements of 'adds' representing dynamic variables of the vessel (like "rtzv", "psxv" and so on) need to be at time steps 't' and thus have length equal to the length of 't'.
esnm	is the name of the acoustical instrument, given as a four character string. See sonR_implemented() for the implemented systems. May be given in 'data', and in lower case.
TVG	is FALSE if TVG compensation is to be removed from the data. No longer active. TVG.exp = 0 now corresponds to TVG = FALSE.
TVG.exp	is the exponent in the range compensation function (Time varied gain or TVG). TVG.exp=2 corresponds to the convensional 20 log R-TVG used for volume backscattering strength Sv. TVG.exp=0 removes the range compensation.
ideal	is TRUE if the speed of sound in water is assumed to be constant.
cs	is the coordinate system of the voxel midpoints or edges of the voxels.
seabed	is the depth of the seabed, at which the beams are reflected when calculating the midpoints of voxels.
rot	see soundbeam.TSD().
compensation	is a vector of string giving which rotation values that are compensated for in the sonar. Only c("pitch", "roll") is available for the current version. Used in soundbeam.TSD.
exact	is TRUE if the volumes should be calculated by the slower procedure incorporating the edges of the voxels. If FALSE (default) use the fast functions which only account for changes in the thickness of the voxels.
origin	is (1) a vector of two elements representing the origin of the global coordinate system (G), (2) the numbering index of the ping in the total sequence of pings of the event, which is to be regarded as the origin of (G) (ignoring heave so that the x-y-plane of (G) is on the surface of the sea), or (3) NULL, implying that the origin be put to the mid point of the vessel posistions.
dir.data	is the path to the directory in which the projects are stored, defaulted by the variable Acoustics_datasets_directory().
drop.out	is FALSE if output should not be dropped of dimensions of only one level.
strip.out	is FALSE if duplicated elements of the output list should be kept.
dir.out	is TRUE if only the path to the directory of the event is to be returned.
mask	is TRUE to return a data frame of the segmentation mask.
Paout	is TRUE if pressure data are to be returned in Pascal.
bgns	indicates wheter the estimated background noise should be subtracted, resulting in some negative sv-values. If TRUE (default) the background noise is kept in the data (no action). If FALSE the background noise estimates are attemptedly located in the event directory or the noise estimate directory of the cruise. If string, it should be the path to the file holding the background noise estimates. If the length of 'bgns' is longer than 1, the background noise estmate taken as the simple mean for all beams, regardless of the periodic noise is used.
pdns	indicates wheter the estimated periodic noise should be subtracted. If TRUE (default) the periodic noise is kept in the data (no action). If FALSE the periodic noise estimates are attemptedly located in the event directory or the noise estimate directory of the cruise. If string, it should be the path to the file holding the periodic noise estimates.
nrns	indicates wheter the estimated close range (previously named "near range") noise should be subtracted. If TRUE (default) the close range noise is kept in the data (no action). If FALSE the near range noise estimates are attemptedly located in the event directory or the noise estimate directory of the cruise.
hins	indicates wheter the estimated high intensity noise should be subtracted. If TRUE (default) the high intensity noise is kept in the data (no action). If FALSE the high intensity noise estimates are attemptedly located in the event directory or the noise estimate directory of the cruise.
kern	is the standard deviation in units of the number of voxels used in a Gaussian kernel smoother along the beams (no smoothing if kern == 0 or length(kern) == 0, which is the default). If given as an integer, say 5L, median smoothing is applied instead of Gaussian.
merge	is TRUE if variables read for more than one file are to be merged.
msg	is TRUE to print messages to the console.
segpar	is a list of elements named "bwGp", "lsth"/"rlst", "usth"/"rust", or "sgth"/"sgt0" specifying the parameters of the segmentation data to read.
pamkpar	is a list of parameters ('krange', 'criterion', 'alpha' and 'mindist') used pamk() when clustering the segmented voxels 'sgsc'. The voxels 'sgsc' are also ordered so that the voxels belonging to the largest cluster lead and the second to largest cluster follows. A suggested set of parameters are pamkpar = list(krange = 1:4, criterion = "asw", alpha = 0.05, N = 1e2, mindist = 100).
nsind	is a vector of indexes along the beams, as input to ind.expand(), used to select the subset over which the estimation of the phase of the periodic noise is done. If given as a single numeric, the outermost 'nsind' voxels are used in each beam.
hins_add	is the number of voxels that should be discarded on both sides of high intensity noise voxels voxels along beams, used for accounting for possible high values that are related to the high intensity noise but not classified as such voxels.
pdns_scale	is used in get.pdns_phase.event() to scale the noise in order to allow the optimization to work.
TOV	is the time offset of the vessel information, discovered by Holmin and Korneliussen in 2013. The default is found in "/Applications/echoIBM/Documentation/Error in yaw MS70/Error in yaw MS70.R".
allow.old	is a TRUE if old UNIX_time file is accepted (still with the correct list of files).
ggsz	is the grid size of the global grid in which Sv is returned.
pad	Logical: If TRUE, pad with NAs for non-equal lengths of beams.
split	See mergeListKeepDimensions.
cal	a factor to multiply all data by (prior to range compensation).
fanWidth	has a number of possible values: (1) "b1": one way beam width. (2) "b2": two way beam width. (3) "fe": beams modeled by rectangular cones with width withing the fan given by the inter-beam angle, and calculated using the equivalent beam angle. This normally causes larged fan width due to overlap between beams.
onestep	is TRUE or 1 to allow for files with only one time step to be read regardless of 't'. If set to 2, the single time step is repeated to the number of time steps requested by t.
fill	is the value to use for missing data (outside of the mask).
...	are inputs used in ftim.TSD(), but more importantly in pplot3d.TSD(). Particularly, 'ind', 'range', and 'subset' can be used to subset the data in pplot3d.TSD(), but 'ind' can also be used to subset the acoustic data.
other.	is TRUE to read other files than acoustic, electrical angle, vessel, beams, noise, ctd, school, seg, time.

arnejohannesholmin/sonR documentation built on April 14, 2024, 11:39 p.m.