depthfilter: Filter locations by water depth
In SDLfilter: Filtering and Assessing the Sample Size of Tracking Data

depthfilter

R Documentation

Filter locations by water depth

Description

Function to filter locations according to bathymetry and tide.

Usage

depthfilter(
  sdata,
  bathymetry,
  bilinear = TRUE,
  qi = 4,
  tide,
  tidal.plane,
  type = "HT",
  height = 0,
  filter = TRUE
)

Arguments

`sdata`	A data frame containing columns with the following headers: "id", "DateTime", "lat", "lon", "qi". See the data `turtle` for an example. The function filters the input data by a unique "id" (e.g. transmitter number, identifier for each animal). "DateTime" is the GMT date & time of each location in class `POSIXct` or `character` with the following format "2012-06-03 01:33:46". "lat" and "lon" are the latitude and longitude of each location in decimal degrees. "qi" is the quality index associated with each location fix. The input values can be either the number of GPS satellites or Argos Location Classes. Argos Location Classes will be converted to numerical values, where "A", "B", "Z" will be replaced with "-1", "-2", "-3" respectively. The greater number indicates a higher accuracy.
`bathymetry`	A stars object containing bathymetric data in metres. Negative and positive values indicate below and above the water respectively. Geographic coordinate system is WGS84.
`bilinear`	Logical. This defines a method for how to extract cell values from the bathymetry layer. Options are bilinear (TRUE) or nearest neighbour (False) as inherited from `st_extract`.
`qi`	An integer specifying a threshold of quality index. depthfilter does not filter a location that is associated with a quality index higher than this threshold. Default is 4.
`tide`	A data frame containing columns with the following headers: "tideDT", "reading", "standard.port". "tideDT" is date & time in class `POSIXct` at each observation. "reading" is the observed tidal height in metres. "standard.port" is the identifier of each tidal station.
`tidal.plane`	A data frame containing columns with the following headers: "standard.port", "secondary.port", "lat", "lon", "timeDiff", "datumDiff". "standard.port" is the identifier for a tidal observation station. "secondary.port" is the identifier for a station at which tide is only predicted using tidal records observed at the related standard port. "lat" and "lon" are the latitude and longitude of each secondary port in decimal degrees. "timeDiff" is the time difference between standard port and its associated secondary port. "datumDiff" is the baseline difference in metres if bathymetry and tidal observations/predictions uses different datum (e.g. LAT and MSL).
`type`	The type of water depth considered in the filtering process. "exp" is for the water depth experienced by the animal at the time. This option may be applicable to species that remain in water at all times (e.g. dugongs, dolphins, etc). "HT" is for the water depth at the nearest high tide (default). This option is useful for animals that use inter-tidal zones at high tide and may remain there even after the tide drops (e.g. some sea turtles).
`height`	A numerical value to adjust the water depth an animal is likely to use. Default is 0 m. This parameter is useful if the minimum water depth used by the animal is known. For example, a dugong is unlikely to use water shallower than its body height (e.g. ~0.5 m) so it may be sensible to consider the fix is an error if the estimated water depth is shallower than its body height. A negative value indicates below the water surface. For the dugong example, to remove locations for which the water depth was <0.5 m, it should be specified as; height = -0.5. By supplying the body height to this argument, all the locations recorded shallower than its body will be removed.
`filter`	Default is TRUE. If FALSE, the function does not filter locations but it still returns estimates of the water depth experienced by the animal at each location.

Details

The function examines each location according to the water depth experienced by the animal or the water depth at the nearest high tide. The function looks for the closest match between each fix and tidal observations or predictions in temporal and spatial scales. When filter is disabled, the function does not filter locations but returns the estimated water depth of each location with the tide effect considered (bathymetry + tide).

Value

When filter option is enabled, this function filters the input data and returns with two additional columns; "depth.exp", "depth.HT". "depth.exp" is the estimated water depth at each location at the time of location fixing. "depth.HT" is the estimated water depth at the nearest high tide at each location.

Note

The input data must not contain temporal or spatial duplicates.

Author(s)

Takahiro Shimada

References

Shimada T, Limpus C, Jones R, Hazel J, Groom R, Hamann M (2016) Sea turtles return home after intentional displacement from coastal foraging areas. Marine Biology 163:1-14 \Sexpr[results=rd]{tools:::Rd_expr_doi("10.1007/s00227-015-2771-0")}

Beaman, R.J. (2010) Project 3DGBR: A high-resolution depth model for the Great Barrier Reef and Coral Sea. Marine and Tropical Sciences Research Facility (MTSRF) Project 2.5i.1a Final Report, MTSRF, Cairns, Australia, pp. 13 plus Appendix 1.

Examples

## Not run: 

#### Load data sets
## Fastloc GPS data obtained from a green turtle
data(turtle)

## Bathymetry model developed by Beaman (2010)
data(bathymodel)

## A tidal plane for the example site
data(tidalplane)

## Tidal observations and predictions for the example site
data(tidedata)

## Maps for the example site
data(SandyStrait)


#### Remove temporal and/or spatial duplicates and biologically unrealistic fixes 
turtle.dd <- ddfilter(dupfilter(turtle))


#### Apply depthfilter
turtle <- depthfilter(sdata = turtle.dd, bathymetry = bathymodel, 
tide = tidedata, tidal.plane = tidalplane)


#### Plot data removed or retained by depthfilter
to_map(turtle.dd, bgmap = SandyStrait, point.bg = "red", point.size = 2, line.size = 0.5, 
        axes.lab.size = 0, title.size = 0, multiplot = FALSE)[[1]] + 
geom_point(aes(x = lon, y = lat), data = turtle, size = 2, fill = "yellow", shape = 21)+
geom_point(aes(x = x, y = y), data = data.frame(x = c(152.68, 152.68), y = c(-25.3, -25.34)), 
           size = 3, fill = c("yellow", "red"), shape = 21) + 
annotate("text", x = c(152.7, 152.7), y = c(-25.3, -25.34), label = c("Retained", "Removed"), 
         colour = "black", size = 4, hjust = 0)

## End(Not run)

SDLfilter documentation built on Nov. 10, 2023, 1:11 a.m.