surveyPlanner: Plan an acoustic-trawl survey.
In Sea2Data/Rstox: Running Stox functionality independently in R

Description Usage Arguments Details Value See Also Examples

surveyPlanner reads a WKT (Well known text) file, shapefiles, or a StoX project and generates a survey plan of parallel or zig zag transects.

plotStratum plots the survey plan returned by surveyPlanner .

readStrataPolygons reads a WKT (Well known text) file, shapefiles, or a StoX project and returns the strata system.

surveyPlanner(projectName, parameters = NULL, type = "Parallel",
  bearing = "N", rev = FALSE, retour = FALSE, toursFirst = FALSE,
  hours = 240, nmi = NULL, t0 = NULL, knots = 10, seed = 0,
  angsep = 1/6, distsep = NULL, margin = NULL, equalEffort = FALSE,
  byStratum = TRUE, strata = "all", cruise = "surveyPlanner",
  keepTransport = TRUE, centroid = NULL, ...)

addStratum(x, acousticProc = "FilterAcoustic")

subsetStrata(strata, lonlat)

plotStratum(x, plot = c("map", "stratum", "transect"), centroid = NULL,
  transport_alpha = 0.1, zoom = 1.5, aspectratio = NULL,
  xlab = "Longitude", ylab = "Latitude", xlim = NULL, ylim = NULL,
  keep0effort = TRUE, strata = "all", strataNameCol = "darkblue",
  ...)

addStratumBordersAndNames(p, x, strataNameCol = "darkblue")

readStrataPolygons(projectName, ...)

getCentroid(lonlat, proj = "aeqd", lonlatnames = c("longitude",
  "latitude"))

`projectName`	The name or full path of the project, a baseline object (as returned from `getBaseline` or `runBaseline`, og a project object (as returned from `openProject`). Can also be the path to a shapefile or folder of shape files, or to a file with polygons given as a two column matrix with stratum name in the first column and a MULTIPOLYGON wkt string in the second conlumn.
`parameters`	Optional named list of parameters overriding the inputs "type", "bearing", "retour", "hours", "knots", "nmi", "seed" or "t0". This list is returned from `surveyPlanner` (located in the element $parameters), and can be useful when changing say the 'nmi' in the last strata given time lost due to weather in the first strata. See examples.
`type`	The type of the transects, repeated to the number of stratums. See details for possible values. Case insensitive.
`bearing`	The survey bearing of each transect, given in one of 4 ways: (1) by codes "N", "NW", "W", "WS", "S", "SE", "E", "NE", (2) as angles counter clockwise from EAST in degrees, (3) as a string "along" or "across" the stratum orientation as obtained by the principal components of the stratum borders after populating with 1000 points with nearly equal separation along the border in geographic corrdinates, or (4) as a data frame with columns "lon_start", "lon_stop", "lat_start", "lat_stop" defining the angles between a start and end point for each stratum.
`rev`	Logical: If TRUE, the bearing calculated by the funciton when bearing = "along" or "across" is reversed, i.e., going from East to West instead of West to East.
`retour`	Logical: If TRUE, continue with the transects back to the start point of the stratum.
`toursFirst`	Logical: If TRUE, do all tours first followed by the retours (only effective if retour is TRUE).
`hours, nmi`	The time/traveled distance to spend in each stratum, given in hours/nautical miles (repeated to the number of strata), where `nmi` has precedence over `hours`. If given as a list of one element, these are interpreted as the hours/nmi for the entire survey, in which case selecting only a subset of the strata using `strata` will increase the effort in each of the remaining strata.
`t0`	The start time of the survey, set to Sys.time() formatted to UTC by default. A as.POSIXct object or a string of a recognisable form (such as "%Y-%m-%d %H:%M:%S") are supported.
`knots`	The speed to use in the stratum, given in knots.
`seed`	The seed(s) to use for the random transects. If not given as an integer vector (such as c(2L, 5L)) of length equal to the number of strata, random seed are drawn using `getSeedV`.
`angsep`	The separation in degrees of points populating the stratum polygons (geographical coordinates longitude, latitude). Low values preserve the stratum borders when converting to Cartesian coordinates.
`distsep`	The separation in nautical miles of points populating the transects in Cartesian coordinates before converting back to geographical coordinates. When given, this parameter preserves the shortest travel distance (great-circle distances) of the transects (inducing curved lines in geographical coordinates).
`margin`	The margin to accept for deviation between input and output total travelled distance. Setting this may result in unequal coverage, since forcing the total traveled distance towards a fixed value may force specific paths due to the shape of the stratum. Rather, increase the input `hours`, og accept the "noise" in the output total traveled distance. For `plotStratum` margin is the margin around the borders of the survey area in units of its dimensions.
`equalEffort`	Logical: If TRUE, assign effort proportional to the area of each stratum.
`byStratum`	Logical: If FALSE, include the transport between strata in the total traveled distance given in $Survey of the output.
`strata`	Specification of the strata to include, either given as the string "all", implying all strata to be used; an index vector as given to "[]" (negative values may be used to exclude specific strata), or a character vector of the strata names. Note that if the strata are named by integers, these names must be given as character and not integers, which would act as indices.
`cruise`	A string or numeric giving the cruise name/code.
`keepTransport`	Logical: If FALSE, remove transport stretches in the Transect output.
`centroid`	Logical: If TRUE, plot the centroid of the strata.
`...`	Used for flexibility, and including shapenames: A list of length 3 giving the names of the longitude, latitude and stratum column in the shape files.
`x`	The output from `surveyPlanner`.
`transport_alpha`	The transparency to use for the transport paths.
`zoom`	The zoom relative to the extent of the range of the transect positions. Default is 1.5.
`aspectratio`	The aspect ratio of the plot, adjusted automatically by default.
`xlab, ylab`	The x and y label for the plot.
`xlim, ylim`	The x and y limit of the plot.
`keep0effort`	Logical: If FALSE, keep only the strata with positive effort.
`transect`	Logical: If TRUE, plot the transects.

The surveyPlanner function generates the survey plan (transect lines) in a cartesian coordinate system, and transforms the positions to the geographical coordinate system (longitude, latitude) using the azimuthal equal distance projection, which ensures that distances, and also equal coverage, if the method used is designed with this prerequisite, are preserved in the transformation. Strindberg and Buckland (2004): Strindberg, S., & Buckland, S. T. (2004). Zigzag survey designs in line transect sampling. Journal of Agricultural, Biological, and Environmental Statistics, 9(4), 443 The following types are implemented:

"Parallel": "Parallel transects"
"EqAngZZ": "Equal angle zigzag sampler (not implemented), Strindberg and Buckland (2004)"
"EqSpZZ": "Equal space zigzag sampler, Strindberg and Buckland (2004). End transects are generated different from Strindberg and Buckland (2004), by mirroring the last transect around the line perpendicular to the survey direction passing through the last intersection point between the stratum border and the parallel lines used to generate the transects."
"AdjAngZZ": "Adjusted angle zigzag sampler (not implemented), Strindberg and Buckland (2004)"
"RectEnclZZ": "Rectangular enclosure zigzag sampler, Harbitz (2019)"
"CurvEnclZZ": "Curved enclosure zigzag sampler (not implemented), Harbitz (2019)"

surveyPlanner returns a list of the following elements:

"transects": "A data frame with the geographic and Cartesian transect coordinates for all strata, along with start, mid and stop time and sailed distance"
"totalSailedDist": "A data fram with total, transect, transport and input (nmi) sailed distance, also given in percent of 'nmi'."
"lonlat": "The input stratum polygons (longitude, latitude) in a list with one matrix per stratum"
"parameters": "A list of parameters for each stratum: type, bearing, retour, hours, knots, nmi, seed"
"proj": "The projection string used to convert from (longitude, latitude) to (x, y)"
"area": "The area og each polygon in square nautical miles"
"centroid": "The centroid of the strata, used in the projection"
"strata": "The stratum names"

polyArea returns area in nmi squared, and matrix2multipolygon returns a MULTIPOLYGON wkt.

See ?writeTransects for writing the transects to verious files.

# Generate parallel transects with equal effort in each stratum (proportional to area):
projectName <- "Test_Rstox"
system.time(Parallel <- surveyPlanner(projectName=projectName, type="Parallel", bearing="N",
    nmi=2000, knots=10, seed=0, equalEffort=TRUE))
dev.new()
p <- plotStratum(Parallel)

# Running surveyPlanner() on a project takes some time, since the project has to be opened and
# the process data read to obtain the strata. A quicker way is to specify the strata definitions 
# directly, either as the path to a file or as a folder or vector of paths to shapefiles:
# This produces a different strata system than that in the Test_Rstox project:
system.time(Parallel <- surveyPlanner(projectName=file.path(dirname(getProjectPaths()$projectRoot),
     "reference", "stratum", "norwegian_sea2014.txt"), type="Parallel", bearing="N",
    nmi=2000, knots=10, seed=0, equalEffort=TRUE))
dev.new()
p <- plotStratum(Parallel)

# Write the transects to one csv file (to write one file per stratum use byStratum=TRUE). 
# Use ext="nc" to write to a NetCDF4 file. Use 'dir' to specify the directory in which to place 
# the file(s) (otherwise the files are placed in the R Report directory of the project):
filename <- writeTransects(Parallel, projectName=projectName, byStratum=FALSE)
filename

# Zigzag with equal coverage probability:
system.time(Zigzag <- surveyPlanner(projectName=projectName, type="RectEnclZZ", bearing="N",
    nmi=2000, knots=10, seed=0, equalEffort=TRUE))
dev.new()
p <- plotStratum(Zigzag)

# The parallel survey use 23.39 percent of sailing distance for transport between transects, 
# whereas the zigzag survey use 10.76 percent.
Parallel$Survey
Zigzag$Survey

# Reduce effort in the last three strata, e.g. due to lost time due to bad weather in stratum 1:
# Note that the parameter 'nmi' must be NULL (default) to effectively change the 'hours', since
# 'nmi', when specified, har precedence over 'hours'. 
# Also, the parameter 'equalEffort' must be FALSE (default) since TRUE implies recalculating
# the distance to traveled in each stratum so that this distance is proportional to stratum area:
hours <- Parallel$parameters$hours
hours[2:4] <- hours[2:4] - 50
system.time(Parallel2 <- surveyPlanner(projectName=projectName, type="Parallel", bearing="N",
    knots=10, seed=0, hours=hours))
dev.new()
p <- plotStratum(Parallel2)

# Tour-retour zigzag in stratum 1 and 3:
system.time(Zigzag2 <- surveyPlanner(projectName=projectName, type="RectEnclZZ", bearing="N",
    nmi=2000, knots=10, seed=0, equalEffort=TRUE, retour=c(TRUE, FALSE, TRUE, FALSE)))
dev.new()
p <- plotStratum(Zigzag2)

# Populate the transects with points separated by 10 nmi specified by the 'distsep' parameter, 
# for visualizing the true track along the great-circle:
system.time(Zigzag3 <- surveyPlanner(projectName=projectName, type="RectEnclZZ", bearing="N",
    nmi=2000, knots=10, seed=0, equalEffort=TRUE, retour=c(TRUE, FALSE, TRUE, FALSE), distsep=10))
dev.new()
p <- plotStratum(Zigzag3)

# Write the transects to a NetCDF4 file in the output folder of the project (alternatively specify
# the directory using 'dir', or the filenames using 'filenames'. Also use 'prefix' or 'suffix' 
# to add info to the file names):
writeTransects(Zigzag3, projectName, ext="nc")