echoIBM: Simulates echo sounder observations based on positions,...

Description Usage Arguments

View source: R/echoIBM.R

Description

Simulates echo sounder observations based on positions, orientations, sizes and other specifics of each fish in a known (simulated) school. The variables of the school, vessel, acoustic instrument and sea are given as files in the TSD format located in the directory specified by 'event'. More than one school may be given located in separate directories in 'event'. The simulated echogram will be stored as a TSD file in 'event'. The function includes an option to plot the vessel path relative to the centers of mass of the school. Schools can be given compactly in order to save space, in which case the individual fish information is generated on the fly (see "Example of compact schools in echoIBM.R").

Merges time steps of acoustic data located in the neighbor directory "temp" of the "tsd"-directory given by 'event'.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
echoIBM(event, t = 1, adds = NULL, rph = NULL, esnm = NULL,
  TVG.exp = 2, compensated = c("pitch", "roll"), filesize = 3e+08,
  calibrate = TRUE, noise = c("bg", "cex"), mode = c("active", "passive"),
  tvessel = NULL, scan.volume = TRUE, margin = 500, smooth = "spline",
  max.memory = 1e+09, ow = TRUE, origin = 1, recycle = FALSE,
  keep.temp = c(TRUE, FALSE), dumpsize = 1e+07, cores = 1, rand.sel = 1,
  scls = 1, method = c("closest", "linear"), ask = FALSE,
  parlist = list(), bptfile = TRUE, max.radius = 0.2, path = FALSE,
  pathnr = 1, onlyMerge = FALSE, msg = FALSE)

echoIBM.add.noise.event(event, fileind = NULL, beams0 = NULL, ctd = NULL,
  TVG.in = TRUE, TVG.out = TRUE, TVG.exp = 2, noisetypes = c("nr", "bg",
  "cex"), ow = TRUE, parlist = list(), cores = 1)

Arguments

event

is a vector of strings, where the first is the path to the directory of the simulation files, and any additional stings are directories or files containing for example school files located elsewhere than the main directory given by the first string in 'event'. Additional schools must be given as directories in 'event', not as paths to individual files, as this implies that these files "belong" to any existing school located in event[1]. Files containing beam configuration, noise values, calibration values, ctd-values and vessel dynamics need to be given in the main directory! Also the directories need to be exact, and not directories above the actual directory, like in read.event(). School information may be given also ...???

t

is a vector of the numbers of the pings to be simulated, as listed from 1 to the number of time steps of the simulated school. If t=="all", all time steps are simulated.

adds

is an optional list of variables overriding the variables located in the 'event' directory.

rph

is a matrix of two columns of length 3 representing the mean (column 1) and the standard deviation (column 2) of the roll values (rtxv), pitch values (rtyv) and heave values (przv) of the vessel, used in gaussian simulation of the roll, pitch and heave values.

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.exp

is the exponent of the eamotric spreading of the sound wave, theoretically 2 for Sv and 4 for TS.

compensated

specifies which rotations are compensated for by the echo sounder:

filesize

is the maximum size of the merged files.

calibrate

is FALSE if calibration data are to be discarded if present.

noise

See echoIBM.add.noise().

mode

is one of "active" and "passive".

tvessel

has two different interpretations depending on the option 'path': In the case that path==TRUE 'tvessel' is the UNIX time values to be written to the .vessel-file. When path==FALSE 'tvessel' is a vector of the index numbers of the time steps to assign to the simulated pings. If tvessel==NULL the school time points are used.

scan.volume

is TRUE if the volume selected when path=TRUE is to be scanned to see if the school is inside the volume at each ping.

margin

is a vector of the margins on either side of the span of 'x' (recycled if not of length 4).

smooth

has one possible value "spline", smooths the x-values and the y-values of the generated vessel path separately using the spline function.

max.memory

is the maximum amount of memory to allow for the function to occupy. The level of for loops is chosen according to this value, i.e. if the method using only two loops, one for the radial distances and one for the unique frequencies, demands more memory than 'max.memory', the method usint three for loops is chosen.

ow

is TRUE if the user wish to overwrite existing file.

origin

is a vector of two elements representing the origin of the global coordinate system (G), or the numbering index of the ping regarded as the origin of (G) (ignoring heave so that the x-y-plane of (G) is on the surface of the sea).

recycle

can be given in a number of ways. If more than one school is to be simulated, 'recycle' must either be a list, or is converted to a list, of length equal to the number of schools / folders including school files. Each list element can be (1) a function selecting the appriopriate time steps, as indexed for each school (say if school nr. 2 has the time step indices 4, 5, 7 with respect to the time steps of the vessel, and the function is to alternate between the second and third time step, the result is 5, 7, 5, 7, and so on). A second possibility (2) is that 'recycle' is given as TRUE, to indicate recycling the first time step. Also (3) a vector of time step indices is accepted, which for the example above would be 2:3. If schools are given compactly (see "Example of compact schools in echoIBM.R"), 'recycle' can be given as a single numeric to freeze the schools at a specific time step.

keep.temp

has two elements, where the first is TRUE if the temporary directory holding the noiseless data directory is to be kept, and where the second is TRUE if the noise-added data directory is to be kept.

cores

is an integer specifying the number of cores to run the simulations over in parallel (should be lower than the number of cores in the computer).

rand.sel

is a numeric specifying a random selection of the school to use in the simulations. If rand.sel>1, 1/rand.sel of the targets are selected, and the selected targets are scaled by 'rand.sel' to keep the original backscatter from the school. If given as a vector of length 2, the second element is regarded as the seed for the random selection.

scls

is a factor by which the backscattering cross sectional area of the targets are scaled.

method

is "closest" if the beam pattern value of the closest grid point is to be selected, and "linear" if linear interpolation should be used to extract the beam pattern value (time demanding and only available for 2D grids).

ask

is TRUE if the used should be asked to for approval if the memory of the least memory demanding calculation method of the individual radial sampling intervals exceed the memory limit 'max.memory'.

parlist

is a list of input parameters to the function echoIBM.add.noise(), which generates noise and randomness. See echoIBM.add.noise() for explaination of the possible variables. Important variables are seed and pre=TRUE to use pre-generated randomness.

bptfile

is the name of the file to which 'sllf', 'rad1', 'rad2', 'pbp1' and 'pbp2' is written (use NULL for no writing).

path

is TRUE to allow the user to select vessel positions interactively.

pathnr

is the number of the vessel path drawn, to be used in the name of the ".vessel" file. If a new ".vessel" file is to be written, 'pathnr' must be different than the pathnr of existing files.

beams0

is the list of beams inputs as returned from read.TSD. For the treatment of noise at least one of the following variables are required: bgns, nrn0.

ctd

is the list of ctd inputs as returned from read.TSD.

TVG.in

is TRUE if Time Varied Gain compensation is already applied to the input.

TVG.out

is TRUE if Time Varied Gain compensation should be applied to the output.

noisetypes

See echoIBM.add.noise().

event

is the path to the directory of the simulated files. If the length of 'event' is 2, the second string is the path to the temp-directory holding the files to merge, while the first is the directory in which to put the merged files.

TVG.exp

is the exponent in the TVG amplification (usually 2 for Sv and 4 for TS).

ow

is TRUE if the user wish to overwrite existing file(s).

parlist

is a list of input parameters to the function echoIBM.add.noise(), which generates noise and randomness. See echoIBM.add.noise() for explaination of the possible variables.


arnejohannesholmin/echoIBM documentation built on March 19, 2018, 9:16 a.m.