integrate_profile: Vertically integrate profiles ('vp' or 'vpts') into an...

View source: R/integrate_profile.R

integrate_profileR Documentation

Vertically integrate profiles (vp or vpts) into an integrated profile (vpi)

Description

Performs a vertical integration of density, reflectivity and migration traffic rate, and a vertical averaging of ground speed and direction weighted by density.

Usage

integrate_profile(
  x,
  alt_min,
  alt_max,
  alpha = NA,
  interval_max = 3600,
  interval_replace = NA,
  height_quantile = NA
)

## S3 method for class 'vp'
integrate_profile(
  x,
  alt_min = 0,
  alt_max = Inf,
  alpha = NA,
  interval_max = 3600,
  interval_replace = NA,
  height_quantile = NA
)

## S3 method for class 'list'
integrate_profile(
  x,
  alt_min = 0,
  alt_max = Inf,
  alpha = NA,
  interval_max = 3600,
  interval_replace = NA,
  height_quantile = NA
)

## S3 method for class 'vpts'
integrate_profile(
  x,
  alt_min = 0,
  alt_max = Inf,
  alpha = NA,
  interval_max = 3600,
  interval_replace = NA,
  height_quantile = NA
)

Arguments

x

A vp or vpts object.

alt_min

Minimum altitude in m. "antenna" can be used to set the minimum altitude to the height of the antenna.

alt_max

Maximum altitude in m.

alpha

Migratory direction in clockwise degrees from north.

interval_max

Maximum time interval belonging to a single profile in seconds. Traffic rates are set to zero at times t for which no profiles can be found within the period t-interval_max/2 to t+interval_max/2. Ignored for single profiles of class vp.

interval_replace

Time interval to use for any interval > interval_max. By default the mean of all intervals <= interval_max

height_quantile

For default NA the calculated height equals the mean flight altitude. Otherwise a number between 0 and 1 specifying a quantile of the height distribution.

Details

Available quantities

The function generates a specially classed data frame with the following quantities:

  • datetime: POSIXct date of each profile in UTC

  • vid: Vertically Integrated Density in individuals/km^2. vid is a surface density, whereas dens in vp objects is a volume density.

  • vir: Vertically Integrated Reflectivity in cm^2/km^2

  • mtr: Migration Traffic Rate in individuals/km/h

  • rtr: Reflectivity Traffic Rate in cm^2/km/h

  • mt: Migration Traffic in individuals/km, cumulated from the start of the time series up to datetime

  • rt: Reflectivity Traffic in cm^2/km, cumulated from the start of the time series up to datetime

  • ff: Horizontal ground speed in m/s

  • dd: Direction of the horizontal ground speed in degrees

  • u: Ground speed component west to east in m/s

  • v: Ground speed component south to north in m/s

  • height: Mean flight height (height weighted by eta) in m above sea level

Vertically integrated density and reflectivity are related according to vid=vir/rcs(x), with rcs the assumed radar cross section per individual. Similarly, migration traffic rate and reflectivity traffic rate are related according to mtr=rtr/rcs(x)

Migration traffic rate (mtr) and reflectivity traffic rate (rtr)

Migration traffic rate (mtr) for an altitude layer is a flux measure, defined as the number of targets crossing a unit of transect per hour.

Column mtr of the output dataframe gives migration traffic rates in individuals/km/hour.

The transect direction is set by the angle alpha. When alpha=NA, the transect runs perpendicular to the measured migratory direction. mtr then equals the number of crossing targets per km transect per hour, for a transect kept perpendicular to the measured migratory movement at all times and altitudes. In this case mtr is always a positive quantity, defined as:

mtr = 3.6 \sum_i \mathit{dens}_i \mathit{ff}_i \Delta h

with the sum running over all altitude layers between alt_min and alt_max, \mathit{dens}_i the bird density, \mathit{ff}_i the ground speed at altitude layer i, and \Delta h the altitude layer width. The factor 3.6 refers to a unit conversion of speeds \mathit{ff}_i from m/s to km/h.

If alpha is given a numeric value, the transect is taken perpendicular to the direction alpha, and the number of crossing targets per hour per km transect is calculated as:

mtr = 3.6 \sum_i \mathit{dens}_i \mathit{ff}_i \cos((dd_i-\alpha) \pi/180) \Delta h

with dd_i the migratory direction at altitude i.

Note that this equation evaluates to the previous equation when alpha equals dd_i. Also note we can rewrite this equation using trigonometry as:

mtr = 3.6 \sum_i \mathit{dens}_i (u_i \sin(\alpha \pi/180) + v_i \cos(\alpha \pi/180)) \Delta h

with u_i and v_i the u and v ground speed components at altitude i.

In this definition mtr is a traditional flux into a direction of interest. Targets moving into the direction alpha contribute positively to mtr, while targets moving in the opposite direction contribute negatively to mtr. Therefore mtr can be both positive or negative, depending on the definition of alpha.

Note that mtr for a given value of alpha can also be calculated from the vertically integrated density vid and the height-integrated velocity components u and v as follows:

mtr = 3.6 (u \sin(\alpha \pi/180) + v \cos(\alpha \pi/180)) vid

Formula for reflectivity traffic rate rtr are found by replacing dens with eta and vid with vir in the formula for mtr. Reflectivity traffic rate gives the cross-sectional area passing the radar per km transect perpendicular to the migratory direction per hour. mtr values are conditional on settings of rcs, while rtr values are not.

Migration traffic (mt) and reflectivity traffic (rt)

Migration traffic is calculated by time-integration of migration traffic rates. Migration traffic gives the number of individuals that have passed per km perpendicular to the migratory direction at the position of the radar for the full period of the time series within the specified altitude band.

Reflectivity traffic is calculated by time-integration of reflectivity traffic rates. Reflectivity traffic gives the total cross-sectional area that has passed per km perpendicular to the migratory direction at the position of the radar for the full period of the time series within the specified altitude band.

mt values are conditional on settings of rcs, while rt values are not.

Columns mt and rt in the output dataframe provides migration traffic as a numeric value equal to migration traffic and reflectivity traffic from the start of the time series up till the moment of the time stamp of the respective row.

Ground speed (ff) and ground speed components (u,v)

The height-averaged ground speed is defined as:

\mathit{ff} = \sum_i \mathit{dens}_i \mathit{ff}_i / \sum_i \mathit{dens}_i

with the sum running over all altitude layers between alt_min and alt_max, \mathit{dens}_i the bird density, \mathit{ff}_i the ground speed at altitude layer i.

the height-averaged u component (west to east) is defined as:

u = \sum_i \mathit{dens}_i u_i / \sum_i \mathit{dens}_i

the height-averaged v component (south to north) is defined as:

v = \sum_i \mathit{dens}_i v_i / \sum_i \mathit{dens}_i

Note that \mathit{ff}_i=\sqrt(u_i^2 + v_i^2), but the same does not hold for the height-integrated speeds, i.e. \mathit{ff} \neq \sqrt(u^2 + v^2) as soon as the ground speed directions vary with altitude.

Value

an object of class vpi, a data frame with vertically integrated profile quantities

Methods (by class)

  • integrate_profile(vp): Vertically integrate a vertical profile (vp).

  • integrate_profile(list): Vertically integrate a list of vertical profiles (vp).

  • integrate_profile(vpts): Vertically integrate a time series of vertical profiles (vpts).

Examples

# Calculate migration traffic rates for a single vp
integrate_profile(example_vp)

# Calculate migration traffic rates for a list of vps
integrate_profile(c(example_vp, example_vp))

# Calculate migration traffic rates for a vpts
vpi <- integrate_profile(example_vpts)

# Plot migration traffic rate (mtr) for the full air column
plot(integrate_profile(example_vpts))

# Plot migration traffic rate (mtr) for altitudes > 1 km above sea level
plot(integrate_profile(example_vpts, alt_min = 1000))

# Plot cumulative migration traffic rates (mt)
plot(integrate_profile(example_vpts), quantity = "mt")
# calculate median flight altitude (instead of default mean)
integrate_profile(example_vp, height_quantile=.5)
# calculate the 90% percentile of the flight altitude distribution
integrate_profile(example_vpts, height_quantile=.9)

bioRad documentation built on Oct. 20, 2023, 5:06 p.m.