pleistodist_visibility: Estimate island visibility relative to horizon

In g33k5p34k/PleistoDistR: Calculating Island Geomorphologies Over Pleistocene Time

Estimate island visibility relative to horizon

Description

This function estimates the visibility of a destination island relative to a user-defined point located on or above on an origin island for each sea level/time interval. This function works by first calculating the expected horizon distance relative to the origin point, accounting for the local curvature of the Earth's surface as well as the height of both the ground level and the height of the observer above the ground level (users can set this relative height to 0 for non-flying organisms). If the destination island is within the bounds of the horizon radius, this function then calculates the area of the viewshed on the destination island relative to the origin point, to account for the effect of geographical features such as mountains blocking an observer's view. This viewshed area is thus the region visible to an observer standing at a particular height above the origin point. This function also calculates the visible area of the island relative to the total area of the island. If the destination island is not visible, then this function will return a value of 0. Do note that the horizon distance calculation is made relative to the centroid of the destination island, rather than to the specific coordinates of the destination point. Also note that this calculation is a very rough estimate and the calculated visible area may not be identical across different runs (due to the sampling method applied), and does not account for the effect of fog, mist, haze, etc. Lastly, this function calculates the weighted mean visibility over time/sea level of the destination island relative to the origin point.

Usage

pleistodist_visibility(
  points,
  epsg,
  intervalfile,
  mapdir,
  outdir,
  height = 0,
  plotfigs = FALSE
)

Arguments

points	A user-generated multi-point shapefile (.shp) containing at least two points. If the shapefile attribute table contains a column labelled 'Name', the output distance matrix will use the identifiers in this column to label each pairwise comparison. Otherwise, the output distance matrix will use the attribute FID values instead.
epsg	The projected coordinate system in EPSG code format. Because of the curvature of the Earth's surface, we need to apply a map projection to accurately calculate straight-line distances between points instead of using the default WGS84 geographical coordinate system. Users should specify a projected coordinate system appropriate to the geographic region being analysed using the projection's associated EPSG code (https://epsg.org/home). Geographic coordinate system projections are not recommended as those will result in distance matrices calculated in decimal degrees rather than in distance units.
intervalfile	This is the master control file generated using either the getintervals_time() or getintervals_sealvl() function that defines the number of intervals, the sea level at each interval, and the duration of each interval. By default, this function will use the "intervals.csv" file stored in the output folder, but users can also specify their own custom interval file (with nice round mean sea level values, for example), although users need to ensure that the same column names are preserved, and be aware that custom interval files may lead to inaccurate weighted mean calculations.
mapdir	The directory containing map outputs from the makemaps() function (i.e. the directory containing the raster_flat, raster_topo, and shapefile folders).
outdir	The output directory for the inter-island visibility matrices. This function generates two files, one estimating the absolute visible area of the destination island, and another estimating the proportion of the destination island visible.
height	The height of the observer relative to the ground level. This can be used to model the visibility of nearby islands to flying animals (e.g. birds, bats, insects). As such, if an origin point is defined on a pixel that is 100m above sea level, a height value of 100 will result in visibility estimates for an organism flying 200m above sea level (with sea level calibrated relative to the sea level of that particular interval).
plotfigs	TRUE/FALSE option to generate island visibility maps for each pairwise island comparison. The function will generate a prompt if the number of pairwise comparisons is very high (>5 points in the points file).

Value

This function returns two matrices, both in long format, of the visible area of island 2 relative to and origin point on island 1, and the proportion of the visible area on island 2 relative to the entire island area.

Examples

#create temp directory
path <- file.path(tempdir())
#create points shapefile
points <- sf::st_multipoint(rbind(c(178.68408,-16.82573), c(179.13585,-16.59487)))
#convert points to feature geometry
points <- sf::st_sfc(points)
points <- sf::st_cast(points, "POINT")
#set default projection (WGS84)
sf::st_crs(points) <- 4326
#save shapefile
sf::write_sf(points,paste0(path,"/points.shp"))
#load bathymetry file
fiji <- system.file("extdata","FJ.asc",package="PleistoDist")
#generate interval file for 1 interval and 20 kya cutoff time, binning by time
getintervals_time(time=20,intervals=1,outdir=path)
#generate maps based on interval file, projecting map using EPSG:3141
makemaps(inputraster=fiji,epsg=3141,intervalfile=paste0(path,"/intervals.csv"),outdir=path)
#calculate inter-island visibility, projecting points using EPSG:3141,
#with an observer height of 0 and no figure plotting
pleistodist_visibility(points=paste0(path,"/points.shp"),epsg=3141,
    intervalfile=paste0(path,"/intervals.csv"),mapdir=path,outdir=path,height=0,plotfigs=FALSE)

g33k5p34k/PleistoDistR documentation built on Oct. 9, 2022, 5:27 a.m.