Package for analyzing DEPONS simulation output

Description

Methods for analyzing population dynamics and movement tracks simulated using the DEPONS model (v.3.0; https://www.depons.eu), for manipulating input raster files, shipping routes and for analyzing sound propagated from ships.

The classes used in DEPONS2R include:

• DeponsTrack movement tracks, read from "RandomPorpoise.XXX.csv" files

• DeponsDyn population dynamics data, from "Statistics.XXX.csv" files

• DeponsBlockdyn data from "PorpoisePerBlock.XXX.csv" files

• DeponsShips data from "ships.json" files or from AIS data

Here the DeponsDyn data include both changes in population size and energetics through time for the entire landscape, whereas DeponsBlockdyn data include variations in population size in different parts (or 'blocks') of the landscape. XXX is the date and time when the simulation was finished.

DeponsBlockdyn-class

Description

Stores objects containing population size for different parts of the landscape (i.e. different 'blocks')

Details

The dyn slot contains a data frame with the columns 'tick', which indicates the number of half-hourly time steps since the start of the simulation; a column 'block' indicating the region of the landscape where animals were counted, a 'count' column with the number of animals in that block and tick. The 'real.time' column shows the real-world equivalent to 'tick, i.e. the time that has passed since 'startday'.

Slots

title

Character. Name of the object or simulation

landscape

Character. Identifier for the landscape used in the DEPONS simulations. The landscapes 'DanTysk', 'Gemini', 'Kattegat', 'North Sea', 'Homogeneous', and 'User defined' are distributed with the DEPONS model.

simtime

POSIXlt object with the date and time when the simulation was finished. This is read from the name of the imput file.

startday

POSIXlt object with the first day of the simulation, i.e. the first day in the period that the simulations are intended to represent in the real world.

dyn

Data frame with simulation output.

Note

DeponsBlockdyn-objects are usually read in from csv files produced during DEPONS simulations. These files are named 'PorpoisePerBlock.XXX.csv', where XXX indicates the date and time when the simulation was finished.

See Also

plot.DeponsBlockdyn and read.DeponsBlockdyn.

Examples

a.DeponsBlockdyn <- new("DeponsBlockdyn")
a.DeponsBlockdyn

DeponsDyn-class

Description

Stores objects containing population dynamics output and energetic output simulated using the DEPONS model.

Details

The following columns are included in the simulation output data frame: 'tick', which indicates the number of half-hourly time steps since the start of the simulation; 'count', which indicates the population size at a given time; 'anim.e', showing the average amount of energy stored by simulated animals; 'lands.e', which shows the total amount of energy in the landscape, and 'real.time' which shows the time relative to 'startday'.

Slots

title

Character. Name of the object or simulation

landscape

Character. Identifier for the landscape used in the DEPONS simulations. The landscapes 'DanTysk', 'Gemini', 'Kattegat', 'North Sea', 'Homogeneous', and 'User defined' are distributed with the DEPONS model.

simtime

POSIXlt object with the date and time when the simulation was finished. This is read from the name of the imput file.

startday

POSIXlt object with the first day of the simulation, i.e. the first day in the period that the simulations are intended to represent in the real world.

dyn

Data frame with simulation output.

Note

DeponsDyn-objects are usually read in from csv files produced during DEPONS simulations. These files are named 'Statistics.XXX.csv', where XXX indicates the date and time when the simulation was finished.

See Also

plot.DeponsDyn and read.DeponsDyn.

Examples

a.DeponsDyn <- new("DeponsDyn")
a.DeponsDyn

DeponsRaster-class

Description

Stores objects containing raster landscapes used as input in DEPONS simulations.

Slots

type

Character. Identifies the kind of data stored in the raster; should be 'food', 'patches', bathymetry', 'dtc', 'salinity', 'blocks' or 'NA'.

landscape

Character Identifier for the landscape used in the DEPONS simulations. The landscapes 'DanTysk', 'Gemini', 'Kattegat', 'North Sea', 'Homogeneous', and 'User defined' are distributed with the DEPONS model.

crs

Object of class "CRS", i.e. the coordinate reference system. This is provided as a proj4string text string.

header

Data frame with data on number of columns and rows in the input raster, the coordinates of the lower left corner, the size of each grid cell and the integer value used to represent missing data.

ext

Data frame with the extent of the landscape.

data

The actual data values for each of the grid cells.

Note

DeponsRaster-objects are typically read in from ascii raster files that have been used for DEPONS simulations.

See Also

plot.DeponsRaster, read.DeponsRaster and make.blocksraster. bathymetry is an example of a DeponsRaster-object.

Examples

a.deponsraster <- new("DeponsRaster")
a.deponsraster

DeponsShips-class

Description

Objects containing ship routes and ships

Methods for manipulating, plotting and analyzing ship routes and ship agents used in DEPONS simulations.

Slots

title

Name of the object (character)

landscape

Name of the landscape that the ships occur in (character)

crs

CRS object providing the coordinate reference system used; see CRS for details

routes

data.frame geographic positions of the 'virtual buoys' that define one or more ship routes that ship agents follow, and the speed that the ships should use when following this route. They also provide information about how long ships should use speed zero when reaching a specific buoy ('i.e. 'pause', measured in minutes). Can be extracted using the routes function.

ships

data.frame defining each of the ships occurring in DEPONS simulations, and the routes they occur on. The data frame includes the variables 'name', 'type', 'length', and 'route'. Info can be extracted using the ships function.

See Also

plot.DeponsShips, and read.DeponsShips

Examples

data(shipdata)
ships(shipdata)[1:10,]
routes(shipdata)
plot(shipdata, col=c("red", "purple", "blue"))

DeponsTrack-class

Description

Stores objects containing animal movement tracks simulated using the DEPONS model

Classes for manipulating and plotting movement tracks generated with DEPONS.

Slots

title

Name of the object (character)

landscape

Name of the object (character)

simtime

POSIXlt object with the date and time when the simulation was finished. This is read from the name of the imput file.

crs

CRS object providing the coordinate reference system used; see st_crs for details

tracks

Listwith one or more tracks, each stored as a SpatialPointsDataFrame object)

See Also

plot.DeponsTrack and read.DeponsTrack

Summary

Description

Summarizes different kinds of objects created based on output from the DEPONS model

Usage

## S4 method for signature 'DeponsBlockdyn'
summary(object)

## S4 method for signature 'DeponsDyn'
summary(object)

## S4 method for signature 'DeponsRaster'
summary(object)

## S4 method for signature 'DeponsShips'
summary(object)

## S4 method for signature 'DeponsTrack'
summary(object)

Arguments

Details

The summary method is available for DeponsTrack-class, DeponsDyn-class, DeponsRaster-class, and DeponsBlockdyn-class-objects.

Value

list summarizing the DeponsBlockdyn object

table summarizing the DeponsBlockdyn object

list summarizing the DeponsRaster object

list summarizing the DeponsTrack object

Convert ship tracks to DeponsShips object

Description

Convert Automatic Identification System (AIS) data for ships to ship track objects. This is done by cropping one or more ship tracks to the extent of a landscape and converting the data to a DeponsShips-class object. If the AIS data does not include ship positions recorded in half-hour steps, the tracks are interpolated to make objects suitable for use in DEPONS.

Usage

ais.to.DeponsShips(data, landsc, title = "NA", ...)

Arguments

Value

Returns a DeponsShips object containing one or more ships assigned to each of the routes in the object. All ships on a particular route move at the same speed along the route. The routes are defined by x and y coordinates based on the same coordinate reference system as the landscape they are located in. The speed that ships use after reaching a particular position (a particular 'virtual buoy') is calculated from the distance to the following position, and the time it takes reaching that position. If speed is included in the input AIS data, this is NOT used. The routes include one position per half-hour time step, corresponding to the default time step used in the DEPONS model. If input data does not include one position per half hour, new positions are generated using linear interpolation. If the input data contains many positions in a particular half-hour interval, only the positions closest to the half-hour interval are used. The routes contain information about the number of half-hour intervals were ships 'pause' at a particular location, e.g. in a port. These are calculated based on the input AIS data.

See Also

aisdata for an example of data that can be used as input to ais.to.DeponsShips. The function builds on interpolate.ais.data, which interpolates tracks to ensure that there is a position every 30 minutes. Use check.DeponsShips for testing if speeds are realistic. See write.DeponsShips for conversion of DeponsShips objects to json-files to be used in DEPONS. Use routes, ships, and title for inspection/modification of the ship tracks.

Examples

data(aisdata)
plot(aisdata$x, aisdata$y, type="n", asp=1)
ids <- sort(unique(aisdata$id))
my.colors <- heat.colors(length(ids))
for (i in 1:length(ids)) {
  id <- ids[i]
  points(aisdata$x[aisdata$id==id], aisdata$y[aisdata$id==id],
     cex=0.6, col=my.colors[i])
}
data(bathymetry)
plot(bathymetry, add=TRUE)
depons.ais <- ais.to.DeponsShips(aisdata, bathymetry)
the.routes <- routes(depons.ais)
for (i in 1:length(ids)) {
points(the.routes[[i]]$x, the.routes[[i]]$y,
        cex=0.6, pch=16, col=my.colors[i])
}
depons.ais <- ais.to.DeponsShips(aisdata, bathymetry,
   startday="2015-12-20", endday="2015-12-20")
routes(depons.ais)
aisdata2 <- aisdata
aisdata2$time <- format(as.POSIXct(aisdata$time)+300)
depons.ais2 <- ais.to.DeponsShips(aisdata2, bathymetry,
                               startday="2015-12-20", endday="2015-12-21")
routes(depons.ais2)

Position for three ships in the inner Danish waters

Description

Automatic identification system (AIS) data for three ships in Kattegat and the Western Baltic from 20 Dec 2015. The data set includes the variables id (the Maritime Mobile Service Identity number), time, speed (in knots), type, length (in metres), x and y (which provide the coordinates of the ship at a given time. The coordinates use the UTM zone 32 projection (CRS = "+proj=utm +zone=32 +units=m +no_defs +datum=WGS84").

Format

data.frame

Convert DeponsDyn object to data frame

Description

Function for converting DEPONS population dynamics object to a data frame.

Usage

## S4 method for signature 'DeponsDyn'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

data.frame object

Examples

data(porpoisedyn)
class(porpoisedyn)
the.dyn <- as.data.frame(porpoisedyn)

Convert DeponsTrack to data frame

Description

Function for converting DEPONS movement track file to a data frame.

Usage

## S4 method for signature 'DeponsTrack'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

Value

data.frame object

Examples

data(porpoisetrack)
class(porpoisetrack)
the.track <- as.data.frame(porpoisetrack)

Bathymetry of the Kattegat area

Description

The standard bathymetry file for Kattegat which is used in DEPONS simulations. It is based on a raster file with 1000 rows and 600 columns where each grid cell corresponds to 400 m x 400 m. Cells on land are assigned a missing data value of -9999.

The Kattegat landscapes use the UTM zone 32 projection, (EPSG:32632) as in the study by Nabe-Nielsen et al (2014). The corresponding proj4string is "+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs" (see https://epsg.io/32632).

Format

DeponsRaster

References

Nabe-Nielsen, J., Sibly, R. M., Tougaard, J., Teilmann, J., & Sveegaard, S. (2014). Effects of noise and by-catch on a Danish harbour porpoise population. Ecological Modelling, 272, 242–251. doi:10.1016/j.ecolmodel.2013.09.025

See Also

DeponsRaster-class

Get bbox from Depons* object

Description

Retrieves spatial bounding box from object. If a Depons* object is a DeponsTrack object containing multiple track, the box bounds all tracks.

Usage

## S4 method for signature 'DeponsRaster'
bbox(obj)

## S4 method for signature 'DeponsTrack'
bbox(obj)

Arguments

Value

Returns a matrix defining the northern, southern, eastern and western boundary of a DeponsRaster object or of one or more DeponsTrack objects.

See Also

make.clip.poly

Plot distribution of turning angles, step lengths and speed of tracked simulated porpoises.

Description

Plot distribution of turning angles, step lengths and speed of tracked simulated porpoises.

Usage

calib_01(depons_track)

Arguments

Value

Plot histograms of turning angles, step length and speed. It also stores those metrics of the animal in a dataframe.

Check if ships move at unrealistic speeds or are outside the map boundary

Description

Checks if calculated speeds in DeponsShips objects are unrealistic, which may result from inaccurate AIS positional records or from ships leaving the map area, then re-entering at a remote position. As ship speed in DEPONS directly influences the amount of noise generated, it is advisable to detect and remove such instances to avoid the creation of extreme noise sources. The function can also repair issues arising from ship positions that are a fraction of a meter outside the map boundary (causing loading errors on simulation start).

Usage

check.DeponsShips(
  x,
  threshold = 35,
  fix = F,
  replacements = NA,
  landscape = NULL
)

Arguments

Details

The default replacement speeds (knots) for recognized ship types are as follows (class reference speeds from MacGillivray & de Jong, 2021, Table 1): Fishing, 6.4; Tug, 3.7; Naval, 11.1; Recreational, 10.6; Government/Research, 8; Cruise, 17.1; Passenger, 9.7; Bulker, 13.9; Containership, 18.0; Tanker, 12.4; Dredger, 9.5; Other, 7.4.

If a simulation fails during data loading with an error that indicates ship positions outside the simulation area, this may be caused by a mismatch in rounding between the map extent of the map used with ais.to.DeponsShips, and of generated ship position exactly on the boundary. If a map representative of the simulation area extent is provided (usually the bathymetry map), the function will also repair these positions by rounding them up/down to the floor/ceiling of the map extent (fractional meter adjustments).

Value

If fix = FALSE, a data frame with columns "route number", "name", "type", "length", and "speed", containing one entry for each ship where an excessive speed occurred. If fix = TRUE, a DeponsShip object where instances of excessive speed have been replaced, and (if a map has been provided) where ship positions on the boundary have been adjusted.

Reference

MacGillivray, A., & de Jong, C (2021). A reference spectrum model for estimating source levels of marine shipping based on Automated Identification System data. Journal of Marince Science and Engineering, 9(4), 369. doi:10.3390/jmse9040369

See Also

ais.to.DeponsShips for creation of DeponsShips objects (including calculated speeds) from AIS data

Examples

## Not run: 
x <- shipdata
check.DeponsShips(x)

x@routes$route[[1]]$speed <- x@routes$route[[1]]$speed * 3
check.DeponsShips(x)
x <- check.DeponsShips(x, fix = T)
## End(Not run)

Coastline of Northern Europe

Description

An object of class SpatialPolygonsDataFrame showing the coastline of the North Sea, Kattegat, and the Western Baltic. The map projection used is ETRS89 – EPSG:3035 projection as for the North Sea raster files used by DEPONS. The corresponding proj4string is "+proj=laea +lat_0=52 +lon_0=10 +x_0=4321000 +y_0=3210000 +datum=WGS84 +units=m +no_defs".

Format

SpatialPolygonsDataFrame

Get or set map projection in Depons* objects

Description

Get or set the map projection (also known as coordinate reference system, crs) of DeponsRaster and DeponsTrack objects.

Usage

## S4 method for signature 'DeponsTrack'
crs(x)

## S4 method for signature 'DeponsShips'
crs(x)

## S4 method for signature 'DeponsRaster'
crs(x)

## S4 replacement method for signature 'DeponsTrack'
crs(x) <- value

## S4 replacement method for signature 'DeponsShips'
crs(x) <- value

## S4 replacement method for signature 'DeponsRaster'
crs(x) <- value

Arguments

Extract population dynamics from objects

Description

Extract population dynamics from objects

Usage

## S4 method for signature 'DeponsDyn'
dyn(x)

## S4 method for signature 'DeponsBlockdyn'
dyn(x)

Arguments

Get name of newest file

Description

Returns the name of the newest simulation output of a particular type within the specified directory. The date and time are extracted from the file name.

Usage

get.latest.sim(type = "dyn", dir)

Arguments

Value

character string with the name of the most recent simulation output file.

See Also

read.DeponsBlockdyn for example.

Get simulation date

Description

Returns the date and time when a specific simulation was finished, obtained from the date stored as part of the file name. The date format is system dependent, but the function attemts to extract the data assuming that either the English or the local language is used. (a POSIXlt object)

Usage

get.simtime(fname = NULL, tz = "UTC")

Arguments

Value

Returns a POSIXlt object

See Also

get.latest.sim

Interpolate AIS data

Description

Interpolates ship movement tracks obtained from Automatic Identification System (AIS) data to obtain exactly one position per 30 minutes. The first and last position in the original track are omitted unless minutes = 0 or 30 and seconds = 0.

Usage

interpolate.ais.data(aisdata)

Arguments

Value

Returns a data frame with the same columns as the input data. Tracks that are too short to interpolate are omitted (with a warning)

See Also

read.DeponsShips and ais.to.DeponsShips

Examples

data(aisdata)
ais.testdata <- aisdata[c(12,14,16) ,]
plot(ais.testdata[c("x", "y")], asp=1, col="green", pch=16, xlim=c(780000, 837000))
lines(ais.testdata[c("x", "y")])
# Add 600 sec to 'time' to mis-allign with intervcal needed
ais.testdata$time <- format(as.POSIXlt(ais.testdata$time, tz = "UTC")+600)
text(ais.testdata[c("x", "y")]-900, ais.testdata$time, adj=0, cex=0.5)
interpolated <- interpolate.ais.data(ais.testdata)
points(interpolated[,c("x", "y")], col="red")
text(interpolated[c("x", "y")]-900, interpolated$time, adj=0, cex=0.5)
legend("bottomright", bty="n", pch=c(16, 1), col=c("green", "red"),
    legend=c("original positions", "interpolated"))

Get or set the landscape name

Description

Get or set the landscape name

Get or set the landscape name

Usage

## S4 replacement method for signature 'DeponsTrack'
landscape(x) <- value

## S4 method for signature 'DeponsTrack'
landscape(x)

## S4 replacement method for signature 'DeponsDyn'
landscape(x) <- value

## S4 method for signature 'DeponsDyn'
landscape(x)

## S4 replacement method for signature 'DeponsBlockdyn'
landscape(x) <- value

## S4 method for signature 'DeponsBlockdyn'
landscape(x)

Arguments

Make DeponsDyn object from data stored in data frame

Description

Function for reading converting a data frame containing DEPONS simulation output to a DeponsDyn object.

Usage

make.DeponsDyn(
  oname,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  startday = "2000-01-01",
  timestep = 30,
  tz = "UTC"
)

Arguments

Value

DeponsDyn object containing simulation output

See Also

See DeponsDyn-class for details on what is stored in the output object.

Examples

data(porpoisedyn)
the.data <- as.data.frame(porpoisedyn)
the.data <- the.data[, c(1:4)]
names(the.data) <- c("tick", "PorpoiseCount", "FoodEnergyLevel", "PorpoiseEnergyLevel")
porpoisedyn2 <- make.DeponsDyn(the.data, startday="2010-01-01")
porpoisedyn2

Makes new file with blocks

Description

Produces a DeponsRaster object of type='blocks' for use in DEPONS simulations. This allows animals to be counted within specific regions (blocks) of the landscape during the simulation. The new blocks can be specified as either matrices or SpatialPolygons objects. For matrices, the blocks are defined as the smallest rectangle that includes all the specified positions.

Usage

## S4 method for signature 'DeponsRaster'
make.blocksraster(
  template,
  blocks = NA,
  blockvals = NULL,
  NAvalue = -9999,
  plot = FALSE,
  fname = NULL,
  overwrite = FALSE
)

Arguments

Value

RasterLayer object defining different subregions of the landscape where animals should be counted.

Note

The blocks file should not be modified when running DEPONS simulations using the 'Kattegat' landscape. In this landscape the simulated animals use the blocks file for navigation. Also note that blocks are added to the new blocks raster in the order they are file in the order in which they are listed in 'blocks', so the order mattes if the blocks overlap.

Examples

#Load file to use as template for new blocks file
data("bathymetry")

# Make list of blocks to create
new.blocks <- list()
x <- runif(8, 700000, 760000)
y <- runif(8, 6200000, 6300000)
new.blocks[[1]] <- cbind(x,y)
x <- c(600000, 635000, 670000, 635000)
y <- c(6150000, 6200000, 6150000, 6100000)
library(sp)
srl <- list(Polygon(cbind(x,y)))
Srl <- list(Polygons(srl, ID=as.vector("p")))
new.blocks[[2]] <- SpatialPolygons(Srl, proj4string=crs(bathymetry))

make.blocksraster(bathymetry, new.blocks, plot=TRUE)
points(new.blocks[[1]])
plot(new.blocks[[2]], add=TRUE)


the.dir <- tempdir()
make.blocksraster(bathymetry, new.blocks, fname=paste0(the.dir, "/test.asc"))

Make clipping polygon from bbox

Description

Makes a polygon from a bounding box to use for clipping the coastline, or other SpatialPolygons objects

Usage

## S4 method for signature 'matrix'
make.clip.poly(bbox, crs)

Arguments

Value

SpatialPolygons object

See Also

bbox for creation of bbox matrix from DeponsRaster

Examples

data(bathymetry)
bbox <- cbind("min"=c(549517, 6155000), "max"=c(636000, 6210000))
rownames(bbox) <- c("x", "y")
clip.poly <- make.clip.poly(bbox, crs(bathymetry))

Identify and parameterize stationary active ships in a DeponsShips object

Description

Identifies ship positions in a DeponsShips object where the ship is stationary (pausing) but potentially still actively using its engine (bollard pushing or using dynamic positioning system), and if desired assigns a suitable non-zero speed to ensure noise generation at that time point. Candidates may be found either among all ships that are at a minimum distance from shore, or among those that are close to specific structures of interest, such as wind turbines.

Usage

make.stationary.ships(
  x,
  action = "check",
  candidates = NULL,
  distcrit = "shore",
  landscape = NULL,
  structure_locations = NULL,
  start_day = NA,
  start_times = NULL,
  verbose = F
)

Arguments

Details

When a DeponsShips object is created using ais.to.DeponsShips, positions are interpolated at 30-minute intervals (ticks). If a ship's position does not change during sequential ticks, these ticks are combined into a pause of the appropriate duration, with a movement speed of 0. However, in some cases, an unmoving ship is actually using its engine to hold position, such as a crew transfer vessel performing a bollard push against a turbine pile, or an offshore supply vessel using a dynamic position system (DPS). Under these circumstances, the ship should emit noise to affect porpoise agents. This function attempts to identify and rewrite such pausing instances in an existing DeponsShips object. A pause is converted into an active stationary position by assigning a non-zero speed and thus noise emission. Note that assigning a speed does not translate into movement, as movement in the model is only derived from position changes, and speed is only used to drive noise calculation.

The intended functionality is to first run the function using 'action = "check"' to return a table of candidate instances. After this has been inspected and thinned as desired by the user, the function is run again using 'action = "replace"' while providing the table as 'candidates', which returns a DeponsShips object where the identified candidate pauses have been replaced with speed values. No testing criteria (distcrit, landscape, stucture_locations, start_day, start_times) are required for a "replace" run, as the instances provided as 'candidates' are then modified without further checks.

Only ships with type "Other" or "Government/Research" (following the key in Table 1 in MacGillivray & de Jong 2021) are tested, as these categories contain the survey, construction and crew transfer ships that are the primary candidate types. Passenger, recreational, fishing and cargo vessels are assumed to not or rarely use DPS and are omitted. However, the "Other" category also contains vessels that hold position for extended periods without using DPS, such as jack-up rigs and platforms; also, ship type codes provided in AIS data are frequently unreliable. We therefore strongly suggest that the user should carefully scrutinize the candidates table produced in a "check" run, look up vessels by their MMSI code, and remove any false positives from the table before processing it in a "replace" run.

The inserted speed values are 7.4 knots for "Other" and 8 knots for "Government/Research", based on the class reference speeds in MacGillivray & de Jong (2021).

When 'distcrit = "shore"', pause instances are additionally tested against the following criteria: 1) not in a cell (400x400 m) directly adjacent to land, to exclude berthed ships; 2) not in a cell at the map boundary, as ais.to.DeponsShips will create inactive (pausing) placeholder positions at the point of entry if a ship enters the map with a delay after the object's start, or at the point of exit if it leaves before the end of the object's duration; 3) not in the first or last position of the ship's track (same reason).

When candidates are identified based on proximity to a list of structures, a maximum distance of 97.72 m is allowed, based on an estimate of mean AIS positioning error (Jankowski et al. 2021).

Value

If 'action = "check"' (default), returns a data frame with columns "route_number", "ship_name", "ship_type", "route_pos" (position number along route), and "pauses" (number of pauses at this position), with one row for each position that is a candidate for stationary activity based on the selected criteria. If "replace" and a candidates data frame is provided, returns a DeponsShip object where the pauses identified in the data frame have been converted to stationary active status (i.e., a non-zero speed has been assigned).

References

MacGillivray, A., & de Jong, C (2021). A reference spectrum model for estimating source levels of marine shipping based on Automated Identification System data. Journal of Marince Science and Engineering, 9(4), 369. doi:10.3390/jmse9040369"

Jankowski, D, Lamm A, & Hahn, A (2021). Determination of AIS position accuracy and evaluation of reconstruction methods for maritime observation data. IFAC-PapersOnLine, 54(16), 97-104. doi:10.1016/j.ifacol.2021.10.079

See Also

ais.to.DeponsShips for creation of DeponsShips objects (including calculated speeds) from AIS data

Examples

## Not run: 
data(shipdata)
data(bathymetry)
candidates <- make.stationary.ships(shipdata,
                                   landscape = bathymetry,
                                   verbose = T)
shipdata.updated <- make.stationary.ships(shipdata,
                                         action = "replace",
                                         candidates = candidates,
                                         landscape = bathymetry)
## End(Not run)

Make wind farm construction scenario

Description

Produce a hypothetical wind farm construction scenario, specifying the position and timing of individual piling events, as well as the sound source level. All wind farms are assumed to consist of the same number of turbines, laid out in a rectangular grid. The start and end tick (i.e. the number of half-hour intervals since simulation start) is generated based on provided values for the time it required for each piling and the time between piling events.

Usage

make.windfarms(
  area.file,
  area.def,
  n.wf,
  n.turb,
  turb.dist,
  min.wf.dist,
  impact,
  constr.start,
  constr.end,
  constr.time,
  constr.break,
  iterate = 10000,
  verbose = FALSE,
  wf.coords = "random"
)

Arguments

Value

data.frame specifying the position of each turbine in a wind farm, along with the start time and end time for pile driving of the turbine foundation and the sound source level during pile driving. Can be exported as a text file and used for controlling DEPONS simulations.

Note

The parameters constr.start, constr.end, constr.time, and constr.break are truncated to nearest integer value. Construction of wind farms starts in WF001 at tick constr.start. Each turbine foundation is piled over a period of constr.time, followed by a noise-free period of constr.break. Several pile driving operations may take place at the same time, to ensure that the last piling ends before constr.end.

Plot a DeponsBlockdyn object

Description

Plot population dynamics simulated with DEPONS

Usage

## S4 method for signature 'DeponsBlockdyn,missing'
plot(x, y, dilute = 5, ...)

Arguments

Value

data.frame listing blocks where no animals were counted (returned invisibly)

Note

The function returns a data frame with numbers of blocks with no agents.

Examples

data("porpoisebdyn")
my.col <- c("red", "darkgreen", "orange")
plot(porpoisebdyn, col=my.col)
legend("bottomright", bty="n", fill=my.col, legend=paste("Block", 0:2))

# Show all data points for small range of x-values
plot(porpoisebdyn, xlim=c(1950, 2050), ylim=c(4850, 5050), type="p", dilute=1, col=my.col)

Plot a DeponsDyn object

Description

Plot population dynamics simulated with DEPONS

Usage

## S4 method for signature 'DeponsDyn,missing'
plot(x, y, dilute = 5, plot.energy = TRUE, plot.legend = TRUE, ...)

Arguments

Examples

data("porpoisedyn")

# Plot for specific range of years
rg <- c(as.POSIXlt("2011-01-01", tz = "UTC"), as.POSIXlt("2018-12-31", tz = "UTC"))
plot(porpoisedyn, xlim=as.POSIXct(rg), plot.energy=TRUE)

## Not run: 
# Read data from default DEPONS simulation directory:
sim.dir <- "/Applications/DEPONS 2.1/DEPONS"
new.sim.name <- get.latest.sim(dir=sim.dir)
new.sim.out <- read.DeponsDyn(fname=paste(sim.dir, new.sim.name, sep="/"))
plot(new.sim.out)

## End(Not run)

Plot a DeponsRaster object

Description

Plot the values in a DeponsRaster object. Porpoisetracks or other kinds of lines, poits etc. can be drawn on top of the plot by adding

Usage

## S4 method for signature 'DeponsRaster,ANY'
plot(x, y, col, trackToPlot = 1, ...)

Arguments

Value

No return value, called for side effects

See Also

See method for plot in the raster package for plotting parameters and plot.DeponsTrack for plotting of DeponsRasters cropped to the extent of tracks.

Plot a DeponsShips object

Description

Plot the tracks that ship agents move along in DEPONS.

Usage

## S4 method for signature 'DeponsShips,missing'
plot(x, y, ...)

Arguments

Value

No return value, called for side effects

Examples

data(shipdata)
plot(shipdata, col=c("red", "green", "blue"))


# convert route coordinate units from 'grid squares' to UTM
data(bathymetry)
out <- summary(bathymetry)
left <- out[[4]][1]
bottom <- out[[4]][2]
for (i in 1:3) {
    newroute <- shipdata@routes[[2]][[i]]*400
    newroute$x <- newroute$x + as.numeric(left)
    newroute$y <- newroute$y + as.numeric(bottom)
    shipdata@routes[[2]][[i]] <- newroute
    }

# Reproject coastline and clip to size of Kattegat landscape
library(sp)
data(bathymetry)
data(coastline)
coastline_sf <- sf::st_as_sf(coastline)
coastline2 <- sf::st_transform(coastline_sf, crs(bathymetry))
bbox <- bbox(bathymetry)
clip.poly <- make.clip.poly(bbox, crs(bathymetry))
plot(shipdata, col=c("red", "green", "blue"), add=TRUE, add.legend=TRUE)
plot(clip.poly, add=TRUE)

Plot a DeponsTrack object

Description

Plot the coordinates in a movement track simulated with DEPONS.

Usage

## S4 method for signature 'DeponsTrack,missing'
plot(x, y, trackToPlot = 1, add = FALSE, ...)

Arguments

Value

No return value, called for side effects

Examples

data(porpoisetrack)
data("porpoisetrack")
plot(porpoisetrack)

Simulated porpoise population dynamics

Description

An object of class DeponsBlockdyn with output from a DEPONS simulation based on the North Sea landscape, using a landscape divided into two blocks. Numbers of animals are counted per block.

Format

DeponsBlockdyn

See Also

DeponsBlockdyn-class, porpoisedyn

Simulated porpoise population dynamics

Description

An object of class DeponsDyn with output from a DEPONS simulation based on the Kattegat landscape, assuming that the simulation represents the period 2010-01-01 onward in the real world. Number of animals and energy availability is recorded for the entire landscape.

Format

DeponsDyn

See Also

DeponsDyn-class, porpoisebdyn

Simulated porpoise track

Description

An object with five elements: title, landscape, simtime, crs, and tracks. The crs stores information about the map projection used ("+proj=utm +zone=32 +datum=WGS84 +units=m +no_defs"). The tracks element is a list of objects of class SpatialPointsDataFrame, each ofwhich corresponds to one simulated animal. simtime is the simulation date.

Format

DeponsTrack

See Also

DeponsTrack-class

Reading simulated population count for blocks

Description

Function for reading DEPONS simulation output with number of animals per block for each time step.

Usage

read.DeponsBlockdyn(
  fname,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  timestep = 30,
  startday = "2010-01-01",
  tz = "UTC"
)

Arguments

Value

DeponsBlockdyn object

See Also

See DeponsBlockdyn-class for details on what is stored in the output object and read.DeponsParam for reading the parameters used in the simulation.

Examples

## Not run: 
# File loaded from default location
the.file <- "/Applications/DEPONS 2.1/DEPONS/PorpoisePerBlock.2020.Sep.02.20_24_17.csv"
file.exists(the.file)
porpoise.blockdyn <- read.DeponsBlockdyn(fname=the.file,
  title="Test simulation with two blocks", landscape="North Sea")
porpoise.blockdyn

# Get the latest simulation
the.file <- get.latest.sim(type="blockdyn", dir="/Applications/DEPONS 2.1/DEPONS")
owd <- getwd()
setwd("/Applications/DEPONS 2.1/DEPONS")
porpoise.blockdyn <- read.DeponsBlockdyn(fname=the.file)
setwd(owd)

## End(Not run)

Reading DEPONS simulation output

Description

Function for reading simulation output produced by DEPONS.

Usage

read.DeponsDyn(
  fname,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  startday = "2010-01-01",
  timestep = 30,
  tz = "UTC"
)

Arguments

Value

DeponsDyn object containing simulation output

See Also

See DeponsDyn-class for details on what is stored in the output object and as.data.frame for converting from data frame.

Examples

## Not run: 
dyn.file <- "/Applications/DEPONS 2.1/DEPONS/Statistics.2020.Sep.02.20_24_17.csv"
file.exists(dyn.file)
porpoisedyn <- read.DeponsDyn(dyn.file, startday=as.POSIXlt("2010-01-01", tz = "UTC"))
porpoisedyn

## End(Not run)

Read and merges DEPONS Batchmap and Statistics Files

Description

Reads batch map files and statistics files from a specified directory and returns a list of 'DeponsDyn' objects and parameter values.

Usage

read.DeponsDynBatch(
  dir,
  par,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  startday = "NA",
  timestep = 30,
  tz = "UTC"
)

Arguments

Value

A list of 'DeponsDyn' objects and parameter values associated with run id

Examples

## Not run: 
# Specify the directory containing Batchmap and Statistics files
dir_path <- "path/to/batchdata"

# Specify parameters to extract from Batchmap files
par <- c("parameter1", "parameter2")

# Run the function
results <- read.DeponsBatch(
  dir = dir_path,
  par = par,
  startday = "2010-01-01"
)

## End(Not run)

Read simulation parameters

Description

Read the parameters that were used for running a specific DEPONS simulation

Usage

read.DeponsParam(fname)

Arguments

Details

The parameter file can be generated from within DEPONS by pressing the 'Save' icon after modifying the user settings on the 'Parameters' tab within the main DEPONS model window. See TRACE document for details regarding the parameters in the model: https://github.com/jacobnabe/DEPONS. It is strongly recommended that the parameter list is stored with the simulation output.

Value

Data frame containing all parameters used in a specific simulation

Examples

## Not run: 
# Parameters read from file created by DEPONS run in interactive mode
the.file <- "/Applications/DEPONS 2.1/DEPONS/DEPONS.rs/parameters.xml"
pfile <- read.DeponsParam(the.file)

## End(Not run)

Reading DEPONS raster files

Description

Function for reading raster files that have been used in DEPONS simulations. DEPONS rasters define amount of food available for simulated animals, spatial distribution of food patches, bathymetry, and distance to coast (dtc). The 'blocks' raster enables the user to count animals in specific parts of the landscape during simulations. See Nabe-Nielsen et al. (2018) for details regarding these files. In DEPONS 2.0 the salinity raster file was introduced; see TRACE document for details: https://github.com/jacobnabe/DEPONS

Usage

read.DeponsRaster(fname, type = "NA", landscape = "NA", crs = "NA")

Arguments

Value

Returns a DeponsRaster object. The object inherits slots from the "RasterLayer" class, including "title", which is used for storing the file name.

References

Nabe-Nielsen, J., van Beest, F. M., Grimm, V., Sibly, R. M., Teilmann, J., & Thompson, P. M. (2018). Predicting the impacts of anthropogenic disturbances on marine populations. Conservation Letters, 11(5), e12563. doi:10.1111/conl.12563

See Also

DeponsRaster-class

Read DEPONS ship files

Description

Function for reading the json-files that are used for controlling how ship agents behave in DEPONS. Ships move along pre-defined routes in 30-min time steps. The routes are defined by the fix-points provided in the json file, and the geographic projection is assumed to match that of the landscape.

Usage

read.DeponsShips(fname, title = "NA", landscape = "NA", crs = as.character(NA))

Arguments

Value

Returns an object with the elements title landscape, crs, routes and ships.

See Also

ais.to.DeponsShips, write.DeponsShips

Reading DEPONS track files

Description

Function for reading movement tracks produced by DEPONS. These describe movements of simulated animals within the simulation landscape, where the positions after each 30-min time step are provided using the coordinate reference system that were used for generating these landscapes.See van Beest et al. (2018) and Nabe-Nielsen et al. (2013) for details regarding how these files were generated as a balance between correlated random walk behaviour and spatial memory behaviour, which allows animals to return to previously visited food patches.

Usage

read.DeponsTrack(
  fname,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  crs = as.character(NA),
  tz = "UTC"
)

Arguments

Value

Returns a DeponsTrack object with the elements title, simtime, crs, and tracks. The date is extracted from input data if not provided explicitly and stored as a POSIXlt object. The element tracks is a list of objects of class SpatialPointsDataFrame, each of which corresponds to one simulated animal (several animals can be tracked in one simulation).

Examples

data(porpoisetrack) # Load data for use in example

# Use standard DEPONS coordinate reference system / map projection:
the.crs <- "+proj=laea +lat_0=52 +lon_0=10 +x_0=4321000 +y_0=3210000
 +datum=WGS84 +units=m +no_defs"

## Not run: 
one.fname <- "~/Applications/DEPONS/
  RandomPorpoise.2020.Jul.31.09_43_10.csv"

porpoisetrack <- read.DeponsTrack(one.fname, title="Track simulated using DEPONS 2.0",
  crs=the.crs)


## End(Not run)

# Plot the first of the simulated tracks
plot(porpoisetrack)

Read and Process DEPONS Batchmap and Statistics Files

Description

Reads batch map files and random porpoise files from a specified directory, merges them for each run, and returns a list of 'DeponsTrack' objects and parameter values

Usage

read.DeponsTrackBatch(
  dir,
  par,
  title = "NA",
  landscape = "NA",
  simtime = "NA",
  crs = as.character(NA),
  tz = "UTC"
)

Arguments

Value

A list of 'DeponsTrack' objects and parameter values associated with run id

Examples

## Not run: 
# Specify the directory containing Batchmap and Statistics files
dir_path <- "path/to/batchdata"

# Specify parameters to extract from Batchmap files
par <- c("parameter1", "parameter2")

# Run the function
results <- read.DeponsBatch(
  dir = dir_path,
  par = par,
  crs = "+proj=longlat +datum=WGS84"
)

## End(Not run)

Get or define routes in DeponsShips objects

Description

Get or define routes in DeponsShips objects

Usage

## S4 method for signature 'DeponsShips'
routes(x)

## S4 replacement method for signature 'DeponsShips'
routes(x) <- value

Arguments

Note

The unit of 'speed' is knots.

See Also

ships

Ships on example routes through the Kattegat

Description

The routes of fifteen ships of different types in the Kattegat during a period of 15 days. The fix points that define the routes use the UTM zone 32 projection (CRS = "+proj=utm +zone=32 +units=m +no_defs +datum=WGS84"; EPSG:32632; see https://epsg.io/32632).

Format

DeponsShips object

See Also

[DeponsShips-class]

Get or define ships in DeponsShips objects

Description

Get or define ships in DeponsShips objects

Usage

## S4 method for signature 'DeponsShips'
ships(x)

ships(x) <- value

Arguments

See Also

routes

Examples

data(shipdata)
ships(shipdata)

Get or set start date for simulation

Description

Get or set start date for simulation

Get or set start date for simulation

Usage

## S4 method for signature 'DeponsBlockdyn'
startday(x)

## S4 method for signature 'DeponsDyn'
startday(x)

## S4 replacement method for signature 'DeponsBlockdyn'
startday(x) <- value

## S4 replacement method for signature 'DeponsDyn'
startday(x) <- value

Arguments

Details

The start date indicates the start of the period that the simulation is supposed to represent.

The start date indicates the start of the period that the simulation is supposed to represent.

Note

The assignment of a new start time is currently quite time consuming.

Convert tick number to time object

Description

Converts the number of ticks since the start of the simulation to a specific date while taking into account that DEPONS assumes that there are 360 days in a simulation year.

Usage

tick.to.time(tick, timestep = 30, origin = "2010-01-01", tz = "UTC", ...)

Arguments

Value

object of class as.POSIXlt

Note

The function assumes that there are 30 days in each month, except in January, February and March with 31, 28 and 31 days, respectively.

See Also

time.to.tick is the inverse of this function, converting dates to ticks

Convert date to tick number

Description

Convert a date to the number of ticks since simulation start while taking into account that DEPONS assumes that there are 360 days in a simulation year.

Usage

time.to.tick(time, timestep = 30, origin = "2010-01-01", tz = "UTC", ...)

Arguments

Details

Times are rounded down to the current 30-minute interval during conversion. The function assumes that there are 30 days in each month, except in January, February and March with 31, 28 and 31 days, respectively. Provided dates that fall on days that are not accommodated (February 29, and the 31st day of the months May, July, August, October, and December) are returned as NA.

The function may be used to, e.g., convert recorded piling dates to ticks for use in wind farm scenarios (see make.windfarms for construction of hypothetical scenarios from parametric inputs).

Value

Numeric vector of tick numbers.

See Also

tick.to.time is the inverse of this function, converting ticks to dates

Examples

## Not run: 
#Uses date column of AIS data.
#Times are in 30-minute intervals, and converting back yields the same times
data(aisdata)
ticks <- time.to.tick(aisdata$time, origin = "2015-12-20")
times_reconverted <- tick.to.time(ticks, origin = "2015-12-20")

#Uses dates at other intervals.
#Converting back yields times rounded down to the current 30-minute interval
times <- c("2016-12-20 00:10:00",
          "2016-12-20 02:45:30",
          "2016-12-20 05:01:05",
          "2016-12-22 01:30:00")
ticks <- time.to.tick(times, origin = "2015-12-20")
times_reconverted <- tick.to.time(ticks, origin = "2015-12-20")
## End(Not run)

Get or set the title of Depons* objects

Description

Get or set the title of Depons* objects

Usage

## S4 replacement method for signature 'DeponsTrack'
title(x) <- value

## S4 replacement method for signature 'DeponsDyn'
title(x) <- value

## S4 replacement method for signature 'DeponsShips'
title(x) <- value

## S4 method for signature 'DeponsTrack'
title(x, value)

## S4 method for signature 'DeponsDyn'
title(x, value)

## S4 method for signature 'DeponsShips'
title(x, value)

Arguments

Write DEPONS ship files

Description

Function for writing a json-file for controlling how ship agents behave in DEPONS. Ships move along pre-defined routes in 30-min time steps. The routes are defined by the fix-points provided in the json file, and the geographic projection is assumed to match that of the landscape. The projection is not stored as part of the json file.

Usage

## S4 method for signature 'DeponsShips'
write(x, file)

Arguments

Value

No return value, called for side effects

Note

The exported json file is intended for use in DEPONS 2.3 or later (released July 2022) where the sound pressure level (SPL) is calculated within DEPONS based on ship type, ship length and speed.